0.4.0: Getting started

The biggest hurdle to overcome when upgrading to version 0.4.0 is the new configuration method. You can still use the "old" configuration method but it is a good idea to at least learn how the new configuration method works and how to incorporate it with the old method. The "new" and the "old" methods are not mutually exclusive, but before we get started on that lets go through some theory...

Configuration

The configuration in NSCP 0.4.0 has been redesigned and split into separate modules (albeit still inside the same physical executable). The idea is that a "settings store" is loaded which can be implemented using one or more of several different configuration providers. This "store" can then include other types (using different providers). So from the "old" configuration you can include the "new" and vice versa.

The current list of providers are:

• ini A plain text file in the form of an ini file that uses an extended "path like" syntax in the section headers (foo/bar as opposed to [foo bar]).
• registry Tree structure stored inside the registry. This has the drawback of not having any comments and/or descriptions available which means you need to know the syntax of any changes being made.
• old The "old" text file format, in reality this is a text file mapping of "old" keys into the corresponding "new" ones
• http An experimental way to load ini files over HTTP (this allows for remote configurations)

To specify the root or first settings store, and from there all consecutive ones, we use something that looks similar to a URL. This URL has a set of properties which are expanded when the file is loaded, for example ​ini://${exe-path}/nsclient.ini will be read like: Use the ini type provider and load the settings in file nsclient.ini which resides in the same folder as the NSCP executable. There is also a shorthand "ini" which will be the same.

All providers have support for "including" other stores from different providers (http, "old" method, etc.) thus you can start with an old file store and include an ini file and/or a http file and so on. In the future this will be extended to provide support for loading scripts that generate configurations making this even more flexible.

When a key is requested by a plugin or command from NSCP the root store is checked first, if the key is not found the request will be passed to the next store and then the next and so on down the line until there are no more stores to check, if the key is still not found it will be marked as "not found" which in most cases will result in a default value being used. This process is the same regardless of which types of store are used. The "search" is recursive, meaning if A includes B and C and B in turn includes D D will be searched before C.

boot.ini

So how does nsclient++ know which file to load then? Well there is a magic file called boot.ini which defines this. This file is not required and if missing nsclient++ will use a default set of files thish is (in order) old, ini. On non windows os:es the old file will not be used so then it is only ini. This means by default nsclient++ will load a file called nsclient.ini (or nsc.ini) located in the same folder as the exe file (this is subject to change I have some ideas to have a "shared location" where the file is located but we shall see in the future, right now the default is the same folder as the executable.

The syntax of the "magic" boot.ini file is the following:

[settings]
1=old
2=ini
3=registry

Where each line under settings specify a location and the key (number) is the order they will be tried. Whenever a file is found all others will be discarded so you can only have one active file. There are some ideas to have a save location as well to allow you to direct where new keys and updated values will be added but this is for the future right now.

Using the configuration from command line

Since maintaining the configuration has now been modified from the previous "edit said text file" method there is a whole set of new commands to manipulate the settings store and the various aspects surrounding it. The best way to understand how it works is to start NSCP with the command line option --settings-help which gives you a list of all available command line arguments and a short description of what they do.

>nscp --settings-help
Settings options:
  --migrate-to arg      Migrate (copy) settings from current store to target
                        store
  --migrate-from arg    Migrate (copy) settings from current store to target
                        store
  --generate arg        (re)Generate a commented settings store or similar KEY
                        can be trac, settings or the target store.
  --add-defaults        Add all default (if missing) values.
  --path arg            Path of key to work with.
  --key arg             Key to work with.
  --set arg             Set a key and path to a given value.
  --show                Set a value given a key and path.
  --list                Set all keys below the path (or root).

This tells us we can do: nscp --settings --list to get a list of all keys in all used settings store in other words what the program will see. Another quite handy command is:

nscp --settings --migrate-to ini

Which will take (if you are using the old file) your old settings file and convert it to the new ini format as well as update the boot.ini to use the new settings store.

To make this even more useful we can add --add-defaults which will add all available keys and their default values (in effect generating a nice new nsclient.ini file for us) like so:

nscp --settings --migrate-to ini --add-defaults

There is also commands to set values --settings --path /foo --key bar --set test as well as generate a file from scratch (or update the current one) nscp --settings --generate ini --add-defaults.

That is all for now but perhaps I will extend this a bit later on.

Setting keys

Using the command line syntax to for instance enable a module:

nscp --settings --path /modules --key NRPEClient --set ""