[Nagiosplug-devel] RFC: Plugins config file (final proposal)

[Ton Voon]

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