Configuration Files

General

SNClient uses the INI-style configuration format with some enhancements (see syntax specification below).

The default configuration is explained in the packaging file.

File Locations

By default SNClient searches for a snclient.ini in the following folders:

• ./snclient.ini (current folder)
• /etc/snclient/snclient.ini
• ${exe-path}/snclient.ini (this is C:\Program Files\snclient\snclient.ini on Windows)

Custom Configuration

The default config file includes a wildcard pattern snclient_local*.ini which makes it easy to include local custom configuration. Putting custom configuration in a separate file has a couple of advantages.

• no conflicts during package updates.
• clean separation of upstream and user configuration.
• no need to walk through the whole default configuration to see what has been customized.

Best practice is to create a snclient_local.ini file, for example:

[/modules]
CheckExternalScripts = enabled

[/settings/default]
allowed hosts = 127.0.0.1, 10.0.1.2
password = SHA256:9f86d081884...

See the includes section for details about including files.

Windows

The location for a custom file would be: C:\Program Files\snclient\snclient_local.ini

Linux

The location for a custom file would be: /etc/snclient/snclient_local.ini

Syntax

The configuration uses the INI file format. For example:

[/settings/default]
allowed hosts = 127.0.0.1, ::1

The maximum length of a single line in the INI file is limited to 1MB.

Comments

Lines starting with # or ; are treated as comments and ignored. You can use both characters in values.

[/settings/external scripts]
# this is a comment
check_echo = echo '# this is not a comment and printed as is.'

Quotes

Quotes are optional, even for text.

[/settings/default]
tls min version = tls1.2
password        = "CHANGEME"

There is no difference between single and double quotes. Macros will be interpolated in both variants.

Quotes will be removed from the value if the value starts and ends with them.

[/settings/external scripts]
# will be used without quotes
check_remove_quotes = "${script}/test.sh"

# quotes will not be trimmed here since they don't surround the value:
check_keep_quotes = "C:\Program Files\snclient\snclient.exe" -V

# quotes will also be kept here:
check_also_keep = "part 1" something else "part 2"

# this will throw an error
check_wrong = "unclosed quotes

Multiline Values

End a line with a space or tab followed by \ to continue its value on the next line. The backslash and surrounding whitespace, including indentation on the next line, are replaced with a single space. This works for configuration values in all sections, including external commands and check_multi commands.

For example, check the size of a backup folder:

[/settings/check/multi/backups]
command[size] = check_files \
          "path=/srv/backups" \
          "warn=total_size > 10GiB"

A continuation must be followed immediately by a nonempty line. A blank or whitespace-only line, or the end of the file, causes an unfinished line continuation error. Windows paths such as C:\scripts\ remain unchanged because the final backslash is not preceded by a space or tab.

See external commands for an external command example.

Appending Values

You may use the += operator to append to existing values and write more readable configuration files.

[/settings/default]
allowed hosts  = 127.0.0.1, ::1
allowed hosts += , 192.168.0.1
allowed hosts += , 192.168.0.2,192.168.0.3

Values will simply be joined as text, so in case you want to create lists, make sure you add a comma. (Starting with v0.38 this will be done automatically)

Inheritance

The configuration is split into multiple sections, but in order to avoid having duplicate password or allowed hosts entries, inheritance can be used to define shared settings only once.

[/settings/sub1/other]
key = value

[/settings/sub1/default]
; fallback if the above is not set
key = value

[/settings/sub1]
; fallback if the above is not set
key = value

[/settings/default]
; fallback if the above is not set
key = value

Each section inherits values from its default section, from parent sections and their default sections.

This is the order of inheritance for the example above:

• /settings/sub1/other (most significant)
• /settings/sub1/default
• /settings/sub1
• /settings/default (least significant)

The first defined value will be used.

Includes

It is possible and encouraged to include other INI files to organize your settings.

Includes can either be local files or HTTP(S) URLs to load remote configuration files.

Local Includes

For local includes it is recommended to make use of the default include path snclient_local*.ini.

[/includes]
local = snclient_local*.ini

HTTPS Includes

HTTPS URLs can also be used to load centrally managed configuration files. It is recommended to use HTTPS links and use some sort of authentication.

The simple way:

[/includes]
remote = https://user:password@central.company/snclient/default.ini

If you want to configure more details, create a new section for each include and adjust all default HTTP client options:

[/includes/company]
url                  = https://central.company/snclient/default.ini
#user                = test        # set a username to authenticate
#password            = changeme    # use a password
#insecure            = false       # skip hostname verification
#request timeout     = 60          # change http request timeout
#client certificate  = client1.crt # use client certificates to authenticate
#certificate key     = client1.key # private key for client certificate

The HTTP include will be locally cached, so SNClient will still start, even if the remote server is temporarily not available. The agent will try to update the include on reload and daemon startup. The SNClient will not try to update the include for simple commands, such as snclient run ... or snclient hash, unless the include has never been downloaded.

In case the include cannot be downloaded and no local cache is present, the agent will refuse to start.

Macros

Macros can be used in the INI file configuration to access path variables.

Supported macro variants:

• ${macro name}
• %(macro name)
• all variants of $ / % and {} / () are interchangeable

Available Macros

Basically all the values from the [/paths] section are available as macros plus some more.

List of available macros:

On-Demand Macros

Besides the path macros, you can access and reference any configuration value with on-demand macros:

• ${/settings/section/attribute}
• %(/settings/section/attribute)

For example, add a dummy check which returns the allowed hosts setting for the webserver component:

[/settings/external scripts/alias]
alias_allowed_hosts = check_dummy 0 "weballowed:${/settings/WEB/server/allowed hosts}"

On-demand macros are only available during the initial config parsing and will not be used for plugin arguments for security reasons.

Macro Operators

The list of available macro operators is defined here.

For example, to define a dummy command which prints the hostname in lowercase letters:

[/settings/external scripts/alias]
alias_hostname = check_dummy 0 "host:${hostname:lc}"