Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

Understand user monitors

August 11, 2023
Contributed by: 
C S

User monitors extend the scope of custom monitors. You can create user monitors to track the health of customized applications and protocols that the Citrix ADC appliance does not support. The following diagram illustrates how a user monitor works.

Figure 1. User Monitors

User-monitor

A user monitor requires the following components.

  • Dispatcher. A process, on the appliance, that listens to monitoring requests. A dispatcher can be on the loopback IP address (127.0.0.1) and port 3013. Dispatchers are also known as internal dispatchers. A dispatcher can also be a web server that supports the Common Gateway Interface (CGI). Such dispatchers are also known as external dispatchers. They are used for custom scripts that do not run on the FreeBSD environment, such as .NET scripts.

Note:

You can configure the monitor and the dispatcher to use HTTPS instead of HTTP by enabling the “secure” option on the monitor, and configure it as an external dispatcher. However, an internal dispatcher understands only HTTP, and cannot use HTTPS.

In a HA setup, the dispatcher runs on both the primary and secondary Citrix ADC appliances. The dispatcher remains inactive on the secondary appliance.

Script. The script is a program that sends custom probes to the load balanced server and returns the response code to the dispatcher. The script can return any value to the dispatcher, but if a probe succeeds, the script must return a value of zero (0). The dispatcher considers any other value as probe failure.

The Citrix ADC appliance is bundled with sample scripts for commonly used protocols. The scripts exist in the /nsconfig/monitors directory. If you want to add a script, add it there. To customize an existing script, create a copy with a new name and modify it.

Important:

  • Starting with Citrix ADC release 13.0 build 41.20, you can use the nsntlm-lwp.pl script to create a monitor for monitoring a secure NTLM server.

  • Starting with release 10.1 build 122.17, the script files for user monitors are in a new location.

    If you upgrade an MPX or VPX virtual appliance to release 10.1 build 122.17 or later, the changes are as follows:

    • A new directory named conflicts is created in /nsconfig/monitors/ and all the built-in scripts of the previous builds are moved to this directory.
    • All new built-in scripts are available in the /netscaler/monitors/ directory. All custom scripts are available in the /nsconfig/monitors/ directory.
    • Save a new custom script in the /nsconfig/monitors/ directory.
    • After the upgrade is completed, if a custom script is created and saved in the /nsconfig/monitors/ directory, with the same name as the built-in script, the script in the /netscaler/monitors/ directory takes priority. The custom script does not run.

    If you provision a virtual appliance with release 10.1 build 122.17 or later, the changes are as follows:

    • All built-in scripts are available in the /netscaler/monitors/ directory.
    • The /nsconfig/monitors/ directory is empty.
    • If you create a custom script, you must save it in the /nsconfig/monitors/ directory.

For the scripts to function correctly:

  • The maximum number of characters in the name of the script must not exceed 63.
  • The maximum number of script arguments that can be provided to a script must not exceed 512.
  • The maximum number of characters that can be provided in the parameter script arguments must not exceed 639.

To debug the script, you must run it by using the nsumon-debug.pl script from the CLI. You use the script name (with its arguments), IP address, and the port as the arguments of the nsumon-debug.pl script. Users must use the script name, IP address, port, time-out, and the script arguments for the nsumon-debug.pl script.

At the CLI, type:

nsumon-debug.pl <scriptname> <IP> <port> <timeout> <partitionID> [scriptarguments][is_secure]
<!--NeedCopy-->

Important: Starting with release 10.5 build 57.x, and 11.0 script files for user monitors support IPv6 addresses and include the following changes:

  • For the following protocols, new pm files have been included for IPv6 support.

    • RADIUS
    • NNTP
    • POP3
    • SMTP

  • The following sample scripts in /netscaler/monitors/ has been updated for IPv6 support:

    • nsbmradius.pl

    • nsldap.pl

    • nsnntp.pl

    • nspop3 nssf.pl

    • nssnmp.pl

    • nswi.pl

    • nstftp.pl

    • nssmtp.pl

    • nsrdp.pl

    • nsntlm-lwp.pl

    • nsftp.pl

    • nsappc.pl

    After upgrading to release 10.5 build 57.x, or 11.0, if you want to use your existing custom scripts with IPv6 services, make sure that you update the existing custom scripts with the changes provided in the updated sample scripts in /netscaler/monitors/.

Note:

