Ubuntu Manpage: xymonserver.cfg - Xymon environment variables

NAME

       xymonserver.cfg - Xymon environment variables

DESCRIPTION

       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 NAME=VALUE and defines one environment variable NAME with
       the value VALUE.

       You can also append data to existing variables, using the  syntax  NAME+=VALUE.  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 definition.

ENVIRONMENT AREAS

       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 AREA/NAME=VALUE.

       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) file.

GENERAL SETTINGS

XYMONSERVERHOSTNAME
The fully-qualified hostname of the server that is running Xymon.

XYMONSERVERWWWNAME
The hostname used to access this servers' web-pages, used to construct URL's in the
Xymon webpages. Default is the XYMONSERVERHOSTNAME.

XYMONSERVERIP
The public IP-address of the server that is running Xymon.

XYMONSERVEROS
A name identifying the operating system of the Xymon server. The known names are
currently "linux", "freebsd", "solaris", "hpux", "aix" and "osf".

FQDN 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. Default: TRUE.

XYMONLOGSTATUS
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 significantly.

PINGCOLUMN
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.

INFOCOLUMN
Defines the name of the column for the "info" pages.

TRENDSCOLUMN
Defines the name of the column for the RRD graph pages.

RRDHEIGHT
The default height (in pixels) of the RRD graph images. Default: 120 pixels.

RRDWIDTH
The default width (in pixels) of the RRD graph images. Default: 576 pixels.

TRENDSECONDS
The graphs on the "trends" page show data for the past TRENDSECONDS seconds.
Default: 172800 seconds, i.e. 48 hours.

HTMLCONTENTTYPE
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.
HTMLCONTENTTYPE="text/html; charset=euc-jp"
for a Japanese character sets. Note: Some webservers will automatically add this,
if configured to do so.

HOLIDAYS
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.

WEEKSTART
Defines which day is the first day of the week. Set to "0" for Sunday, "1" for
Monday. Default: 1 (Monday).

XYMONBODYHEADER
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"

XYMONBODYFOOTER
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.

XYMONBODYMENUCSS
URL for the Xymon menu CSS file. Default: "$XYMONMENUSKIN/xymonmenu.css"

HOSTPOPUP
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

STATUSLIFETIME
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

DIRECTORIES

XYMONSERVERROOT
The top-level directory for the Xymon installation. The default is the home-
directory for the user running Xymon.

XYMONSERVERLOGS
The directory for the Xymon's own logfiles (NOT the status-logs from the monitored
hosts).

XYMONHOME
The Xymon server directory, where programs and configurations are kept. Default:
$XYMONSERVERROOT/server/ .

XYMONTMP
Directory used for temporary files. Default: $XYMONHOME/tmp/

XYMONWWWDIR
Directory for Xymon webfiles. The $XYMONWEB URL must map to this directory.
Default: $XYMONHOME/www/

XYMONNOTESDIR
Directory for Xymon notes-files. The $XYMONNOTESSKIN URL must map to this
directory. Default: $XYMONHOME/www/notes/

XYMONREPDIR
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/

XYMONSNAPDIR
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/

XYMONVAR
Directory for all data stored about the monitored items. Default:
$XYMONSERVERROOT/data/

XYMONRAWSTATUSDIR
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/

XYMONHTMLSTATUSDIR
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/

XYMONHISTDIR
Directory for storing the history of monitored items. Default: $XYMONVAR/hist/

XYMONHISTLOGS
Directory for storing the detailed status-log of historical events. Default:
$XYMONVAR/histlogs/

XYMONACKDIR
Directory for storing information about alerts that have been acknowledged.
Default: $XYMONVAR/acks/

XYMONDISABLEDDIR
Directory for storing information about tests that have been disabled. Default:
$XYMONVAR/disabled/

XYMONDATADIR
Directory for storing incoming "data" messages. Default: $XYMONVAR/data/

XYMONRRDS
Top-level directory for storing RRD files (the databases with trend-information
used to generate graphs). Default: $XYMONVAR/rrd/

CLIENTLOGS
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/

XYMONCGILOGDIR
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.

SYSTEM FILES

       HOSTSCFG
              Full   path   to   the   Xymon   hosts.cfg(5)    configuration    file.    Default:
              $XYMONHOME/etc/hosts.cfg.

       XYMON  Full path to the xymon(1) client program. Default: $XYMONHOME/bin/xymon.

       XYMONGEN
              Full    path    to    the   xymongen(1)   webpage   generator   program.   Default:
              $XYMONHOME/bin/xymongen.

URLS

XYMONSERVERWWWURL
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.

XYMONSERVERCGIURL
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.

XYMONWEBHOST
Initial part of the Xymon URL, including just the protocol and the hostname, e.g.
"http://www.foo.com"

XYMONWEBHOSTURL
Prefix for all of the static Xymon webpages, e.g. "http://www.foo.com/xymon"

XYMONWEBHTMLLOGS
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.

XYMONWEB
URL prefix (without hostname) of the Xymon webpages. E.g. "/xymon".

XYMONSKIN
URL prefix (without hostname) of the Xymon graphics. E.g. "/xymon/gifs".

XYMONHELPSKIN
URL prefix (without hostname) of the Xymon on-line help files. E.g "/xymon/help".

XYMONMENUSKIN
URL prefix (without hostname) of the Xymon menu files. E.g "/xymon/menu".

XYMONNOTESSKIN
URL prefix (without hostname) of the Xymon on-line notes files. E.g "/xymon/notes".

XYMONREPURL
URL prefix (without hostname) of the Xymon availability reports. E.g. "/xymon/rep".

XYMONSNAPURL
URL prefix (without hostname) of the Xymon snapshots. E.g. "/xymon/snap".

