XYMON(1)

📦
version 4.3.30 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ xymon — the manual, but make it cute ✨

okay bestie, gather round, because xymon(1) is literally the whole vibe of the Xymon client communication program 💖 it's the little program that talks to your Xymon server, and she is busy.

🌸 NAME 🌸

xymon — the Xymon client communication program 🫶

🎀 SYNOPSIS 🎀

xymon [options] RECIPIENT message

like... that's the shape of it. options, then who you're sending to, then the message. slay ✨

💅 DESCRIPTION 💅

So xymon(1) is the client program you use to communicate with a Xymon server. That's the whole job. She's the messenger 🦋

She gets used constantly by Xymon client systems to send in status messages and pager alerts on local tests. Every time your little client box has something to say, this is how it says it.

But wait, there's more — in Xymon, the xymon program is also the admin bestie. Like, renaming or deleting hosts? Disabling hosts that are gonna be down for a while? Yeah. That's her too. Main character energy fr fr 👑

✨ OPTIONS AND PARAMETERS ✨

  • --debug — turns on debugging. She'll print out all the deets about how the connection to the Xymon server is being established. nosy in the best way 🔍
  • --proxy=http://PROXYSERVER:PROXYPORT/ — when you're sending status messages via HTTP, use this server as an HTTP proxy instead of connecting straight to the Xymon server. go-between era 💫
  • --timeout=N — sets the timeout for connecting to the Xymon server, in seconds. The default is 5 seconds. no waiting around forever, periodt ⏰
  • --response — okay so xymon normally knows when to expect a response from the server, so honestly this option is not required. BUT if you use it, any response from the server gets displayed. curious girlies only 🙈
  • --merge — merge the command line message text with the data you're piping in on standard input, and send the combined result to the Xymon server. The message text you gave on the command line becomes the first line of the merged message. it's giving teamwork 🤝
  • RECIPIENT — this parameter defines which server receives the message.
    • If RECIPIENT is given as "0.0.0.0", then the message gets sent to all of the servers listed in the XYMSERVERS environment variable. broadcast queen 📢
    • Usually, a client will use "$XYMSRV" for the RECIPIENT parameter, because that's defined for the client scripts to automatically contain the correct value. iykyk 💜
    • The RECIPIENT parameter may also be a URL for a webserver that has the xymoncgimsg.cgi or similar script installed. This tunnels the Xymon messages to the Xymon server using standard HTTP protocol. Heads up though: the xymoncgimsg.cgi(8) CGI tool (included in Xymon) must be installed on the webserver for the HTTP transport to work. no script, no tunnel, bestie 🚧
  • MESSAGE — this is the message being sent across to the Xymon server. Messages must be enclosed in quotes, but here's the cute part: by quoting them they can span multiple lines. 💖
    • The maximum size of a message is defined by the maximum allowed length of your shell's command-line, and is typically 8-32 KB.
    • If you need to send longer status messages, you can specify "@" as the message: xymon will then read the status message from its stdin. tiny little handoff, huge results 🎀

🌈 XYMON MESSAGE SYNTAX 🌈

This section lists the most commonly used messages in the Xymon protocol. sit down, hydrate, we're going through all of them 💧

