unix_socket
unix_socket opens a connection to a Unix socket on the node and closes it
again. A Unix socket is a file through which programs on the same machine
talk to each other; many web application servers and databases listen on
one, such as PHP-FPM on /run/php/php-fpm.sock. The check is healthy when
the connection opens.
Choose unix_socket for a program that listens on a socket file. A program
that listens on a TCP port has tcp.
Inputs
The module takes one value, which a check writes after the module's name, and no other input.
- the value of
unix_socket(string; required): The absolute path of the Unix socket.
When the check fails, and when it cannot check
A run is healthy when the connection opens, with the message
Unix socket connection accepted. A run fails when:
- the socket file is missing:
/run/php/php-fpm.sock does not exist; - no program accepts connections on it, such as when a program ended
and left its socket file behind:
no program accepts connections on the Unix socket /run/php/php-fpm.sock; - the connection does not open within the check group's
time_limit_per_run, or the connection attempt returns another error. MMWatchdog shows the cause in Go's words.
A unix_socket check has no unknown result of its own. Like every check,
a unix_socket check is unknown when the run does not end
(a run that does not end). A
failed run starts or continues the check's
failing time. unix_socket reports
no measurement, so a unix_socket check takes no limit.
Examples
# /etc/mmwatchdog/check_groups/php_fpm_socket.yml
check_groups:
php_fpm_socket:
check_every: 30s
time_limit_per_run: 5s
alert_after_failing_for: 1m
recovered_after_healthy_for: 30s
unix_socket: /run/php/php-fpm.sock
alert_severity: sos
The check is written directly on the check group, so status shows it as
php_fpm_socket/unix_socket. Every 30 seconds, MMWatchdog on the node connects to
/run/php/php-fpm.sock, sends nothing, and closes the connection. When no
connection has opened for 1 minute, MMWatchdog sends the sos alert.
How it works
- The value is the absolute path of the socket, written alone after
unix_socket:. The check takes no other input. - MMWatchdog connects as root. The node monitoring process, which runs the check, runs as root, so the permissions of the socket file do not stop the check.
- The check sends and reads nothing. A healthy result establishes only that a connection to the socket opened.
Errors and what they mean
mmwatchdog validate and mmwatchdog reload print each error after the file, the line, and
the column, which the table leaves out.
| Message | What the message means, and what to do |
|---|---|
check_groups.php_fpm_socket.unix_socket: must be the absolute path of a Unix socket, such as /run/php/php-fpm.sock |
The path does not start with /, or is not written in plain form, such as a path with .. or a trailing / |
check_groups.php_fpm_socket.unix_socket: expected a string, found a mapping |
The check is written as a mapping, such as unix_socket: {path: /run/php/php-fpm.sock}. Write the path alone: unix_socket: /run/php/php-fpm.sock |
Tested on
- Go tests in
internal/checksandalerts:TestUnixSocketCheck(a connection that opens, a missing socket file, a socket file that no program listens on, and validation). They ran on macOS ARM64 and, as the native suite, on the AMD64 guest of every target distribution. - The node suite (
tests/integration/node_scenarios.py), on every target distribution: a real socket that a program listens on, the program killed with its socket file left behind, and the file removed, each with its own message.
Why it works this way
unix_socketis built intommwatchdogas a core module. Programs on any Linux server can use Unix sockets, so checking connections does not require a module for a particular tool.- A missing socket file and a socket file with no listener are common failures with separate messages. For example, a program that never started can leave no socket file. A program that ended without removing the socket file can leave a file that no program listens on.
This page is docs/reference/modules/unix_socket.md in the MMWatchdog repository.