V11.5 Update Guide

DISK_FULL_ACTION (SUBSYSTEM)

FairCom Server supports a configuration option to call an external script when a specified DISK_FULL_LIMIT or DISK_FULL_VOLUME limit is reached. This allows server administrator to configure an external process to run when a disk-full limit is reached, for example, the process could write information to a log or notify the administrator.

To configure an external process to run when the space on the specified volume is below the specified limit, set the DISK_FULL_ACTION configuration option in ctsrvr.cfg with the run action.

The supported syntax is:

SUBSYSTEM EVENT DISK_FULL_ACTION {

volume VOLUME

limit LIMIT

run EXE [OPTIONS]

freq FREQUENCY

maxruntime MAXRUNTIME

}

The volume, limit, and run parameters are required. The freq and maxruntime are optional.

• VOLUME is the name of the disk volume to check: a drive name (for example, C:\) on Windows systems, or a directory name (for example, /users/faircom/data) on Unix/Linux systems.
• LIMIT is the threshold of available space that triggers the running of the script. The KB, MB, GB, TB, and PB suffixes can be used for this value (for example: "limit 100 GB" means 100 gigabytes).
• EXE is the name of an executable, batch file, or Unix shell script to run, and OPTIONS are optional command-line options to pass to the external program.
• FREQUENCY indicates the frequency at which this condition is checked. The default is to check the condition every 60 seconds. Minimum frequency is 1; maximum frequency is 32,000,000.
• MAXRUNTIME indicates the maximum amount of time, in seconds, that the external script is permitted to run. If the external script has not terminated after the specified amount of time, the server terminates the script. The default is 60 seconds. A setting of 0 means the script will never be forced to terminate.

  Note: When setting a MAXRUNTIME value, consider that no other DISK_FULL_ACTION checks will take place until the script completes, regardless of the FREQ setting. This is of particular importance if more than one DISK_FULL_ACTION is created.

In V12 and later, disk full monitoring keywords have been added to the default ctsrvr.cfg. These keywords are present in this config file, but they have been commented out for so they are there if you need them, but they are NOT enabled.

; SUBSYSTEM EVENT DISK_FULL_ACTION {

volume VOLUME

limit LIMIT

run EXE [OPTIONS]

freq FREQUENCY

maxruntime MAXRUNTIME

}

Example DISK_FULL_ACTION with external process action

The following configuration option causes the batch file diskfull.bat to be run when writing to a c-tree data or index file detects that the space on C:\ has dropped below 1 GB. This disk-full condition is checked once every 60 seconds.

SUBSYSTEM EVENT DISK_FULL_ACTION {

volume C:\

limit 1 GB

run diskfull.bat

freq 60

maxruntime 120

}

Reading parameters sent from the server to the external process

FairCom Server passes a set of ASCII key/value pairs to the external process using standard input, where the input format is key=value, one per line. The keys that FairCom Server passes to the external process are:

• volume - The VOLUME setting from the DISK_FULL_ACTION configuration option.
• limit - The disk-full limit in bytes that was specified for that volume.
• available - The amount of disk space in bytes that is currently available on that volume.

Writing parameters from the external process to the server

The external process can optionally pass ASCII key/value pairs back to the server by writing them to standard output in the format key=value, one entry per line. FairCom Server recognizes the following keys:

• action=continue - (indicating to continue FairCom Server operation; this is the default)

  or

• action=shutdown - (indicating to shut down FairCom Server)
• comments=MESSAGE - A user-defined message that will be written to CTSTATUS.FCS.

Note: FairCom Server reads only the first 1024 bytes of the output data returned by the script. All data after the first 1024 bytes of output data is ignored.

If the external script's output is not in the supported format, a message is written to CTSTATUS.FCS. Example:

DISK_FULL_ACTION: Command diskfull.bat output does not match format var=value: line 3 column 8

Unlimited MAXRUNTIME script

An unlimited script runtime can be set with MAXRUNTIME 0. When configured as unlimited and a script is run due to the LIMIT and RUN options, the script will never be forced to terminate.

Note: When setting a MAXRUNTIME value, consider that no other DISK_FULL_ACTION checks will take place until the script completes, regardless of the FREQ setting. This is of particular importance if more than one DISK_FULL_ACTION is created.