HOSTS.CFG(5)

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

💖 HOSTS.CFG — the manual page, bestie edition 💖

okay so this is hosts.cfg(5) from the File Formats Manual and it is THE most important file in the whole Xymon universe. Sit down, grab a snack 🍓, we're doing this.

✨ NAME ✨

hosts.cfg — the main Xymon configuration file. That's it, that's the name, iconic behavior honestly 👑

✨ SYNOPSIS ✨

hosts.cfg

✨ DESCRIPTION ✨

So hosts.cfg(5) is literally the most important configuration file for all the Xymon programs — no cap, every single one. It holds the full list of every system Xymon monitors, plus all the tests and other config items stored for each host. It's giving main character energy for real. 💅

✨ FILE FORMAT ✨

Each line of the file = one host. Simple as that. 🦋

Blank lines? Ignored. Lines starting with a hash mark (#)? Also ignored, they're just comments, they said nothing and we respect that. 🙈

Long lines can be broken up by putting a backslash at the end of the line and continuing the entry on the next line — the way that a backslash literally saves you from the world's longest line, obsessed.

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

IP-address hostname # tag1 tag2 ...

The IP-address and hostname are mandatory — all of the tags are optional. If you list a host with only IP-address and hostname, a network test gets executed for the host. And bestie, what's running by default? The connectivity test, that's it — enabled by default, but no other tests. Minimalist queen. ✨

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

There's an example of setting up the hosts.cfg file in the Xymon on-line documentation — from the Help menu, choose "Configuring Monitoring". And the following describes the possible settings in a hosts.cfg file supported by Xymon. (Yes, the following is a lot. We stay hydrated. 💜)

✨ TAGS RECOGNIZED BY ALL TOOLS ✨

  • include filename — this tag pulls another file into the hosts.cfg file at run-time, so a huge hosts.cfg can be split up into more manageable pieces. We love organization. 🎀

The filename argument should point to a file that uses the same syntax as hosts.cfg. The filename can be an absolute filename (if it begins with a /), or a relative filename — relative file names are prefixed with the directory where the main hosts.cfg file is located (usually $XYMONHOME/etc/).

You can nest include tags, i.e. a file that is included from the main hosts.cfg file can itself include other files. Includes within includes. It's giving inception. 😭

  • dispinclude filename — acts like the include tag, but only for the xymongen tool. Can be used e.g. to put a group of hosts on multiple sub-pages, without having to repeat the host definitions. Say it with me: no repeat, no problem. 💅
  • netinclude filename — acts like the include tag, but only for the xymonnet tool. Same energy, different audience.
  • directory directoryname — this tag includes all files in the named directory. Files are included in alphabetical order. If there are sub-directories, these are recursively included also. But bestie, some files are NOT invited to the party — the following are ignored:
    • files that begin with a dot
    • files that end with a tilde
    • RCS files that end with ,v
    • RPM package manager files ending in .rpmsave or .rpmnew
    • DPKG package manager files ending in .dpkg-new or .dpkg-orig
    • and all special files (devices, sockets, pipes etc)

It's giving strict guest list and honestly? Fair. 🚫

  • optional include/directory — both include and directory can be prefixed with the tag optional, which will prevent an error message being logged if the file or directory is not present on a system. So chill. So forgiving. We stan a low-maintenance config. 🫶

✨ GENERAL PER-HOST OPTIONS ✨

  • noclear — controls whether stale status messages go purple or clear when a host is down. Normally, when a host is down the client statuses (cpu, disk, memory etc) will stop updating — this would usually make them go "purple" which can trigger alerts. To avoid that, Xymon checks if the conn test has failed, and if that is true then the other tests will go "clear" instead of purple, so you only get alerts for the conn test. If you do want the stale statuses to go purple, you can use the noclear tag to override this behaviour. You're the main character, you get to choose. 👑
Heads up bestie: noclear also affects the behaviour of network tests; see below. 👀
  • prefer — when a single host is defined multiple times in the hosts.cfg file, xymongen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other xymongen-specific settings. Host definitions that have a noconn tag or an IP of 0.0.0.0 get lower priority. Oof, ranking. 💀

By using the prefer tag you tell xymongen that this host definition should be used.

Note: This only applies to hosts that are defined multiple times in the hosts.cfg file, although it will not hurt to add it on other hosts as well. (Adding it anywhere is harmless. Go off, tag it up. ✨)
  • multihomed — tells Xymon that data from the host can arrive from multiple IP-addresses. By default, Xymon will warn if it sees data for one host coming from different IP-addresses, because this usually indicates a mis-configuration of the hostname on at least one of the servers involved. Some hosts with multiple IP-addresses may use different IP's for sending data to Xymon, however. This tag disables the check of source IP when receiving data. Not me letting a host have multiple home addresses 🏠🏠
  • delayred=STATUSCOLUMN:DELAY[,STATUSCOLUMN:DELAY...] — usually, status changes happen immediately. This tag is used to defer an update to red for the STATUSCOLUMN status for DELAY minutes. E.g. with delayred=disk:10,cpu:30, a red disk-status will not appear on the Xymon webpages until it has been red for at least 10 minutes.
Note: Since most tests only execute once every 5 minutes, it will usually not make sense to set N to anything but a multiple of 5. The exception is network tests, since xymonnet-again.sh(1) will re-run failed network tests once a minute for up to 30 minutes. Math bestie, do the math. 🧚
  • delayyellow=STATUSCOLUMN:DELAY[,STATUSCOLUMN:DELAY...] — same as delayred, but defers the change to a yellow status. Yellow gets the same dramatic delay treatment, slay. 💛

🦋 XYMONGEN DISPLAY OPTIONS 🦋

okay bestie, these next tags are the ones xymongen(1) actually reads when it's building your Xymon webpages or reports. like, this is the ✨aesthetic✨ layer of your setup. let's go 💅

  • page NAME [Page-title] — this makes a page one level below the entry page. every host that comes after the page line lives on this page… until you hit a new page, subpage, or subparent line. then it's a new era. 🎀
  • subpage NAME [Page-title] — same vibe but it's a sub-page, second level below the entry page. you must already have a page line above it for this sub-page to hook onto. no page parent = nowhere to live, bestie. 😭
  • subparent parentpage newpage [Page-title] — this one is for when you want sub-pages at literally whatever depth you feel like. just like the standard subpage tag, subparent defines a new Xymon web page — but with subparent you say out loud which page it should be a sub-page of. you can pick any page as the parent: pages, sub-pages, even other subparent pages. so yeah, any tree structure you want. slay. 🌳

like, if you put this in hosts.cfg:

page USA United States
subpage NY New York
subparent NY manhattan Manhattan data centers
subparent manhattan wallstreet Wall Street center

you get this hierarchy of pages:

USA (United States)
  NY (New York)
    manhattan (Manhattan data centers)
       wallstreet (Wall Street center)
Note: the parent page must be defined before you define the subparent. if not, the page will not be generated, and you get a message in the log file. order matters, no cap.
Note: xymongen is case-sensitive when it's trying to match the name of the parent page. NY is not ny, and she will not be fooled. 💀

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

  • vpage
  • vsubpage
  • vsubparent — these are page-definitions similar to the page, subpage and subparent definitions. but on these pages the rows are the tests, and the columns are the hosts (normal pages have it the other way around). so it's giving rotated, and that's the point ✨ this is useful if you have a very large number of tests for a few hosts, and you'd rather have them listed on a page you can scroll vertically. ngl, if you've got 900 tests and 3 hosts, this is your moment. note that the group directives have no effect on these types of pages. none. zero. they do not pass the vibe check here. 🚫
  • group [group-title]
  • group-compress [group-title] — defines a group of hosts that show up together on the web page, with a single header-line listing all of the columns. hosts following the group line appear inside the group, until a new group or page-line shows up. the two group-directives are handled identically by Xymon and xymongen, but both forms are allowed for backwards compatibility. twins, fr fr 👯
  • group-sorted [group-title] — same as the group line, but it will sort the hosts inside the group so they appear in strict lexicographic order. alphabetized, organized, main character energy 👑
  • group-only COLUMN1|COLUMN2|COLUMN3 [group-title] — same as the group and group-compress lines, but it includes only the columns explicitly listed in the group. any columns not listed will be ignored for these hosts. exclusive club only 💅
  • group-except COLUMN1|COLUMN2|COLUMN3 [group-title] — same as the group-only lines, but it includes all columns EXCEPT those explicitly listed in the group. any columns listed will be ignored for these hosts — all other columns are shown. so it's the reverse-guestlist situation. 🚪
  • title Page, group or host title text — the title tag is used to put custom headings into the pages generated by xymongen, in front of page/subpage links, groups or hosts. cute little labels, basically. 🎀

the title tag operates on the next item in the hosts.cfg file following the title tag. so it's attached to whatever comes right after it.

  • if a title tag precedes a host entry, the title is shown just before the host is listed on the status page. the column headings present for the host will be repeated just after the heading.
  • if a title tag precedes a group entry, the title is shown just before the group on the status page.
  • if a title tag precedes a page/subpage/subparent entry, the title text replaces the normal "Pages hosted locally" heading normally inserted by Xymon. this appears on the page that links to the sub-pages, not on the sub-page itself. to get a custom heading on the sub-page, you may want to use the --pagetext-heading when running xymongen(1). sneaky but valid 😌
  • NAME:hostname — overrides the default hostname used on the overview web pages. if hostname contains spaces, it must be enclosed in double quotes, e.g. NAME:"R&D Oracle Server". yes, quotes, she's picky. 🙈
  • CLIENT:hostname — defines an alias for a host, which will be used when identifying status messages. this is typically used to accommodate a local client that sends in status reports with a different hostname — e.g. if you use hostnames with domains in your Xymon configuration, but the client is a silly Window box that does not include the hostname. or vice-versa. whatever the reason, this can be used to match status reports with the hosts you define in your hosts.cfg file. it causes incoming status reports with the specified hostname to be filed using the hostname defined in hosts.cfg. basically a name tag for the confused ones 🏷️
  • NOCOLUMNS:column[,column] — used to drop certain of the status columns generated by the Xymon client. column is one of cpu, disk, files, memory, msgs, ports, procs. this setting stops these columns from being updated for the host.
Note: if the columns already exist, you must use the xymon(1) utility to drop them, or they will go purple. purple is not the vibe you want here, bestie 💜➡️💀
  • COMMENT:Host comment — adds a small text after the hostname on the web page. this can be used to describe the host, without completely changing its display-name the way the NAME: tag does. if the comment includes whitespace, it must be in double-quotes, e.g. COMMENT:"Sun web server". little footnote energy 📝
  • DESCR:Hosttype:Description — define some informational text about the host. the Hosttype is a text describing the type of this device — router, switch, hub, server etc. the Description is an informational text that will be shown on the Info column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. if the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch". receipts for your hardware, literally 🧾
  • CLASS:Classname — force the host to belong to a specific class. class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5), analysis.cfg(5) and alerts.cfg(5) to group log file checks or alerts). normally, class-names are controlled on the client by starting the Xymon client with the --class=Classname option. if you specify it in the hosts.cfg file on the Xymon server, it overrides any class name that the client reports. if not set, then the host belongs to a class named by the operating system the Xymon client is running on. server says so = server wins, periodt 💅
  • dialup — the keyword dialup for a host means that it is OK for it to be off-line — this should not trigger an alert. all network tests will go clear upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated. she's offline and that's fine, she's on her own schedule 🌙
  • nonongreen — ignore this host on the "All non-green" page. even if it has an active alert, it will not be included in the "All non-green" page. this also removes the host from the event-log display. not me showing up but refusing to be listed 🫣
  • nodisp — ignore this host completely when generating the Xymon webpages. can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. or for hiding a host that is shown only on a second pageset. she's monitoring but she's not on the grid 🕶️
  • TRENDS:[*,][![graph,...]] — defines the RRD graphs to include in the trends column generated by xymongen. this option syntax is complex. lowkey chaos but we can handle it.

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

  • if this option is specified, the list of graphs to include start out as being empty (no graphs).
  • to include all default graphs, use an asterisk. e.g. "TRENDS:*"
  • to exclude a certain graph, specify it prefixed with !. e.g. to see all graphs except users: "TRENDS:*,!users"
  • the netstat, vmstat and tcp graphs have many "subgraphs". which of these are shown can be specified like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" this will show all graphs, but instead of the normal netstat graph, there will be two: the netstat2 and netstat3 graphs. instead of the combined tcp graphs showing all services, there will be three: one for each of the http, conn and smtp services. choose-your-own-adventure graphs 🔥
  • COMPACT:COLUMN=COLUMN1|COLUMN2|COLUMN3[,ditto] — collapses a series of statuses into a single column on the overview web page. squish. tiny. efficient. 🤏
  • INTERFACES:REGEXP — on systems with multiple network interfaces, the operating system may report a number of network interface where the statistics are of no interest. by default Xymon tracks and graphs the traffic on all network interfaces. this option defines a regular expression, and only those interfaces whose name matches the expression are tracked. filter, girl, filter 🌸

