Configuration

The main configuration lives in monitor.ini. By default, SimpleMonitor will look for it in the working directory when launched. To specify a different file, use the -f option.

The format is fairly standard “INI”; section names are lowercase in [square brackets], and values inside the sections are defined as key=value. You can use blank lines to space things out, and comments start with #.

Section names and option values, but not option names, support environment variable injection. To include the value of an environment variable, use %env:VARIABLE%, which will inject the value of $VARAIBLE from the environment. You can use this to share a common configuration file across multiple hosts, for example.

This main configuration file contains the global settings for SimpleMonitor, plus the logging and alerting configuration. A separate file, by default monitors.ini, contains the monitor configuration. You can specify a different monitors configuration file using a directive in the main configuration.

Warning

I know the configuration file names are dumb, sorry.

Configuration value types

Values which take bool accept 1, yes, and true as truthy, and everything else as falsey.

Values which take bytes accept suffixes of K, M, or G for kibibytes, mibibytes or gibibytes, otherwise are just a number of bytes.

monitor.ini

This file must contain a [monitor] section, which must contain at least the interval setting.

[monitor] section

interval
Type

integer

Required

true

defines how many seconds to wait between running all the monitors. Note that the time taken to run the monitors is not subtracted from the interval, so the next iteration will run at interval + time_to_run_monitors seconds.

monitors
Type

string

Required

false

Default

monitors.ini

the filename to load the monitors themselves from. Relative to the cwd, not the path of this configuration file.

pidfile
Type

string

Required

false

Default

none

the path to write a pidfile to.

remote
Type

bool

Required

false

Default

false

enables the listener for receiving data from remote instances. Can be overridden to disabled with -N command line option.

remote_port
Type

integer

Required

if remote is enabled

the TCP port to listen on for remote data

key
Type

string

Required

if remote is enabled

shared secret for validating data from remote instances.

bind_host
Type

string

Required

false

Default

0.0.0.0 (all interfaces)

the local IP address to listen on, if remote is enabled.

hup_file
Type

string

Required

false

Default

none

a file to watch the modification time on. If the modification time increases, SimpleMonitor reloads its configuration.

Tip

SimpleMonitor will reload if it receives SIGHUP; this option is useful for platforms which don’t have that.

bind_host
Type

string

Required

false

Default

all interfaces

the local address to bind to for remote data

[reporting] section

loggers
Type

comma-separated list of string

Required

false

Default

none

the names of the loggers you want to use. Each one must be a [section] in this configuration file.

See Loggers for the common options and list of Alerters with their configurations.

alerters
Type

comma-separated list of string

Required

false

Default

none

the names of the alerters you want to use. Each one must be a [section] in this configuration file.

See Alerters for the common options and list of Alerters with their configurations.

monitors.ini

This file only contains monitors. Each monitor is a [section] in the file, with the section name giving the monitor its name. The name defaults is reserved, and can be used to specify default values for options. Each monitor’s individual configuration overrides the defaults.

See Monitors for the common options and list of Monitors with their configurations.

Example configuration

This is an example pair of configuration files to show what goes where. For more examples, see Config examples.

monitor.ini:

[monitor]
interval=60

[reporting]
loggers=logfile
alerters=email,sms

# write a log file with the state of each monitor, each time
[logfile]
type=logfile
filename=monitor.log

# email me when monitors fail or succeed
[email]
type=email
host=mailserver.example.com
from=monitor@example.com
to=admin@example.com

# send me an SMS after a monitor has failed 10 times in a row
[sms]
type=bulksms
username=some-username
password=some-password
target=+447777123456
limit=10

monitors.ini:

# check the webserver pings
[www-ping]
type=ping
host=www.example.com

# check the webserver answers https; don't bother checking if it's not pinging
[www-http]
type=http
url=https://www.example.com
depend=www-ping

# check the root partition has at least 1GB of free space
[root-diskspace]
type=diskspace
partition=/
limit=1G

Reloading

You can send SimpleMonitor a SIGHUP to make it reload its configuration. On platforms which don’t have that (e.g. Windows), you can specify a file to watch. If the modification time of the file changes, SimpleMonitor will reload its configration.

Reloading will pick up a change to interval but no other configuration in the [monitor] section. Monitors, Alerters and Loggers are reloaded. You can add and remove them, and change their configurations, but not change their types. (To change a type, first remove it from the configuration and reload, then add it back in.)