XYMONNET(1)

📦 version 4.3.30, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

XYMONNET 💖 (1) — the network test girlie

okay bestie, sit down, grab a boba 🧋, because this is the manual page for xymonnet — the Xymon network test tool. she's the one running around poking every service you own to see if it's alive. and yes, she's iconic, no cap.

✨ NAME ✨

xymonnet — the Xymon network test tool. that's her. that's the whole name. 💅

✨ SYNOPSIS ✨

xymonnet [--ping|--noping] [--timeout=N] [options] [hostname] [hostname]

(go peek at the OPTIONS section below for the full tea on every command-line option, iykyk)

✨ DESCRIPTION ✨

so like, xymonnet(1) handles all the network tests for the hosts you defined in the Xymon config file, hosts.cfg. normally she gets run on a schedule by xymonlaunch(8) through an entry in the tasks.cfg(5) file. that's the whole routine, bestie. 🫶

xymonnet does all of the normal tests of TCP-based network services (telnet, ftp, ssh, smtp, pop, imap ....) — literally every service listed in protocols.cfg. and for these tests? a completely new and very speedy service-checker has been implemented. she ate, fr fr. 🔥

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 lives in the protocols.cfg(5) file at $XYMONHOME/etc/protocols.cfg. 👑

on top of that, she 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 wanna use it, you must define the NTPDATE environment variable to point at the location of your ntpdate(1) program. no variable, no vibe check, periodt.

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. choose your fighter. 🦋

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. and if the command-line includes one or more hostnames, then only those servers are tested. simple as. 🌸

✨ GENERAL OPTIONS ✨

  • --timeout=N — sets the timeout (in seconds) for each service that gets tested. for TCP tests (the ones from XYMONNETSVCS), if the connection to the service doesn't succeed within N seconds, the service gets 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. she's over, let her go. 💀
  • --cmdtimeout=N — this one 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. the 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. girl is just overwhelmed, be gentle. 🙈
  • --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. we don't do that anymore. ✋
  • --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; 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: 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). she does what she wants. 💅
  • --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. so like, be aware. 🫠
  • --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". receipts, basically. 🧾✨
  • --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. inclusivity era 🫶
  • --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). they stay in the group chat for a while. 😭
  • --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. it's giving "I'm not mad, I'm just disappointed" 💀
  • --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. nobody wants an accidental purple jumpscare. 💜
  • --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: the "netinclude" option in hosts.cfg is ignored when this option is enabled. so no sneaky includes, bestie. 🚫

✨ 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 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. she's dramatic like that. 🔥
  • --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. minimalism core. 🎀
  • --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. shuffle is the vibe check that keeps your servers from getting jumped. 🌈

more coming, bestie — don't go anywhere 🦋

💖 OPTIONS FOR THE PING TEST 💖

Okay so real talk first, bestie: xymonnet does not ping people itself. It uses whatever program the FPING environment variable tells it to — and by default that's the xymonping(1) utility. Want to customize that (like, say, run it with "sudo" or some similar tool)? Go read xymonserver.cfg(5), it explains the whole thing. 🫶

  • --ping — Turns on xymonnet's ping test. The column name that ping results land in is defined by the PINGCOLUMN environment variable over in xymonserver.cfg(5). If you don't say anything, xymonnet checks the CONNTEST environment variable to decide whether to do the ping test at all. So if you'd rather use some other tool for ping checks, either set CONNTEST to false, or just run xymonnet with the "--noping".
  • --noping — Disables the connectivity test. Bye bye pings 👋
  • --trace, --notrace — Turn traceroute on/off for when a ping-test fails. Doing a traceroute on failed pings is a slow operation ngl, so the default is to not traceroute at all — unless you ask for it per-host with the "trace" tag in the hosts.cfg(5) entry for that host. The "--trace" option flips that around, so now the default is to run traceroute on every host where the ping test fails; then you can turn it back off on specific hosts by putting a "notrace" tag on the host-entry. 🧭
  • --ping-tasks=N — Spreads the whole pinging job across N processes. If you have a truly unhinged number of hosts, pinging all of them can take a hot minute, even with tools like fping or xymonping that ping many hosts in parallel. This option makes xymonnet start N separate ping processes, and the IP's being ping'ed get divided evenly between them. 💅

