[Nagiosplug-devel] RFC: Plugins config file (final proposal)
Ton Voon
ton.voon at altinity.com
Wed Jan 31 13:50:02 CET 2007
Hi all,
There's been lots of great feedback. Here's a summary and an updated
RFC.
COMMAND LINE OPTIONS
There's been a shift from the "replacement inline" to "config file
defines defaults override-able on command line". I think conceptually
it is straightforward (and is equivalent to how mysql handle their
my.cnf files), so there shouldn't be a problem understanding it. I
still prefer "replacement" as I think it covers more possibilities
and retains order of options, but I'll go with the majority :(
I would propose that we rename from --extra-opts to --default-opts to
reflect the new logic.
DUPLICATED OPTIONS
Sean Finney brings up a suggestion of dissuading the use of multiple
options at the plugin level. There are some plugins that support
duplicate options, such as check_disk -p, check_http -k, check_tcp's -
e, most of the -v. Most of the time, duplicate options is the only
"nice" way to define multiple things. I think this is best fixed by
saying that the behaviour of multiple options is undefined using the
config file, so you shouldn't use config files for these options.
STDIN SUPPORT
John P Rouillard requests stdin support for passing data from Nagios'
config files. I think support for stdin (--default-opts=-) should be
fine on condition that the input file is not processed any
differently. John, would you still like this functionality?
CONFIG FILE FORMAT FOR ENVIRONMENT VARIABLES
I think everyone appeared happy with the ini style config file, until
environment variables were brought in. I would prefer to avoid the
development time in handling a new config file format, just so that
it looks nicer or makes more semantical sense, and concentrate on
providing the essential functionality.
So I would propose that we have a prefix of "environment-" as the
stanza name for environment variables, which will be processed
differently. However, to stay on focus, the work to add
"environment-" will be done after the option processing.
By using other people's libraries, we can help patch their work if
there is a case they haven't considered.
CONFIG FILE IN XML FORMAT
I'd like to discount XML because it cannot be easily read by humans.
QUOTING IN CONFIG FILE
It appears that there is not a specific standard for ini files
(http://en.wikipedia.org/wiki/INI_file), so I think to move the
conversation forward, I've described some common cases in the RFC
below. These can form the basis of some unit tests which will be
written in perl and C to check the implementations work as expected.
I'd appreciate any other test cases which I can add - please add in
the same format: a config file, a command to run, the expected
results, plus a description of why it should be this way.
NEXT STEPS
- More test cases - I found it helps understand implementation
issues (No single switch parameters, ordering possibly changed,
number of options may change)
- Agree on RFC for addition to dev guidelines
UPDATED RFC
-----
PROBLEM
There are security issues with passing user authentication
information into some plugins via the command line. We would like the
use of configuration files, secured at the file level, allowing
configuration variables on a per-plugin basis.
PROPOSED SOLUTION
A new option is allowed: --default-opts. The idea is this option
reads in
default values for configuration options from the configuration file.
The configuration file has a windows ini style format:
[stanza_name]
option1=argument1
option2=argument2
There can be multiple stanzas in a configuration file. The options
are directly mapped to the plugin parameter options. The
configuration file has no concept of whether the options are valid or
not for the specific plugin. The options can be the long or short
options - the routine will assume all single letter options are short
options.
The --default-opts parameter will take a value in the format:
--default-opts=[stanza_name][@config_filename]
If stanza_name is missed out, will assume stanza_name = plugin name.
If @config_filename is missed out, will search for the configuration
file in default locations.
A stanza_name prefixed with "environment-" is processed differently.
It will set the environment variables within the current process.
IMPLEMENTATION DETAILS
The C routine is to be called np_getopt_long and has the same
interface as getopt_long (from gnulib).
The perl routine in Nagios::Plugin will not require any changes at
the plugin level.
Both the C and the perl routines do not require specification of --
default-opts to process that option - it is implicitly checked and
processed.
When processing options, there needs to be a first pass to extract
all the --default-opts options and process the config files.
Duplicate config options are removed, last one wins. Any options on
command line will remove the default.
Duplicates removal would include equivalent short and long options.
For instance, a default config file of username=manager with a -u
admin on command line would produce the equivalent of -u admin.
The number of options will be guaranteed only for options on the
command line as duplicate ones in configuration files will be
removed. If you want a specific number of options, it is best to
avoid --default-opts.
The order of the options is not guaranteed - defaults maybe added at
beginning or the end of processing. If you want to use options that
could be positional dependant (such as check_disk's -p), it is
recommended to avoid --default-opts.
Only options with an argument will be in the configuration file.
Switch parameters are not supported.
The configuration file would be searched for in default locations
(specified at compile time).
A stanza_name of "default" and "environment-default" are reserved for
future use.
As this facility can be used beyond just authentication (for
instance, common parameters on a plugin basis), it is up to the
system administrator to ensure the file permissions on a
configuration file is appropriate.
If -v -v -v is specified, the config file routine will print the
output of the equivalent command line options with the --default-opts
options replaced. It is not defined whether long or short options
will be displayed.
Config file accepts # as a comment line. A ";" is acceptable for
comments (some libraries will recognise), but discouraged.
The implementation should allow multiple specifications of --default-
opts.
If default-opts is not found, return state unknown with appropriate
message.
If stanza is not found, return state unknown with appropriate message.
If there is a parse error, return state unknown with appropriate
message.
EXAMPLES
Assuming default config file holds:
[check_mysql]
username=tonvoon
password=secret
[more_options]
username=altinity
warning=10
critical=15
[check_disk]
p=/tmp
[check_2_disks]
p=/tmp
p=/var
[funny_stuff]
username="Ton Voon"
p=
expect=" space in front"
An invocation of:
./check_mysql -S --default-opts= --default-opts=more_options -H
localhost
is effectively (order not necessarily preserved, see implementation
details):
./check-mysql -S --username=altinity --password=secret
--warning=10 --critical=5 -H localhost
(Last invocation of --username is used from two config files)
An invocation of:
./check_mysql --username=admin --default-opts=more_options --warning=5
is effectively:
./check_mysql --username=admin --critical=15 --warning=5
(command line overrides config file for --username)
An invocation of:
./check_mysql --default-opts= -u admin
is effectively:
./check_mysql --username=admin --password=secret
(-u on command line overrides --username. It is not defined whether
the effective command is -u or --username)
An invocation of:
./check_disk --default-opts= -p=/home
is effectively:
./check_disk -p /home
(Handles single character options in config file correctly)
An invocation of:
./check_disk --default-opts=check_2_disks
is effectively:
./check_disk -p /var
(p=/var is read last, so takes priority over p=/tmp)
An invocation of:
./check_disk --default-opts= -p=/home -p=/users
is effectively:
./check_disk -p /home -p /users
(-p from config is overridden. Will retain the number of -p from
command line)
An invocation of:
./check_disk --default-opts=funny_stuff -p=/home -p=/users
is effectively:
./check_disk --username "Ton Voon" -p "" --expect=" space in front"
(-p has a value associated, but null. Space retained in username.
Space in front retained in expect)
An invocation of:
./check_disk --default-opts=@/non/existant/file
returns UNKNOWN, with error message
An invocation of:
./check_disk --default-opts=unknown-stanza
returns UNKNOWN, with error message
-----
Ton
http://www.altinity.com
T: +44 (0)870 787 9243
F: +44 (0)845 280 1725
Skype: tonvoon
More information about the Devel
mailing list