hosts.cfg

title: hosts.cfg(5)

summary: Main Xymon configuration file

text:
# hosts.cfg(5)

## NAME
hosts.cfg - Main Xymon configuration file

## SYNOPSIS
hosts.cfg

## DESCRIPTION
The hosts.cfg(5) file is the most important configuration file for all of the Xymon programs. This file contains the full list of all the systems monitored by Xymon, including the set of tests and other configuration items stored for each host.

## FILE FORMAT
Each line of the file defines a host. Blank lines and lines starting with a hash mark (#) are treated as comments and ignored. Long lines can be broken up by putting a backslash at the end of the line and continuing the entry on the next line.

The format of an entry in the hosts.cfg file is as follows:

IP-address hostname # tag1 tag2 ...

The IP-address and hostname are mandatory; all of the tags are optional. Listing a host with only IP-address and hostname will cause a network test to be executed for the host - the connectivity test is enabled by default, but no other tests.

The optional tags are then used to define which tests are relevant for the host, and also to set e.g. the time-interval used for availability reporting by xymongen(1)

An example of setting up the hosts.cfg file is in the Xymon on-line documentation (from the Help menu, choose "Configuring Monitoring"). The following describes the possible settings in a hosts.cfg file supported by Xymon.

## TAGS RECOGNIZED BY ALL TOOLS
include filename

This tag is used to include another file into the hosts.cfg file at run-time, allowing for a large hosts.cfg file to be split up into more manageable pieces. The "filename" argument should point to a file that uses the same syntax as hosts.cfg. The filename can be an absolute filename (if it begins with a '/'), or a relative filename - relative file names are prefixed with the directory where the main hosts.cfg file is located (usually $XYMONHOME/etc/).

You can nest include tags, i.e. a file that is included from the main hosts.cfg file can itself include other files.

dispinclude filename

Acts like the "include" tag, but only for the xymongen tool. Can be used e.g. to put a group of hosts on multiple sub-pages, without having to repeat the host definitions.

netinclude filename

Acts like the "include" tag, but only for the xymonnet tool.

directory directoryname

This tag is used to include all files in the named directory. Files are included in alphabetical order. If there are sub- directories, these are recursively included also. The following files are ignored: Files that begin with a dot, files that end with a tilde, RCS files that end with ",v", RPM package manager files ending in ".rpmsave" or ".rpmnew", DPKG package manager files ending in ".dpkg-new" or ".dpkg-orig", and all special files (devices, sockets, pipes etc).

optional include/directory

Both "include" and "directory" can be prefixed with the tag "optional", which will preven an error message being logged if the file or directory is not present on a system.

## GENERAL PER-HOST OPTIONS
noclear

Controls whether stale status messages go purple or clear when a host is down. Normally, when a host is down the client statuses ("cpu", "disk", "memory" etc) will stop updating - this would usually make them go "purple" which can trigger alerts. To avoid that, Xymon checks if the "conn" test has failed, and if that is true then the other tests will go "clear" instead of purple so you only get alerts for the "conn" test. If you do want the stale statuses to go purple, you can use the "noclear" tag to override this behaviour. Note that "noclear" also affects the behaviour of network tests; see below.

prefer

When a single host is defined multiple time in the hosts.cfg file, xymongen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other xymongen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority. By using the "prefer" tag you tell xymongen that this host definition should be used.

Note: This only applies to hosts that are defined multiple times in the hosts.cfg file, although it will not hurt to add it on other hosts as well.

multihomed

Tell Xymon that data from the host can arrive from multiple IP-addresses. By default, Xymon will warn if it sees data for one host coming from different IP-addresses, because this usually indicates a mis-configuration of the hostname on at least one of the servers involved. Some hosts with multiple IP-addresses may use different IP's for sending data to Xymon, however. This tag disables the check of source IP when receiving data.

delayred=STATUSCOLUMN:DELAY[,STATUSCOLUMN:DELAY...]

Usually, status changes happen immediately. This tag is used to defer an update to red for the STATUSCOLUMN status for DELAY minutes. E.g. with delayred=disk:10,cpu:30, a red disk-status will not appear on the Xymon webpages until it has been red for at least 10 minutes. Note: Since most tests only execute once every 5 minutes, it will usually not make sense to set N to anything but a multiple of 5. The exception is network tests, since xymonnet-again.sh(1) will re-run failed network tests once a minute for up to 30 minutes.

delayyellow=STATUSCOLUMN:DELAY[,STATUSCOLUMN:DELAY...]

Same as delayred, but defers the change to a yellow status.

## XYMONGEN DISPLAY OPTIONS
These tags are processed by the xymongen(1) tool when generating the Xymon webpages or reports.

page NAME [Page-title]

This defines a page at the level below the entry page. All hosts following the "page" directive appear on this page, until a new "page", "subpage" or "subparent" line is found.

subpage NAME [Page-title]

This defines a sub-page in the second level below the entry page. You must have a previous "page" line to hook this sub-page to.

subparent parentpage newpage [Page-title]

This is used to define sub-pages in whatever levels you may wish. Just like the standard "subpage" tag, "subparent" defines a new Xymon web page; however with "subparent" you explicitly list which page it should go as a sub-page to. You can pick any page as the parent - pages, sub-pages or even other subparent pages. So this allows you to define any tree structure of pages that you like. E.g. with this in hosts.cfg:

page USA United States

subpage NY New York

subparent NY manhattan Manhattan data centers

subparent manhattan wallstreet Wall Street center

you get this hierarchy of pages:

USA (United States)

NY (New York)

manhattan (Manhattan data centers)

wallstreet (Wall Street center)

Note: The parent page must be defined before you define the subparent. If not, the page will not be generated, and you get a message in the log file.

Note: xymongen is case-sensitive, when trying to match the name of the parent page.

The inspiration for this came from Craig Cook's mkbb.pl script, and I am grateful to Craig for suggesting that I implement it in xymongen. The idea to explicitly list the parent page in the "subparent" tag was what made it easy to implement.

vpage

vsubpage

vsubparent

These are page-definitions similar to the "page", "subpage" and "subparent" definitions. However, on these pages the rows are the tests, and the columns are the hosts (normal pages have it the other way around). This is useful if you have a very large number of tests for a few hosts, and prefer to have them listed on a page that can be scrolled vertically.

Note that the "group" directives have no effect on these types of pages.

group [group-title]

group-compress [group-title]

Defines a group of hosts, that appear together on the web page, with a single header-line listing all of the columns. Hosts following the "group" line appear inside the group, until a new "group" or page-line is found. The two group-directives are handled identically by Xymon and xymongen, but both forms are allowed for backwards compatibility.

group-sorted [group-title]

Same as the "group" line, but will sort the hosts inside the group so they appear in strict lexicographic order.

group-only COLUMN1|COLUMN2|COLUMN3 [group-title]

Same as the "group" and "group-compress" lines, but includes only the columns explicitly listed in the group. Any columns not listed will be ignored for these hosts.

group-except COLUMN1|COLUMN2|COLUMN3 [group-title]

Same as the "group-only" lines, but includes all columns EXCEPT those explicitly listed in the group. Any columns listed will be ignored for these hosts - all other columns are shown.

title Page, group or host title text

The "title" tag is used to put custom headings into the pages generated by xymongen, in front of page/subpage links, groups or hosts. The title tag operates on the next item in the hosts.cfg file following the title tag.

If a title tag precedes a host entry, the title is shown just before the host is listed on the status page. The column headings present for the host will be repeated just after the heading.

If a title tag precedes a group entry, the title is show just before the group on the status page.

If a title tag precedes a page/subpage/subparent entry, the title text replaces the normal "Pages hosted locally" heading normally inserted by Xymon. This appears on the page that links to the sub-pages, not on the sub-page itself. To get a custom heading on the sub-page, you may want to use the "--pagetext-heading" when running xymongen(1)

NAME:hostname

Overrides the default hostname used on the overview web pages. If "hostname" contains spaces, it must be enclosed in double quotes, e.g. NAME:"R&D Oracle Server"

CLIENT:hostname

Defines an alias for a host, which will be used when identifying status messages. This is typically used to accommodate a local client that sends in status reports with a different hostname, e.g. if you use hostnames with domains in your Xymon configuration, but the client is a silly Window box that does not include the hostname. Or vice-versa. Whatever the reason, this can be used to match status reports with the hosts you define in your hosts.cfg file. It causes incoming status reports with the specified hostname to be filed using the hostname defined in hosts.cfg.

NOCOLUMNS:column[,column]

Used to drop certain of the status columns generated by the Xymon client. column is one of cpu, disk, files, memory, msgs, ports, procs. This setting stops these columns from being updated for the host. Note: If the columns already exist, you must use the xymon(1) utility to drop them, or they will go purple.

COMMENT:Host comment

Adds a small text after the hostname on the web page. This can be used to describe the host, without completely changing its display-name as the NAME: tag does. If the comment includes whitespace, it must be in double-quotes, e.g. COMMENT:"Sun web server"

DESCR:Hosttype:Description

Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname

Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5), analysis.cfg(5) and alerts.cfg(5) to group log file checks or alerts). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the hosts.cfg file on the Xymon server, it overrides any class name that the client reports. If not set, then the host belongs to a class named by the operating system the Xymon client is running on.