Each message must begin with one of the Xymon commands. Where a HOSTNAME is specified, it must have any dots in the hostname changed to commas if the Xymon FQDN setting is enabled (which is the default). So the host "www.foo.com", for example, would report as "www,foo,com". commas not dots, got it? ⭐

  • status[+LIFETIME][/group:GROUP] HOSTNAME.TESTNAME COLOR <additional text> — This sends in a status message for a single test (column) on a single host.
    • TESTNAME is the name of the column where this test will show up; any name is valid except that using dots in the testname will not work. (rude but true 💀)
    • COLOR must be one of the valid colors: "green", "yellow", "red" or "clear". The colors "blue" and "purple" — although valid colors — should not be sent in a status message, because these are handled specially by the Xymon server. don't do it, she'll handle those herself 🙅‍♀️
    • As a special case (for supporting older clients), "client" can be used as the name of the color. This causes the status message to be handled by Xymon as a "client" data message, and the TESTNAME parameter is used as the "collector id". vintage support, iconic ✨
    • The "additional text" normally includes a local timestamp and a summary of the test result on the first line. Any lines following the first one are free-form, and can include any information that may be useful to diagnose the problem being reported. spill the tea, it's for diagnostics 🍵
    • The LIFETIME defines how long this status is valid after being received by the Xymon server. The default is 30 minutes, but you can set any period you like. E.g. for a custom test that runs once an hour, you will want to set this to at least 60 minutes — otherwise the status will go purple after 30 minutes. 😭
    • It is a good idea to set the LIFETIME to slightly longer than the interval between your tests, to allow for variations in the time it takes your test to complete.
    • The LIFETIME is in minutes, unless you add an "h" (hours), "d" (days) or "w" (weeks) immediately after the number, e.g. "status+5h" for a status that is valid for 5 hours.
    • The GROUP option is used to direct alerts from the status to a specific group. It is currently used for status generated from the Xymon clients' data, e.g. to direct alerts for a "procs" status to different people, depending on exactly which process is down. targeted notifs, we love to see it 🎯
  • notify HOSTNAME.TESTNAME <message text> — This triggers an informational message to be sent to those who receive alerts for this HOSTNAME+TESTNAME combination, according to the rules defined in alerts.cfg(5). This is used by the enadis.cgi(1) tool to notify people about hosts being disabled or enabled, but it can also serve as a general way of notifying server administrators. hey bestie, heads up 📣
  • data HOSTNAME.DATANAME<newline><additional text> — The "data" message allows tools to send data about a host, without it appearing as a column on the Xymon webpages. This is used, for example, to report statistics about a host, e.g. vmstat data, which does not in itself represent something that has a red, yellow or green identity. It is used by RRD bottom-feeder modules, among others. In Xymon, data messages are by default processed only by the xymond_rrd(8) module. If you want to handle data-messages using an external application, you may want to enable the xymond_filestore(8) module for data-messages, to store data-messages in a format compatible with how the Big Brother daemon does. off-the-record data, love that for her 📊
  • disable HOSTNAME.TESTNAME DURATION <additional text> — Disables a specific test for DURATION minutes. This will cause the status of this test to be listed as "blue" on the Xymon server, and no alerts for this host/test will be generated. If DURATION is given as a number followed by s/m/h/d, it is interpreted as being in seconds/minutes/hours/days respectively. To disable a test until it becomes OK, use "-1" as the DURATION. To disable all tests for a host, use an asterisk "*" for TESTNAME. silencing the noise, self-care tbh 💙
  • enable HOSTNAME.TESTNAME — Re-enables a test that had been disabled. she's back, baby 🫶
  • query HOSTNAME.TESTNAME — Query the Xymon server for the latest status reported for this particular test. If the host/test status is known, the response is the first line of the status report — the current color will be the first word on the line. Additional lines of text that might be present on the status message cannot be retrieved. This allows any Xymon client to determine the status of a particular test, whether it is one pertaining to the host where the client is running, some other host, or perhaps the result of a combined test from multiple hosts managed by combostatus(1). This will typically be useful to Xymon client extension scripts, that need to determine the status of other hosts, for example, to decide if an automatic recovery action should be initiated. just asking, no big deal 💅
  • config FILENAME — Retrieve one of the Xymon configuration files from the server. This command allows a client to pull files from the $XYMONHOME/etc/ directory on the server, allowing for semi-automatic updates of the client configuration. Since the configuration files are designed to have a common file for the configuration of all hosts in the system — and this is in fact the recommended way of configuring your clients — this makes it easier to keep the configuration files synchronized. one file to rule them all, synchronized and stunning 🎀
  • drop HOSTNAME — Removes all data stored about the host HOSTNAME. It is assumed that you have already deleted the host from the hosts.cfg configuration file. bye forever, but do your homework first 📝
  • drop HOSTNAME TESTNAME — Remove data about a single test (column). just the one, surgical 🦋
  • rename OLDHOSTNAME NEWHOSTNAME — Rename all data for a host that has had its name changed. You should do this after changing the hostname in the hosts.cfg configuration file. glow-up, but in the right order ⭐
  • rename HOSTNAME OLDTESTNAME NEWTESTNAME — Rename data about a single test (column). same energy, one column 💜
  • xymondlog HOSTNAME.TESTNAME — Retrieve the Xymon status-log for a single test. The first line of the response contains a series of fields separated by a pipe-sign:
    • hostname — The name of the host
    • testname — The name of the test
    • color — Status color (green, yellow, red, blue, clear, purple)
    • testflags — For network tests, the flags indicating details about the test (used by xymongen).
    • lastchange — Unix timestamp when the status color last changed.
    • logtime — Unix timestamp when the log message was received.
    • validtime — Unix timestamp when the log message is no longer valid (it goes purple at this time).
    • acktime — Either -1 or Unix timestamp when an active acknowledgement expires.
    • disabletime — Either -1 or Unix timestamp when the status is no longer disabled.
    • sender — IP address where the status was received from.
    • cookie — Either -1 or the cookie value used to acknowledge an alert.
    • ackmsg — Empty or the acknowledgment message sent when the status was acknowledged. Newline, pipe-signs and backslashes are escaped with a backslash, C-style.
    • dismsg — Empty or the message sent when the status was disabled. Newline, pipe-signs and backslashes are escaped with a backslash, C-style.
    • After the first line comes the full status log in plain text format.
  • xymondxlog HOSTNAME.TESTNAME — Retrieves an XML string containing the status log as with the "xymondlog" command. same tea, XML edition ✨
  • xymondboard [CRITERIA] [fields=FIELDLIST] — Retrieves a summary of the status of all known tests available to the Xymon daemon.