👑 XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE 👑

⚠️ NOTE: the "NK" set of tags is deprecated. They'll still work for Xymon 4.x, but bestie they are getting dropped in version 5. So the move is: migrate your critical systems view over to the criticalview.cgi(1) viewer instead. That one comes with its own config tool, criticaleditor.cgi(1), which has way more facilities than the NK tags in hosts.cfg ever did. Do it now, thank me later 💅

So xymongen makes three sets of pages, okay:

  1. The main page — xymon.html
  2. The all-non-green-statuses page — nongreen.html
  3. A ✨specially reduced✨ version of nongreen.html with only selected tests — critical.html

That third one only shows the selected tests that are currently sitting at a red or yellow status. It's giving "only the drama, please" 🎀

  • NK:testname[,testname] — NOTE: this has been deprecated, you should use criticalview.cgi(1) instead of the NK tag.

This is where you define the tests you want to show up on the critical page. Like, say you've got a host where you only want the http tests visible on critical.html — you write it like this:

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

Wanna have multiple tests for one host pop up on critical.html? Just list all of them, comma-separated. And heads up: the test names match up to the column names (so e.g. https tests are covered by an "NK:http" tag — yes really, iykyk).

  • NKTIME=day:starttime:endtime[,day:starttime:endtime] — this tag restricts when an active alert gets presented on the NK web page.

