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)