A Nagios Plugin written for the Citrix NetScaler Application Delivery Controller. It's based on Perl (Monitoring::Plugin) and using the the NITRO REST API. No need for SNMP.
Currently the plugin has the following subcommands:
| command | description |
|---|---|
| state | check the current service state of vservers (e.g. lb, vpn, gslb), services and service groups and servers |
| matches, matches_not | check if a string matches the the api response or not |
| above, below | check if a value is above/below a threshold (e.g. traffic limits, concurrent connections) |
| sslcert | check the lifetime for installed ssl certificates |
| nsconfig | check for configuration changes which are not saved to disk |
| license | check the expiry date of a local installed license file |
| hastatus | check the high availability status of a appliance |
| staserver | check if configured STA (secure ticket authority) servers are available |
| servicegroup | check the state of a servicegroup and its members |
| hwinfo | just print information about the Netscaler itself |
| interfaces | check state of all interfaces and add performance data for each interface |
| perfdata | gather performancedata from all sorts of API endpoints |
| ntp | check the ntp synchronization status |
| debug | debug command, print all data for a endpoint |
This plugin works with VPX, MPX, SDX and CPX NetScaler Appliances. The api responses may differ by build, appliance type and your installed license.
The plugin supports performance data for the commands state and the above or below threshold checks. Also there is a perfdata command to gather information from your NetScaler.
Example configurations for Nagios and Icinga 2 can be found in the examples directory of this repository.
Feedback and feature requests are appreciated. Just create an issue on GitHub or send me a pull request.
If you looking for a plugin to test your NetScaler Gateway vServer and Storefront see also check_netscaler_gateway.
Run the following commands to install all Perl dependencies (Monitoring::Plugin, LWP, JSON, Time::Piece, Data::Dumper).
yum install perl-libwww-perl perl-JSON perl-Monitoring-Plugin perl-Time-Piece perl-Data-Dumper
If you want to connect to your NetScaler with SSL/HTTPS you should also install the LWP HTTPS package.
yum install perl-LWP-Protocol-https
apt-get install libwww-perl liblwp-protocol-https-perl libjson-perl libmonitoring-plugin-perl
The preinstalled Perl distribution is missing the JSON and Monitoring::Plugin libaries. The best way is to install them is trough the cpanminus tool. The cpanminus tool can be installed trough brew.
brew install cpanminus
Use the following commands to install the missing perl libaries.
sudo cpanm JSON
sudo cpanm Monitoring::Plugin
Usage: check_netscaler
-H|--hostname=<hostname> -C|--command=<command>
[ -o|--objecttype=<objecttype> ] [ -n|--objectname=<objectname> ]
[ -u|--username=<username> ] [ -p|--password=<password> ]
[ -s|--ssl ] [ -a|--api=<version> ] [ -P|--port=<port> ]
[ -e|--endpoint=<endpoint> ] [ -w|--warning=<warning> ] [ -c|--critical=<critical> ]
[ -v|--verbose ] [ -t|--timeout=<timeout> ] [ -x|--urlopts=<urlopts> ]
-?, --usage
Print usage information
-h, --help
Print detailed help screen
-V, --version
Print version information
--extra-opts=[section][@file]
Read options from an ini file. See https://www.monitoring-plugins.org/doc/extra-opts.html
for usage and examples.
-H, --hostname=STRING
Hostname of the NetScaler appliance to connect to
-u, --username=STRING
Username to log into box as (default: nsroot)
-p, --password=STRING
Password for login username (default: nsroot)
-s, --ssl
Establish connection to NetScaler using SSL
-P, --port=INTEGER
Establish connection to a alternate TCP Port
-C, --command=STRING
Check to be executed on the appliance
-o, --objecttype=STRING
Objecttype (target) to for the check command
-n, --objectname=STRING
Filter request to a specific objectname
-e, --endpoint=STRING
Override option for the API endpoint (stat or config)
-w, --warning=STRING
Value for warning
-c, --critical=STRING
Value for critical
-x, --urlopts=STRING
add additional url options
-a, --api=STRING
version of the NITRO API to use (default: v1)
-f, --filter=STRING
filter out objects from the API response (regular expression syntax)
-l, --limit=STRING
limit check to objects matching this pattern (regular expression syntax)
-L, --label=STRING
optional name of the field, which will be used as identifier when the response contians multiple items (default is to use the array index instead)
--seperator=STRING
optional seperator for perfdata values (see #47 for details)
-t, --timeout=INTEGER
Seconds before plugin times out (default: 15)
-v, --verbose
Show details for command-line debugging (can repeat up to 3 times)
# NetScaler::LBvServer
./check_netscaler.pl -H ${IPADDR} -s -C state -o lbvserver
# NetScaler::LBvServer::Website
./check_netscaler.pl -H ${IPADDR} -s -C state -o lbvserver -n vs_lb_http_webserver
# NetScaler::VPNvServer
./check_netscaler.pl -H ${IPADDR} -s -C state -o vpnvserver
# NetScaler::GSLBvServer
./check_netscaler.pl -H ${IPADDR} -s -C state -o gslbvserver
# NetScaler::AAAvServer
./check_netscaler.pl -H ${IPADDR} -s -C state -o authenticationvserver
# NetScaler::CSvServer
./check_netscaler.pl -H ${IPADDR} -s -C state -o csvserver
# NetScaler::SSLvServer (obsolet and replaced by lbvserver for newer builds)
./check_netscaler.pl -H ${IPADDR} -s -C state -o sslvserver
# NetScaler::Services
./check_netscaler.pl -H ${IPADDR} -s -C state -o service
# NetScaler::Services::Webserver
./check_netscaler.pl -H ${IPADDR} -s -C state -o service -n svc_webserver
# NetScaler::Servicegroups
./check_netscaler.pl -H ${IPADDR} -s -C state -o servicegroup
# NetScaler::Servicegroups::Webservers
./check_netscaler.pl -H ${IPADDR} -s -C state -o servicegroup -n sg_webservers
Define member quorum (in percent) with warning and critical values.
# NetScaler::Servicegroup::Webservers
./check_netscaler.pl -H ${IPADDR} -s -C servicegroup -n sg_webservers -w 75 -c 50
# NetScaler::Servers
./check_netscaler.pl -H ${IPADDR} -s -C state -o server
# NetScaler::Servers::web01.example.com
./check_netscaler.pl -H ${IPADDR} -s -C state -o server -n web01.example.com
Multiple fields need to be seperated by a colon.
# NetScaler::Memory
./check_netscaler.pl -H ${IPADDR} -s -C above -o system -n memusagepcnt -w 75 -c 80
# NetScaler::CPU
./check_netscaler.pl -H ${IPADDR} -s -C above -o system -n cpuusagepcnt,mgmtcpuusagepcnt -w 75 -c 80
# NetScaler::Disk
./check_netscaler.pl -H ${IPADDR} -s -C above -o system -n disk0perusage,disk1perusage -w 75 -c 80
# NetScaler::HA::Status
./check_netscaler.pl -H ${IPADDR} -s -C matches_not -o hanode -n hacurstatus -w YES -c YES
# NetScaler::HA::State
./check_netscaler.pl -H ${IPADDR} -s -C matches_not -o hanode -n hacurstate -w UP -c UP
# NetScaler::Certs
./check_netscaler.pl -H ${IPADDR} -s -C sslcert -w 30 -c 10
# NetScaler::Certs::Wildcard
./check_netscaler.pl -H ${IPADDR} -s -C sslcert -n wildcard.example.com -w 30 -c 10
# NetScaler::Config
./check_netscaler.pl -H ${IPADDR} -s -C nsconfig
The license file must be placed in /nsconfig/license. An optional filename could be passed via the objectname parameter. If no objectname is given, all installed license files will be checked.
The NITRO user needs permissions to access the filesystem directly (NITRO command systemfile). This could be achieved with the following command policy.
add system cmdPolicy nagios-license-check ALLOW "(^show\\s+system\\s+\\S+)|(^show\\s+system\\s+\\S+\\s+.*)"
Multiple license files can be passed, separated with a colon.
# NetScaler::License
./check_netscaler.pl -H ${IPADDR} -s -C license -n FID_4c9a2c7e_14292ea2df2_2a97.lic,FID_2b9a2c7e_14212ef2d27_4b87.lic -w 30 -c 10
# NetScaler::License::All
./check_netscaler.pl -H ${IPADDR} -s -C license -w 30 -c 10
# NetScaler::HA
./check_netscaler.pl -H ${IPADDR} -s -C hastatus
# NetScaler::STA
./check_netscaler.pl -H ${IPADDR} -s -C staserver
# NetScaler::STA::vs_vpn_gateway
./check_netscaler.pl -H ${IPADDR} -s -C staserver -n vs_vpn_gateway
# NetScaler::HWInfo
./check_netscaler.pl -H ${IPADDR} -s -C hwinfo
# NetScaler::Interfaces
./check_netscaler.pl -H ${IPADDR} -s -C interfaces
All fields must be defined via "-n" option and be seperated with a comma.
# NetScaler::Performancedata on Cache hit/misses
./check_netscaler.pl -H ${IPADDR} -s -C perfdata -o ns -n cachetothits,cachetotmisses
# NetScaler::Performancedata on tcp connections
./check_netscaler.pl -H ${IPADDR} -s -C perfdata -o ns -n tcpcurclientconn,tcpcurclientconnestablished,tcpcurserverconn,tcpcurserverconnestablished
# NetScaler::Performancedata on network interfaces
./check_netscaler.pl -H ${IPADDR} -s -C perfdata -o Interface -n id.totrxbytes
# NetScaler::Current user sessions
./check_netscaler.pl -H ${IPADDR} -s -C perfdata -o aaa -n aaacuricasessions,aaacuricaonlyconn
# find more object names to check out for object type "ns"
/check_netscaler.pl -H ${IPADDR} -s -C debug -o ns
Global counters can be accessed as follows (NetScaler 12.0 and newer).
./check_netscaler.pl -H ${IPADDR} -s -C perfdata -o nsglobalcntr -n http_tot_Requests,http_tot_Responses -x 'args=counters:http_tot_Requests;http_tot_Responses'
For more interesting performance data object types see the following API methods.
- ns
- cache
- protocolhttp
- protocolip
- protocoltcp
This is pretty much a reimplementation of check_ntp_peer. Output format and performance data should match to 99%. Also the behaviour of the warning and critical threshold checking got matched to check_ntp_peer. To avoid adding a couple of extra command line options the thresholds can be set with following options. Format: "option=value". They have to be comma separated.
- o -> offset
- s -> stratum
- j -> jitter
- t -> truechimers
# check NTP status
./check_netscaler.pl -H ${IPADDR} -s -C ntp -w o=0.03,j=100,s=1,t=3 -c o=0.05,j=200,s=2,t=2
This means:
- offset WARNING if peer offset is >= 30 ms or <= - 30 ms
- jitter WARNING if jitter is >= 100 ms
- stratum WARNING if peer stratum > 1
- truechimers WARNING if number of truechimers (possible sync sources) is <= 3
- offset CRITICAL if peer offset is >= 50 ms or <= - 50 ms
- jitter CRITICAL if jitter is >= 200 ms
- stratum CRITICAL if peer stratum > 2
- truechimers CRITICAL if number of truechimers (possible sync sources) is <= 2
Check all interfaces but ignore interface LO/1 and 0/1.
./check_netscaler.pl -H ${IPADDR} -C interfaces -f '(LO.1|0.1)'
Check only interface 0/2 and 0/3.
./check_netscaler.pl -H ${IPADDR} -C interfaces -l '(0.2|0.3)'
By default the array index will be used as perfdata label.
# default behavior - use the array index
./check_netscaler.pl -H ${IPADDR} -C perfdata -o Interface -n rxbytesrate
NetScaler OK - perfdata: Interface.rxbytesrate[0]: 1711; Interface.rxbytesrate[1]: 13915 | 'Interface.rxbytesrate[0]'=1711;; 'Interface.rxbytesrate[1]'=13915;;
This behavior can be changed with the label switch.
# set the label switch to 'id'
./check_netscaler.pl -H ${IPADDR} -C perfdata -o Interface -n rxbytesrate -L id
NetScaler OK - perfdata: Interface.rxbytesrate[0/1]: 1575; Interface.rxbytesrate[LO/1]: 12130 | 'Interface.rxbytesrate[0/1]'=1575;; 'Interface.rxbytesrate[LO/1]'=12130;;
By default the perfdata seperator is set to a dot (e.g. 0/1.txbytes'=492581B;;). This behavior can be changed with the --seperator switch.
./check_netscaler.pl -H ${IPADDR} -s -C interfaces --seperator='_'
- Set label to field
id - Limit response to regular expression
0.[0-9] - Filter out interface
0.2 - Use underline as perfdata seperator
./check_netscaler.pl -H ${IPADDR} -C perfdata -o Interface -n rxbytesrate -L id -l '0.[0-9]' -f '0.2' --seperator='_'
# Print all LB vServers (stat endpoint)
./check_netscaler.pl -H ${IPADDR} -s -C debug -o lbvserver
# Print all LB vServers (config endpoint)
./check_netscaler.pl -H ${IPADDR} -s -C debug -o lbvserver -e config
The plugin uses the Monitoring::Plugin Libary, so you can use --extra-opts and seperate the login crendetials from your nagios configuration.
define command {
command_name check_netscaler_vserver
command_line $USER5$/3rdparty/check_netscaler/check_netscaler.pl -H $HOSTADDRESS$ -s --extra-opts=netscaler@$USER11$/plugins.ini -C state -n '$ARG1$'
}
[netscaler]
hostname=netscaler01
username=nagios
password=password
ssl=true
If you do not want to install all dependencies on your machine you can build a static standalone binary of this plugin via the Perl Archive Toolkit (PAR). A Makefile for doing so is provided in the projects root folder.
yum install -y epel-release
yum install -y perl-libwww-perl perl-JSON perl-Monitoring-Plugin perl-Time-Piece perl-Data-Dumper perl-LWP-Protocol-https
yum install -y perl-PAR perl-PAR-Dist perl-PAR-Packer make
make
Using the plugin via PAR is not yet widely tested in production setups. Feedback is appreciated.
You will find a full documentation about the NITRO API on your NetScaler Appliance in the "Download" area.
http://NSIP/nitro-rest.tgz (where NSIP is the IP address of your NetScaler appliance).
Tested with NetScaler 10.5, 11.0, 11.1, 12.0, 12.1 and 13.0. The plugin should work with all available firmware builds.
Every commit and pull request in this repository will trigger a continuous integration test with Travis CI. The test starts a NetScaler CPX instance (currently build 12.0-56.20) and runs tests/travis_test.sh against the container.
Please add tests if you add new commands to this plugin. Be aware that a NetScaler CPX is very limited in it's features and not all checks of this plugin will work against a CPX instance (e.g. hwinfo, ntp, ...).
See CHANGELOG