Default behaviour: tests with a red or yellow status that are listed in the "NK:testname" tag show up on the NK page. But lowkey you might not want the test showing outside normal working hours — like if the host isn't even being serviced on weekends, why is it yelling at you 🙈

That's exactly when you reach for the NKTIME tag: it defines the time periods where the alert will show up on the NK page.

The time spec breaks down like this:

  • day-of-week: W means Mon-Fri ("weekdays"), * means all days, 0 .. 6 = Sunday .. Saturday. You can list multiple days too — e.g. "60" is totally valid and means "Saturday and Sunday".
  • starttime: the time to start showing errors. Must be in 24-hour clock format as HHMM hours/minutes. So 8 am is "0800", and 9.30 pm is "2130".
  • endtime: the time to stop showing errors.

If you need multiple periods, go off — you can specify more than one. E.g. to monitor a site 24x7 except between noon and 1 pm, you'd use:

NKTIME=*:0000:1159,*:1300:2359

And the interval between start time and end time may cross midnight — e.g. *:2330:0200 is valid and has the same effect as *:2330:2400,*:0000:0200. 🌙

📱 XYMON TAGS FOR THE WML (WAP) CARDS 📱

If xymongen gets run with the --wml option, it generates a set of WAP-format output "cards" that you can view on a WAP-capable device — a PDA, a cell-phone, whatever old-school tech is in your bag 🦋

  • WML:[+|-]testname[,[+|-]testname] — this tag decides which tests for this host get included in the WML (WAP) page. The syntax is identical to the NK: tag.

The default set of WML tests comes from the --wml command line option. And if no "WML:" tag is specified, then the "NK:" tag is used if it's present. Reuse, recycle, slay ♻️

⬆️ XYMON STATUS PROPAGATION OPTIONS ⬆️

These tags control how a status propagates upwards — from a single test up to the page and higher beyond that. You can also do this with the command-line options --nopropyellow and --nopropred, BUT: the tags apply to individual hosts, whereas the command line options are global. Different tools, different energies 💅

  • NOPROPRED:[+|-]testname[,[+|-]testname] — this tag is used to inhibit a yellow or red status from propagating upwards, i.e. from a test status color to the (sub)page status color, and further on up to xymon.html or nongreen.html.

If a host-specific tag starts with a - or a +, the host-specific tags get removed/added to the default setting from the command-line option. But if the host-specific tag does not start with a + or a -, then the default setting is just ignored for this host and NOPROPRED applies to the tests given with this tag.

E.g.: xymongen runs with "--nopropred=ftp,smtp". Then:

  • "NOPROPRED:+dns,-smtp" gives a NOPROPRED setting of "ftp,dns" (dns is added to the default, smtp is removed) ✅
  • "NOPROPRED:dns" gives a setting of "dns" only (the default is ignored) ✅
Note: if you use the "--nopropred=*" command line option to disable propagation of all alerts, you cannot use the "+" and "-" methods to add or remove from the wildcard setting. In that case, don't use the "+" or "-" setting — just simply list the required tests that you want to keep from propagating. No half-measures, bestie.
  • NOPROPYELLOW:[+|-]testname[,[+|-]testname] — similar to the NOPROPRED: tag, but this one applies to propagating a yellow status upwards.
  • NOPROPPURPLE:[+|-]testname[,[+|-]testname] — similar to the NOPROPRED: tag, but this one applies to propagating a purple status upwards.
  • NOPROPACK:[+|-]testname[,[+|-]testname] — similar to the NOPROPRED: tag, but this one applies to propagating an acknowledged status upwards. 👍

📊 XYMON AVAILABILITY REPORT OPTIONS 📊

These options affect the way the Xymon availability reports get processed (peep report.cgi(1) for the details about availability reports 👀).

  • REPORTTIME=day:starttime:endtime[,day:starttime:endtime] — this tag defines the time interval where you measure the uptime of a service for reporting purposes.

When xymongen generates a report, it computes the availability of each service — i.e. the percentage of time that the service is reported as available (meaning: not red).

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

