1Monitoring::Plugin::GetUospetr(3C)ontributed Perl DocumeMnotnaittioorning::Plugin::Getopt(3)
2
3
4

NAME

6       Monitoring::Plugin::Getopt - OO perl module providing standardised
7       argument processing for Nagios plugins
8

SYNOPSIS

10         use Monitoring::Plugin::Getopt;
11
12         # Instantiate object (usage is mandatory)
13         $ng = Monitoring::Plugin::Getopt->new(
14           usage => "Usage: %s -H <host> -w <warning> -c <critical>",
15           version => '0.1',
16           url => 'http://www.openfusion.com.au/labs/nagios/',
17           blurb => 'This plugin tests various stuff.',
18         );
19
20         # Add argument - named parameters (spec and help are mandatory)
21         $ng->arg(
22           spec => 'critical|c=i',
23           help => q(Exit with CRITICAL status if fewer than INTEGER foobars are free),
24           required => 1,
25           default => 10,
26         );
27
28         # Add argument - positional parameters - arg spec, help text,
29         #   default value, required? (first two mandatory)
30         $ng->arg(
31           'warning|w=i',
32           q(Exit with WARNING status if fewer than INTEGER foobars are free),
33           5,
34           1);
35
36         # Parse arguments and process standard ones (e.g. usage, help, version)
37         $ng->getopts;
38
39         # Access arguments using named accessors or or via the generic get()
40         print $ng->opts->warning;
41         print $ng->opts->get('critical');
42

DESCRIPTION

