This article describes how to create a Perl based Custom Monitor on NetScaler.

Background

The NetScaler appliance has a lot of different monitors inbuilt, but there are use cases these monitors do not cover. For this NetScaler supports monitors of type USER, which brings the possibility to run external Perl scripts to track the health of a custom application or server. This article shows the steps you need to do before successfully running a custom monitor.

For an overview about Custom User Monitors refer to Citrix Documentation - https://docs.netscaler.com/en-us/citrix-adc/current-release/load-balancing/load-balancing-custom-monitors/understand-user-monitors.html

---

Instructions

Prerequisites

1. Log on to NetScaler via SSH and go into Shell.
2. A common problem is that the Perl interpreter does not recognize module. To solve this, we create a symbolic link to point on the located.
   1. mkdir /usr/local/lib/perl5/site_perl/mach/5.30/Netscaler
   2. ln -s /netscaler/monitors/perl_mod/Netscaler/usr/local/lib/perl5/site_perl/mach/5.30/Netscaler.
3. To make changes reboot persistent, we create a file /nsconfig/rc.netscaler (if it does not already exists) and insert commands used previously:
   1. touch /nsconfig/rc.netscaler
   2. chmod a+x rc.netscaler
   3. echo "mkdir /usr/local/lib/perl5/site_perl/mach/5.30/Netscaler" >> /nsconfig/rc.netscaler
   4. echo "ln -s /netscaler/monitors/perl_mod/Netscaler /usr/local/lib/perl5/site_perl/mach/5.30/Netscaler >> /nsconfig/rc.netscaler

 

Perl Script

This is a simple script example showing the requirements. Using the NetScaler KAS module and strict pragma are mandatory, other modules/libraries are optional.

We also need a sub doing the data processing with a response code of 0 (probe successful) or 1 (probe failed). Finally we need to register the sub to KAS.

#!/usr/bin/perl -w
################################################################
##
################################################################
 
use Netscaler::KAS;
use strict;
 
sub soap_probe {
 ## init variable with argument
 my $searchString = $ARGV[0];
 
 ## send request and collect response here
 my $response = "value";
 
 ## check response
 if (index($response, $searchString) != -1) {
  return(0);
 } else {
  return (1,"String not found");
 }
 
## register prob sub to the KAS module
probe(\&soap_probe);

Add Custom Monitor to NetScaler

Dispatcher IP and port must remain at 127.0.0.1:3013 for internal communication. Optional is the parameter "-scriptargs" which allows us to submit parameters like the backend server IP or any search pattern for the given response. In our Perl script we can select these parameters as typical command line arguments. The delimiter between multiple arguments is ";".

From NetScaler GUI

1. Add new monitor of type User under Traffic Management > Load Balancing > Monitors.
2. Set the Interval the script should run and the Response Time-out. This is the amount of time the script waits for a response before it gives up and marks the probe as failed.

   

3. Go into Special Parameters tab, upload and select the Perl script and define optional script arguments if required.

   

From NetScaler CLI

1. Upload the script with an SCP tool to /nsconfig/monitor/ directory.

   

2. Add the probe with the following command:
   add lb monitor lbm-custom USER -scriptName custom-probe.pl -dispatcherIP 127.0.0.1 -dispatcherPort 3013 -resptimeout 3

Debugging

To debug the script, you must run it by using the nsumon-debug.pl script, located in /netscaler/monitors/.

To the run this debug script you must enter the following arguments:
nsumon-debug.pl <scriptname> <IP> <port> <timeout> <partitionID> [scriptarguments] [is_secure]

Another possibility is to run the script with the Perl interpreter to check any errors:
root@cns1# perl custom-probe.pl test
1,String not found

This example shows a failed probe because the search string was not found in the response.