The REPORTTIME tag lets you specify a period of time other than 24x7 for the service availability calculation. Got systems where you only guarantee availability from, like, 7 AM to 8 PM on weekdays? Then use:

REPORTTIME=W:0700:2000

...and the availability calculation will only be performed for the service with measurements from that time interval. Chef's kiss 👑

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

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

  • Only measurements done during the given time period are used for the calculation.
  • "blue" time reduces the length of the report interval — so if you're generating a report for a 10-hour period and there are 20 minutes of "blue" time, then the availability calculation will consider the reporting period to be 580 minutes (10 hours minus 20 minutes). This is what lets you have scheduled downtime during the REPORTTIME interval without hurting your availability; this is (I believe) the whole idea of the downtime being "planned". 🧚
  • "red" and "clear" status count as downtime; "yellow" and "green" count as uptime. "purple" time is ignored.
  • The availability calculation correctly handles status changes that cross into/out of a REPORTTIME interval. Clean. ✨

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

  • WARNPCT:percentage — Xymon's reporting facility uses a computed availability threshold to color services green (100% available), yellow (above threshold, but less than 100%), or red (below threshold) in the reports.

This option lets you set that threshold value on a host-by-host basis, instead of using one global setting for all hosts. The threshold is defined as the percentage of the time the host must be available — e.g. "WARNPCT:98.5" if you want the threshold sitting at 98.5%. Precise 💅

  • noflap[=test1,test2,...] — disable flap detection for this host, or for specific tests on this host. Flap detection is globally controlled by options given to xymond on the command line, but if it is enabled, you can turn it off using this option. Situational. 🌸

🎀 NETWORK TEST SETTINGS 🎀

okay bestie, this is the part where we tell Xymon how to actually poke the host over the network. buckle up 💅

  • testip — by default Xymon does a name lookup of the hostname to figure out the IP address it's gonna use for network tests. this tag says "nah, just use the IP sitting right there in the hosts.cfg file." 🌸
  • NET:location — this tag marks the host as being tested from one specific location. so if xymonnet spots that the environment variable XYMONNETWORK is set, it will only test the hosts that have a matching NET:location tag in the hosts.cfg file. super useful when you've got more than one system running network tests but you still wanna keep one consolidated hosts.cfg for all of them. 🫶
note: the --test-untagged option changes this behaviour, go peek at xymonnet(1) — iykyk
  • noclear — some network tests are lowkey codependent on each other 😭 like, if the host doesn't even respond to ping, there's a pretty solid chance the whole host is down and every network test is about to fail. or if the http server is down, then literally any web content check is gonna fail too. to avoid a flood of alerts, the default behaviour is for xymonnet to switch the status of these "failed because of another problem" tests to "clear" instead of "red". the noclear tag disables that and makes all failing tests report with their true color. no cap.

you can also do this per-test by slapping the "~" flag on any network test. 🦋

psst — noclear also affects whether stale status messages (like from a client on the host) go purple or clear when the host is down. see the noclear description in the GENERAL PER-HOST OPTIONS section above. 👑
  • nosslcert — disables the standard check of any SSL certificates for this host. by default, if an SSL-enabled service gets tested, a second test result pops out with all the SSL certificate deets. this tag kills the SSL certificate checks for the host. 🙈
  • ssldays=WARNDAYS:ALARMDAYS — sets how many days before an SSL certificate expires you want the sslcert status to go warning (yellow) or alarm (red). these default to whatever you passed via the --sslwarn and --sslalarm options for the xymonnet(1) tool — and honestly, whatever you put in the ssldays tag overrides that default. periodt. ⭐
  • sslbits=MINIMUMKEYBITS — turns on checking of the encryption strength of the SSL protocol the server is offering. if the server offers encryption using a key with fewer than MINIMUMKEYBITS bits, the sslcert test goes red. e.g. to make sure your server only uses strong encryption (128 bits or better), use sslbits=128. 🔥
  • sni
  • nosni — enables or disables use of SNI (Server Name Indication) for SSL tests.

some SSL implementations simply cannot handle SSL handshakes with SNI data, so Xymon by default does not use SNI. that default can be flipped with the --sni option for xymonnet(1), but you can also manage it per host with these tags. 💅

SNI support showed up in Xymon 4.3.13, where the default was to use SNI. that got changed in 4.3.14 so SNI support is disabled by default — and the sni and nosni tags were introduced right alongside the --sni option for xymonnet. the way this evolved is giving very much "we fixed it, then un-fixed it, then made it configurable." 😭

💜 the DOWNTIME era 💜

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

this tag lets you ignore failed checks during specific times of the day — like, if you run services that are only monitored Mon-Fri 8am-5pm, or you always reboot a server every Monday between 5 and 6 pm. iconic. 🌈

here's the tea: if a test fails during the specified time, it gets reported with status BLUE instead of red, yellow, or purple. so you can still see when the service was unavailable, but alarms won't trigger and the downtime is not counted in the availability calculations generated by the Xymon reports. best of both worlds bestie ✨

the columns and cause settings are optional — but both or neither must be specified, no in-between.

  • columns may be a comma-separated list of status columns that DOWNTIME will apply to.
  • cause is a string that gets displayed on the status web page to explain why the system is down.

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

  • SLA=day:starttime:endtime[,day:starttime:endtime] — okay so this tag is now deprecated. use the DOWNTIME tag instead, fr fr.

SLA works the opposite of DOWNTIME — you use it to specify the periods of the day that the service should be green. failures OUTSIDE the SLA interval get reported as blue. 💀

  • depends=(testA:host1/test1,host2/test2),(testB:host3/test3),[...] — this is the ~friendship~ tag, it defines dependencies between tests. so if "testA" for the current host depends on "test1" for host "host1" and test "test2" for "host2", you write it like this:
depends=(testA:host1/test1,host2/test2)

when Xymon is deciding what color to report for testA: if either host1/test1 failed or host2/test2 failed, and testA has also failed, then testA's color will be "clear" instead of red or yellow. 💖

because all tests are actually run before the dependencies get evaluated, you can use any host/test in the dependency — doesn't matter what order the hosts are listed in, or what order the tests run in. and it's totally valid to use tests from the same host that the dependency is for. e.g.

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

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

