{"id":13585383,"url":"https://github.com/StewLG/check_truenas_extended_play","last_synced_at":"2025-04-07T09:34:40.267Z","repository":{"id":43455004,"uuid":"263830246","full_name":"StewLG/check_truenas_extended_play","owner":"StewLG","description":"TrueNAS/FreeNAS Nagios check script. Checks for Alerts, Pool health, Pool capacity, Replication errors, TrueNAS software updates, etc.","archived":false,"fork":false,"pushed_at":"2023-01-31T00:35:37.000Z","size":67,"stargazers_count":20,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-02T16:00:08.377Z","etag":null,"topics":["freenas","nagios","nagios-plugin","truenas"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StewLG.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-14T06:08:14.000Z","updated_at":"2024-03-22T19:08:49.000Z","dependencies_parsed_at":"2023-02-16T13:31:06.684Z","dependency_job_id":null,"html_url":"https://github.com/StewLG/check_truenas_extended_play","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StewLG%2Fcheck_truenas_extended_play","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StewLG%2Fcheck_truenas_extended_play/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StewLG%2Fcheck_truenas_extended_play/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StewLG%2Fcheck_truenas_extended_play/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StewLG","download_url":"https://codeload.github.com/StewLG/check_truenas_extended_play/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223277837,"owners_count":17118654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["freenas","nagios","nagios-plugin","truenas"],"created_at":"2024-08-01T15:04:54.669Z","updated_at":"2024-11-06T03:31:00.762Z","avatar_url":"https://github.com/StewLG.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Check TrueNAS - Extended Play\nThis is a TrueNAS/FreeNAS Nagios check script. Checks for Alerts, Pool health, Pool capacity, Replication errors, TrueNAS software updates, etc.\n\nThis is an updated version of `check_truenas.py`, written by Goran Tornqvist, and originally found here:\n\nhttps://exchange.nagios.org/directory/Plugins/Hardware/Storage-Systems/SAN-and-NAS/Check-TrueNAS-Health-2FReplication/details\n```\nChecks a TrueNAS/FreeNAS server using the 2.0 API. Version 1.42\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -H HOSTNAME, --hostname HOSTNAME\n                        Hostname or IP address\n  -u USER, --user USER  Username, only root works, if not specified: use API Key\n  -p PASSWD, --passwd PASSWD\n                        Password or API Key\n  -t TYPE, --type TYPE  Type of check, either alerts, zpool, zpool_capacity, repl, or update\n  -pn ZPOOLNAME, --zpoolname ZPOOLNAME\n                        For check type zpool, the name of zpool to check. Optional; defaults to all zpools.\n  -ns, --no-ssl         Disable SSL (use HTTP); default is to use SSL (use HTTPS)\n  -nv, --no-verify-cert\n                        Do not verify the server SSL cert; default is to verify the SSL cert\n  -ig, --ignore-dismissed-alerts\n                        Ignore alerts that have already been dismissed in FreeNas/TrueNAS; default is to treat them as\n                        relevant\n  -d, --debug           Display debugging information; run script this way and record result when asking for help.\n  -zw ZPOOL_WARN, --zpool-warn ZPOOL_WARN\n                        ZPool warning storage capacity free threshold. Give a percent value in the range 1-100,\n                        defaults to 80%. Used with zpool_capacity check.\n  -zc ZPOOL_CRITICAL, --zpool-critical ZPOOL_CRITICAL\n                        ZPool critical storage capacity free threshold. Give a percent value in the range 1-100,\n                        defaults to 90%. Used with zpool_capacity check.\n  -zp, --zpool-perfdata\n                        Add Zpool capacity perf data to output. Used with zpool_capacity check.\n```\n# Requirements\n\n- Python 3.7 or greater\n   \n  If you get an error like:\n  \n      File \"./check_truenas_extended_play.py\", line 48\n        ZpoolName: str\n\n  Check to make sure you are running an up-to-date Python.\n\n- python3-urllib3\n- python3-requests\n\n# Usage Examples:\n\n#### Check for alerts. This may be all the average user needs to set up. TrueNAS/FreeNas alerts about nearly all significant events here.\n\n#### Alerts normal operation - username/password authentication\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -u root -p RootPassy --type alerts -nv\nOK - No problem alerts\n```\n\n#### Alerts normal operation - API Key authentication\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -p 1-weuiK4YY7OUduhpzKISIJJIDIJSJ4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M --type alerts -nv\nOK - No problem alerts\n```\n\n#### Alerts sample error condition\n```\ncheck_truenas_extended_play.py -H sicknas.yourdomain.local -u root -p RootPa$$worD -type alerts -nv -ns\nCRITICAL - (C) Space usage for pool \"BigMediaThree\" is 85%. Optimal pool performance requires\nused space remain below 80%. - (W) New feature flags are available for volume BigMediaToo. Refer\nto the \"Upgrading a ZFS Pool\" subsection in the User Guide \"Installing and Upgrading\" chapter\nand \"Upgrading\" section for more instructions. - (W) New feature flags are available for volume \nBigMediaThree. Refer to the \"Upgrading a ZFS Pool\" subsection in the User Guide \"Installing and Upgrading\" \nchapter and \"Upgrading\" section for more instructions.\n```\n\n## Check Zpool health\n\n#### Check all Zpools\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -u root -p RootPassy --type zpool -nv\nOK - No problem Zpools. Zpools examined:  ApolloZpoolOne ApolloZPoolEleven\n```\n\n#### Check a specifically named Zpool, ignoring any others\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -u root -p RootPassy --type zpool -nv --zpoolname ApolloZPoolEleven\nOK - No problem Zpools. Zpools examined:  ApolloZPoolEleven\n```\n\n#### Example of what happens if Zpool is not present\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -u root -p RootPassy --type zpool -nv --zpoolname PoolNameWhichIsNotActuallyThere\nCRITICAL - No Zpools found matching PoolNameWhichIsNotActuallyThere out of 2 pools (ApolloZpoolOne ApolloZPoolEleven)\n```\n\n## Check Zpool capacity\n\n#### Check all zpools for capacity issues\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -t zpool_capacity -p 1-weuiK4YY7OUdukdiejsijeiYFe4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv \nOK - No Zpool capacity issues. ZPools examined: ApolloZpoolOne (75.8% used) - ApolloZPoolEleven (64.0% used) - Root level datasets examined: ApolloZpoolOne ApolloZPoolEleven\n```\nNote that the default warning level (80%) and default critical level (90%) will be used here.\n\n#### Check specific zpool for capacity issues\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -t zpool_capacity -pn ApolloZpoolOne -p 1-weuiK4YY7OUdukdiejsijeiYFe4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv \nOK - No Zpool capacity issues. ZPools examined: ApolloZpoolOne (75.8% used) - Root level datasets examined: ApolloZpoolOne\n```\n\n#### Check all zpools with custom warning level\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -t zpool_capacity -zw 30 -p 1-weuiK4YY7OUdukdiejsijeiYFe4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv \nWARNING - Pool ApolloZpoolOne usage 75.8% exceeds warning value of 30% - Pool ApolloZPoolEleven usage 64.0% exceeds warning value of 30%\n```\n\n#### Check all zpools with custom error level\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -t zpool_capacity -zc 40 -p 1-weuiK4YY7OUdukdiejsijeiYFe4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv \nCRITICAL - Pool ApolloZpoolOne usage 75.8% exceeds warning value of 40% - Pool ApolloZPoolEleven usage 64.0% exceeds critical value of 40%\n```\n\n#### Check specific zpool for capacity issues, adding on perf data as well\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -t zpool_capacity -pn ApolloZpoolOne -zp -p 1-weuiK4YY7OUdukdiejsijeiYFe4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv \nOK - No Zpool capacity issues. ZPools examined: ApolloZpoolOne (75.8% used) - Root level datasets examined: ApolloZpoolOne;| ApolloZpoolOne=294202.30MB;310479.52;155239.76;0;388099.40\n```\n\n## Check replication health\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local -u root -p RootPassy --type repl -nv\nOK - No replication errors. Replications examined:  ApolloDatasetReplications: FINISHED\n```\n\n## Check for TrueNAS updates\n\n#### Check for TrueNAS updates - no updates available\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local --type update -p 1-weuiK4YY7OUduhpzKISIJJIDIJSJ4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv\nOK - Update Status: UNAVAILABLE (no update available)\n```\n'UNAVAILABLE' is the normal update status, and does not indicate a problem.\n\n#### Check for TrueNAS updates - possible updates available\n```\ncheck_truenas_extended_play.py -H apollo.yourdomain.local --type update -p 1-weuiK4YY7OUduhpzKISIJJIDIJSJ4YgMwvea3dEhf3ITmoRRYZ3HBkDr2s1KZ1ft7M -nv\nWARNING - Update Status: AVAILABLE (an update is available). Update may be required. Go to TrueNAS Dashboard -\u003e System -\u003e Update to check for newer version.\n```\n\nAll update issues are merely warnings, and not critical errors.\n\nAs of 12/15/2021 there is an apparent issue with update checks when the ixsystems update servers are down, and the relevant API call crashes cryptically. I have filed a bug report with IX Systems:\n\nhttps://jira.ixsystems.com/browse/NAS-113833\n\n# Version History\n\n*June 18, 2020 - Version 1.0*\n\nInitial release. Script was not explicitly versioned - no version number displayed.\n\n*August 14, 2020 - Version 1.1*\n\nReplication check problems corrected. This check wasn't fully tested by author until this release.\n\n*December 3, 2021 - Version 1.2* \n\nAdded API Key authentication. Thanks to Folke Ashberg.\n\n*December 4, 2021 - Version 1.3* \n\nAdded update check, by request of @madtempest.\n\n*December 6, 2021 - Version 1.4*\n\nZPool capacity check added.\n\nThanks to both Folke Ashberg (@fashberg) and @Cosmits. Each made an independent pull request with a suggested implementation of the zpool capacity check feature, demonstrating a strong demand. It has been a bit involved to implement correctly, so if anyone sees free/used values for their ZPools that don't seem right, please let us know.\n\n*March 1, 2022 - Version 1.41*\n\nAdding well-intentioned but likely futile version check for Python 3.7 or greater. Clarifying in docs that Python 3.7 or greater is required.\n\n*January 30, 2023 - Version 1.42*\n\n@juleslink found a typo in a hardcoded byte count - \"1204\" instead of \"1024\" as it should have been. This caused incorrect byte math in capacity checks. Apologies for not seeing this earlier, and for any disruption this causes to your checks or metrics tracking!\n\n# Feedback Welcome\nIf you have a suggestion or encounter a problem, I encourage users to get in touch. I've found half-baked Nagios plugins to be a chore to deal with, and I'd like this not to be one of them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStewLG%2Fcheck_truenas_extended_play","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStewLG%2Fcheck_truenas_extended_play","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStewLG%2Fcheck_truenas_extended_play/lists"}