okay so real talk 💖 by default — like, if you hand over no CRITERIA at all — it just dumps one line for every single status message it can find in Xymon. That's the whole vibe. But bestie you can absolutely filter that response down: pick a specific page, host, test, color, or a bunch of other fields, and it'll only serve you what you asked for. ✨

Here's the tea on how the params behave, because they do not all work the same way:

  • The PAGEPATH, NETWORK, HOSTNAME, TESTNAME, and *MSG parameters are interpreted as perl-compatible regular expressions 🦋
  • The COLOR parameter accepts multiple colors separated by commas
  • The *TIME values accept unix epoch timestamps

Other variables identified in xymon-xmh(5) may also be used. 🌸

speed tip, no cap ⚡ — because host filtration is done before test filtration, it's more efficient (with very large data sets) to use PAGEPATH, HOSTNAME, NETWORK, and other XMH_ filters when possible, before you go globally filtering with COLOR, *MSG, *TIME, or TESTNAME. Basically: narrow by host first, get specific later. Main character energy for your query planner. 👑

And yes, you can stack them — filter on, for example, both a hostname and a testname. Two filters, one icon. 💅

🌈 the filter squad 🌈

  • page=PAGEPATH — include only tests from hosts found on the PAGEPATH page in the hosts.cfg file. 📄
  • net=NETWORK — include only tests from hosts with this NET: tag.
  • ip=IPAddress — include only tests from hosts with this IP address. This is a regex, not CIDR. Don't come at it with a /24, it will not understand you. 😭
  • host=HOSTNAME — include only tests from the host HOSTNAME.
  • test=TESTNAME — include only tests with the testname TESTNAME.
  • color=COLORNAME — include only tests where the status color is COLORNAME.
  • tag=TAGNAME — include only hosts with a certain tag specified in the hosts.cfg(5) line. Note: only items known to xymon components are included here — arbitrary text is not included. 🙈
  • XMH_string=VALUE — include only hosts with a xymon-xmh(5) variable matching this value.

✨ Advanced Filtering ✨

  • msg=MESSAGE — include only tests with full content matching MESSAGE. Use "\s" to escape spaces (or other PCRE strings). 🫶
  • ackmsg=MESSAGE — include only tests with acknowledgement(s) MESSAGE. Use "\s" to escape spaces (or other PCRE strings).
  • dismsg=MESSAGE — include only tests that have been disabled with strings matching MESSAGE. Use "\s" to escape spaces (or other PCRE strings). Pro tip: it is most efficient to pair this with color=blue. 💙

⏰ Timestamp Filters ⏰

Certain fields (explained below) can be filtered with unix timestamps and with the following inequalities:

>= > <= < = !=

These filters are: lastchange, logtime, validtime, acktime, disabletime. 🕰️

