xymonnet - Xymon network test tool
xymonnet [--ping|--noping] [--timeout=N] [options] [hostname] [hostname]
(See the OPTIONS section for a description of the available command-line
handles the network tests of hosts defined in the Xymon
configuration file, hosts.cfg. It is normally run at regular intervals by
via an entry in the tasks.cfg(5)
xymonnet does all of the normal tests of TCP-based network services (telnet,
ftp, ssh, smtp, pop, imap ....) - i.e. all of the services listed in
protocols.cfg. For these tests, a completely new and very speedy service-
checker has been implemented.
xymonnet has built-in support for testing SSL-enabled protocols, e.g. imaps,
pop3s, nntps, telnets, if SSL-support was enabled when configuring xymonnet.
The full list of known tests is found in the protocols.cfg(5)
In addition, it implements the "dns" and "dig" tests for
testing DNS servers.
xymonnet also implements a check for NTP servers - this test is called
"ntp". If you want to use it, you must define the NTPDATE
environment variable to point at the location of your ntpdate(1)
Note: xymonnet performs the connectivity test (ping) based on the hostname,
unless the host is tagged with "testip" or the "--dns=ip"
option is used. So the target of the connectivity test can be determined by
your /etc/hosts file or DNS.
By default, all servers are tested - if XYMONNETWORK is set via
then only the hosts marked as belonging to this
network are tested. If the command-line includes one or more hostnames, then
only those servers are tested.
- Determines the timeout (in seconds) for each service that is tested. For
TCP tests (those from XYMONNETSVCS), if the connection to the service does
not succeed within N seconds, the service is reported as being down. For
HTTP tests, this is the absolute limit for the entire request to the
webserver (the time needed to connect to the server, plus the time it
takes the server to respond to the request). Default: 10 seconds
- This option is deprecated, and will be ignored. Use the --timeout option
- This option sets a timeout for the external commands used for testing of
NTP and RPC services, and to perform traceroute.
- Determines the number of network tests that run in parallel. Default is
operating system dependent, but will usually be 256. If xymonnet begins to
complain about not being able to get a "socket", try running
xymonnet with a lower value like 50 or 100.
- --dns-timeout=N (default: 30 seconds)
- xymonnet will timeout all DNS lookups after N seconds. Any pending DNS
lookups are regarded as failed, i.e. the network tests that depend on this
DNS lookup will report an error.
Note: If you use the --no-ares option, timeout of DNS lookups cannot be
controlled by xymonnet.
- Same as "--dns-timeout=N". The "--dns-max-all" option
is deprecated and should not be used.
- Determines how xymonnet finds the IP addresses of the hosts to test. By
default (the "standard"), xymonnet does a DNS lookup of the
hostname to determine the IP address, unless the host has the
"testip" tag, or the DNS lookup fails.
With "--dns=only" xymonnet will ONLY do the DNS lookup; if it
fails, then all services on that host will be reported as being down.
With "--dns=ip" xymonnet will never do a DNS lookup; it will use
the IP adresse specified in hosts.cfg for the tests. Thus, this setting is
equivalent to having the "testip" tag on all hosts. Note that
http tests will ignore this setting and still perform a DNS lookup for the
hostname given in the URL; see the "xymonnet tags for HTTP
tests" section in hosts.cfg(5)
- Disable the ARES resolver built into xymonnet. This makes xymonnet resolve
hostnames using your system resolver function. You should only use this as
a last resort if xymonnet cannot resolve the hostnames you use in the
normal way (via DNS or /etc/hosts). One reason for using this would be if
you need to resolve hostnames via NIS/NIS+ (a.k.a. Yellow Pages).
The system resolver function does not provide a mechanism for controlling
timeouts of the hostname lookups, so if your DNS or NIS server is down,
xymonnet can take a very long time to run. The --dns-timeout option is
effectively disabled when using this option.
- Log failed hostname lookups to the file FILENAME. FILENAME should be a
- With this option, xymonnet will send a status message with details of how
many hosts were processed, how many tests were generated, any errors that
occurred during the run, and some timing statistics. The default
columnname is "xymonnet".
- When using the XYMONNETWORK environment variable to test only hosts on a
particular network segment, xymonnet will ignore hosts that do not have
any "NET:x" tag. So only hosts that have a NET:$XYMONNETWORK tag
will be tested.
With this option, hosts with no NET: tag are included in the test, so that
all hosts that either have a matching NET: tag, or no NET: tag at all are
- Used with the xymonnet-again.sh(1) Xymon extension. This option
determines how long failed tests remain in the frequent-test queue. The
default is 1800 seconds (30 minutes).
- Causes xymonnet to generate a warning if the run-time of xymonnet exceeds
N seconds. By default N is set to the value of TASKSLEEP, so a warning
triggers if the network tests cannot complete in the time given for one
cycle of the xymonnet task. Apart from the warning, this option has no
effect, i.e. it will not terminate xymonnet prematurely. So to eliminate
any such warnings, use this option with a very high value of N.
- Warn if the response from a TCP test is more than N bytes. If you see from
the xymonnet status report that you are transferring large amounts of data
for your tests, you can enable this option to see which tests have large
Default: 0 (disabled).
- Make the test results valid for N minutes before they go purple. By
default test results are valid for 30 minutes; if you run xymonnet less
often than that, the results will go purple before the next run of
xymonnet. This option lets you change how long the status is valid.
- On multi-homed hosts, this option can be used to explicitly select the
source IP address used for the network tests. "IPADDRESS" must
be a valid IP-address on the host running xymonnet.
- Instead of reading the hosts.cfg file, xymonnet will load the hosts.cfg
configuration from the xymond daemon. This eliminates the need for reading
the hosts.cfg, and if you have xymond and xymonnet running on different
hosts, it also eliminates the need for copying the hosts.cfg file between
systems. Note that the "netinclude" option in hosts.cfg is
ignored when this option is enabled.
- When testing well-known services (e.g. FTP, SSH, SMTP, POP-2, POP-3, IMAP,
NNTP and rsync), xymonnet will look for a valid service-specific
"OK" response. If another response is seen, this will cause the
test to report a warning (yellow) status. Without this option, the
response from the service is ignored.
The optional color-name is used to select a color other than yellow for the
status message when the response is wrong. E.g.
"--checkresponse=red" will cause a "red" status
message to be sent when the service does not respond as expected.
- By default, xymonnet sends some extra information in the status messages,
called "flags". These are used by xymongen e.g. to pick
different icons for reversed tests when generating the Xymon webpages.
This option makes xymonnet omit these flags from the status messages.
- By default, TCP tests run roughly in the order that the hosts are listed
in the hosts.cfg file. If you have many tests for one server, this may
result in an exceptionally large load when Xymon is testing it because
Xymon will perform a lot of tests at the same time. To avoid this, the
--shuffle option reorders the sequence of tests so they are spread
randomly across all of the servers tested.
Note: xymonnet uses the program defined by the FPING environment to execute
ping-tests - by default, that is the xymonping(1)
for a description of how to customize this, e.g. if
you need to run it with "sudo" or a similar tool.
- Enables xymonnet's ping test. The column name used for ping test results
is defined by the PINGCOLUMN environment variable in
If not specified, xymonnet uses the CONNTEST environment variable to
determine if it should perform the ping test or not. So if you prefer to
use another tool to implement ping checks, either set the CONNTEST
environment variable to false, or run xymonnet with the
- Disable the connectivity test.
- Enable/disable the use of traceroute when a ping-test fails. Performing a
traceroute for failed ping tests is a slow operation, so the default is
not to do any traceroute, unless it is requested on a per-host basis via
the "trace" tag in the hosts.cfg(5) entry for each host.
The "--trace" option changes this, so the default becomes to run
traceroute on all hosts where the ping test fails; you can then disable it
on specific hosts by putting a "notrace" tag on the host-entry.
- Spread the task of pinging the hosts over N processes. If you have a very
large number of hosts the time it takes to ping all of them can be
substantial, even with the use of tools like fping or xymonping that ping
many hosts in parallel. This option causes xymonnet to start N separate
ping processes, the IP's that are being ping'ed will be divided evenly
between these processes.
- Determines the name of the column Xymon displays for content checks. The
default is "content". If you have used the "cont.sh"
or "cont2.sh" scripts earlier, you may want to use
"--content=cont" to report content checks using the same test
name as these scripts do.
- Adhere to the Big Brother syntax for a URL, which allows specifying a HTTP
proxy as part of a URL. See "HTTP Testing via proxy" in
the hosts.cfg(5) file for details. Beginning with Xymon 4.3.0, this
behaviour is disabled by default since URL's that include other URL's are
now much more common. This option restores the old Big Brother-compatible
- Determines the name of the column Xymon displays for the SSL certificate
checks. The default is "sslcert".
- Disables reporting of the SSL certificate check.
- Determines the number of days before an SSL certificate expires, where
xymonnet will generate a warning or alarm status for the SSL certificate
- Enables checking that the encryption supported by the SSL protocol uses an
encryption key of at least N bits. E.g. to trigger an alert if your
SSL-enabled website supports less than 128 bits of encryption, use
"--sslbits=128". Note: This can be enabled on a per-host basis
using the "sslbits=N" setting in hosts.cfg(5)
- Enables checking of the length of the public key in SSL certificates. N is
the minimum size of the SSL public key, typically such keys are 2048 bits,
but some older certificates may use keys with 1024 bits or less. If you
specify this, SSL certificates with keys less than N bits will result in
the "sslcert" status going yellow. Default: 0, i.e. this check
- Do not show encryption cipher details on the "sslcert" status.
- List ALL locally available encryption ciphers on the "sslcert"
- Sets the default for whether SSL connections use SNI (Server Name
Indication). This can also be set with the "sni" or
"nosni" options in hosts.cfg for each host - the hosts.cfg
entries override this option. Default: off
- Don't send any status updates to the Xymon server. Instead, all messages
are dumped to stdout.
- Causes xymonnet to collect information about the time spent in different
parts of the program. The information is printed on stdout just before the
program ends. Note that this information is also included in the status
report sent with the "--report" option.
- Dumps a bunch of status about the tests as they progress to stdout.
- Dumps internal memory structures before and/or after the tests have
- --help or -?
- Provide a summary of available command-line options.
- Prints the version number of xymonnet
- Dump the list of defined TCP services xymonnet knows how to test. Do not
run any tests.
If the file $XYMONHOME/etc/cookies exist, cookies will be read from this file
and sent along with the HTTP requests when checking websites. This file is in
the Netscape Cookie format, see
http://www.netscape.com/newsref/std/cookie_spec.html for details on this
format. The curl(1)
utility can output a file in this format if run
with the "--cookie-jar FILENAME" option.
When xymonnet tests services that use SSL- or TLS-based protocols, it will check
that the server certificate has not expired. This check happens automatically
for https (secure web), pop3s, imaps, nntps and all other SSL-enabled services
(except ldap, see LDAP TESTS below).
All certificates found for a host are reported in one status message.
Note: On most systems, the end-date of the certificate is limited to Jan 19th,
2038. If your certificate is valid after this date, xymonnet will report it as
valid only until Jan 19, 2038. This is due to limitations in your operating
system C library. See http://en.wikipedia.org/wiki/2038_problem .
ldap testing can be done in two ways. If you just put an "ldap" or
"ldaps" tag in hosts.cfg, a simple test is performed that just
verifies that it is possible to establish a connection to the port running the
ldap service (389 for ldap, 636 for ldaps).
Instead you can put an LDAP URI in hosts.cfg. This will cause xymonnet to
initiate a full-blown LDAP session with the server, and do an LDAP search for
the objects defined by the URI. This requires that xymonnet was built with
LDAP support, and relies on an existing LDAP library to be installed. It has
been tested with OpenLDAP 2.0.26 (from Red Hat 9) and 2.1.22. The Solaris 8
system ldap library has also been confirmed to work for un-encrypted (plain
The format of LDAP URI's is defined in RFC 2255. LDAP URLs look like this:
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.
All "bind" operations to LDAP servers use simple authentication.
Kerberos and SASL are not supported. If your LDAP server requires a
username/password, use the "ldaplogin" tag to specify this, cf.
If no username/password information is provided, an
anonymous bind will be attempted.
SSL support requires both a client library and an LDAP server that support
LDAPv3; it uses the LDAP "STARTTLS" protocol request after
establishing a connection to the standard (non-encrypted) LDAP port (usually
port 389). It has only been tested with OpenSSL 2.x, and probably will not
work with any other LDAP library.
The older LDAPv2 experimental method of tunnelling normal LDAP traffic through
an SSL connection - ldaps, running on port 636 - is not supported, unless
someone can explain how to get the OpenLDAP library to support it. This method
was never formally described in an RFC, and implementations of it are
For a discussion of the various ways of running encrypted ldap, see
When testing LDAP URI's, all of the communications are handled by the ldap
library. Therefore, it is not possible to obtain the SSL certificate used by
the LDAP server, and it will not show up in the "sslcert" column.
If you have more than one system running network tests - e.g. if your network is
separated by firewalls - then is is problematic to maintain multiple hosts.cfg
files for each of the systems. xymonnet supports the NET:location tag in
to distinguish between hosts that should be tested from
different network locations. If you set the environment variable XYMONNETWORK
e.g. to "dmz" before running xymonnet, then it will only test hosts
that have a "NET:dmz" tag in hosts.cfg. This allows you to keep all
of your hosts in the same hosts.cfg file, but test different sets of hosts by
different systems running xymonnet.
xymonnet first reads the protocols.cfg file to see which network tests are
defined. It then scans the hosts.cfg file, and collects information about the
TCP service tests that need to be tested. It picks out only the tests that
were listed in the protocols.cfg file, plus the "dns",
"dig" and "ntp" tests.
It then runs two tasks in parallel: First, a separate process is started to run
the "xymonping" tool for the connectivity tests. While xymonping is
busy doing the "ping" checks, xymonnet runs all of the TCP-based
All of the TCP-based service checks are handled by a connection tester written
specifically for this purpose. It uses only standard Unix-style network
programming, but relies on the Unix "select(2)" system-call to
handle many simultaneous connections happening in parallel. Exactly how many
parallel connections are being used depends on your operating system - the
default is FD_SETSIZE/4, which amounts to 256 on many Unix systems.
You can choose the number of concurrent connections with the
"--concurrency=N" option to xymonnet.
Connection attempts timeout after 10 seconds - this can be changed with the
Both of these settings play a part in deciding how long the testing takes. A
conservative estimate for doing N TCP tests is:
(1 + (N / concurrency)) * timeout
In real life it will probably be less, as the above formula is for every test to
require a timeout. Since the most normal use of Xymon is to check for services
that are active, you should have a lot less timeouts.
The "ntp" and "rpcinfo" checks rely on external programs to
do each test.
- Defines the network segment where xymonnet is currently running. This is
used to filter out only the entries in the hosts.cfg(5) file that
have a matching "NET:LOCATION" tag, and execute the tests for
only those hosts.
- Defines the maximum number of status messages that can be sent in one
combo message. Default is 0 - no limit.
In practice, the maximum size of a single Xymon message sets a limit - the
default value for the maximum message size is 32 KB, but that will easily
accommodate 100 status messages per transmission. So if you want to
experiment with this setting, I suggest starting with a value of 10.
- Defines a a delay (in microseconds) after each message is transmitted to
the Xymon server. The default is 0, i.e. send the messages as fast as
possible. This gives your Xymon server some time to process the message
before the next message comes in. Depending on the speed of your Xymon
server, it may be necessary to set this value to half a second or even 1
or 2 seconds. Note that the value is specified in MICROseconds, so to
define a delay of half a second, this must be set to the value
"500000"; a delay of 1 second is achieved by setting this to
"1000000" (one million).
- Command used to run the xymonping(1) utility. Used by xymonnet for
connectivity (ping) testing. See xymonserver.cfg(5) for more
information about how to customize the program that is executed to do ping
- Location of the traceroute(8) utility, or an equivalent tool e.g.
mtr(8). Optionally used when a connectivity test fails to pinpoint
the network location that is causing the failure.
- Location of the ntpdate(1) utility. Used by xymonnet when checking
the "ntp" service.
- Location of the rpcinfo(8) utility. Used by xymonnet for the
"rpc" service checks.
- This file contains definitions of TCP services that xymonnet can test.
Definitions for a default set of common services is built into xymonnet,
but these can be overridden or supplemented by defining services in the
protocols.cfg file. See protocols.cfg(5) for details on this file.
- $XYMONHOME/etc/netrc - authentication data for password-protected
- If you have password-protected sites, you can put the usernames and
passwords for these here. They will then get picked up automatically when
running your network tests. This works for web-sites that use the
"Basic" authentication scheme in HTTP. See ftp(1) for
details - a sample entry would look like this
machine www.acme.com login fred password Wilma1
Note that the machine-name must be the name you use in the
http://machinename/ URL setting - it need not be the one you use for the
system-name in Xymon.
- This file may contain website cookies, in the Netscape HTTP Cookie format.
If a website requires a static cookie to be present in order for the check
to complete, then you can add this cookie to this file, and it will be
sent along with the HTTP request. To get the cookies into this file, you
can use the "curl --cookie-jar FILE" to request the URL that
sets the cookie.
- $XYMONTMP/*.status - test status summary
- Each time xymonnet runs, if any tests fail (i.e. they result in a red
status) then they will be listed in a file name
TESTNAME.[LOCATION].status. The LOCATION part may be null. This file is
used to determine how long the failure has lasted, which in turn decides
if this test should be included in the tests done by
It is also used internally by xymonnet when determining the color for tests
that use the "badconn" or "badTESTNAME" tags.
- This file contains the hostnames of those hosts that should be retested by
the xymonnet-again.sh(1) test tool. It is updated only by xymonnet
during the normal runs, and read by xymonnet-again.sh.
hosts.cfg(5), protocols.cfg(5), xymonserver.cfg(5), xymonping(1), curl(1),
ftp(1), fping(1), ntpdate(1), rpcinfo(8)