note: the depends tag is evaluated by xymonnet while it's running the network tests. so it can only refer to other network tests handled by the same server — there's currently no way to use, like, the status of locally run tests (disk, cpu, msgs) or network tests from other servers in a dependency definition. such dependencies are silently ignored. 😶
  • badTEST[-weekdays-starttime-endtime]:x:y:z — NOTE: this has been deprecated, use the delayred and delayyellow settings instead. 🚨

normally when a network test fails, the status flips to red immediately. with a "badTEST:x:y:z" tag, that behaviour changes:

  • while "z" or more successive tests fail, the column goes RED.
  • while "y" or more successive tests fail, but fewer than "z", the column goes YELLOW.
  • while "x" or more successive tests fail, but fewer than "y", the column goes CLEAR.
  • while fewer than "x" successive tests fail, the column stays GREEN.

the optional time specification limits this "badTEST" setting to a particular time of day — e.g. to require a longer period of downtime before raising an alarm during out-of-office hours. the time-specification uses:

  • Weekdays: the weekdays this badTEST tag applies to, from 0 (Sunday) through 6 (Saturday). putting "W" here counts as "12345", i.e. all working days. putting "*" here counts as all days of the week, equivalent to "0123456". 📅
  • start time and end time are specified using 24-hour clocks, e.g. "badTEST-W-0900-2000" is valid for working days between 9 AM (09:00) and 8 PM (20:00).

when you use multiple badTEST tags, the LAST one specified with a matching time-spec is the one that wins. 👑

note: "TEST" gets replaced by the name of the test, e.g.
12.34.56.78  www.foo.com  # http://www.foo.com/ badhttp:1:2:4

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

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

✨ CONNECTIVITY (PING) TEST ✨

okay so these tags are the ones that control how the xymonnet connectivity test behaves 💖

  • noping — turns OFF the ping-test, but keeps the conn column chillin' on the web display with a lil notice saying it's been disabled 🫶
  • noconn — turns OFF the ping-test AND dips out completely, no conn column on the web display at all 💅
  • conn — bestie, so the conn test (which literally just pings the host) is on for ALL hosts by default, and normally you'd only ever want to turn it off with noconn or noping. BUT (and this is the fun part 💀) on those rare occasions where you wanna check that a host is NOT up, you can specify it as an explicit test and use the normal test modifiers. So !conn will be green when the host is NOT up, and red if it DOES show up on the network. icon main character energy honestly.

the actual name of the tag — conn by default — depends on the --ping=TESTNAME option for xymonnet, because that's what decides the testname for the connectivity test. periodt.

  • conn={best,|worst,}IP1[,IP2...] — this one adds EXTRA IP-addresses that get pinged during the normal conn test. so the normal conn test has to be enabled (the default) before this tag does anything, got it? 🎀 the IP-addresses you list here get pinged IN ADDITION to the main IP-address.

when multiple IP's are pinged, you get to choose if ALL IP's must respond (that's the worst method) or AT LEAST one IP must respond (that's the best setting). all of the IP's are reported in a single conn status, and its color comes from the result of pinging the IP's plus the best/worst setting. the default method is best — so it'll report green if, like, just one of the IP's responds to ping. slay 🌈

  • badconn[-weekdays-starttime-endtime]:x:y:z — okay this is taken directly from the fping.sh connectivity-testing script, and it's used by xymonnet when it runs with ping testing enabled (the default). see the description of the badTEST tag 🙈
  • route:router1,router2,.... — this tag comes straight from the fping.sh script, and xymonnet uses it when run with the --ping option to enable ping testing.

the router1,router2,... is a comma-separated list of hosts elsewhere in the hosts.cfg file. you cannot have any spaces in the list — separate hosts with commas, fr fr 🚫

this tag changes the color reported for a ping check that fails, when one or more of the hosts in the route list is ALSO down. a red status becomes yellow — other colors are unchanged. the status message will include info about the hosts in the router-list that are down, to help track down which router is the root cause of the problem. detective work bestie 🔍

Note: internally, the ping test will still be handled as failed, and therefore any other tests run for this host will report a status of clear. so it's giving green on the outside but still lowkey failing underneath 💀
  • route_LOCATION:router1,router2,... — if the XYMONNETWORK environment variable is defined, a tag of route_XYMONNETWORK: is recognized by xymonnet with the same effect as the normal route: tag (see above). this lets you have different route: tags for each server running xymonnet. the actual text for the tag then has to match the value you have for the XYMONNETWORK setting. e.g. with XYMONNETWORK=dmz, the tag becomes route_dmz: 💅
  • trace — if the connectivity test fails, run a traceroute and include the output from it in the status message from the failed connectivity test. Note: for this to work, you may have to define the TRACEROUTE environment variable, see xymonserver.cfg(5) 🦋
  • notrace — similar to the trace option, this disables the running of a traceroute for the host after a failed connectivity test. it's only used if running traceroute is made the default via the --trace option 🙌

🌸 SIMPLE NETWORK TESTS 🌸

these tests do a simple network test of a service by connecting to the port and possibly checking that a banner is shown by the server. it's giving "hi bestie, u up?" energy 💖

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

you can modify the behaviour of these tests on a per-test basis by adding one or more modifiers to the test:

  • :NUMBER changes the port number from the default to the one you specify for this test. e.g. to test ssh running on port 8022, specify the test as ssh:8022.
  • :s makes the test silent, i.e. it does not send any data to the service. e.g. to do a silent test of an smtp server, enter smtp:s.
  • you can combine these two: ftp:8021:s is valid. combo queen ✨

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

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

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

by prefixing a test with ? errors will be reported with a clear status instead of red. this is known as a test for a "dialup" service, and it lets you run tests of hosts that are not always online, without getting alarms while they are off-line. thank u bestie, very considerate 🫶

  • ftp ssh telnet smtp pop3 imap nntp rsync clamd oratns qmtp qmqp — these tags are for testing services offering the FTP, Secure Shell (ssh), SMTP, POP3, IMAP, NNTP, rsync, CLAM anti-virus daemon (clamd), Oracle TNS listener (oratns), qmail QMTP and QMQP protocols. look at the range 💅
  • ftps telnets smtps pop3s imaps nntps — these tags are for testing the SSL-tunneled versions of the standard ftp, telnet, smtp, pop3, imap and nntp protocols. if Xymon was configured with support for SSL, you can test these services like any other network service — xymonnet will set up an SSL-encrypted session while testing the service. the server certificate is validated and information about it sent in the sslcert column. Note that smtps does not have a standard port number assignment, so you'll need to enter this into the protocols.cfg file or your /etc/services file. secure queen 🔒✨
  • bbd — test that a Big Brother compatible daemon is running. this check works both for the Xymon xymond(8) daemon, AND the original Big Brother bbd daemon. nostalgic icon 💜