dialup

The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nonongreen

Ignore this host on the "All non-green" page. Even if it has an active alert, it will not be included in the "All non-green" page. This also removes the host from the event-log display.

nodisp

Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

TRENDS:[*,][![graph,...]]

Defines the RRD graphs to include in the "trends" column generated by xymongen. This option syntax is complex.

If this option is not present, xymongen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail

* If this option is specified, the list of graphs to include start out as being empty (no graphs).

* To include all default graphs, use an asterisk. E.g. "TRENDS:*"

* To exclude a certain graph, specify it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"

* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be specified like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

COMPACT:COLUMN=COLUMN1|COLUMN2|COLUMN3[,ditto]

Collapses a series of statuses into a single column on the overview web page.

INTERFACES:REGEXP

On systems with multiple network interfaces, the operating system may report a number of network interface where the statistics are of no interest. By default Xymon tracks and graphs the traffic on all network interfaces. This option defines a regular expression, and only those interfaces whose name matches the expression are tracked.

## XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE
NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the criticalview.cgi(1) viewer, which has a separate configuration tool, criticaleditor.cgi(1) with more facilities than the NK tags in hosts.cfg.

xymongen will create three sets of pages: The main page xymon.html, the all-non-green-statuses page (nongreen.html), and a specially reduced version of nongreen.html with only selected tests (critical.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]

NOTE: This has been deprecated, you should use criticalview.cgi(1) instead of the NK tag. Define the tests that you want included on the critical page. E.g. if you have a host where you only want to see the http tests on critical.html, you specify it as

12.34.56.78 www.acme.com # http://www.acme.com/ NK:http

If you want multiple tests for a host to show up on the critical.html page, specify all the tests separated by commas. The test names correspond to the column names (e.g. https tests are covered by an "NK:http" tag).

NKTIME=day:starttime:endtime[,day:starttime:endtime]

This tag limits the time when an active alert is presented on the NK web page. By default, tests with a red or yellow status that are listed in the "NK:testname" tag will appear on the NK page. However, you may not want the test to be shown outside of normal working hours - if, for example, the host is not being serviced during week-ends.

You can then use the NKTIME tag to define the time periods where the alert will show up on the NK page.

The time specification consists of

day-of-week: W means Mon-Fri ("weekdays"), * means all days, 0 .. 6 = Sunday .. Saturday. Listing multiple days is possible, e.g. "60" is valid meaning "Saturday and Sunday".

starttime: Time to start showing errors, must be in 24-hour clock format as HHMM hours/minutes. E.g. for 8 am enter "0800", for 9.30 pm enter "2130"

endtime: Time to stop showing errors.

If necessary, multiple periods can be specified. E.g. to monitor a site 24x7, except between noon and 1 pm, use NKTIME=*:0000:1159,*:1300:2359

The interval between start time and end time may cross midnight, e.g. *:2330:0200 would be valid and have the same effect as *:2330:2400,*:0000:0200.

## XYMON TAGS FOR THE WML (WAP) CARDS
If xymongen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]

This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag. The default set of WML tests are taken from the --wml command line option. If no "WML:" tag is specified, the "NK:" tag is used if present.

## XYMON STATUS PROPAGATION OPTIONS
These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]

This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to xymon.html or nongreen.html If a host-specific tag begins with a '-' or a '+', the host-specific tags are removed/added to the default setting from the command-line option. If the host-specific tag does not begin with a '+' or a '-', the default setting is ignored for this host and the NOPROPRED applies to the tests given with this tag.

E.g.: xymongen runs with "--nopropred=ftp,smtp". "NOPROPRED:+dns,-smtp" gives a NOPROPRED setting of "ftp,dns" (dns is added to the default, smtp is removed). "NOPROPRED:dns" gives a setting of "dns" only (the default is ignored).

Note: If you set use the "--nopropred=*" command line option to disable propagation of all alerts, you cannot use the "+" and "-" methods to add or remove from the wildcard setting. In that case, do not use the "+" or "-" setting, but simply list the required tests that you want to keep from propagating.

NOPROPYELLOW:[+|-]testname[,[+|-]testname]

Similar to NOPROPRED: tag, but applies to propagating a yellow status upwards.

NOPROPPURPLE:[+|-]testname[,[+|-]testname]

Similar to NOPROPRED: tag, but applies to propagating a purple status upwards.

NOPROPACK:[+|-]testname[,[+|-]testname]

Similar to NOPROPRED: tag, but applies to propagating an acknowledged status upwards.

## XYMON AVAILABILITY REPORT OPTIONS
These options affect the way the Xymon availability reports are processed (see report.cgi(1) for details about availability reports).

REPORTTIME=day:starttime:endtime[,day:starttime:endtime]

This tag defines the time interval where you measure uptime of a service for reporting purposes. When xymongen generates a report, it computes the availability of each service - i.e. the percentage of time that the service is reported as available (meaning: not red).

By default, this calculation is done on a 24x7 basis, so no matter when an outage occurs, it counts as downtime.

The REPORTTIME tag allows you to specify a period of time other than 24x7 for the service availability calculation. If you have systems where you only guarantee availability from e.g. 7 AM to 8 PM on weekdays, you can use

REPORTTIME=W:0700:2000

and the availability calculation will only be performed for the service with measurements from this time interval.

The syntax for REPORTTIME is the same as the one used by the NKTIME parameter.

When REPORTTIME is specified, the availability calculation happens like this:

* Only measurements done during the given time period is used for the calculation.

* "blue" time reduces the length of the report interval, so if you are generating a report for a 10-hour period and there are 20 minutes of "blue" time, then the availability calculation will consider the reporting period to be 580 minutes (10 hours minus 20 minutes). This allows you to have scheduled downtime during the REPORTTIME interval without hurting your availability; this is (I believe) the whole idea of the downtime being "planned".

* "red" and "clear" status counts as downtime; "yellow" and "green" count as uptime. "purple" time is ignored.

The availability calculation correctly handles status changes that cross into/out of a REPORTTIME interval.

If no REPORTTIME is given, the standard 24x7 calculation is used.

WARNPCT:percentage

Xymon's reporting facility uses a computed availability threshold to color services green (100% available), yellow (above threshold, but less than 100%), or red (below threshold) in the reports. This option allows you to set the threshold value on a host-by-host basis, instead of using a global setting for all hosts. The threshold is defined as the percentage of the time that the host must be available, e.g. "WARNPCT:98.5" if you want the threshold to be at 98.5%