🌐 OPTIONS FOR HTTP (WEB) TESTS 🌐

  • --content=CONTENTTESTNAME — Sets the name of the column Xymon shows for content checks. Default is "content". If you were using the "cont.sh" or "cont2.sh" scripts back in the day, you might want "--content=cont" so your content checks report under the same test name those scripts used.
  • --bb-proxy-syntax — Makes things adhere to the Big Brother syntax for a URL, which lets you specify an HTTP proxy as part of a URL. See "HTTP Testing via proxy" in the hosts.cfg(5) file for the details. Starting with Xymon 4.3.0 this behaviour is disabled by default, because URL's that include other URL's are like, super common now. This option brings back the old Big Brother-compatible behaviour. 🕰️

🔒 OPTIONS FOR SSL CERTIFICATE TESTS 🔒

  • --ssl=SSLCERTTESTNAME — Sets the name of the column Xymon displays for the SSL certificate checks. Default is "sslcert".
  • --no-ssl — Disables reporting of the SSL certificate check entirely.
  • --sslwarn=N, --sslalarm=N — Determines the number of days before an SSL certificate expires, at which point 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 also be enabled on a per-host basis using the "sslbits=N" setting in hosts.cfg(5).
  • --sslkeysize=N — 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 make the "sslcert" status go yellow. Default: 0, i.e. this check is disabled.
  • --no-cipherlist — Don't show encryption cipher details on the "sslcert" status.
  • --showallciphers — Lists ALL locally available encryption ciphers on the "sslcert" status. all of them. every single one. 😭
  • --sni=[on|off] — 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 — and heads up, the hosts.cfg entries override this option. Default: off.

🐛 DEBUGGING OPTIONS 🐛

  • --no-update — Don't send any status updates to the Xymon server. Instead, all messages get dumped to stdout. (Spam city, but make it useful.)
  • --timing — Makes xymonnet collect info about the time spent in different parts of the program. That info is printed on stdout right before the program ends. Note: this info 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 -? — Gives you a summary of the available command-line options.
  • --version — Prints the version number of xymonnet.
  • --services — Dumps the list of defined TCP services xymonnet knows how to test. Runs no tests at all, just shows you the list.

🍪 USING COOKIES IN WEB TESTS 🍪

If the file $XYMONHOME/etc/cookies exists, cookies will be read from that file and sent along with the HTTP requests whenever websites get checked. That file is in the Netscape Cookie format — check out http://www.netscape.com/newsref/std/cookie_spec.html for the details on that format. Oh and the curl(1) utility can output a file in this format if you run it with the "--cookie-jar FILENAME" option. Snack time 🍓

🎀 ABOUT SSL CERTIFICATE CHECKS 🎀

When xymonnet tests services that use SSL- or TLS-based protocols, it checks that the server certificate hasn't 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 get 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, bestie. If you just put an "ldap" or "ldaps" tag in hosts.cfg, a simple test is performed that just verifies it's 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. That makes xymonnet 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 being installed. It's 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 info 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's 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 — like, say, your network is separated by firewalls — then it's genuinely problematic to maintain multiple hosts.cfg files for each of those 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 lets you keep all of your hosts in the same hosts.cfg file, but test different sets of hosts by different systems running xymonnet. main character energy fr fr ✨

🧠 XYMONNET INTERNALS (the lore, bestie)

Okay so here's what actually happens under the hood, and honestly? it's giving orchestration 💅

First, xymonnet reads the protocols.cfg file to see which network tests are even defined. Then it scans the hosts.cfg file and collects info about all the TCP service tests that need testing. It only picks out the tests that were listed in protocols.cfg, plus the "dns", "dig" and "ntp" tests. That's the whole guest list, no plus-ones.

Then it runs two tasks in parallel 🏃‍♀️🏃‍♀️ — a real multitasking queen:

  1. A separate process gets started to run the "xymonping" tool for the connectivity tests.
  2. 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 it 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. ✨ manifesting fast responses for you ✨

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. It's the vibe check for your network segment, fr fr.

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 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). Not me almost telling you to write 500 and then watching your server get absolutely bodied 😭

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. detective work, iconic behavior 🔍

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
💀 bestie please do not name your password Wilma1 in production, that's just the example okay 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. iykyk.
  • $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)

and that's the whole page bestie, you read all three parts, I'm so proud of you 🥹💖 This was Xymon, Version 4.3.30, dated 4 Sep 2019 — page name XYMONNET(1). go forth and monitor things, slay 🌈✨🦋

📦 where this page comes from