🦋 DNS SERVER TESTS 🦋

these tags are used to set up monitoring of DNS servers.

  • dns — simple DNS test. it will attempt to lookup the A record for the hostname of the DNS server.
  • dig — this is an alias for the dns test. in xymonnet, the dns and dig tests are handled identically, so all of the facilities for testing described for the dns test are also available for the dig test. twins fr fr 👯
  • dns=hostname
  • dns=TYPE:lookup[,TYPE:lookup...] — the default DNS tests will attempt a DNS lookup of the DNS server's own hostname. you can specify the hostname to lookup on a DNS server by listing it on each test.

the second form of the test lets you perform MULTIPLE queries of the DNS server, requesting different types of DNS records. the TYPE defines the type of DNS data: A (IP-address), MX (Mail eXchanger), PTR (reverse), CNAME (alias), SOA (Start-Of-Authority), NS (Name Server) are among the more common ones used. the "lookup" is the query. e.g. to lookup the MX records for the "foo.com" domain, you'd use dns=mx:foo.com. or to lookup the nameservers for the "bar.org" domain, dns=ns:bar.org. you can list multiple lookups, separated by commas. for the test to end up with a green status, ALL lookups must succeed. no half measures 💅

⭐ OTHER NETWORK TESTS ⭐

  • ntp — check for a running NTP (Network Time Protocol) server on this host. this test uses the ntpdate utility to check for a NTP server — you should either have ntpdate in your PATH, or set the location of the ntpdate program in $XYMONHOME/etc/xymonserver.cfg ⏰
  • rpc[=rpcservice1,rpcservice2,...] — check for one or more available RPC services. this check is indirect in that it only queries the RPC Portmapper on the host, not the actual service. it's giving "not the real thing but close enough" 🫠

if only rpc is given, the test only verifies that the port mapper is available on the remote host. if you wanna check that one or more RPC services are registered with the port mapper, list the names of the desired RPC services after the equals-sign. e.g. for a working NFS server the mount, nlockmgr and nfs services must be available; this can be checked with rpc=mount,nlockmgr,nfs. 🎀

this test uses the rpcinfo tool for the actual test; if this tool isn't available in the PATH of xymonnet, you must define the RPCINFO environment variable to point at this tool. see xymonserver.cfg(5) 📌

💖 HTTP TESTS 💖

simple testing of a http URL is done simply by putting the URL into the hosts.cfg file. Note that this only applies to URL's that begin with http: or https:. easy peasy 🌈

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

Basic Authentication with username/password

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

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

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

💖 Authentication with SSL client certificates

Okay bestie, you can totally use an SSL client certificate to prove who you are. Here's the tea: the client certificate has to live in a PEM-formatted file, sitting right next to the client certificate key, inside the $XYMONHOME/certs/ directory. Then you write the URL like this:

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

The CERT: bit is literal — like, you actually type C-E-R-T-then-a-colon, and then the filename of that PEM-formatted certificate. No cap.

And how do you even make a PEM-formatted cert file? You can generate one from certs stored in Microsoft Internet Explorer and OpenSSL. The whole ritual goes like this:

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

Then run:

openssl pkcs12 -in file.pfx -out file.pem

When it asks you for the "Import Password", hand over that temporary password you gave when exporting the certificate. Then it'll ask for a "PEM pass phrase" (twice) — give it one.

That file.pem file? That's the one you use in the FILENAME field in the URL — and it must be kept in $XYMONHOME/certs/. Now, the PEM pass phrase has to go into a file named the same as the certificate, but with the extension .pass. So like, if your PEM certificate lives at $XYMONHOME/certs/client.pem, you gotta put the pass phrase into the $XYMONHOME/certs/client.pass file. And protect that file with Unix permissions so that only the user running Xymon can read it — seriously, lock it down. 🔒

🌈 Forcing an HTTP or SSL version

Some SSL sites are ~picky~ and will only let you connect if you speak specific "dialects" of HTTP or SSL. Normally this gets auto-negotiated, but experience (derogatory) shows it just fails on some systems.

So xymonnet can be told to use specific dialects — you just add one or more "dialect names" to the URL scheme, i.e. the http or https part in the URL:

  • 2, e.g. https2://www.sample.com/ : use only SSLv2
  • 3, e.g. https3://www.sample.com/ : use only SSLv3
  • t, e.g. httpst://www.sample.com/ : use only TLSv1.0
  • a, e.g. httpsa://www.sample.com/ : use only TLSv1.0
  • b, e.g. httpsb://www.sample.com/ : use only TLSv1.1
  • c, e.g. httpsc://www.sample.com/ : use only TLSv1.2
  • m, e.g. httpsm://www.sample.com/ : use only 128-bit ciphers
  • h, e.g. httpsh://www.sample.com/ : use only >128-bit ciphers
  • 10, e.g. http10://www.sample.com/ : use HTTP 1.0
  • 11, e.g. http11://www.sample.com/ : use HTTP 1.1

And you can combine these wherever it makes sense — like, to force TLS1.2 and HTTP 1.0 you'd use httpsc10. Slay.

Heads up bestie: SSLv2 support is disabled in all current OpenSSL releases. And TLS version-specific scheme testing requires OpenSSL 1.0.1 or higher.

💅 Testing sites by IP-address

So xymonnet straight up ignores the testip tag — y'know, the one normally used to force a test to use the IP-address from the hosts.cfg file instead of the hostname — when it's doing http and https tests.

Why, you ask? Because it interacts badly with virtual hosts, especially if those are IP-based, which is super common with https-websites. It's giving chaos.

Instead, the IP-address you connect to can be overridden by specifying it like this:

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