noflap[=test1,test2,...]

Disable flap detection for this host, or for specific tests on this host. Flap detection is globally controlled by options given to xymond on the command line, but, if enabled, it can be disabled using this option.

## NETWORK TEST SETTINGS
testip

By default, Xymon will perform a name lookup of the hostname to get the IP address it will use for network tests. This tag causes Xymon to use the IP listed in the hosts.cfg file.

NET:location

This tag defines the host as being tested from a specific location. If xymonnet sees that the environment variable XYMONNETWORK is set, it will only test the hosts that have a matching "NET:location" tag in the hosts.cfg file. So this tag is useful if you have more than one system running network tests, but you still want to keep a consolidated hosts.cfg file for all your systems. Note: The "--test-untagged" option modifies this behaviour, see xymonnet(1)

noclear

Some network tests depend on others. E.g. if the host does not respond to ping, then there's a good chance that the entire host is down and all network tests will fail. Or if the http server is down, then any web content checks are also likely to fail. To avoid floods of alerts, the default behaviour is for xymonnet to change the status of these tests that fail because of another problem to "clear" instead of "red". The "noclear" tag disables this behaviour and causes all failing tests to be reported with their true color. This behaviour can also be implemented on a per-test basis by putting the "~" flag on any network test.

Note that "noclear" also affects whether stale status messages from e.g. a client on the host go purple or clear when the host is down; see the "noclear" description in the "GENERAL PER-HOST OPTIONS" section above.

nosslcert

Disables the standard check of any SSL certificates for this host. By default, if an SSL-enabled service is tested, a second test result is generated with information about the SSL certificate - this tag disables the SSL certificate checks for the host.

ssldays=WARNDAYS:ALARMDAYS

Define the number of days before an SSL certificate expires, in which the sslcert status shows a warning (yellow) or alarm (red) status. These default to the values from the "--sslwarn" and "--sslalarm" options for the xymonnet(1) tool; the values specified in the "ssldays" tag overrides the default.

sslbits=MINIMUMKEYBITS

Enable checking of the encryption strength of the SSL protocol offered by the server. If the server offers encryption using a key with fewer than MINIMUMKEYBITS bits, the "sslcert" test will go red. E.g. to check that your server only uses strong encryption (128 bits or better), use "sslbits=128".

sni

nosni

Enables or disables use of SNI (Server Name Indication) for SSL tests. Some SSL implementations cannot handle SSL handshakes with SNI data, so Xymon by default does not use SNI. This default can be changed with the "--sni" option for xymonnet(1) but can also be managed per host with these tags.

SNI support was added in Xymon 4.3.13, where the default was to use SNI. This was changed in 4.3.14 so SNI support is disabled by default, and the "sni" and "nosni" tags were introduced together with the "--sni" option for xymonnet.

DOWNTIME=day:starttime:endtime[,day:starttime:endtime]

DOWNTIME=columns:day:starttime:endtime:cause[,columns:day:starttime:endtime:cause]

This tag can be used to ignore failed checks during specific times of the day - e.g. if you run services that are only monitored e.g. Mon-Fri 8am-5pm, or you always reboot a server every Monday between 5 and 6 pm. What happens is that if a test fails during the specified time, it is reported with status BLUE instead of red, yellow, or purple. Thus you can still see when the service was unavailable, but alarms will not be triggered and the downtime is not counted in the availability calculations generated by the Xymon reports.

The "columns" and "cause" settings are optional, but both or neither must be specified. "columns" may be a comma-separated list of status columns to which DOWNTIME will apply. The "cause" string will be displayed on the status web page to explain why the system is down.

The syntax for DOWNTIME is the same as the one used by the NKTIME parameter.

SLA=day:starttime:endtime[,day:starttime:endtime]

This tag is now deprecated. Use the DOWNTIME tag instead. This tag works the opposite of the DOWNTIME tag - you use it to specify the periods of the day that the service should be green. Failures OUTSIDE the SLA interval are reported as blue.

depends=(testA:host1/test1,host2/test2),(testB:host3/test3),[...]

This tag allows you to define dependencies between tests. If "testA" for the current host depends on "test1" for host "host1" and test "test2" for "host2", this can be defined with

depends=(testA:host1/test1,host2/test2)

When deciding the color to report for testA, if either host1/test1 failed or host2/test2 failed, if testA has failed also then the color of testA will be "clear" instead of red or yellow.

Since all tests are actually run before the dependencies are evaluated, you can use any host/test in the dependency - regardless of the actual sequence that the hosts are listed, or the tests run. It is also valid to use tests from the same host that the dependency is for. E.g.

1.2.3.4 foo # http://foo/ webmin depends=(webmin:foo/http)

is valid; if both the http and the webmin tests fail, then webmin will be reported as clear.

Note: The "depends" tag is evaluated by xymonnet while running the network tests. It can therefore only refer to other network tests that are handled by the same server - there is currently no way to use the e.g. the status of locally run tests (disk, cpu, msgs) or network tests from other servers in a dependency definition. Such dependencies are silently ignored.

badTEST[-weekdays-starttime-endtime]:x:y:z

NOTE: This has been deprecated, use the delayred and delayyellow settings instead. Normally when a network test fails, the status changes to red immediately. With a "badTEST:x:y:z" tag this behaviour changes:

* While "z" or more successive tests fail, the column goes RED.

* While "y" or more successive tests fail, but fewer than "z", the column goes YELLOW.

* While "x" or more successive tests fail, but fewer than "y", the column goes CLEAR.

* While fewer than "x" successive tests fail, the column stays GREEN.

The optional time specification can be used to limit this "badTEST" setting to a particular time of day, e.g. to require a longer period of downtime before raising an alarm during out-of-office hours. The time-specification uses:

* Weekdays: The weekdays this badTEST tag applies, from 0 (Sunday) through 6 (Saturday). Putting "W" here counts as "12345", i.e. all working days. Putting "*" here counts as all days of the week, equivalent to "0123456".

* start time and end time are specified using 24-hour clocks, e.g. "badTEST-W-0900-2000" is valid for working days between 9 AM (09:00) and 8 PM (20:00).

When using multiple badTEST tags, the LAST one specified with a matching time-spec is used.

Note: The "TEST" is replaced by the name of the test, e.g.

12.34.56.78 www.foo.com # http://www.foo.com/ badhttp:1:2:4

defines a http test that goes "clear" after the first failure, "yellow" after two successive failures, and "red" after four successive failures.

For LDAP tests using URL's, use the option "badldapurl". For the other network tests, use "badftp", "badssh" etc.

## CONNECTIVITY (PING) TEST
These tags affect the behaviour of the xymonnet connectivity test.

noping

Disables the ping-test, but will keep the "conn" column on the web display with a notice that it has been disabled.

noconn

Disables the ping-test, and does not put a "conn" column on the web display.

conn

The "conn" test (which does a ping of the host) is enabled for all hosts by default, and normally you just want to disable it using "noconn" or "noping". However, on the rare occasion where you may want to check that a host is NOT up, you can specify it as an explicit test, and use the normal test modifiers, e.g. "!conn" will be green when the host is NOT up, and red if it does appear on the network. The actual name of the tag - "conn" by default - depends on the "--ping=TESTNAME" option for xymonnet, as that decides the testname for the connectivity test.

conn={best,|worst,}IP1[,IP2...]

This adds additional IP-addresses that are pinged during the normal "conn" test. So the normal "conn" test must be enabled (the default) before this tag has any effect. The IP-addresses listed here are pinged in addition to the main IP-address. When multiple IP's are pinged, you can choose if ALL IP's must respond (the "worst" method), or AT LEAST one IP must respond (the "best" setting). All of the IP's are reported in a single "conn" status, whose color is determined from the result of pinging the IP's and the best/worst setting. The default method is "best" - so it will report green if just one of the IP's respond to ping.

