XYMONGREP(1)

💖 XYMONGREP 💖

okay bestie so xymongrep is a lil command from the Xymon fam, and its whole thing is picking out lines in hosts.cfg ✨ it's a manual page from the General Commands Manual, and it's giving "small tool, huge main character energy" 🎀

---

✨ SYNOPSIS ✨

xymongrep --help
xymongrep --version
xymongrep [--noextras] [--test-untagged] [--web] [--net]
[--loadhostsfromxymond] TAG [TAG...]

like. that's the whole vibe check right there 🦋

---

🌸 DESCRIPTION 🌸

so xymongrep(1) is literally made for extension scripts — the ones that need to pick out the entries in a hosts.cfg file that actually matter to them 💅

here's the tea: the utility takes test names as parameters, then parses the hosts.cfg file and prints out the host entries that have at least one of the wanted tests. and listen — tags can be given with a trailing asterisk '*', so for example "xymongrep http*" is what you need to find all the http and https tags. iykyk ⭐

also? xymongrep fully supports "include" directives inside the hosts.cfg file, and it will find matching tags in all the included files. no host left behind fr fr 🫶

and if the DOWNTIME or SLA tags are used in the hosts.cfg(5) file, those get interpreted relative to the current time. xymongrep then outputs an "INSIDESLA" or "OUTSIDESLA" tag, which makes it way easier for scripts that wanna check if the current time is inside or outside the expected uptime window 👑

---

🎀 OPTIONS 🎀

• --noextras — removes the "testip", "dialup", "INSIDESLA" and "OUTSIDESLA" tags from the output. decluttered, periodt 💅
• --test-untagged — okay so when you're using the XYMONNETWORK environment variable to test only hosts on a particular network segment, xymonnet will ignore hosts that don't have any "NET:x" tag. so only hosts that have a NET:$XYMONNETWORK tag will be tested. with this option tho? 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 🌈
• --no-down[=TESTNAME] — xymongrep will query the Xymon server for the current status of the "conn" test, and if TESTNAME is specified, also for the current state of that specified test. if the status of the "conn" test for a host is non-green, or the status of the TESTNAME test is disabled, then this host is ignored and will not be included in the output. so it's the "pls don't bother me about hosts that are down" option, or hosts where the custom test is disabled 🙈
• --web — search the hosts.cfg file following include statements as a Xymon web-server would 🦋
• --net — search the hosts.cfg file following include statements as when running xymonnet 🌿
• --loadhostsfromxymond — normally xymongrep attempts to load the HOSTSCFG file by itself when searching for lines to transmit, and if the file is unreadable, it will exit out. with this option, it will query the xymond server (set via the XYMONSERVER environment) for the hosts file. this is the move if you're running this on a client or remote system and can't — or don't wanna — have the hosts.cfg file synchronized across your servers 🔥

---

💫 EXAMPLE 💫

say your hosts.cfg file looks like this:

192.168.1.1   www.test.com  # ftp telnet !oracle
192.168.1.2   db1.test.com  # oracle
192.168.1.3   mail.test.com # smtp

and you have a custom Xymon extension script that performs the "oracle" test. then running "xymongrep oracle" would yield:

192.168.1.1   www.test.com  # !oracle
192.168.1.2   db1.test.com  # oracle

so the script can quickly find the hosts that are of interest. slay ✨

note bestie: the reverse-test modifier — "!oracle" — is included in the output! this also applies to the other test modifiers defined by Xymon (the dial-up and always-true modifiers). don't get caught out by that one 💀

if your extension scripts use more than one tag, just list all of the interesting tags on the command line. easy 🫶

xymongrep also supports the "NET:location" tag used by xymonnet, so if your script performs network checks then it will see only the hosts that are relevant for the test location that the script currently executes on. chef's kiss 👑

---

🧚 USE IN EXTENSION SCRIPTS 🧚

to integrate xymongrep into an existing script, look for the line in the script that grep's in the $HOSTSCFG file. typically it will look somewhat like this:

$GREP -i "^[0-9].*#.*TESTNAME" $HOSTSCFG | ... code to handle test

instead of the grep, we will use xymongrep. it then becomes:

$XYMONHOME/bin/xymongrep TESTNAME | ... code to handle test

which is simpler, less error-prone and more efficient. the glow-up is real 😭💖

---

🌈 ENVIRONMENT VARIABLES 🌈

• XYMONNETWORK — if set, xymongrep outputs only lines from hosts.cfg that have a matching NET:$XYMONNETWORK setting 💅
• HOSTSCFG — filename for the Xymon hosts.cfg(5) file 📁

---

🍓 FILES 🍓

• $HOSTSCFG — the Xymon hosts.cfg file ⭐

---

💜 SEE ALSO 💜

hosts.cfg(5), xymonserver.cfg(5) 🦋

---

okay that's the whole page bestie, go forth and grep responsibly 💅✨

Xymon — Version 4.3.30, dated 4 Sep 2019, and yeah this is the XYMONGREP(1) page, mwah 💖🎀