That =1.2.3.4 makes xymonnet run the test against the IP-address 1.2.3.4, but it's still trying to access a virtual website with the name www.sample.com. Iconic behaviour honestly.

And the =ip.address.of.host has to be the last part of the hostname. So if you need to combine this with, like, an explicit port number, it should be done as:

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

🧚 HTTP Testing via proxy

NOTE: This is not enabled by default. You must add the --bb-proxy-syntax option when running xymonnet(1) if you want to use this. Don't forget, bestie!

xymonnet supports the Big Brother syntax for specifying an HTTP proxy to use when performing http tests. The syntax is basically just joining the proxy- and the target-URL into one, e.g.

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

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

If you don't specify the proxy port number, the default HTTP port number (80) gets used. Simple as that.

And if your proxy is extra and requires authentication, you can put the username and password inside the proxy-part of the URL, e.g.

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

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

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

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

This tag is used to specify a http/https check, where it's also checked that specific content is present in the server response. Two birds, one stone, we love efficiency.

If the URL itself includes a semi-colon, this must be escaped as %3B — otherwise everything gets confused about which semicolon is part of the URL and which semicolon acts as a delimiter. Messy.

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

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

\n     Newline (LF, ASCII 10 decimal)
\r     Carriage return (CR, ASCII 13 decimal)
\t     TAB (ASCII 8 decimal)
\\    Backslash (ASCII 92 decimal)
\XX    The character with ASCII hex-value XX

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

Note: If you are migrating from the cont2.sh script, you must change the _ used as wildcards by cont2.sh into . — which is the regular-expression wildcard character. Don't say I didn't warn you.

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

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

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

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

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

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

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

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

🙈 content=URL

This syntax is deprecated. You should use the cont tag instead, see above. It's giving legacy. Move on, bestie.

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

This tag can be used to test web pages that use an input form. Data can be posted to the form by specifying them in the form-data field, and the result can be checked as if it was a normal content check (see above for a description of the cont-tag and the restrictions on how the URL must be written).

The form-data field must be entered in application/x-www-form-urlencoded format, which is the most commonly used format for web forms.

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

<form action="/cgi-bin/form.cgi" method="post">
  <p>Given name<input type="text" name="givenname"></p>
  <p>Surname<input type="text" name="surname"></p>
  <input type="submit" value="Send">
</form>

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

givenname=John&surname=Doe+Jr.

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

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

That expected_data_regexp / #digesttype:digest situation is literally the data the server is supposed to hand back when the POST lands 💌. Peep the cont; tag up above for the deets. If all you care about is "can I even submit this form bestie" and you don't give a single crumb about the actual data, this can be an empty string — BUT 💀 the ; at the very end is mandatory, no cap.

  • nocont[=COLUMN];URL;forbidden_data_regexp — same energy as cont but it flips the whole test. Green when forbidden_data_regexp is NOT chillin' in the response, red when it IS. So it's your little alarm for stuff that should not be in there, like a server error message sneaking through. 💀
  • nopost[=COLUMN];URL;form-data;expected_data_regexp — same as the post tag but reversed. Green when forbidden_data_regexp is NOT found in the response, red when it IS found. Watch for data that should NOT be present, e.g. a server error message. 😤
  • type[=COLUMN];URL;expected_content_type — a lil remix of the content check ✨ instead of digging through the content data, it checks the type of data as told by the HTTP Content-Type: header. Perfect for when you wanna know if a URL returns e.g. a PDF, and you truly do not care what's inside that PDF. 🎀
  • soap[=COLUMN];URL;SOAPMESSAGE;[expected_data_regexp|#digesttype:digest] — sends a SOAP message over HTTP. Identical to the cont test, except the request that goes out to the server uses a Content-type of application/soap+xml, and it also sends a SOAPAction header with the URL. SOAPMESSAGE is the actual SOAP message being sent. And since SOAP messages are usually XML docs, you can stash it in a separate file by passing file:FILENAME as the SOAPMESSAGE parameter 💖. Like, a test spec of:
soap=echo;http://soap.foo.bar/baz?wsdl;file:/home/foo/msg.xml;.

will read the SOAP message from the file /home/foo/msg.xml and post it to the URL http://soap.foo.bar/bas?wsdl

Heads up bestie 🙈 SOAP XML documents usually have to start with the XML version line, <?xml version="1.0">
  • nosoap[=COLUMN];URL;SOAPMESSAGE;[forbidden_data_regexp|#digesttype:digest] — works just like soap but reverses the test. Green when forbidden_data_regexp is NOT found in the response, red when it IS. So use it to watch for data that should NOT be present, e.g. a server error message. 🚨
  • httphead[=COLUMN];URL — does an HTTP HEAD request instead of a GET. Simple. Elegant. Iconic. 💅
  • httpstatus[=COLUMN];URL;okstatusexpr;notokstatusexpr — explicitly tests for certain HTTP status codes returned when the URL is requested. The okstatusexpr and nokokstatusexpr expressions are Perl-compatible regular expressions — e.g. 2..|302 matches all OK codes plus the redirect (302) status code. And if the URL can't be retrieved at all? The status is 999. 😭
  • HIDEHTTP — the status display for HTTP checks usually shows the URL, and for content checks it also shows the actual data from the web page. If you want all that hidden from view, the HIDEHTTP tag keeps that info off the status webpages. 🫣
  • headermatch — content checks by default only search the HTML body the webserver sends back. This option makes it also search the HTTP headers for the string that must / must not be present. 🔍
  • browser=BROWSERNAME — by default, Xymon sends an HTTP User-Agent header identifying itself as Xymon. Some websites are picky and demand a specific browser, typically Internet Explorer (ikr 💀). To test those sites, this tag modifies the data sent in the User-Agent header. E.g. to run an HTTP test with Xymon masquerading as an Internet Explorer 6.0 browser, use browser="Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)". And if you have no idea what the User-Agent header should be, open up the browser that actually works with that site and open the URL "javascript:document.writeln(navigator.userAgent)" (just copy that into the "Open URL" dialog). Whatever text shows up is exactly what the browser sends as the User-Agent header. 🧚
  • httphdr=STRING — Xymon can send extra headers when doing HTTP checks, perfect for validating any custom configs your site needs ✨. Note that this is a host-wide configuration — the string gets added directly to the headers for all URLs on that host. There is currently no way to make it happen only for specific URLs. The string should be wrapped in quotes, like httphdr="X-Requested-With: XMLHttpRequest". Newlines can be included, BUT the string MUST NOT end with a newline, because that may cause a premature ending of the headers sent. 🚫

🔐 LDAP (DIRECTORY SERVER) TESTS 🔐

  • ldap
  • ldaps — simple check for an LDAP service. This check merely looks for any service running on the ldap/ldaps service port, but does not perform any actual LDAP transaction. Vibe check only, no deep talk. 💅
  • ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]] — checks for an LDAP service by actually performing an LDAP request. This tag takes the form of an LDAP URI (cf. RFC 2255). This type of LDAP test requires that xymonnet(1) was built with support for LDAP, e.g. via the OpenLDAP library. The components of the LDAP URI are:
    • hostport is a host name with an optional ":portnumber"
    • dn is the search base
    • attrs is a comma separated list of attributes to request
    • scope is one of these three strings:
      • base one sub (default=base)
    • filter is filter
    • exts are recognized set of LDAP and/or API extensions.
  • ldaps://hostport/dn[?attrs[?scope[?filter[?exts]]]] — LDAP service check using LDAPv3 and STARTTLS, for talking to an LDAP server that requires TLS encryption 🔒. See xymonnet(1) for a discussion of the different ways of running LDAP servers with SSL/TLS, and which of these are supported by xymonnet.
  • ldaplogin=username:password — define a username and password to use when binding to the LDAP server for ldap URI tests. If you don't specify one, xymonnet will attempt an anonymous bind. 🙈
  • ldapyellowfail — used with an LDAP URL test. If the LDAP query fails during the search of the directory, the ldap status is normally reported as red (alarm). This tag downgrades a search failure to a yellow (warning) status. Softening the blow fr fr. 🥲

