client-local.cfg - Local configuration settings for Xymon clients
The client-local.cfg file contains settings that are used by each Xymon client
when it runs on a monitored host. It provides a convenient way of configuring
clients from a central location without having to setup special configuration
maintenance tools on all clients.
The client-local.cfg file is currently used to configure what logfiles the
client should fetch data from, to be used as the basis for the
"msgs" status column; and to configure which files and directories
are being monitored in the "files" status column.
Note that there is a dependency between the client-local.cfg file and the
file. When monitoring e.g. a logfile, you must first
enter it into the client-local.cfg file, to trigger the Xymon client into
reporting any data about the logfile. Next, you must configure analysis.cfg so
the Xymon server knows what to look for in the file data sent by the client.
So: client-local.cfg defines what raw data is collected by the client, and
analysis.cfg defines how to analyze them.
The client-local.cfg file resides on the Xymon server.
When clients connect to the Xymon server to send in their client data, they will
receive part of this file back from the Xymon server. The configuration
received by the client is then used the next time the client runs.
This method of propagating the configuration means that there is a delay of up
to two poll cycles (i.e. 5-10 minutes) from a configuration change is entered
into the client-local.cfg file, and until you see the result in the status
messages reported by the client.
By default, xymond will look for a matching entry by matching the client
hostname, classname or operating system name against the section expressions.
Hostname matches are used first, then classname matches, then OS matches. The
first match found is the one that is returned to the client.
If xymond is started with the "--merge-clientlocal" option, then
xymond will instead merge all of the matching sections into one, and return
all of this data to the client. So you can have host-specific entries, and
then supplement them with class- or os-generic entries. Note that the merging
does not remove entries, so if you have e.g. a "log" entry defined
in both a hostname- and an osname-matching section, then both entries will be
sent back to the client.
The file is divided into sections, delimited by "[name]" lines. A
section name can be either an operating system identifier - linux, solaris,
hp-ux, aix, freebsd, openbsd, netbsd, darwin - a class, or a hostname. When
deciding which section to send to a client, Xymon will first look for a
section named after the hostname of the client; if such a section does not
exist, it will look for a section named by the operating system of the client.
So you can configure special configurations for individual hosts, and have a
default configuration for all other hosts of a certain type.
It will often be practical to use regular expressions for hostnames. To do this
you must use
where <expression> is a Perl-compatible regular expression. The same kind
of matching can be done on operating system or host class, using
Apart from the section delimiter, the file format is free-form, or rather it is
defined by the tools that make use of the configuration.
A logfile configuration entry looks like this:
line defines the filename of the log, and the
maximum amount of data (in bytes) to send to the Xymon server. FILENAME is
usually an explicit full-path filename on the client. If it is enclosed in
backticks, it is a command which the Xymon client runs and each line of output
from this command is then used as a filename. This allows scripting which
files to monitor, e.g. if you have logfiles that are named with some sort of
timestamp. If FILENAME is enclosed in angle brackets it is treated as a glob
and passed through the local glob(3) function first.
The ignore PATTERN
line (optional) defines lines in the logfile which are
ignored entirely, i.e. they are stripped from the logfile data before sending
it to the Xymon server. It is used to remove completely unwanted
"noise" entries from the logdata processed by Xymon.
"PATTERN" is a regular expression.
The trigger PATTERN
line (optional) is used only when there is more data
in the log than the maximum size set in the "log:FILENAME:SIZE"
line. The "trigger" pattern is then used to find particularly
interesting lines in the logfile - these will always be sent to the Xymon
server. After picking out the "trigger" lines, any remaining space
up to the maximum size is filled in with the most recent entries from the
logfile. "PATTERN" is a regular expression.
A special type of log-handling is possible, where the number of lines matching a
regular expressions are merely counted. This is linecount:FILENAME
followed by a number of lines of the form ID:PATTERN
A file monitoring entry is used to watch the meta-data of a file: Owner, group,
size, permissions, checksum etc. It looks like this:
line defines the filename of the file to monitor. As
with the "log:" entries, a filename enclosed in backticks means a
command which will generate the filenames dynamically. The optional [:HASH]
setting defines what type of hash to compute for the file: md5
, or sha256, sha512
. By default, no hash is calculated.
If you want to check multiple files using a wildcard, you
use a command to generate the filenames. Putting wildcards
directly into the file:
entry will not work.
A directory monitoring entry is used to watch the size of a directory and any
sub-directories. It looks like this:
line defines the filename of the file to monitor.
As with the "log:" entries, a filename enclosed in backticks means a
command which will generate the filenames dynamically and a filename enclosed
in angle brackets will be treated as a fileglob. The Xymon client will run the
command with the directoryname as parameter, and send the output
back to the Xymon server.
If you want to check multiple directories using a wildcard, you
use a command or glob to generate the directory names. Putting
wildcards directly into the dir:
entry will not work. E.g. use
dir:`find /var/log -maxdepth 1 -type d`
The "du" command used can be configured through the DU
environment variable in the xymonclient.cfg file if needed. If not specified,
is used, as on some systems by default du
reports data in
disk blocks instead of KB (e.g. Solaris).
The ability of the Xymon client to calculate file hashes and monitor those can
be used for file integrity validation on a small scale. However, there is a
significant processing overhead in calculating these every time the Xymon
client runs, so this should not be considered a replacement for host-based
intrusion detection systems such as Tripwire or AIDE.
Use of the directory monitoring on directory structures with a large number of
files and/or sub-directories can be quite ressource-intensive.
analysis.cfg(5), xymond_client(8), xymond(8), xymon(7)