badconn[-weekdays-starttime-endtime]:x:y:z

This is taken directly from the "fping.sh" connectivity- testing script, and is used by xymonnet when it runs with ping testing enabled (the default). See the description of the "badTEST" tag.

route:router1,router2,....

This tag is taken from the "fping.sh" script, and is used by xymonnet when run with the "--ping" option to enable ping testing. The router1,router2,... is a comma-separated list of hosts elsewhere in the hosts.cfg file. You cannot have any spaces in the list - separate hosts with commas.

This tag changes the color reported for a ping check that fails, when one or more of the hosts in the "route" list is also down. A "red" status becomes "yellow" - other colors are unchanged. The status message will include information about the hosts in the router-list that are down, to aid tracking down which router is the root cause of the problem.

Note: Internally, the ping test will still be handled as "failed", and therefore any other tests run for this host will report a status of "clear".

route_LOCATION:router1,router2,...

If the XYMONNETWORK environment variable is defined, a tag of "route_XYMONNETWORK:" is recognized by xymonnet with the same effect as the normal "route:" tag (see above). This allows you to have different route: tags for each server running xymonnet. The actual text for the tag then must match the value you have for the XYMONNETWORK setting. E.g. with XYMONNETWORK=dmz, the tag becomes "route_dmz:"

trace

If the connectivity test fails, run a "traceroute" and include the output from this in the status message from the failed connectivity test. Note: For this to work, you may have to define the TRACEROUTE environment variable, see xymonserver.cfg(5)

notrace

Similar to the "trace" option, this disables the running of a traceroute for the host after a failed connectivity test. It is only used if running traceroute is made the default via the --trace option.

## SIMPLE NETWORK TESTS
These tests perform a simple network test of a service by connecting to the port and possibly checking that a banner is shown by the server.

How these tests operate are configured in the protocols.cfg(5) configuration file, which controls which port to use for the service, whether to send any data to the service, whether to check for a response from the service etc.

You can modify the behaviour of these tests on a per-test basis by adding one or more modifiers to the test: :NUMBER changes the port number from the default to the one you specify for this test. E.g. to test ssh running on port 8022, specify the test as ssh:8022.

:s makes the test silent, i.e. it does not send any data to the service. E.g. to do a silent test of an smtp server, enter smtp:s.

You can combine these two: ftp:8021:s is valid.

If you must test a service from a multi-homed host (i.e. using a specific source IP-address instead of the one your operating system provides), you can use the modifier "@IPADDRESS" at the end of the test specification, after any other modifiers or port number. "IPADDRESS" must be a valid dotted IP-address (not hostname) which is assigned to the host running the network tests.

The name of the test also determines the column name that the test result will appear with in the Xymon webpages.

By prefixing a test with "!" it becomes a reverse test: Xymon will expect the service NOT to be available, and send a green status if it does NOT respond. If a connection to the service succeeds, the status will go red.

By prefixing a test with "?" errors will be reported with a "clear" status instead of red. This is known as a test for a "dialup" service, and allows you to run tests of hosts that are not always online, without getting alarms while they are off-line.

ftp ssh telnet smtp pop3 imap nntp rsync clamd oratns qmtp qmqp

These tags are for testing services offering the FTP, Secure Shell (ssh), SMTP, POP3, IMAP, NNTP, rsync, CLAM anti-virus daemon (clamd), Oracle TNS listener (oratns), qmail QMTP and QMQP protocols.

ftps telnets smtps pop3s imaps nntps

These tags are for testing of the SSL-tunneled versions of the standard ftp, telnet, smtp, pop3, imap and nntp protocols. If Xymon was configured with support for SSL, you can test these services like any other network service - xymonnet will setup an SSL-encrypted session while testing the service. The server certificate is validated and information about it sent in the "sslcert" column. Note that smtps does not have a standard port number assignment, so you will need to enter this into the protocols.cfg file or your /etc/services file.

bbd

Test that a Big Brother compatible daemon is running. This check works both for the Xymon xymond(8) daemon, and the original Big Brother bbd daemon.

## DNS SERVER TESTS
These tags are used to setup monitoring of DNS servers.

dns

Simple DNS test. It will attempt to lookup the A record for the hostname of the DNS server.

dig

This is an alias for the "dns" test. In xymonnet, the "dns" and "dig" tests are handled identically, so all of the facilities for testing described for the "dns" test are also available for the "dig" test.

dns=hostname

dns=TYPE:lookup[,TYPE:lookup...]

The default DNS tests will attempt a DNS lookup of the DNS' servers own hostname. You can specify the hostname to lookup on a DNS server by listing it on each test. The second form of the test allows you to perform multiple queries of the DNS server, requesting different types of DNS records. The TYPE defines the type of DNS data: A (IP-address), MX (Mail eXchanger), PTR (reverse), CNAME (alias), SOA (Start-Of-Authority), NS (Name Server) are among the more common ones used. The "lookup" is the query. E.g. to lookup the MX records for the "foo.com" domain, you would use "dns=mx:foo.com". Or to lookup the nameservers for the "bar.org" domain, "dns=ns:bar.org". You can list multiple lookups, separated by commas. For the test to end up with a green status, all lookups must succeed.

## OTHER NETWORK TESTS
ntp

Check for a running NTP (Network Time Protocol) server on this host. This test uses the "ntpdate" utility to check for a NTP server - you should either have ntpdate in your PATH, or set the location of the ntpdate program in $XYMONHOME/etc/xymonserver.cfg

rpc[=rpcservice1,rpcservice2,...]

Check for one or more available RPC services. This check is indirect in that it only queries the RPC Portmapper on the host, not the actual service. If only "rpc" is given, the test only verifies that the port mapper is available on the remote host. If you want to check that one or more RPC services are registered with the port mapper, list the names of the desired RPC services after the equals-sign. E.g. for a working NFS server the "mount", "nlockmgr" and "nfs" services must be available; this can be checked with "rpc=mount,nlockmgr,nfs".

This test uses the rpcinfo tool for the actual test; if this tool is not available in the PATH of xymonnet, you must define the RPCINFO environment variable to point at this tool. See xymonserver.cfg(5)

## HTTP TESTS
Simple testing of a http URL is done simply by putting the URL into the hosts.cfg file. Note that this only applies to URL's that begin with "http:" or "https:".

The following items describe more advanced forms of http URL's.

Basic Authentication with username/password

If the URL requires authentication in the form of a username and password, it is most likely using the HTTP "Basic" authentication. xymonnet support this, and you can provide the username and password either by embedding them in the URL e.g.

http://USERNAME:PASSWORD@www.sample.com/

or by putting the username and password into the ~/.netrc file (see ftp(1) for details).

Authentication with SSL client certificates

An SSL client certificate can be used for authentication. To use this, the client certificate must be stored in a PEM-formatted file together with the client certificate key, in the $XYMONHOME/certs/ directory. The URL is then given as

http://CERT:FILENAME@www.sample.com/

The "CERT:" part is literal - i.e. you write C-E-R-T-colon and then the filename of the PEM-formatted certificate.

A PEM-formatted certificate file can be generated based on certificates stored in Microsoft Internet Explorer and OpenSSL. Do as follows:

From the MSIE Tools-Options menu, pick the Content tab, click on Certificates, choose the Personal tab, select the certificate and click Export. Make sure you export the private key also. In the Export File Format, choose PKCS 12 (.PFX), check the "Include all certificates" checkbox and uncheck the "Enable strong protection". Provide a temporary password for the exported file, and select a filename for the PFX-file.

Now run "openssl pkcs12 -in file.pfx -out file.pem". When prompted for the "Import Password", provide the temporary password you gave when exporting the certificate. Then provide a "PEM pass phrase" (twice) when prompted for one.