📊 PERFORMANCE MONITORING TESTS 📊

  • apache[=URL] — if you're running an Apache web server, adding this tag makes xymonnet(1) collect performance statistics from that Apache server by querying the URL http://IP.ADDRESS.OF.HOST/server-status?auto 🔥. The response is sent as a data-report and processed by the Xymon xymond_rrd module into an RRD file and an apache graph. If your web server needs e.g. authentication, or serves the server-status from a different URL, you can provide the full URL needed to fetch the server-status page, e.g. apache=http://LOGIN:PASSWORD@10.0.0.1/server-status?auto for a password protected server-status page, or apache=http://10.0.0.1:8080/apache/server-status?auto for a server listening on port 8080 with a different path to the server-status page. 👑

You do need to enable the server-status URL in your Apache configuration. This configuration is needed:

    <Location /server-status>
        SetHandler server-status
        Order deny,allow
        Deny from all
        allow from 127.0.0.1
    </Location>
    ExtendedStatus On

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

🏠 DEFAULT HOST 🏠

If you've got certain tags you want to apply to literally every host, you can define a host name .default. and put the tags on that host 💖. Just know that per-host definitions will override the default ones. And to apply to all hosts, this should be listed FIRST in your file.

NOTE: the .default. host entry will only accept the following tags — others are silently ignored: delayyellow, delayred, NOCOLUMNS, COMMENT, DESCR, CLASS, dialup, testip, nonongreen, nodisp, noinfo, notrends, noclient, TRENDS, NOPROPRED, NOPROPYELLOW, NOPROPPURPLE, NOPROPACK, REPORTTIME, WARNPCT, NET, noclear, nosslcert, ssldays, DOWNTIME, depends, noping, noconn, trace, notrace, HIDEHTTP, browser, pulldata. 💀

Specifically, note that network tests, badTEST settings, and alternate pageset relations cannot be listed on the .default. host. 🚫

✨ SENDING SUMMARIES TO REMOTE XYMON SERVERS ✨

okay bestie this one is SO cool if you've got a whole fleet of Xymon servers 🫶

  • summary ROW.COLUMN IP URL — bestie listen. if you're running multiple Xymon servers, summary is the glow-up that lets you build a lil server hierarchy 💅 you take the overall status of this server and yeet it to a remote Xymon server, which then shows it off in a special summary section. fr fr. like, say your offices are spread over three locations — you can totally have a Xymon server at each office 👑 those branch-office Xymon boxes get a summary definition in their hosts.cfg file, and that's what makes them report the overall status of their branch to the central Xymon server you keep at corporate HQ ✨

you can have multiple summary definitions. multiple!! go off 🎀

so the ROW.COLUMN setting decides how this summary gets presented on the server that receives it:

  • the ROW text becomes the heading for a summary line
  • the COLUMN sets the name of the column where this summary shows up — just like the hostname and testname used in the normal displays
  • the IP is the IP-address of the remote (upstream) Xymon server — the one this summary is sent to
  • the URL is the URL of your local Xymon server

and the URL does NOT have to be your Xymon server's main page, bestie — it can be the URL of a sub-page on the local Xymon server 🌸 Xymon will report the summary using the color of the page found at the URL you specify. iykyk.

like, say on your corporate Xymon server you want a summary from the Las Vegas office — but you wanna know both the overall status and the status of the servers on the critical Sales department back-office servers in Las Vegas 👀 so you set up the Las Vegas Xymon server to send two summaries:

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

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

🚨 note bestie: pages defined using alternate pageset definitions cannot be used here. the URL must point to a web page from the default set of Xymon webpages. no workarounds, periodt.

💜 OTHER TAGS 💜

  • pulldata[=[IP][:port]] — this one is recognized by the xymonfetch(8) utility, and it makes it go poll the host for client data 👑 the optional IP-address and port-number are there for when the client-side msgcache(8) daemon is listening on a non-standard IP-address or port-number. cute, right? 🎀

🎀 FILES 🎀

  • ~xymon/server/etc/hosts.cfg

🦋 SEE ALSO 🦋

and that's the whole page bestie, we ATE that 💅 ok so quick sign-off: this was Xymon Version 4.3.30, dated 4 Sep 2019, and the page itself is HOSTS.CFG(5) ✨ go forth and configure your hosts, main character energy only 🌸🫶💖

📦 where this page comes from