The sample script nsmysql.pl does not support the IPv6 address. If an IPv6 service is bound to a user monitor that uses nsmysql.pl, the probe fails.

  • The following LB monitor types have been updated to support IPv6 addresses:

    • USER

    • SMTP

    • NNTP

    • LDAP

    • SNMP

    • POP3

    • FTP_EXTENDED

    • StoreFront

    • APPC

    • CITRIX_WI_EXTENDED

    If you are creating a custom script that uses one of these LB monitors types, ensure to include IPv6 support in the custom script. Refer to the associated sample script in /netscaler/monitors/ for the changes that you have to make in the custom script for IPv6 support.

To track the status of the server, the monitor sends an HTTP POST request to the configured dispatcher. This POST request contains the IP address and port of the server, and the script that must be run. The dispatcher runs the script as a child process, with user-defined parameters (if any). Then, the script sends a probe to the server. The script sends the status of the probe (response code) to the dispatcher. The dispatcher converts the response code to an HTTP response and sends it to the monitor. Based on the HTTP response, the monitor marks the service as up or down.

The Citrix ADC appliance logs the error messages to the /var/nslog/nsumond.log file when user monitor probes fail. These detailed error messages are displayed in the GUI, and in the CLI for the show service/service group commands.

The following table lists the user monitors and the possible reasons for failure.

User monitor type Probe failure reasons
SMTP Monitor fails to establish a connection to the server.
NNTP Monitor fails to establish a connection to the server.
  Missing or invalid script arguments, which can include an invalid number of arguments or argument format.
  Monitor fails to find the NNTP group.
LDAP Monitor fails to establish a connection to the server.
  Missing or invalid script arguments, which can include an invalid number of arguments or argument format.
  Monitor fails to bind to the LDAP server.
  Monitor fails to locate an entry for the target entity in the LDAP server.
FTP The connection to the server times out.
  Missing or invalid script arguments, which can include an invalid number of arguments or argument format.
  Logon fails.
  Monitor fails to find the file on the server.
POP3 Monitor fails to establish a connection to the database.
  Missing or invalid script arguments, which can include an invalid number of arguments or argument format.
  Logon fails.
  Preparation of the SQL query fails.
  Execution of the SQL query fails.
SNMP Monitor fails to establish a connection to the database.
  Missing or invalid script arguments, which can include an invalid number of arguments or argument format.
  Logon fails.
  Monitor fails to create the SNMP session.
  Monitor fails to find the object identifier.
  The monitor threshold value setting is greater than or equal to the actual threshold of the monitor.
RDP (Windows Terminal Server) Missing or invalid script arguments, which can include an invalid number of arguments or argument format.
  Monitor fails to create a socket.
  Mismatch in versions.
  Monitor fails to confirm connection.

You can view the log file from the CLI by using the following commands:

> shell
root@ns# cat /var/nslog/nsumond.log
root@ns# exit
>
<!--NeedCopy-->

The command opens a BSD shell, displays the log file on the screen, closes the BSD shell, and returns you to the CLI.

Before Citrix ADC release 13.0 build 52.X, the show service/service group command displayed a generic error message saying “probe failed” as the cause for the user monitor probe failure.

Example:

show service ftp

Monitor Name: mon2
State: UNKNOWN  Weight: 1   Passive: 0
Probes: 3    Failed [Total: 0 Current: 0]
Last response: Failure - Probe failed.
Response Time: 1071.838 millisec
<!--NeedCopy-->

From Citrix ADC release 13.0 build 52.X onwards, the show service/service group command displays the actual cause for the user monitor probe failure.

Example:

show service ftp

Monitor Name: mon2
State: DOWN   Weight: 1   Passive: 0
Probes: 729   Failed [Total: 726 Current: 726]
Last response: Failure - Login failed.
Response Time: 8000.0 millisec
<!--NeedCopy-->

User monitors also have a time-out value and a retry count for probe failures. You can use user monitors with non-user monitors. During high CPU utilization, a non-user monitor enables faster detection of a server failure.

If the user monitor probe times out during high CPU usage, the state of the service remains unchanged.

Example1:

add lb monitor <name> USER –scriptname <script-name> -resptimeout 5 seconds
<!--NeedCopy-->

Note:

For scriptable monitors, the response timeout must be configured to a value equal to the expected timeout + 1 second. For example, if you expect the timeout to be 4 seconds, configure the response timeout as 5 seconds.

Example2:

add lb monitor <name> USER –scriptname <script-name> -scriptargs <Arguments> -secureargs <Arguments>
<!--NeedCopy-->

Note:

We recommend that you use the secureargs parameter instead of the scriptargs parameter for any sensitive data that is related to the scripts.

Understand user monitors
August 11, 2023
Contributed by: 
C S
August 11, 2023
Contributed by: 
C S

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.