The file.pem file is the one you should use in the FILENAME field in the URL - this file must be kept in $XYMONHOME/certs/. The PEM pass phrase must be put into a file named the same as the certificate, but with extension ".pass". E.g. if you have the PEM certificate in $XYMONHOME/certs/client.pem, you must put the pass phrase into the $XYMONHOME/certs/client.pass file. Make sure to protect this file with Unix permissions, so that only the user running Xymon can read it.

Forcing an HTTP or SSL version

Some SSL sites will only allow you to connect, if you use specific "dialects" of HTTP or SSL. Normally this is auto-negotiated, but experience shows that this fails on some systems. xymonnet can be told to use specific dialects, by adding one or more "dialect names" to the URL scheme, i.e. the "http" or "https" in the URL:

* "2", e.g. https2://www.sample.com/ : use only SSLv2

* "3", e.g. https3://www.sample.com/ : use only SSLv3

* "t", e.g. httpst://www.sample.com/ : use only TLSv1.0

* "a", e.g. httpsa://www.sample.com/ : use only TLSv1.0

* "b", e.g. httpsb://www.sample.com/ : use only TLSv1.1

* "c", e.g. httpsc://www.sample.com/ : use only TLSv1.2

* "m", e.g. httpsm://www.sample.com/ : use only 128-bit ciphers

* "h", e.g. httpsh://www.sample.com/ : use only >128-bit ciphers

* "10", e.g. http10://www.sample.com/ : use HTTP 1.0

* "11", e.g. http11://www.sample.com/ : use HTTP 1.1

These can be combined where it makes sense, e.g to force TLS1.2 and HTTP 1.0 you would use "httpsc10".

Note that SSLv2 support is disabled in all current OpenSSL releases. TLS version-specific scheme testing requires OpenSSL 1.0.1 or higher.

Testing sites by IP-address

xymonnet ignores the "testip" tag normally used to force a test to use the IP-address from the hosts.cfg file instead of the hostname, when it performs http and https tests. The reason for this is that it interacts badly with virtual hosts, especially if these are IP-based as is common with https-websites.

Instead the IP-address to connect to can be overridden by specifying it as:

http://www.sample.com=1.2.3.4/index.html

The "=1.2.3.4" will case xymonnet to run the test against the IP-address "1.2.3.4", but still trying to access a virtual website with the name "www.sample.com".

The "=ip.address.of.host" must be the last part of the hostname, so if you need to combine this with e.g. an explicit port number, it should be done as

http://www.sample.com:3128=1.2.3.4/index.html

HTTP Testing via proxy

NOTE: This is not enabled by default. You must add the "--bb-proxy-syntax" option when running xymonnet(1) if you want to use this. xymonnet supports the Big Brother syntax for specifying an HTTP proxy to use when performing http tests. This syntax just joins the proxy- and the target-URL into one, e.g.

http://webproxy.sample.com:3128/http://www.foo.com/

would be the syntax for testing the www.foo.com website via the proxy running on "webproxy.sample.com" port 3128.

If the proxy port number is not specified, the default HTTP port number (80) is used.

If your proxy requires authentication, you can specify the username and password inside the proxy-part of the URL, e.g.

http://fred:Wilma1@webproxy.sample.com:3128/http://www.foo.com/

will authenticate to the proxy using a username of "fred" and a password of "Wilma1", before requesting the proxy to fetch the www.foo.com homepage.

Note that it is not possible to test https-sites via a proxy, nor is it possible to use https for connecting to the proxy itself.