44       Monitoring::Plugin::Getopt is an OO perl module providing standardised
45       and simplified argument processing for Nagios plugins. It implements a
46       number of standard arguments itself (--help, --version, --usage,
47       --timeout, --verbose, and their short form counterparts), produces
48       standardised nagios plugin help output, and allows additional arguments
49       to be easily defined.
50
51   CONSTRUCTOR
52         # Instantiate object (usage is mandatory)
53         $ng = Monitoring::Plugin::Getopt->new(
54           usage => 'Usage: %s --hello',
55           version => '0.01',
56         );
57
58       The Monitoring::Plugin::Getopt constructor accepts the following named
59       arguments:
60
61       usage (required)
62           Short usage message used with --usage/-? and with missing required
63           arguments, and included in the longer --help output. Can include a
64           '%s' sprintf placeholder which will be replaced with the plugin
65           name e.g.
66
67             usage => qq(Usage: %s -H <hostname> -p <ports> [-v]),
68
69           might be displayed as:
70
71             $ ./check_tcp_range --usage
72             Usage: check_tcp_range -H <hostname> -p <ports> [-v]
73
74       version (required)
75           Plugin version number, included in the --version/-V output, and in
76           the longer --help output. e.g.
77
78             $ ./check_tcp_range --version
79             check_tcp_range 0.2 [http://www.openfusion.com.au/labs/nagios/]
80
81       url URL for info about this plugin, included in the --version/-V
82           output, and in the longer --help output (see preceding 'version'
83           example).
84
85       blurb
86           Short plugin description, included in the longer --help output (see
87           below for an example).
88
89       license
90           License text, included in the longer --help output (see below for
91           an example). By default, this is set to the standard nagios plugins
92           GPL license text:
93
94             This nagios plugin is free software, and comes with ABSOLUTELY
95             NO WARRANTY. It may be used, redistributed and/or modified under
96             the terms of the GNU General Public Licence (see
97             http://www.fsf.org/licensing/licenses/gpl.txt).
98
99           Provide your own to replace this text in the help output.
100
101       extra
102           Extra text to be appended at the end of the longer --help output.
103
104       plugin
105           Plugin name. This defaults to the basename of your plugin, which is
106           usually correct, but you can set it explicitly if not.
107
108       timeout
109           Timeout period in seconds, overriding the standard timeout default
110           (15 seconds).
111
112       The full --help output has the following form:
113
114         version string
115
116         license string
117
118         blurb
119
120         usage string
121
122         options list
123
124         extra text
125
126       The 'blurb' and 'extra text' sections are omitted if not supplied. For
127       example:
128
129         $ ./check_tcp_range -h
130         check_tcp_range 0.2 [http://www.openfusion.com.au/labs/nagios/]
131
132         This nagios plugin is free software, and comes with ABSOLUTELY NO WARRANTY.
133         It may be used, redistributed and/or modified under the terms of the GNU
134         General Public Licence (see http://www.fsf.org/licensing/licenses/gpl.txt).
135
136         This plugin tests arbitrary ranges/sets of tcp ports for a host.
137
138         Usage: check_tcp_range -H <hostname> -p <ports> [-v]
139
140         Options:
141          -h, --help
142            Print detailed help screen
143          -V, --version
144            Print version information
145          -H, --hostname=ADDRESS
146            Host name or IP address
147          -p, --ports=STRING
148            Port numbers to check. Format: comma-separated, colons for ranges,
149            no spaces e.g. 8700:8705,8710:8715,8760
150          -t, --timeout=INTEGER
151            Seconds before plugin times out (default: 15)
152          -v, --verbose
153            Show details for command-line debugging (can repeat up to 3 times)
154
155   ARGUMENTS
156       You can define arguments for your plugin using the arg() method, which
157       supports both named and positional arguments. In both cases the "spec"
158       and "help" arguments are required, while the "label", "default", and
159       "required" arguments are optional:
160
161         # Define --hello argument (named parameters)
162         $ng->arg(
163           spec => 'hello|h=s',
164           help => "Hello string",
165           required => 1,
166         );
167
168         # Define --hello argument (positional parameters)
169         #   Parameter order is 'spec', 'help', 'default', 'required?', 'label'
170         $ng->arg('hello|h=s', "Hello parameter (default %s)", 5, 1);
171
172       spec
173           The "spec" argument (the first argument in the positional variant)
174           is a Getopt::Long argument specification. See Getopt::Long for the
175           details, but basically it is a series of one or more argument names
176           for this argument (separated by '|'), suffixed with an '=<type>'
177           indicator if the argument takes a value. '=s' indicates a string
178           argument; '=i' indicates an integer argument; appending an '@'
179           indicates multiple such arguments are accepted; appending an '!'
180           indicates negation using '--no'-prefix is possible; and so on.  The
181           following are some examples:
182
183           hello=s
184           hello|h=s
185           ports|port|p=i
186           exclude|X=s@
187           perfdata!
188           verbose|v+
189       help
190           The "help" argument is a string displayed in the --help option list
191           output, or it can be a list (an arrayref) of such strings, for
192           multi-line help (see below).
193
194           The help string is munged in two ways:
195
196           •   First, if the help string does NOT begins with a '-' sign, it
197               is prefixed by an expanded form of the "spec" argument. For
198               instance, the following hello argument:
199
200                 $ng->arg(
201                   spec => 'hello|h=s',
202                   help => "Hello string",
203                 );
204
205               would be displayed in the help output as:
206
207                 -h, --hello=STRING
208                   Hello string
209
210               where the '-h, --hello=STRING' part is derived from the spec
211               definition (by convention with short args first, then long,
212               then label/type, if any).
213
214           •   Second, if the string contains a '%s' it will be formatted via
215               "sprintf" with the 'default' as the argument i.e.
216
217                 sprintf($help, $default)
218
219           Multi-line help is useful in cases where an argument can be of
220           different types and you want to make this explicit in your help
221           output e.g.
222
223             $ng->arg(
224               spec => 'warning|w=s',
225               help => [
226                 'Exit with WARNING status if less than BYTES bytes of disk are free',
227                 'Exit with WARNING status if less than PERCENT of disk is free',
228               ],
229               label => [ 'BYTES', 'PERCENT%' ],
230             );
231
232           would be displayed in the help output as:
233
234            -w, --warning=BYTES
235               Exit with WARNING status if less than BYTES bytes of disk are free
236            -w, --warning=PERCENT%
237               Exit with WARNING status if less than PERCENT of disk space is free
238
239           Note that in this case we've also specified explicit labels in
240           another arrayref corresponding to the "help" one - if this had been
241           omitted the types would have defaulted to 'STRING', instead of
242           'BYTES' and 'PERCENT%'.
243
244       label
245           The "label" argument is a scalar or an arrayref (see 'Multi-line
246           help' description above) that overrides the standard type expansion
247           when generating help text from the spec definition. By default,
248           "spec=i" arguments are labelled as "=INTEGER" in the help text, and
249           "spec=s" arguments are labelled as "=STRING". By supplying your own
250           "label" argument you can override these standard 'INTEGER' and
251           'STRING' designations.
252
253           For multi-line help, you can supply an ordered list (arrayref) of
254           labels to match the list of help strings e.g.
255
256             label => [ 'BYTES', 'PERCENT%' ]
257
258           Any labels that are left as undef (or just omitted, if trailing)
259           will just use the default 'INTEGER' or 'STRING' designations e.g.
260
261             label => [ undef, 'PERCENT%' ]
262
263       default
264           The "default" argument is the default value to be given to this
265           parameter if none is explicitly supplied.
266
267       required
268           The "required" argument is a boolean used to indicate that this
269           argument is mandatory (Monitoring::Plugin::Getopt will exit with
270           your usage message and a 'Missing argument' indicator if any
271           required arguments are not supplied).
272
273       Note that --help lists your arguments in the order they are defined, so
274       you should order your arg() calls accordingly.
275
276   GETOPTS
277       The main parsing and processing functionality is provided by the
278       getopts() method, which takes no arguments:
279
280         # Parse and process arguments
281         $ng->getopts;
282
283       This parses the command line arguments passed to your plugin using
284       Getopt::Long and the builtin and provided argument specifications.
285       Flags and argument values are recorded within the object, and can be
286       accessed either using the generic get() accessor, or using named
287       accessors corresponding to your argument names. For example:
288
289         print $ng->get('hello');
290         print $ng->hello();
291
292         if ($ng->verbose) {
293           # ...
294         }
295
296         if ($ng->get('ports') =~ m/:/) {
297           # ...
298         }
299
300       Note that where you have defined alternate argument names, the first is
301       considered the citation form. All the builtin arguments are available
302       using their long variant names.
303
304   BUILTIN PROCESSING
305       The getopts() method also handles processing of the immediate builtin
306       arguments, namely --usage, --version, --help, as well as checking all
307       required arguments have been supplied, so you don't have to handle
308       those yourself. This means that your plugin will exit from the
309       getopts() call in these cases - if you want to catch that you can run
310       getopts() within an eval{}.
311
312       getopts() also sets up a default ALRM timeout handler so you can use an
313
314         alarm $ng->timeout;
315
316       around any blocking operations within your plugin (which you are free
317       to override if you want to use a custom timeout message).
318

SEE ALSO

320       Monitoring::Plugin, Getopt::Long
321

AUTHOR

323       This code is maintained by the Monitoring Plugin Development Team: see
324       https://monitoring-plugins.org
325
326       Originally:
327         Gavin Carr <gavin@openfusion.com.au>
328
330       Copyright (C) 2014      by Monitoring Plugin Team Copyright (C)
331       2006-2014 by Nagios Plugin Development Team
332
333       This library is free software; you can redistribute it and/or modify it
334       under the same terms as Perl itself.
335
336
337
338perl v5.36.0                      2023-01-20     Monitoring::Plugin::Getopt(3)
Impressum