The response is one line for each status that matches the CRITERIA, or all statuses if no criteria is specified. Each line is composed of a number of fields, separated by a pipe-sign. You get to choose which fields come back by listing them in the FIELDLIST. Here's everything on the menu: 🍓

  • hostname — the name of the host.
  • testname — the name of the test.
  • color — status color (green, yellow, red, blue, clear, purple).
  • flags — for network tests, the flags indicating details about the test (used by xymongen).
  • lastchange — unix timestamp when the status color last changed.
  • logtime — unix timestamp when the log message was received.
  • validtime — unix timestamp when the log message is no longer valid (it goes purple at this time).
  • acktime — either -1 or the Unix timestamp when an active acknowledgement expires.
  • disabletime — either -1 or the Unix timestamp when the status is no longer disabled.
  • sender — IP address where the status was received from.
  • cookie — either -1 or the cookie value used to acknowledge an alert.
  • line1 — first line of status log.
  • ackmsg — empty (if no acknowledgement is active), or the text of the acknowledge message.
  • dismsg — empty (if the status is currently enabled), or the text of the disable message.
  • msg — the full text of the current status message.
  • client — shows "Y" if there is client data available, "N" if not.
  • clntstamp — timestamp when the last client message was received, in Unix "epoch" format.
  • acklist — list of the current acknowledgements for a test. This is a text string with multiple fields, delimited by a colon character. There are 5 fields: timestamp for when the ack was generated and when it expires; the "ack level"; the user who sent the ack; and the acknowledgement text.
  • flapinfo — tells if the status is flapping. 5 fields, delimited by "/": a "0" if the status is not flapping and "1" if it is flapping; timestamp when the latest status change was recorded and when the first statuschange was recorded; and the two colors that the status is flapping between. 🦋
  • stats — number of status-changes that have been recorded for this status since xymond was started.
  • modifiers — lists all active modifiers for this status (i.e. updates sent using a "modify" command).
  • XMH_* — the XMH-tags refer to the Xymon hosts.cfg(5) configuration settings. A full list of these can be found in the xymon-xmh(5) man-page.
⚠️ heads up bestie: the ackmsg, dismsg and msg fields have certain characters encoded. Newline is "\n", TAB is "\t", carriage return is "\r", a pipe-sign is "\p", and a backslash is "\\". It's giving escape-room, but make it data. 💀

If the "fields" parameter is omitted, a default set of hostname,testname,color,flags,lastchange,logtime,validtime,acktime,disabletime,sender,cookie,line1 is used. ✨

🎀 xymondxboard 🎀

Retrieves an XML string with the summary of all status logs as for the "xymondboard" command. XML girlies rise. 🙌

💖 hostinfo [CRITERIA] 💖

Retrieves the current configuration of a host (i.e. the hosts.cfg(5) definition). CRITERIA selects which host(s) to report, and is identical to the CRITERIA in the xymondboard command. Same rules, different toy.

The response is one line for each host that matches the CRITERIA, or all hosts if no criteria is specified. The line is composed of a number of fields, separated by a pipe-sign. The first two fields will always be the hostname and the IP-address. The remaining fields — if any — are the hosts.cfg tags in no particular order. Don't @ me about the ordering, it's vibes-based. 😌

📥 download FILENAME 📥

Download a file from the Xymon server's download directory. Grab and go, bestie. 🫳

🧚 client[/COLLECTORID] HOSTNAME.OSTYPE [HOSTCLASS] 🧚

Used to send a "client" message to the Xymon server. Client messages are generated by the Xymon client; when sent to the Xymon server they are matched against the rules in the analysis.cfg(5) configuration file, and status messages are generated for the client-side tests. The COLLECTORID is used when sending client-data that are additions to the standard client data. The data will be concatenated with the normal client data. 🧩

📜 clientlog HOSTNAME [section=SECTIONNAME[,SECTIONNAME...]] 📜

Retrieves the current raw client message last sent by HOSTNAME. The optional "section" filter is used to select specific sections of the client data. Slice it however you want. 🍰

🏓 ping 🏓

Attempts to contact the Xymon server. If successful, the Xymon server version ID is reported. It's literally just "u up?" but for daemons. 💅