cont[=COLUMN];URL;[expected_data_regexp|#digesttype:digest]

This tag is used to specify a http/https check, where it is also checked that specific content is present in the server response. If the URL itself includes a semi-colon, this must be escaped as '%3B' to avoid confusion over which semicolon is part of the URL, and which semicolon acts as a delimiter.

The data that must be returned can be specified either as a regular expression (except that <space> is not allowed) or as a message digest (typically using an MD5 sum or SHA-1 hash).

The regex is pre-processed for backslash "\" escape sequences. So you can really put any character in this string by escaping it first:

\n Newline (LF, ASCII 10 decimal)

\r Carriage return (CR, ASCII 13 decimal)

\t TAB (ASCII 8 decimal)

\\ Backslash (ASCII 92 decimal)

\XX The character with ASCII hex-value XX

If you must have whitespace in the regex, use the [[:space:]] syntax, e.g. if you want to test for the string "All is OK", use "All[[:space:]]is[[:space:]]OK". Note that this may depend on your particular implementation of the regex functions found in your C library. Thanks to Charles Goyard for this tip.

Note: If you are migrating from the "cont2.sh" script, you must change the '_' used as wildcards by cont2.sh into '.' which is the regular-expression wildcard character.

Message digests can use whatever digest algorithms your libcrypto implementation (usually OpenSSL) supports. Common message digests are "md5", "sha1", "sha256" or "sha512". The digest is calculated on the data portion of the response from the server, i.e. HTTP headers are not included in the digest (as they change from one request to the next).

The expected digest value can be computed with the xymondigest(1) utility.

"cont" tags in hosts.cfg result in two status reports: One status with the "http" check, and another with the "content" check.

As with normal URL's, the extended syntax described above can be used e.g. when testing SSL sites that require the use of SSLv2 or strong ciphers.

The column name for the result of the content check is by default called "content" - you can change the default with the "--content=NAME" option to xymonnet. See xymonnet(1) for a description of this option.

If more than one content check is present for a host, the first content check is reported in the column "content", the second is reported in the column "content1", the third in "content2" etc.

You can also specify the column name directly in the test specification, by writing it as "cont=COLUMN;http://...". Column-names cannot include whitespace or semi-colon.

The content-check status by default includes the full URL that was requested, and the HTML data returned by the server. You can hide the HTML data on a per-host (not per-test) basis by adding the HIDEHTTP tag to the host entry.

content=URL

This syntax is deprecated. You should use the "cont" tag instead, see above.

post[=COLUMN];URL;form-data;[expected_data_regexp|#digesttype:digest]

This tag can be used to test web pages, that use an input form. Data can be posted to the form by specifying them in the form-data field, and the result can be checked as if it was a normal content check (see above for a description of the cont-tag and the restrictions on how the URL must be written). The form-data field must be entered in "application/x-www-form-urlencoded" format, which is the most commonly used format for web forms.

E.g. if you have a web form defined like this:

<form action="/cgi-bin/form.cgi" method="post">

<p>Given name<input type="text" name="givenname"></p>

<p>Surname<input type="text" name="surname"></p>

<input type="submit" value="Send">

</form>

and you want to post the value "John" to the first field and "Doe Jr." to the second field, then the form data field would be

givenname=John&surname=Doe+Jr.

Note that any spaces in the input value is replaced with '+'.

If your form-data requires a different content-type, you can specify it by beginning the form-data with (content-type=TYPE), e.g. "(content-type=text/xml)" followed by the POST data. Note that as with normal forms, the POST data should be specified using escape-sequences for reserved characters: "space" should be entered as "\x20", double quote as "\x22", newline as "\n", carriage-return as "\r", TAB as "\t", backslash as "\\". Any byte value can be entered using "\xNN" with NN being the hexadecimal value, e.g. "\x20" is the space character.

The [expected_data_regexp|#digesttype:digest] is the expected data returned from the server in response to the POST. See the "cont;" tag above for details. If you are only interested in knowing if it is possible to submit the form (but don't care about the data), this can be an empty string - but the ';' at the end is required.

nocont[=COLUMN];URL;forbidden_data_regexp

This tag works just like "cont" tag, but reverses the test. It is green when the "forbidden_data_regexp" is NOT found in the response, and red when it IS found. So it can be used to watch for data that should NOT be present in the response, e.g. a server error message.

nopost[=COLUMN];URL;form-data;expected_data_regexp

This tag works just like "post" tag, but reverses the test. It is green when the "forbidden_data_regexp" is NOT found in the response, and red when it IS found. So it can be used to watch for data that should NOT be present in the response, e.g. a server error message.

type[=COLUMN];URL;expected_content_type

This is a variant of the content check - instead of checking the content data, it checks the type of the data as given by the HTTP Content-Type: header. This can used to check if a URL returns e.g. a PDF file, regardless of what is inside the PDF file.

soap[=COLUMN];URL;SOAPMESSAGE;[expected_data_regexp|#digesttype:digest]

Send SOAP message over HTTP. This is identical to the "cont" test, except that the request sent to the server uses a Content-type of "application/soap+xml", and it also sends a "SOAPAction" header with the URL. SOAPMESSAGE is the SOAP message sent to the server. Since SOAP messages are usually XML documents, you can store this in a separate file by specifying "file:FILENAME" as the SOAPMESSAGE parameter. E.g. a test specification of

soap=echo;http://soap.foo.bar/baz?wsdl;file:/home/foo/msg.xml;. will read the SOAP message from the file /home/foo/msg.xml and post it to the URL http://soap.foo.bar/bas?wsdl Note that SOAP XML documents usually must begin with the XML version line, <?xml version="1.0">

nosoap[=COLUMN];URL;SOAPMESSAGE;[forbidden_data_regexp|#digesttype:digest]

This tag works just like "soap" tag, but reverses the test. It is green when the "forbidden_data_regexp" is NOT found in the response, and red when it IS found. So it can be used to watch for data that should NOT be present in the response, e.g. a server error message.

httphead[=COLUMN];URL

This is used to perform an HTTP HEAD request instead of a GET.

httpstatus[=COLUMN];URL;okstatusexpr;notokstatusexpr

This is used to explicitly test for certain HTTP statuscodes returned when the URL is requested. The okstatusexpr and nokokstatusexpr expressions are Perl-compatible regular expressions, e.g. "2..|302" will match all OK codes and the redirect (302) status code. If the URL cannot be retrieved, the status is "999".

HIDEHTTP

The status display for HTTP checks usually includes the URL, and for content checks also the actual data from the web page. If you would like to hide these from view, then the HIDEHTTP tag will keep this information from showing up on the status webpages.

headermatch

Content checks by default only search the HTML body returned by the webserver. This option causes it to also search the HTTP headers for the string that must / must not be present.

browser=BROWSERNAME

By default, Xymon sends an HTTP "User-Agent" header identifying it a "Xymon". Some websites require that you use a specific browser, typically Internet Explorer. To cater for testing of such sites, this tag can be used to modify the data sent in the User-Agent header.

E.g. to perform an HTTP test with Xymon masquerading as an Internet Explorer 6.0 browser, use browser="Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)". If you do not know what the User-Agent header should be, open up the browser that works with this particular site, and open the URL "javascript:document.writeln(navigator.userAgent)" (just copy this into the "Open URL" dialog. The text that shows up is what the browser sends as the User-Agent header.

httphdr=STRING

Xymon can be send additional headers when performing HTTP checks, to allow for validation of any custom configurations needed for your site. Note that this is a host-wide configuration. The string will be added directly to the headers for all URLs on that host. There is currently no way to have this occur only for specific URLs checked.

The string should be encased in quotes, like httphdr="X-Requested-With: XMLHttpRequest". Newlines can be included, however the string MUST NOT end with a newline as that may cause premature ending of the headers sent.

## LDAP (DIRECTORY SERVER) TESTS
ldap

ldaps

Simple check for an LDAP service. This check merely looks for any service running on the ldap/ldaps service port, but does not perform any actual LDAP transaction.

ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]]

Check for an LDAP service by performing an LDAP request. This tag is in the form of an LDAP URI (cf. RFC 2255). This type of LDAP test requires that xymonnet(1) was built with support for LDAP, e.g. via the OpenLDAP library. The components of the LDAP URI are:

```
  hostport is a host name with an optional ":portnumber"

  dn is the search base

  attrs is a comma separated list of attributes to request

  scope is one of these three strings:

    base one sub (default=base)

  filter is filter

  exts are recognized set of LDAP and/or API extensions.
```

ldaps://hostport/dn[?attrs[?scope[?filter[?exts]]]]

LDAP service check using LDAPv3 and STARTTLS for talking to an LDAP server that requires TLS encryption. See xymonnet(1) for a discussion of the different ways of running LDAP servers with SSL/TLS, and which of these are supported by xymonnet.

ldaplogin=username:password

Define a username and password to use when binding to the LDAP server for ldap URI tests. If not specified, xymonnet will attempt an anonymous bind.

ldapyellowfail

Used with an LDAP URL test. If the LDAP query fails during the search of the directory, the ldap status is normally reported as "red" (alarm). This tag reduces a search failure to a "yellow" (warning) status.

## PERFORMANCE MONITORING TESTS
apache[=URL]

If you are running an Apache web server, adding this tag makes xymonnet(1) collect performance statistics from the Apache web server by querying the URL http://IP.ADDRESS.OF.HOST/server-status?auto. The response is sent as a data-report and processed by the Xymon xymond_rrd module into an RRD file and an "apache" graph. If your web server requires e.g. authentication, or runs on a different URL for the server-status, you can provide the full URL needed to fetch the server-status page, e.g. apache=http://LOGIN:PASSWORD@10.0.0.1/server-status?auto for a password protected server-status page, or apache=http://10.0.0.1:8080/apache/server-status?auto for a server listening on port 8080 and with a different path to the server-status page. Note that you need to enable the server-status URL in your Apache configuration. The following configuration is needed:

<Location /server-status>

SetHandler server-status

Order deny,allow

Deny from all

allow from 127.0.0.1

</Location>

ExtendedStatus On

Change "127.0.0.1" to the IP-address of the server that runs your network tests.

## DEFAULT HOST
If you have certain tags that you want to apply to all hosts, you can define a host name ".default." and put the tags on that host. Note that per-host definitions will override the default ones. To apply to all hosts this should be listed FIRST in your file.

NOTE: The ".default." host entry will only accept the following tags - others are silently ignored: delayyellow, delayred, NOCOLUMNS, COMMENT, DESCR, CLASS, dialup, testip, nonongreen, nodisp, noinfo, notrends, noclient, TRENDS, NOPROPRED, NOPROPYELLOW, NOPROPPURPLE, NOPROPACK, REPORTTIME, WARNPCT, NET, noclear, nosslcert, ssldays, DOWNTIME, depends, noping, noconn, trace, notrace, HIDEHTTP, browser, pulldata. Specifically, note that network tests, "badTEST" settings, and alternate pageset relations cannot be listed on the ".default." host.

## SENDING SUMMARIES TO REMOTE XYMON SERVERS
summary ROW.COLUMN IP URL

If you have multiple Xymon servers, the "summary" directive lets you form a hierarchy of servers by sending the overall status of this server to a remote Xymon server, which then displays this in a special summary section. E.g. if your offices are spread over three locations, you can have a Xymon server at each office. These branch-office Xymon have a "summary" definition in their hosts.cfg file that makes them report the overall status of their branch Xymon to the central Xymon server you maintain at the corporate headquarters. Multiple "summary" definitions are allowed.

The ROW.COLUMN setting defines how this summary is presented on the server that receives the summary. The ROW text will be used as the heading for a summary line, and the COLUMN defines the name of the column where this summary is shown - like the hostname and testname used in the normal displays. The IP is the IP-address of the remote (upstream) Xymon server, where this summary is sent). The URL is the URL of your local Xymon server.

The URL need not be that of your Xymon server's main page - it could be the URL of a sub-page on the local Xymon server. Xymon will report the summary using the color of the page found at the URL you specify. E.g. on your corporate Xymon server you want a summary from the Las Vegas office - but you would like to know both what the overall status is, and what is the status of the servers on the critical Sales department back-office servers in Las Vegas. So you configure the Las Vegas Xymon server to send two summaries:

summary Vegas.All 10.0.1.1 http://vegas.foo.com/xymon/

summary Vegas.Sales 10.0.1.1 http://vegas.foo.com/xymon/sales/

This gives you one summary line for Baltimore, with two columns: An "All" column showing the overall status, and a "Sales" column showing the status of the "sales" page on the Baltimore Xymon server.

Note: Pages defined using alternate pageset definitions cannot be used, the URL must point to a web page from the default set of Xymon webpages.

## OTHER TAGS
pulldata[=[IP][:port]]

This option is recognized by the xymonfetch(8) utility, and causes it to poll the host for client data. The optional IP-address and port-number can be used if the client-side msgcache(8) daemon is listening on a non-standard IP-address or port-number.

## FILES
~xymon/server/etc/hosts.cfg

## SEE ALSO
xymongen(1), xymonnet(1), xymondigest(1), xymonserver.cfg(5), xymon(7)


protocols.cfg

package: xymon-man

title: protocols.cfg(5)

summary: Configuration of TCP network services

text:
# protocols.cfg(5)

## NAME
protocols.cfg - Configuration of TCP network services

## SYNOPSIS
$XYMONHOME/etc/protocols.cfg

## DESCRIPTION
protocols.cfg contains definitions of how xymonnet(1) should test a TCP-based network service (i.e. all common network services except HTTP and DNS). For each service, a simple dialogue can be defined to check that the service is functioning normally, and optional flags determine if the service has e.g. a banner or requires SSL- or telnet-style handshaking to be tested.

## FILE FORMAT
protocols.cfg is a text file. A simple service definition for the SMTP service would be this:

[smtp]

send "mail\r\nquit\r\n"

expect "220"

options banner

This defines a service called "smtp". When the connection is first established, xymonnet will send the string "mail\r\nquit\r\n" to the service. It will then expect a response beginning with "220". Any data returned by the service (a so-called "banner") will be recorded and included in the status message.

The full set of commands available for the protocols.cfg file are:

[NAME]

Define the name of the TCP service, which will also be the column-name in the resulting display on the test status. If multiple tests share a common definition (e.g. ssh, ssh1 and ssh2 are tested identically), you may list these in a single "[ssh|ssh1|ssh2]" definition, separating each service-name with a pipe-sign.

send STRING

expect STRING

Defines the strings to send to the service after a connection is established, and the response that is expected. Either of these may be omitted, in which case xymonnet(1) will simply not send any data, or match a response against anything. The send- and expect-strings use standard escaping for non-printable characters. "\r" represents a carriage-return (ASCII 13), "\n" represents a line-feed (ASCII 10), "\t" represents a TAB (ASCII 8). Binary data is input as "\xNN" with NN being the hexadecimal value of the byte.

port NUMBER

Define the default TCP port-number for this service. If no portnumber is defined, xymonnet(1) will attempt to lookup the portnumber in the standard /etc/services file.

options option1[,option2][,option3]

Defines test options. The possible options are

banner - include received data in the status message

ssl - service uses SSL so perform an SSL handshake

telnet - service is telnet, so exchange telnet options

## FILES
$XYMONHOME/etc/protocols.cfg

## SEE ALSO
xymonnet(1)

branch: sisyphus


tasks.cfg

title: tasks.cfg(5)

text:
# tasks.cfg(5)

## NAME
tasks.cfg - Task definitions for the xymonlaunch utility

## SYNOPSIS
~xymon/server/etc/tasks.cfg

## DESCRIPTION
The tasks.cfg file holds the list of tasks that xymonlaunch runs to perform all of the tasks needed by the Xymon monitor.

## FILE FORMAT
A task is defined by a key, a command, and optionally also interval, environment, and logfile.

Blank lines and lines starting with a hash mark (#) are treated as comments and ignored. Long lines can be broken up by putting a backslash at the end of the line and continuing the entry on the next line.

An entry looks like this:

[xymond]

ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg

CMD /usr/local/xymon/server/bin/xymond

[updateweb]

ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg

CMD /usr/local/xymon/server/bin/xymongen

NEEDS xymond

GROUP webupdates

INTERVAL 5m

ONHOST localhost

MAXTIME 10m

LOGFILE /var/log/xymon/updateweb.log

[monthlyreport]

ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg

CMD /usr/local/xymon/server/ext/monthlyreport.sh

CRONDATE 30 4 1 * *

The key is enclosed in angle brackets, and must be unique for each task. You can choose your key-names as you like, they are only used internally in xymonlaunch to identify each task.

The command is defined by the CMD keyword. This is the full command including any options you want to use for this task. This is required for all tasks.

The DISABLED keyword means that this command is disabled. xymonlaunch will not start this task. It is recommended that you use this to disable standard tasks, instead of removing them or commenting them out. Upgrades to Xymon will add standard tasks back into the file, so unless you have them listed as DISABLED then tasks may re-appear unexpectedly after an upgrade. There is also a corresponding ENABLED keyword, to explicitly enable a task.

The ONHOST keyword tells xymonlaunch that this task should only run on specific hosts. After the ONHOST keyword, you must provide a "regular expression"; if the hostname where xymonlaunch runs matches this expression, then the task will run. If it doesn't match, then the task is treated as if it were DISABLED.

The MAXTIME keyword sets a maximum time that the task may run; if exceeded, xymonlaunch will kill the task. The time is in seconds by default, you can specify minutes, hours or days by adding an "m", "h" or "d" after the number. By default there is no upper limit on how long a taskmay run.

The NEEDS instructs xymonlaunch not to run this task unless the task defined by the NEEDS keyword is already running. This is used e.g. to delay the start of some application until the needed daemons have been started. The task that must be running is defined by its key.

The GROUP keyword can be used to limit the number of tasks that may run simultaneously. E.g. if you are generating multiple pagesets of webpages, you don't want them to run at the same time. Putting them into a GROUP will cause xymonlaunch to delay the start of new tasks, so that only one task will run per group. You can change the limit by defining the group before the tasks, with a "GROUP groupname maxtasks" line.

The INTERVAL keyword defines how often this command is executed. The example shows a command that runs every 5 minutes. If no interval is given, the task is only run once - this is useful for tasks that run continually as daemons - although if the task stops for some reason, then xymonlaunch will attempt to restart it. Intervals can be specified in seconds (if you just put a number there), or in minutes (5m), hours (2h), or days (1d).

The CRONDATE keyword is used for tasks that must run at regular intervals or at a specific time. The time specification is identical to the one used by cron in crontab(5) entries, i.e. a sequence of numbers for minute, hour, day-of-month, month and day-of-week. Three-letter abbreviations in english can be used for the month and day-of-week fields. An asterisk is a wildcard. So in the example above, this job would run once a month, at 4:30 AM on the 1st day of the month.

The ENVFILE setting points to a file with definitions of environment variables. Before running the task, xymonlaunch will setup all of the environment variables listed in this file. Since this is a per-task setting, you can use the same xymonlaunch instance to run e.g. both the server- and client-side Xymon tasks. If this option is not present, then the environment defined to xymonlaunch is used.

The ENVAREA setting modifies which environment variables are loaded, by picking up the ones that are defined for this specific "area". See xymonserver.cfg(5) for information about environment areas.

The LOGFILE setting defines a logfile for the task. xymonlaunch will start the task with stdout and stderr redirected to this file. If this option is not present, then the output goes to the same location as the xymonlaunch output.

## SEE ALSO
xymonlaunch(8), xymond(8), crontab(5), xymon(7)


xymon-xmh

title: xymon-xmh(5)

summary: Configuration items available online

text:
# xymon-xmh(5)

## NAME
Xymon-XMH-variables - Configuration items available online

## DESCRIPTION
The hosts.cfg(5) file is the most important configuration file for all of the Xymon programs. This file contains the full list of all the systems monitored by Xymon, including the set of tests and other configuration items stored for each host.

Although the file is in text format and can be searched using tools like xymongrep(1) it can be difficult to pick out specific fields from the configuration due to quoting and other text parsing issues. So Xymon allows for querying this information directly from the xymond daemon via the "xymondboard" command. So the information can be provided together with the current status of a host and/or test. This is done by adding a "fields" definition to the "xymondboard" command.

## XMH items
Except where specified below, all items return the text of a particular setting from the hosts.cfg file, or an empty string if the setting has not been set for the host that is queried.

XMH_ALLPAGEPATHS

List of all pages where the host is found, using the filename hierarchy page path.

XMH_BROWSER

Value of the "browser" tag.

XMH_CLASS

The host "class" (if reported by a Xymon client), or the value of the CLASS tag.

XMH_CLIENTALIAS

Value of the CLIENT tag.

XMH_COMMENT

Value of the COMMENT tag.

XMH_COMPACT

Value of the COMPACT tag.

XMH_DEPENDS

Value of the DEPENDS tag.

XMH_DESCRIPTION

Value of the DESCR tag.

XMH_DGNAME

The text string from the hosts.cfg "group" definition (group, group-only, group-except) in which the host is defined.

XMH_DISPLAYNAME

Value of the NAME tag.

XMH_DOCURL

Value of the DOC tag.

XMH_DOWNTIME

Value of the DOWNTIME tag.

XMH_PULLDATA

Value of the PULLDATA tag (including IP:PORT, if any)

XMH_FLAG_DIALUP

Value of the "dialup" tag.

XMH_FLAG_HIDEHTTP

Value of the HIDEHTTP tag.

XMH_FLAG_LDAPFAILYELLOW

Value of the "ldapyellowfail" tag.

XMH_FLAG_MULTIHOMED

Value of the MULTIHOMED tag.

XMH_FLAG_NOBB2

Value of the "nobb2" tag (deprecated, use NONONGREEN instead).

XMH_FLAG_NOCLEAR

Value of the NOCLEAR tag.

XMH_FLAG_NOCLIENT

Value of the "noclient" tag.

XMH_FLAG_NOCONN

Value of the "noconn" tag.

XMH_FLAG_NODISP

Value of the "nodisp" tag.

XMH_FLAG_NOINFO

Value of the "noinfo" atg.

XMH_FLAG_NONONGREEN

Value of the "nonongreen" tag.

XMH_FLAG_NOPING

Value of the "noping" tag.

XMH_FLAG_NOSSLCERT

Value of the "nosslcert" tag.

XMH_FLAG_NOTRACE

Value of the "notrace" tag.

XMH_FLAG_NOTRENDS

Value of the "notrends" tag.

XMH_FLAG_PREFER

Value of the "prefer" tag.

XMH_FLAG_TESTIP

Value of the "testip" tag.

XMH_FLAG_TRACE

Value of the "trace" tag.

XMH_GROUPID

Number of the group where the host is listed - first group is 0. If a host is present on multiple pages, this is the number of the group for the first page where the host is found.

XMH_HOLIDAYS

Value of the "holidays" tag.

XMH_HOSTNAME

The name of the host.

XMH_HTTPHEADERS

Value of the "httphdr" tag.

XMH_IP

The IP-address of the host (as specified in hosts.cfg).

XMH_LDAPLOGIN

Value of the "ldaplogin" tag.

XMH_NET

Value of the NET tag.

XMH_NK

Value of the NK tag (deprecated).

XMH_NKTIME

Value of the NKTIME tag (deprecated).

XMH_NOCOLUMNS

Value of the NOCOLUMNS tag.

XMH_NOPROP

Value of the NOPROP tag.

XMH_NOPROPACK

Value of the NOPROPACK tag.

XMH_NOPROPPURPLE

Value of the NOPROPPURPLE tag.

XMH_NOPROPRED

Value of the NOPROPRED tag.

XMH_NOPROPYELLOW

Value of the NOPROPYELLOW tag.

XMH_NOTAFTER

Value of the NOTAFTER tag.

XMH_NOTBEFORE

Value of the NOTBEFORE tag.

XMH_OS

The host operating system (if reported by a Xymon client), or the value of the OS tag.

XMH_PAGEINDEX

Index of the host on the page where it is shown, first host has index 0.

XMH_PAGENAME

Name of the page where the host is shown (see also XMH_PAGEPATH).

XMH_PAGEPATH

File path to the page where the host is shown.

XMH_PAGEPATHTITLE

Title of the full path to the page where the host is shown.

XMH_PAGETITLE

Title of the page where the host is shown.

XMH_RAW

All configuration settings for the host. Settings are separated by a pipe-sign.

XMH_REPORTTIME

Value of the REPORTTIME tag.

XMH_SSLDAYS

Value of the "ssldays" tag.

XMH_SSLMINBITS

Value of the "sslbits" tag.

XMH_TRENDS

Value of the TRENDS tag.

XMH_WARNPCT

Value of the WARNPCT tag.

XMH_WARNSTOPS

Value of the WARNSTOPS tag.

XMH_WML

Value of the WML tag.

## SEE ALSO
xymon(1), hosts.cfg(5), xymongrep(1)


xymonclient.cfg

title: xymonclient.cfg(5)

summary: Xymon client environment variables

text:
# xymonclient.cfg(5)

## NAME
xymonclient.cfg - Xymon client environment variables

## DESCRIPTION
Xymon programs use multiple environment variables beside the normal set of variables. For the Xymon client, the environment definitions are stored in the ~xymon/client/etc/xymonclient.cfg file. Each line in this file is of the form NAME=VALUE and defines one environment variable NAME with the value VALUE.

## SETTINGS
XYMSRV

The IP-address used to contact the Xymon server. Default: Chosen when the Xymon client was compiled.

XYMSERVERS

List of IP-addresses of Xymon servers. Data will be sent to all of the servers listed here. This setting is only used if XYMSRV=0.0.0.0.

XYMONDPORT

The port number for used to contact the Xymon server. Default: 1984.

XYMONHOME

The Xymon client top-level directory. Default: The $XYMONCLIENTHOME setting inherited from the "runclient.sh" script which starts the Xymon client.

XYMONCLIENTLOGS

The directory for the Xymon clients' own log files. Default: $XYMONHOME/logs

XYMONTMP

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

XYMON

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

Commands

Many extension scripts expect a series of environment variables to point at various system utilities. These are included in the file when the client is built.

## INHERITED SETTINGS
Some environment variables are inherited from the "runclient.sh" script which launches the Xymon client:

MACHINEDOTS

The hostname of the local system. Default: Taken from "uname -n".

MACHINE

The hostname of the local system, with dots replaced by commas. For compatibility with Big Brother extension scripts.

SERVEROSTYPE

The operating system of the local system, in lowercase. Default: taken from "uname -s".

XYMONCLIENTHOME

The top-level directory for the Xymon client. Default: The location of the "runclient.sh" script.

## SEE ALSO
xymon(7)


xymonserver.cfg

title: xymonserver.cfg(5)

summary: Xymon environment variables

text:
# xymonserver.cfg(5)

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

RRDGRAPHOPTS

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.

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.

XYMWEBREFRESH

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)

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/

XYMONSTATICWWWDIR

Directory for static Xymon webfiles like gifs and CSS files. Default: $XYMONHOME/static/

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.

GRAPHS_<COLUMNAME>

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.

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"

FPINGOPTS

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"

TRACEROUTE

TRACEROUTEOPTS

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.

NTPDATE

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

NTPDATEOPTS

Options used for the ntpdate(1) program. Default: "-u -q -p 1"

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.

ACK_COOKIE_EXPIRATION

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

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

## SEE ALSO
xymon(7)