NAME

       xymongrep - pick out lines in hosts.cfg

SYNOPSIS

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

DESCRIPTION

       xymongrep(1)  is  for use by extension scripts that need to pick out the entries in a hosts.cfg file that
       are relevant to the script.

       The utility accepts test names as parameters, and will then parse the hosts.cfg file and  print  out  the
       host  entries  that  have  at  least one of the wanted tests specified. Tags may be given with a trailing
       asterisk '*', e.g. "xymongrep http*" is needed to find all http and https tags.

       The xymongrep utility supports the use of "include" directives inside the hosts.cfg file, and  will  find
       matching tags in all included files.

       If  the  DOWNTIME  or  SLA  tags are used in the hosts.cfg(5) file, these are interpreted relative to the
       current time.  xymongrep then outputs a "INSIDESLA" or "OUTSIDESLA" tag for easier use  by  scripts  that
       want to check if the current time is inside or outside the expected uptime window.

OPTIONS

       --noextras
              Remove the "testip", "dialup", "INSIDESLA" and "OUTSIDESLA" tags from the output.

       --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.

       --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 the 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.  This can be used to ignore hosts that are down, 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
              xymongrep  will  normally  attempt to load the HOSTSCFG file by itself when searching for lines to
              transmit. 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 can be used if you're
              running this on a client or remote system and can't or don't  want  to  have  the  hosts.cfg  file
              synchronized across your servers.

EXAMPLE

       If 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.

       Note that 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).

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

       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.

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.

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)

Xymon                                      Version 4.3.30:  4 Sep 2019                              XYMONGREP(1)