Private C APIs

This page describes the Monitoring Plugins routines that can be accessed from the internal library.

This page is in development, so these are not guaranteed to be available. As the API matures and is available in libraries, this information will be migrated to the Development Guidelines.

Basic Functions

np_init(char *plugin_name, int argc, char **argv)

Initialize the Monitoring Plugins routines. Pass the plugin name and argc and argv from main().

A variable nagios_plugin will be created for internal use.

np_set_args(int argc, char **argv)

Sets the internally held argc and argv values.

Shouldn't really need this, but due to np_extra_opts(), this is set after that call.

np_cleanup(void)

Used to clean up allocated memory by the nagios_plugin variable. This is called by the die() routine before exiting.

State Information

Saving and restoring state allows a plugin to know the last results and thus work out differences. This is especially useful when a plugin is capturing counter information, which increases with every request.

This currently works by saving state information to a file, though the API doesn't care what the backend implementation is.

Note: Binary data is not currently supported.

Some things to be aware of, if you use state information:

There will be problems if a remote host is checked from two different Nagios instances, as the state file on the remote host will be updated twice as often.
Binary data may not restore on a program compiled with different options from the program that saved it (e.g., 32 or 64 bit).
Binary data may include a structure containing a pointer. Pointer values may not be used in the reading program - i.e., you need to overwrite the value with something malloc(3)ed in the current run of the program.
State files could be left lying around. We recommend you run a regular job to remove unmodified state files older than 1 week.

np_enable_state(char *keyname, int data_version)

Enables the plugin state retention routines. Will set the filename for the state file to be .../{keyname}.

The keyname will have any non alphanumerics replaced with "_".

If keyname is NULL, will generate an SHA1 keyname based on the argv of the plugin (using the Extra-Opts parsed version, if applicable).

Note: The keyname should be uniquely defined for a particular service, to avoid a second invocation of the plugin to use the state information from a different invocation. If in doubt, set keyname=NULL and allow the routine to calculate the keyname.

np_state_read(void)

Reads the state file and returns a state_data variable.

This routine will call die() with UNKNOWN if:

There was a problem reading the state file.

Returns NULL if:

No state file exists - this is possible on the first run.
The state file format (internally held by the plugin) does not match.
The state data format (passed in np_enable_state()) does not match.

Your plugin should always check for NULL. It is recommended that your plugin returns OK on NULL as this is similar to a "first run".

If valid data was read, a pointer will be returned which points to a struct of:

typedef struct state_data_struct {
    time_t time;
    void *data;
    int length; /* Of binary data. */
} state_data;

np_state_write_string(time_t data_time, char *string)

If data_time==0, use current time. Creates state file, with state format version. Writes data version, time, and data. Creates a temporary file and then renames into place. There is a possible loss of data if two things writing to same key at same time, but there will not be a corrupted state file.

np_state_write_binary(time_t data_time, char *start, int length)

Same as np_state_write_string(), but writes binary data. Currently unimplemented.