XYMONWAP
URL prefix (without hostname) of the Xymon WAP/WML files. E.g. "/xymon/wml".

CGIBINURL
URL prefix (without hostname) of the Xymon CGI-scripts. Default: $XYMONSERVERCGIURL
.

COLUMNDOCURL
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.

HOSTDOCURL
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.

SETTINGS FOR SENDING MESSAGES TO XYMON

       XYMSRV The IP-address used to contact the xymond(8) service. Used by clients and the tools
              that perform network tests.  Default: $XYMONSERVERIP

       XYMSERVERS
              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.

       XYMONDPORT
              The  portnumber  for used to contact the xymond(8) service. Used by clients and the
              tools that perform network tests.  Default: 1984.

       MAXMSGSPERCOMBO
              The maximum number of status messages to combine into one combo message.   Default:
              100.

       SLEEPBETWEENMSGS
              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).

XYMOND SETTINGS

ALERTCOLORS
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 alerts.cfg(5) file.

OKCOLORS
Comma-separated list of the colors that may trigger a recovery-message. The
default is "green,clear,blue".

ALERTREPEAT
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) file.

MAXMSG_STATUS
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.

MAXMSG_CLIENT
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.

MAXMSG_DATA
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.

MAXMSG_NOTES
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.

MAXMSG_STACHG
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.

MAXMSG_PAGE
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.

MAXMSG_ENADIS
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.

MAXMSG_CLICHG
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.

MAXMSG_USER
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.

XYMOND_HISTORY SETTINGS

       XYMONALLHISTLOG
              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.

       XYMONHOSTHISTLOG
              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.

       SAVESTATUSLOG
              If  set to TRUE, xymond_history(8) will save historical detailed status-logs to the
              $XYMONHISTLOGS directory.

XYMOND_ALERT SETTINGS

       MAIL   Command used to send alerts via e-mail, including a "Subject:" header in the  mail.
              Default: "mail -s"

       MAILC  Command  used to send alerts via e-mail in a form that does not have a "Subject" in
              the mail. Default: "mail"

       SVCCODES
              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.

XYMOND_RRD SETTINGS

TEST2RRD
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.

This is also used by the svcstatus.cgi(1) script to determine if the detailed
status view of a test should include a graph.

GRAPHS List of the RRD databases, that should be shown as a graph on the "trends" column.

NORRDDISKS
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.

RRDDISKS
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.

XYMONNET NETWORK TEST SETTINGS

XYMONNETWORK
If this variable is defined, then only the hosts that have been tagged with
"NET:$XYMONNETWORK" will be tested by the xymonnet tool.

CONNTEST
If set to TRUE, the connectivity (ping) test will be performed.

IPTEST_2_CLEAR_ON_FAILED_CONN
If set to TRUE, then failing network tests go CLEAR if the conn-test fails.

NONETPAGE
List of network services (separated with <space>) that should go yellow upon
failure instead of red.

XYMONROUTERTEXT
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.

NETFAILTEXT
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 you like.

FPING 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"

TRACEROUTE
Defines the location of the "traceroute" tool and any options needed to run it.
traceroute it used by the connectivity test when the ping test fails; if requested
via the "trace" tag, the TRACEROUTE command is executed to try to determine the
point in the network that is causing the problem. By default the command executed
is "traceroute -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 setting for mtr is
"/usr/sbin/mtr -c 2 -n --report" (the exact path to the mtr utility may be
different on your system). Note that mtr needs to be installed suid-root on most
systems.

NTPDATE
Defines the ntpdate(1) program used for the "ntp" test. Default: "ntpdate"

RPCINFO
Defines the rpcinfo(8) program used for "rpc" tests. Default: "rpcinfo"

XYMONGEN WEBPAGE GENERATOR SETTINGS

XYMONLOGO
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.

XYMONPAGELOCAL
The string "Pages hosted locally" that appears above all of the pages linked from
the main Xymon webpage.

XYMONPAGESUBLOCAL
The string "Subpages hosted locally" that appears above all of the sub-pages linked
from pages below the main Xymon webpage.

XYMONPAGEREMOTE
The string "Remote status display" that appears about the summary statuses
displayed on the min Xymon webpage.

XYMONPAGETITLE
HTML tags designed to go in a <FONT> tag, to choose the font for titles of the
webpages.

XYMONPAGEROWFONT
HTML tags designed to go in a <FONT> tag, to choose the font for row headings
(hostnames) on the webpages.

XYMONPAGECOLFONT
HTML tags designed to go in a <FONT> tag, to chose the font for column headings
(test names) on the webpages.

XYMONPAGEACKFONT
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 acknowledged status.

ACKUNTILMSG
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 your setup.

XYMONDATEFORMAT
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"

HOLIDAYFORMAT
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.

XYMONPAGECOLREPEAT
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, critical.html).

SUMMARY_SET_BKG
If set to TRUE, then summaries will affect the color of the main Xymon webpage.
Default: FALSE.

DOTHEIGHT
The height (in pixels) of the icons showing the color of a status. Default: 16,
which matches the default icons.

DOTWIDTH
The width (in pixels) of the icons showing the color of a status. Default: 16,
which matches the default icons.

CLIENTSVCS
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: cpu,disk,memory,procs,svcs.

XYMONRSSTITLE
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".

WMLMAXCHARS
Maximum size of a WAP/WML output "card" when generating these. Default: 1500.

XYMONNONGREENEXT
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.

XYMONHISTEXT
List of scripts to run as extensions to a history page.

XYMONREPWARN
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: 97 (percent)

XYMONGENREPOPTS
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.

XYMONGENSNAPOPTS
Default xymongen options used by snapshots. This should be identical to the options
you normally used when building Xymon webpages.

FILES

       ~xymon/server/etc/xymonserver.cfg