||FreeBSD File Formats Manual
xymonserver.cfg - Xymon environment variables
Xymon programs use multiple environment variables beside the normal set of
variables. The environment definitions are stored in the
~Xymon/server/etc/xymonserver.cfg file. Each line in this file is of the form
and defines one environment variable NAME with the value
You can also append data to existing variables, using the syntax
. VALUE is then appended to the existing value of the NAME
variable. If NAME has not been defined, then this acts as if it were a normal
In some cases it may be useful to have different values for an environment
variable, depending on where it is used. This is possible by defining
variables with an associated "area". Such definitions have the form
E.g. to define a special setup of the XYMSERVERS variable when it is used by an
application in the "management" area, you would do this:
XYMSERVERS="127.0.0.1" # Default definition
management/XYMSERVERS="10.1.0.5" # Definition in the "management" area
Areas are invoked by using the "--area" option for all tools, or via
the ENVAREA setting in the tasks.cfg(5)
- The fully-qualified hostname of the server that is running Xymon.
- The hostname used to access this servers' web-pages, used to construct
URL's in the Xymon webpages. Default is the XYMONSERVERHOSTNAME.
- The public IP-address of the server that is running Xymon.
- A name identifying the operating system of the Xymon server. The known
names are currently "linux", "freebsd",
"solaris", "hpux", "aix" and
- If set to TRUE, Xymon will use fully-qualified hostnames throughout. If
set to FALSE, hostnames are stripped of their domain-part before being
processed. It is highly recommended that you keep this set to TRUE.
- Controls how the HTML page for a status log is generated. If set to
DYNAMIC, the HTML logs are generated on-demand by the
svcstatus.cgi(1) script. If set to STATIC, you must activate the
xymond_filestore(8) module (through an entry in the
tasks.cfg(5) file) to create and store the HTML logs whenever a
status update is received. Setting "XYMONLOGSTATUS=STATIC" is
discouraged since the I/O load on the Xymon server will increase
- Defines the name of the column for "ping" test status. The data
from the "ping" test is used internally by Xymon, so it must be
defined here so all of the Xymon tools know which column to watch for this
data. The default setting is PINGCOLUMN=conn.
- Defines the name of the column for the "info" pages.
- Defines the name of the column for the RRD graph pages.
- The default height (in pixels) of the RRD graph images. Default: 120
- The default width (in pixels) of the RRD graph images. Default: 576
- Extra options for the RRD graph command. These are passed directly to the
"rrdgraph" command used to generate graphs, see the
rrdgraph(1) man-page for details of the options.
- The graphs on the "trends" page show data for the past
TRENDSECONDS seconds. Default: 172800 seconds, i.e. 48 hours.
- The Content-type reported by the CGI scripts that generate web pages. By
default, this it "text/html". If you have on-line help texts in
character sets other than the ISO-8859-1 (western european) character set,
it may be necessary to modify this to include a character set. E.g.
for a Japanese character sets. Note: Some webservers will automatically add
this, if configured to do so.
- The default HTTP page reload interval for many xymongen and status pages.
Note that while this can be overridden in the header template files for
regular pages, dynamically generated status logs displayed with
svcstatus.cgi(1) use this value in the HTTP response header and for
security reasons the value in hostsvc_header may be ignored on many modern
browsers. (default [seconds]: 60)
- Defines the default set of holidays used if there is no
"holidays" tag for a host in the hosts.cfg file. Holiday sets
are defined in the holidays.cfg(5) file. If not defined, only the
default holidays (those defined outside a named holiday set) will be
considered as holidays.
- Defines which day is the first day of the week. Set to "0" for
Sunday, "1" for Monday. Default: 1 (Monday).
- Text that is included in the Xymon web pages at the location specified by
~xymon/server/web/*_header templates. If this is set to a value beginning
with "file:", then the contents of the specified file is
included. Default: "file:$XYMONHOME/etc/xymonmenu.cfg"
- Text that is included in the Xymon web pages at the location specified by
~xymon/server/web/*_footer templates. If this is set to a value beginning
with "file:", then the contents of the specified file is
included. Default: Empty.
- URL for the Xymon menu CSS file. Default:
- Determines what is used as the host comment on the webpages. The comment
by default appears as a pop-up when the mouse hovers over the hostname,
and is also shown on the "info" status page. This setting must
be one or more of the letters "C" (COMMENT), "D"
(DESCRIPTION) or "I" (IP-address). Including "C" uses
the COMMENT setting for the host, including "D" uses the DESCR
setting for the host, and "I" uses the IP-address of the host.
If more than one of these is set, then COMMENT takes precedence over DESCR
which again has precence over IP. Note that DESCR and IP only appear in
pop-up windows (if enabled), whereas the COMMENT is always used - if
pop-up's have been disabled, then the COMMENT value is displayed next to
the hostname on the webpages. Default: CDI
- The number of minutes that a status is considered valid after an update.
After this time elapses, the status will go purple. Default: 30 minutes
- The top-level directory for the Xymon installation. The default is the
home-directory for the user running Xymon.
- The directory for the Xymon's own logfiles (NOT the status-logs from the
- The Xymon server directory, where programs and configurations are kept.
Default: $XYMONSERVERROOT/server/ .
- Directory used for temporary files. Default: $XYMONHOME/tmp/
- Directory for Xymon webfiles. The $XYMONWEB URL must map to this
directory. Default: $XYMONHOME/www/
- Directory for Xymon notes-files. The $XYMONNOTESSKIN URL must map to this
directory. Default: $XYMONHOME/www/notes/
- Directory for Xymon availability reports. The $XYMONREPURL URL must map to
this directory. Note also that your webserver must have write-access to
this directory, if you want to use the report.cgi(1) CGI script to
generate reports on-demand. Default: $XYMONHOME/www/rep/
- Directory for Xymon snapshots. The $XYMONSNAPURL URL must map to this
directory. Note also that your webserver must have write-access to this
directory, if you want to use the snapshot.cgi(1) CGI script to
generate snapshots on-demand. Default: $XYMONHOME/www/snap/
- Directory for all data stored about the monitored items. Default:
- Directory for storing the raw status-logs. Not used unless
"xymond_filestore --status" is running, which is
discouraged since it increases the load on the Xymon server
significantly. Default: $XYMONVAR/logs/
- Directory for storing HTML status-logs. Not used unless
"xymond_filestore --status --html" is running, which is
discouraged since it increases the load on the Xymon server
significantly. Default: $XYMONHOME/www/html/
- Directory for storing the history of monitored items. Default:
- Directory for storing the detailed status-log of historical events.
- Directory for storing information about alerts that have been
acknowledged. Default: $XYMONVAR/acks/
- Directory for storing information about tests that have been disabled.
- Directory for storing incoming "data" messages. Default:
- Top-level directory for storing RRD files (the databases with
trend-information used to generate graphs). Default: $XYMONVAR/rrd/
- Directory for storing the data sent by a Xymon client around the time a
status changes to a warning (yellow) or critical (red) state. Used by the
xymond_hostdata(8) module. Default: $XYMONVAR/hostdata/
- Directory where debug output from CGI applications are stored. If not
specified, it defaults to $XYMONSERVERLOGS, but this is often a directory
that is not writable by the userid running the CGI applications. It is
therefore recommended when using "--debug" on CGI applications
that you create a separate directory owned by the user running your
webserver, and point XYMONCGILOGDIR to this directory.
- Full path to the Xymon hosts.cfg(5) configuration file. Default:
- Full path to the xymon(1) client program. Default:
- Full path to the xymongen(1) webpage generator program. Default:
- The root URL for the Xymon webpages, without the hostname. This URL must
be mapped to the ~/server/www/ directory in your webserver configuration.
See the sample Apache configuration in ~/server/etc/xymon-apache.conf.
- The root URL for the Xymon CGI-scripts, without the hostname. This
directory must be mapped to the ~/cgi-bin/ directory in your webserver
configuration, and must be flagged as holding executable scripts. See the
sample Apache configuration in ~/server/etc/xymon-apache.conf.
- Initial part of the Xymon URL, including just the protocol and the
hostname, e.g. "http://www.foo.com"
- Prefix for all of the static Xymon webpages, e.g.
- URL prefix for the static HTML status-logs generated when
XYMONLOGSTATUS=STATIC. Note that this setting is discouraged so
this setting should not be used.
- URL prefix (without hostname) of the Xymon webpages. E.g.
- URL prefix (without hostname) of the Xymon graphics. E.g.
- URL prefix (without hostname) of the Xymon on-line help files. E.g
- URL prefix (without hostname) of the Xymon menu files. E.g
- URL prefix (without hostname) of the Xymon on-line notes files. E.g
- URL prefix (without hostname) of the Xymon availability reports. E.g.
- URL prefix (without hostname) of the Xymon snapshots. E.g.
- URL prefix (without hostname) of the Xymon WAP/WML files. E.g.
- URL prefix (without hostname) of the Xymon CGI-scripts. Default:
- Format string used to build a link to the documentation for a column
heading. Default: "$CGIBINURL/columndoc.sh?%s", which causes
links to use the columndoc.sh(1) script to document a column.
- Format string used to build a link to the documentation for a host. If not
set, then Xymon falls back to scanning the XYMONNOTES directory for files
matching the hostname, or the hostname together with a common filename
extension (.php, .html, .doc and so on). If set, this string becomes a
formatting string for the documentation URL. E.g. for the host
"myhost", a setting of HOSTDOCURL="/docs/%s.php" will
generate a link to "/docs/myhost.php". Default: Not set, so host
documentation will be retrieved from the XYMONNOTES directory.
- The IP-address used to contact the xymond(8) service. Used by
clients and the tools that perform network tests. Default: $XYMONSERVERIP
- List of IP-addresses. Clients and network test tools will try to send
status reports to a Xymon server running on each of these addresses. This
setting is only used if XYMSRV=0.0.0.0.
- The portnumber for used to contact the xymond(8) service. Used by
clients and the tools that perform network tests. Default: 1984.
- The maximum number of status messages to combine into one combo message.
- Length of a pause introduced between each successive transmission of a
combo-message by xymonnet, in microseconds. Default: 0 (send messages as
quickly as possible).
- Comma-separated list of the colors that may trigger an alert-message. The
default is "red,yellow,purple". Note that alerts may further be
generated or suppresed based on the configuration in the
- Comma-separated list of the colors that may trigger a recovery-message.
The default is "green,clear,blue".
- How often alerts get repeated while a status is in an alert state. This is
the default setting, which may be changed in the alerts.cfg(5)
- The maximum size of a "status" message in kB, default: 256.
Status messages are the ones that end up as columns on the web display.
The default size should be adequate in most cases, but some extension
scripts can generate very large status messages - close to 1024 kB. You
should only change this if you see messages in the xymond log file about
status messages being truncated.
- The maximum size of a "client" message in kB, default: 512.
"client" messages are generated by the Xymon client, and often
include large process-listings. You should only change this if you see
messages in the xymond log file about client messages being truncated.
- The maximum size of a "data" message in kB, default: 256.
"data" messages are typically used for client reports of e.g.
netstat or vmstat data. You should only change this setting if you see
messages in the xymond log file about data messages being truncated.
- The maximum size of a "notes" message in kB, default: 256.
"notes" messages provide a way for uploading documentation about
a host to Xymon; it is not enabled by default. If you want to upload large
documents, you may need to change this setting.
- The maximum size of a "status change" message in kB, default:
Current value of the MAXMSG_STATUS setting. Status-change messages occur
when a status changes color. There is no reason to change this setting.
- The maximum size of a "page" message in kB, default: Current
value of the MAXMSG_STATUS setting. "page" messages are alerts,
and include the status message that triggers the alert. There is no reason
to change this setting.
- The maximum size of an "enadis" message in kB, default: 32.
"enadis" are small messages used when enabling or disabling
hosts and tests, so the default size should be adequate.
- The maximum size of a "client change" message in kB, default:
Current value of the MAXMSG_CLIENT setting. Client-change messages occur
when a status changes color to one of the alert-colors, usually red,
yellow and purple. There is no reason to change this setting.
- The maximum size of a "user" message in kB, default: 128.
"user" messages are for communication between custom Xymon
modules you have installed, it is not used directly by Xymon.
- If set to TRUE, xymond_history(8) will update the
$XYMONHISTDIR/allevents file logging all changes to a status. The
allevents file is used by the eventlog.cgi(1) tool to show the list
of recent events on the "All non-green" webpage.
- If set to TRUE, xymond_history(8) will update the host-specific
eventlog that keeps record of all status changes for a host. This logfile
is not used by any Xymon tool.
- If set to TRUE, xymond_history(8) will save historical detailed
status-logs to the $XYMONHISTLOGS directory.
- Command used to send alerts via e-mail, including a "Subject:"
header in the mail. Default: "mail -s"
- Command used to send alerts via e-mail in a form that does not have a
"Subject" in the mail. Default: "mail"
- Maps status-columns to numeric service-codes. The numeric codes are used
when sending an alert using a script, where the numeric code of the
service is provided in the BBSVCNUM variable.
- List of "COLUMNNAME[=RRDSERVICE]" settings, that define which
status- and data-messages have a corresponding RRD graph. You will
normally not need to modify this, unless you have added a custom TCP-based
test to the protocols.cfg file, and want to collect data about the
response-time, OR if you are using the xymond_rrd(8) external
script mechanism to collect data from custom tests. Note: All TCP tests
are automatically added.
- List of GRAPHs that should be displayed on the corresponding colmn page.
Note this will override the default, so to add multiple graphs you should
include the original one (e.g. GRAPHS_cpu="la,vmstat1").
These are used together by the svcstatus.cgi(1) script to determine
if the detailed status view of a test should include a graph.
- List of the RRD databases, that should be shown as a graph on the
- This is used to disable the tracking of certain filesystems. By default
all filesystems reported by a client are tracked. In some cases you may
want to disable this for certain filesystems, e.g. database filesystems
since they are always completely full. This setting is a regular
expression that is matched against the filesystem name (the Unix
mount-point, or the Windows disk-letter) - if the filesystem name matches
this expression, then it will not be tracked by Xymon.
Note: Setting this does not affect filesystems that are already being
tracked by Xymon - to remove them, you must remove the RRD files for the
unwanted filesystems from the ~xymon/data/rrd/HOSTNAME/ directory.
- This is used to enable tracking of only selected filesystems (see the
NORRDDISKS setting above). By default all filesystems are being tracked,
setting this changes that default so that only those filesystems that
match this pattern will be tracked.
- If this variable is defined, then only the hosts that have been tagged
with "NET:$XYMONNETWORK" will be tested by the xymonnet tool.
- If set to TRUE, the connectivity (ping) test will be performed.
- If set to TRUE, then failing network tests go CLEAR if the conn-test
- List of network services (separated with <space>) that should go
yellow upon failure instead of red.
- When using the "router" or "depends" tags for a host,
a failure status will include text that an "Intermediate router is
down". With todays network topologies, the router could be a switch
or another network device; if you define this environment variable the
word "router" will be replaced with whatever you put into the
variable. So to inform the users that an intermediate switch or router is
down, use XYMONROUTERTEXT="switch or router". This can also be
set on a per-host basis using the "DESCR:hosttype:description"
tag in the hosts.cfg(5) file.
- When a network test fails, the status message reports "SERVICENAME
not OK". The "not OK" message can be changed via this
variable, e.g. you can change it to "FAILED" or customize it as
- The command used to run the xymonping(1) tool for the connectivity
test. (The name FPING is due to the fact that the "fping"
utility was used until Xymon version 4.2). This may include suid-root
wrappers and xymonping options. Default: "xymonping"
- Options used for the fping(1) or xymonping(1) tool for the
connectivity test. Note that xymonnet will still expect the output to
match the default format. Default: "-Ae"
- Defines the location of the "traceroute" tool and any options
needed to run it. traceroute is used by the connectivity test when the
ping test fails; if requested via the "trace" tag, the
TRACEROUTE command is executed to try to indicate the point in the network
that is causing the problem. For backwards compatibility, with prior
versions, if TRACEROUTEOPTS is unset, TRACEROUTE is assumed to have
whatever options are desired and no addl options are used. Recommended
defaults are: "-n -q 2 -w 2 -m 15" (no DNS lookup, max. 2
probes, wait 2 seconds per hop, max 15 hops).
If you have the mtr(8) tool installed - available from
http://www.bitwizard.nl/mtr/ - I strongly recommend using this instead.
The recommended TRACEROUTEOPTS for mtr are "-c 2 -n --report"
Note that mtr needs to be installed suid-root on most systems.
- Defines the ntpdate(1) program used for the "ntp" test.
- Options used for the ntpdate(1) program. Default: "-u -q -p
- Defines the rpcinfo(8) program used for "rpc" tests.
- HTML code that is inserted on all standard headers. The default is to add
the text "Xymon" in the upper-left corner of the page, but you
can easily replace this with e.g. a company logo. If you do, I suggest
that you keep it at about 30-35 pixels high, and 100-150 pixels wide.
- The string "Pages hosted locally" that appears above all of the
pages linked from the main Xymon webpage.
- The string "Subpages hosted locally" that appears above all of
the sub-pages linked from pages below the main Xymon webpage.
- The string "Remote status display" that appears about the
summary statuses displayed on the min Xymon webpage.
- HTML tags designed to go in a <FONT> tag, to choose the font for
titles of the webpages.
- HTML tags designed to go in a <FONT> tag, to choose the font for row
headings (hostnames) on the webpages.
- HTML tags designed to go in a <FONT> tag, to chose the font for
column headings (test names) on the webpages.
- HTML tags designed to go in a <FONT> tag, to chose the font for the
acknowledgement text displayed on the status-log HTML page for an
- When displaying the detailed status of an acknowledged test, Xymon will
include the time that the acknowledge expires using the print-format
defined in this setting. You can define the timeformat using the controls
in your systems strftime(3) routine, and add the text suitable for
- The valid length of an acknowledgement cookie. You want to set this large
enough so that a late-answered acknowledgement for an alert is still
processed properly. Default value: 86400
- On webpages generated by xymongen, the default header includes the current
date and time. Normally this looks like "Tue Aug 24 21:59:47
2004". The XYMONDATEFORMAT controls the format of this timestamp -
you can define the format using the controls in the strftime(3)
routine. E.g. to have it show up as "2004-08-24 21:59:47 +0200"
you would set XYMONDATEFORMAT="%Y-%m-%d %H:%M:%S %z"
- How holiday dates are displayed. The default is "%d/%m" which
show the day and month. American users may want to change this to
"%m/%d" to suit their preferred date-display style. This is a
formatting string for the system strftime(3) routine, so any
controls available for this routine may be used.
- Inspired by Jeff Stoner's col_repeat_patch.tgz patch, this defines the
maximum number of rows before repeating the column headings on a webpage.
This sets the default value for the xymongen(1)
"--maxrows" option; if the command-line option is also
specified, then it overrides this environment variable. Note that unlike
Jeff's patch, xymongen implements this for both the "All
non-green" page and all other pages (xymon.html, subpages,
- If set to TRUE, then summaries will affect the color of the main Xymon
webpage. Default: FALSE.
- The height (in pixels) of the icons showing the color of a status.
Default: 16, which matches the default icons.
- The width (in pixels) of the icons showing the color of a status. Default:
16, which matches the default icons.
- List of the status logs fed by data from the Xymon client. These status
logs will - if there are Xymon client data available for the host -
include a link to the raw data sent by the client. Default:
- If defined, this is the title of the RSS/RDF documents generated when
xymongen(1) is invoked with the "--rss" option. The
default value is "Xymon Alerts".
- Maximum size of a WAP/WML output "card" when generating these.
- List of scripts to run as extensions to the "All non-green"
page. Note that two scripts, "eventlog.sh" and
"acklog.sh" are handled specially: They are handled internally
by xymongen, but the script names must be listed in this variable for this
function to be enabled.
- List of scripts to run as extensions to a history page.
- Default threshold for listing the availability as "critical"
(red) when generating the availability report. This can be set on a
per-host basis with the WARNPCT setting in hosts.cfg(5). Default:
- Default xymongen options used for reports. This will typically include
such options as "--subpagecolumns", and also
"--ignorecolumns" if you wish to exclude certain tests from
reports by default.
- Default xymongen options used by snapshots. This should be identical to
the options you normally used when building Xymon webpages.
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.