--- name: "Monitoring::Plugin::Getopt" section: "3pm" platform: "linux" package: "libmonitoring-plugin-perl" version: "0.40-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Monitoring::Plugin::Getopt" --- # Monitoring::Plugin::Getopt(3pm) OO perl module providing standardised argument processing for Nagios plugins ## NAME Monitoring::Plugin::Getopt - OO perl module providing standardised argument processing for Nagios plugins ## SYNOPSIS ``` use Monitoring::Plugin::Getopt; # Instantiate object (usage is mandatory) $ng = Monitoring::Plugin::Getopt->new( usage => "Usage: %s -H -w -c ", version => '0.1', url => 'http://www.openfusion.com.au/labs/nagios/', blurb => 'This plugin tests various stuff.', ); # Add argument - named parameters (spec and help are mandatory) $ng->arg( spec => 'critical|c=i', help => q(Exit with CRITICAL status if fewer than INTEGER foobars are free), required => 1, default => 10, ); # Add argument - positional parameters - arg spec, help text, # default value, required? (first two mandatory) $ng->arg( 'warning|w=i', q(Exit with WARNING status if fewer than INTEGER foobars are free), 5, 1); # Parse arguments and process standard ones (e.g. usage, help, version) $ng->getopts; # Access arguments using named accessors or or via the generic get() print $ng->opts->warning; print $ng->opts->get('critical'); ``` ## DESCRIPTION Monitoring::Plugin::Getopt is an OO perl module providing standardised and simplified argument processing for Nagios plugins. It implements a number of standard arguments itself (--help, --version, --usage, --timeout, --verbose, and their short form counterparts), produces standardised nagios plugin help output, and allows additional arguments to be easily defined. ### CONSTRUCTOR ``` # Instantiate object (usage is mandatory) $ng = Monitoring::Plugin::Getopt->new( usage => 'Usage: %s --hello', version => '0.01', ); ``` The Monitoring::Plugin::Getopt constructor accepts the following named arguments: - usage (required) Short usage message used with --usage/-? and with missing required arguments, and included in the longer --help output. Can include a '%s' sprintf placeholder which will be replaced with the plugin name e.g. ``` usage => qq(Usage: %s -H -p [-v]), ``` might be displayed as: ``` $ ./check_tcp_range --usage Usage: check_tcp_range -H -p [-v] ``` - version (required) Plugin version number, included in the --version/-V output, and in the longer --help output. e.g. ``` $ ./check_tcp_range --version check_tcp_range 0.2 [http://www.openfusion.com.au/labs/nagios/] ``` - url URL for info about this plugin, included in the --version/-V output, and in the longer --help output (see preceding 'version' example). - blurb Short plugin description, included in the longer --help output (see below for an example). - license License text, included in the longer --help output (see below for an example). By default, this is set to the standard nagios plugins GPL license text: ``` This nagios plugin is free software, and comes with ABSOLUTELY NO WARRANTY. It may be used, redistributed and/or modified under the terms of the GNU General Public Licence (see http://www.fsf.org/licensing/licenses/gpl.txt). ``` Provide your own to replace this text in the help output. - extra Extra text to be appended at the end of the longer --help output. - plugin Plugin name. This defaults to the basename of your plugin, which is usually correct, but you can set it explicitly if not. - timeout Timeout period in seconds, overriding the standard timeout default (15 seconds). The full --help output has the following form: ``` version string license string blurb usage string options list extra text ``` The 'blurb' and 'extra text' sections are omitted if not supplied. For example: ``` $ ./check_tcp_range -h check_tcp_range 0.2 [http://www.openfusion.com.au/labs/nagios/] This nagios plugin is free software, and comes with ABSOLUTELY NO WARRANTY. It may be used, redistributed and/or modified under the terms of the GNU General Public Licence (see http://www.fsf.org/licensing/licenses/gpl.txt). This plugin tests arbitrary ranges/sets of tcp ports for a host. Usage: check_tcp_range -H -p [-v] Options: -h, --help Print detailed help screen -V, --version Print version information -H, --hostname=ADDRESS Host name or IP address -p, --ports=STRING Port numbers to check. Format: comma-separated, colons for ranges, no spaces e.g. 8700:8705,8710:8715,8760 -t, --timeout=INTEGER Seconds before plugin times out (default: 15) -v, --verbose Show details for command-line debugging (can repeat up to 3 times) ``` ### ARGUMENTS You can define arguments for your plugin using the *arg()* method, which supports both named and positional arguments. In both cases the `"spec"` and `"help"` arguments are required, while the `"label"`, `"default"`, and `"required"` arguments are optional: ``` # Define --hello argument (named parameters) $ng->arg( spec => 'hello|h=s', help => "Hello string", required => 1, ); # Define --hello argument (positional parameters) # Parameter order is 'spec', 'help', 'default', 'required?', 'label' $ng->arg('hello|h=s', "Hello parameter (default %s)", 5, 1); ``` - spec The `"spec"` argument (the first argument in the positional variant) is a Getopt::Long argument specification. See Getopt::Long for the details, but basically it is a series of one or more argument names for this argument (separated by '\|'), suffixed with an '=\' indicator if the argument takes a value. '=s' indicates a string argument; '=i' indicates an integer argument; appending an '@' indicates multiple such arguments are accepted; appending an '!' indicates negation using '--no'-prefix is possible; and so on. The following are some examples: - hello=s - hello\|h=s - ports\|port\|p=i - exclude\|X=s@ - perfdata! - verbose\|v+ - help The `"help"` argument is a string displayed in the --help option list output, or it can be a list (an arrayref) of such strings, for multi-line help (see below). The help string is munged in two ways: - • First, if the help string does NOT begins with a '-' sign, it is prefixed by an expanded form of the `"spec"` argument. For instance, the following hello argument: ``` $ng->arg( spec => 'hello|h=s', help => "Hello string", ); ``` would be displayed in the help output as: ``` -h, --hello=STRING Hello string ``` where the '-h, --hello=STRING' part is derived from the spec definition (by convention with short args first, then long, then label/type, if any). - • Second, if the string contains a '%s' it will be formatted via `"sprintf"` with the 'default' as the argument i.e. ``` sprintf($help, $default) ``` Multi-line help is useful in cases where an argument can be of different types and you want to make this explicit in your help output e.g. ``` $ng->arg( spec => 'warning|w=s', help => [ 'Exit with WARNING status if less than BYTES bytes of disk are free', 'Exit with WARNING status if less than PERCENT of disk is free', ], label => [ 'BYTES', 'PERCENT%' ], ); ``` would be displayed in the help output as: ``` -w, --warning=BYTES Exit with WARNING status if less than BYTES bytes of disk are free -w, --warning=PERCENT% Exit with WARNING status if less than PERCENT of disk space is free ``` Note that in this case we've also specified explicit labels in another arrayref corresponding to the `"help"` one - if this had been omitted the types would have defaulted to 'STRING', instead of 'BYTES' and 'PERCENT%'. - label The `"label"` argument is a scalar or an arrayref (see 'Multi-line help' description above) that overrides the standard type expansion when generating help text from the spec definition. By default, `"spec=i"` arguments are labelled as `"=INTEGER"` in the help text, and `"spec=s"` arguments are labelled as `"=STRING"`. By supplying your own `"label"` argument you can override these standard 'INTEGER' and 'STRING' designations. For multi-line help, you can supply an ordered list (arrayref) of labels to match the list of help strings e.g. ``` label => [ 'BYTES', 'PERCENT%' ] ``` Any labels that are left as undef (or just omitted, if trailing) will just use the default 'INTEGER' or 'STRING' designations e.g. ``` label => [ undef, 'PERCENT%' ] ``` - default The `"default"` argument is the default value to be given to this parameter if none is explicitly supplied. - required The `"required"` argument is a boolean used to indicate that this argument is mandatory (Monitoring::Plugin::Getopt will exit with your usage message and a 'Missing argument' indicator if any required arguments are not supplied). Note that --help lists your arguments in the order they are defined, so you should order your `"arg()"` calls accordingly. ### GETOPTS The main parsing and processing functionality is provided by the *getopts()* method, which takes no arguments: ``` # Parse and process arguments $ng->getopts; ``` This parses the command line arguments passed to your plugin using Getopt::Long and the builtin and provided argument specifications. Flags and argument values are recorded within the object, and can be accessed either using the generic *get()* accessor, or using named accessors corresponding to your argument names. For example: ``` print $ng->get('hello'); print $ng->hello(); if ($ng->verbose) { # ... } if ($ng->get('ports') =~ m/:/) { # ... } ``` Note that where you have defined alternate argument names, the first is considered the citation form. All the builtin arguments are available using their long variant names. ### BUILTIN PROCESSING The `"getopts()"` method also handles processing of the immediate builtin arguments, namely --usage, --version, --help, as well as checking all required arguments have been supplied, so you don't have to handle those yourself. This means that your plugin will exit from the *getopts()* call in these cases - if you want to catch that you can run *getopts()* within an eval{}. `"getopts()"` also sets up a default ALRM timeout handler so you can use an ``` alarm $ng->timeout; ``` around any blocking operations within your plugin (which you are free to override if you want to use a custom timeout message). ## SEE ALSO Monitoring::Plugin, Getopt::Long ## AUTHOR This code is maintained by the Monitoring Plugin Development Team: see https://monitoring-plugins.org Originally:\ Gavin Carr \ ## COPYRIGHT AND LICENSE Copyright (C) 2014 by Monitoring Plugin Team Copyright (C) 2006-2014 by Nagios Plugin Development Team This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.