Watchghost configuration lives within four files within a single directory. These files describe our monitored infrastructure. Each file contains one kind of configured element.

The four kind of configuration element (and their filenames) are:

  • servers
  • groups
  • watchers
  • loggers

The default directory is ~/.config/watchghost. This folder can be changed using the config option of Watchghost executables.

The format of these files is TOML and each file contains a list of elements.


class watchghost.config.Server(name, config)

A Server is only represented by its name. This name is a string that must be unique amongst all servers and groups.

Any other pair of key/value can be configured.


ipv4 = ""
ipv6 = "2001:db8:100:0:bda1:1c51:c598:6ef8"

ipv4 = ""
ipv6 = "2001:db8:100:0:2df2:b059:4067:437e"

ipv4 = ""
ipv6 = "2001:db8:100:0:eccf:6af2:e2:9e"


A Group is only represented by its name. This name is a string that must be unique amongst all servers and groups. Values must be a list of valid server names.


postgres = ["jupiter", "vulcan"]
linux = ["jupiter", "ceres"]
windows = ["vulcan"]

This example defines three groups named postgres (including the jupiter and vulcan servers), linux (including the jupiter and ceres servers), and windows (including the vulcan server).


class, group=None, server=None)

A Service is responsible for checking something.

A Watcher is a Service applied to a server or a group, with custom attributes.

Any watcher must have the following attribute:

  • service: the service class name.

Any watcher can have the following attributes:

  • server or group: the server name or group name.
  • description: a string representing the watcher (default: None).
  • repeat: the time period between two checks, in seconds (default: 3600).
  • after: the hour when the checks must start (default: 00:00:00).
  • before: the hour when the checks must stop (default: 23:59:59).
  • retry: the number of checks giving the same result before declaring the state as hard (default: 2).
  • retry_interval: the time period (in seconds), between two checks when the state is not hard (default: 15).
  • status: a mapping between statuses and filters that trigger these statuses.


service = "network.Ping"
group = "postgres"
description = "Ping IPv4"
ip_version = 4

service = "network.HTTP"
server = "ceres"
description = "HTTP"
url = ""
warning = [ { code = 404 } ]

This example defines two watchers. The first one pings the IPv4 of the postgres group’s servers. The second one fetches the “” page on the “ceres” server and gives a warning status when the status code is 404 (otherwise gives what the HTTP watcher’s default config does).

See the list of builtin services used by watchers


class watchghost.loggers.Logger

A logger make a recording of services watches.

All loggers share the following properties:

  • type: the name of the class to use as logger. This class must be found in watchghost.loggers module.
  • status: a list of status level that the logger accepts. A status level is one of info, warning, error, critical or unknown.
  • only_hard: whether or not the logger should act only on hard statuses or not. A status is hard when a watcher gives the same result N times (N being defined on the watcher).


type = "Console"
status = ["error", "critical"]
only_hard = True

This example defines a logger that will use the class watchghost.loggers.Console. This logger will only log error and critical statuses when these statuses are hard.

See the list of builtin loggers