🌸 pullclient 🌸

This message is used when fetching client data via the "pull" mechanism implemented by xymonfetch(8) and msgcache(8) for clients that cannot connect directly to the Xymon server. Shy clients deserve love too. 🥺

👻 ghostlist 👻

Report a list of ghost clients seen by the Xymon server. Ghosts are systems that report data to the Xymon server, but are not listed in the hosts.cfg file. Spooky. They're here, they're reporting, they're not on the guest list. 🎃

🗓️ schedule [TIMESTAMP COMMAND] 🗓️

Schedules a command sent to the Xymon server for execution at a later time. E.g. used to schedule disabling of a host or service at sometime in the future. COMMAND is a complete Xymon command such as the ones listed above. TIMESTAMP is the Unix epoch time when the command will be executed. Future-you says thanks. ⏳

If no parameters are given, the currently scheduled tasks are listed in the response. The response is one line per scheduled command, with the job-id, the time when the command will be executed, the IP address from which this was sent, and the full command string.

To cancel a previously scheduled command, "schedule cancel JOBID" can be used. JOBID is a number provided as the first item in the output from the schedule list. ✂️

📝 notes FILENAME 📝

The message text will be stored in $XYMONHOME/notes/FILENAME which is then used as hyperlinks from hostnames or column names. This requires that the "storenotes" task is enabled in tasks.cfg (it is disabled by default ⚠️). FILENAME cannot contain any directory path — these are stripped automatically. No sneaky ../ shenanigans, bestie. 🚫

📨 usermsg ID 📨

These messages will be relayed directly to modules listening on the "user" channel of the Xymon daemon. This is intended for custom communication between client-side modules and the Xymon server. Private group chat, but make it daemons. 💬

🎨 modify HOSTNAME.TESTNAME COLOR SOURCE CAUSE 🎨

Modify the color of a specific status, without generating a complete status message. This is for backend processors (e.g. RRD graphs) that can override the color of a status based on some criteria determined outside the normal flow of a status. E.g. the normal "conn" status may appear to be green since it merely checks on whether a host can be ping'ed or not; the RRD handler can then use a "modify" command to override this is the actual ping responsetime exceeds a given threshold. (See the "DS" configuration setting in analysis.cfg(5) for how to do this.) 🔥

SOURCE is some identification of the module that generates the "modify" message — future modifications must use the same source. There may be several sources that modify the same status (the most severe status then becomes the actual color of the status). CAUSE is a one-line text string explaining the reason for overriding the normal status color — it will be displayed on the status webpage. 👑

🌟 EXAMPLE 🌟

Okay bestie, here's the vibe in action. Sending a normal status message to the Xymon server, using the standard Xymon protocol on TCP port 1984:

$ $XYMON $XYMSRV "status www,foo,com.http green `date` Web OK"

Same status message, but this time we're going through the HTTP protocol via the webserver's xymoncgimsg.cgi script instead:

$ $XYMON http://bb.foo.com/cgi-bin/xymoncgimsg.cgi "status www,foo,com.http green `date` Web OK"

Now let's use a query message to find out the color of the www test, and restart Apache if it's red 🔥:

$ WWW=`$XYMON $XYMSRV "query www,foo,com.www" | awk '{print $1}'`
$ if [ "$WWW" = "red" ]; then /etc/init.d/apache restart; fi

Next up, a config message to update a local mytest.cfg file — but only if we actually get a response back (we're not out here clobbering our config for nothing 💅):

$ $XYMON $XYMSRV "config mytest.cfg" >/tmp/mytest.cfg.new
$ if [ -s /tmp/mytest.cfg.new ]; then
    mv /tmp/mytest.cfg.new $XYMONHOME/etc/mytest.cfg
  fi

And finally, sending a very large status message that's been built up in the file statusmsg.txt. Instead of putting it on the command-line, you pass it via stdin to the xymon command. Obsessed, honestly:

$ cat statusmsg.txt | $XYMON $XYMSRV "@"

👀 SEE ALSO 👀

And that's the whole page, bestie — you ate that 🫶 Xymon, Version 4.3.30, dated 4 Sep 2019. Go forth and monitor literally everything ✨💖

📦 where this page comes from