Provided by: xymon_4.3.7-1ubuntu2_amd64 
NAME
xymonnet - Xymon network test tool
SYNOPSIS
xymonnet [--ping|--noping] [--timeout=N] [options] [hostname] [hostname]
(See the OPTIONS section for a description of the available command-line options).
DESCRIPTION
xymonnet(1) handles the network tests of hosts defined in the Xymon configuration file,
hosts.cfg. It is normally run at regular intervals by xymonlaunch(8) via an entry in the
tasks.cfg(5) file.
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) file in $XYMONHOME/etc/protocols.cfg.
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) program.
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 xymonserver.cfg(5) 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.
GENERAL OPTIONS
--timeout=N
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
--conntimeout=N
This option is deprecated, and will be ignored. Use the --timeout option instead.
--cmdtimeout=N
This option sets a timeout for the external commands used for testing of NTP and
RPC services, and to perform traceroute.
--concurrency=N
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.
--dns-max-all=N
Same as "--dns-timeout=N". The "--dns-max-all" option is deprecated and should not
be used.
--dns=[ip|only|standard]
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; it 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)
--no-ares
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.
--dnslog=FILENAME
Log failed hostname lookups to the file FILENAME. FILENAME should be a full
pathname.
--report[=COLUMNNAME]
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".
--test-untagged
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 tested.
--frequenttestlimit=N
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).
--timelimit=N
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.
--huge=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 replies.
Default: 0 (disabled).
--validity=N
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.
--source-ip=IPADDRESS
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.
--loadhostsfromxymond
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.
OPTIONS FOR TESTS OF THE SIMPLE TCP SERVICES
--checkresponse[=COLOR]
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
reponse 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.
--no-flags
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.
--shuffle
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.
OPTIONS FOR THE PING TEST
Note: xymonnet uses the program defined by the FPING environment to execute ping-tests -
by default, that is the xymonping(1) utility. See xymonserver.cfg(5) for a description of
how to customize this, e.g. if you need to run it with "sudo" or a similar tool.
--ping Enables xymonnet's ping test. The column name used for ping test results is defined
by the PINGCOLUMN environment variable in xymonserver.cfg(5).
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 "--noping".
--noping
Disable the connectivity test.
--trace
--notrace
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.
--ping-tasks=N
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.
OPTIONS FOR HTTP (WEB) TESTS
--content=CONTENTTESTNAME
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.
--bb-proxy-syntax
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 behaviour.
OPTIONS FOR SSL CERTIFICATE TESTS
--ssl=SSLCERTTESTNAME
Determines the name of the column Xymon displays for the SSL certificate checks.
The default is "sslcert".
--no-ssl
Disables reporting of the SSL certificate check.
--sslwarn=N
--sslalarm=N
Determines the number of days before an SSL certificate expires, where xymonnet
will generate a warning or alarm status for the SSL certificate column.
--sslbits=N
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)
DEBUGGING OPTIONS
--no-update
Don't send any status updates to the Xymon server. Instead, all messages are dumped
to stdout.
--timing
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.
--debug
Dumps a bunch of status about the tests as they progress to stdout.
--dump[=before|=after|=both]
Dumps internal memory structures before and/or after the tests have executed.
INFORMATIONAL OPTIONS
--help or -?
Provide a summary of available command-line options.
--version
Prints the version number of xymonnet
--services
Dump the list of defined TCP services xymonnet knows how to test. Do not run any
tests.
USING COOKIES IN WEB 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.
ABOUT SSL CERTIFICATE CHECKS
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 TESTS
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 ldap) access.
The format of LDAP URI's is defined in RFC 2255. LDAP URLs look like this:
ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]]
where:
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.
Example:
ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*)
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. hosts.cfg(5) 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 non-standard.
For a discussion of the various ways of running encrypted ldap, see
http://www.openldap.org/lists/openldap-software/200305/msg00079.html
http://www.openldap.org/lists/openldap-software/200305/msg00084.html
http://www.openldap.org/lists/openldap-software/200201/msg00042.html
http://www.openldap.org/lists/openldap-software/200206/msg00387.html
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.
USING MULTIPLE NETWORK TEST SYSTEMS
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 hosts.cfg(5) 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 INTERNALS
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 network tests.
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 "--timeout=N"
option.
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.
ENVIRONMENT VARIABLES
XYMONNETWORK
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.
MAXMSGSPERCOMBO
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.
SLEEPBETWEENMSGS
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).
FPING 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 tests.
TRACEROUTE
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.
NTPDATE
Location of the ntpdate(1) utility. Used by xymonnet when checking the "ntp"
service.
RPCINFO
Location of the rpcinfo(8) utility. Used by xymonnet for the "rpc" service checks.
FILES
~/server/etc/protocols.cfg
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 webs
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.
$XYMONHOME/etc/cookies
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
xymonnet-again.sh(1)
It is also used internally by xymonnet when determining the color for tests that
use the "badconn" or "badTESTNAME" tags.
$XYMONTMP/frequenttests.[LOCATION]
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.
SEE ALSO
hosts.cfg(5), protocols.cfg(5), xymonserver.cfg(5), xymonping(1), curl(1), ftp(1),
fping(1), ntpdate(1), rpcinfo(8)