Provided by: xymon_4.3.7-1ubuntu2_amd64 bug

NAME

       xymonnet - Xymon network test tool

SYNOPSIS

       xymonnet [--ping|--noping] [--timeout=N] [options] [hostname] [hostname]
       (See the OPTIONS section for a description of the available command-line options).

DESCRIPTION

       xymonnet(1)  handles  the  network tests of hosts defined in the Xymon configuration file,
       hosts.cfg. It is normally run at regular intervals by xymonlaunch(8) via an entry  in  the
       tasks.cfg(5) file.

       xymonnet  does  all  of  the normal tests of TCP-based network services (telnet, ftp, ssh,
       smtp, pop, imap ....) - i.e.  all of the  services  listed  in  protocols.cfg.  For  these
       tests, a completely new and very speedy service- checker has been implemented.

       xymonnet has built-in support for testing SSL-enabled protocols, e.g. imaps, pop3s, nntps,
       telnets, if SSL-support was enabled when configuring xymonnet.  The  full  list  of  known
       tests is found in the protocols.cfg(5) file in $XYMONHOME/etc/protocols.cfg.

       In addition, it implements the "dns" and "dig" tests for testing DNS servers.

       xymonnet  also implements a check for NTP servers - this test is called "ntp". If you want
       to use it, you must define the NTPDATE environment variable to point at  the  location  of
       your ntpdate(1) program.

       Note:  xymonnet  performs  the  connectivity test (ping) based on the hostname, unless the
       host is tagged with "testip" or the "--dns=ip" option  is  used.  So  the  target  of  the
       connectivity test can be determined by your /etc/hosts file or DNS.

       By  default,  all  servers are tested - if XYMONNETWORK is set via xymonserver.cfg(5) then
       only the hosts marked as belonging  to  this  network  are  tested.  If  the  command-line
       includes one or more hostnames, then only those servers are tested.

GENERAL OPTIONS

       --timeout=N
              Determines  the timeout (in seconds) for each service that is tested. For TCP tests
              (those from XYMONNETSVCS), if the connection to the service does not succeed within
              N  seconds,  the  service  is  reported  as being down. For HTTP tests, this is the
              absolute limit for the entire request to the webserver (the time needed to  connect
              to  the  server,  plus  the  time  it  takes the server to respond to the request).
              Default: 10 seconds

       --conntimeout=N
              This option is deprecated, and will be ignored. Use the --timeout option instead.

       --cmdtimeout=N
              This option sets a timeout for the external commands used for testing  of  NTP  and
              RPC services, and to perform traceroute.

       --concurrency=N
              Determines  the  number of network tests that run in parallel. Default is operating
              system dependent, but will usually be 256. If xymonnet begins to complain about not
              being  able  to  get a "socket", try running xymonnet with a lower value like 50 or
              100.

       --dns-timeout=N (default: 30 seconds)
              xymonnet will timeout all DNS lookups after N seconds.  Any pending DNS lookups are
              regarded  as  failed,  i.e.  the  network tests that depend on this DNS lookup will
              report an error.
              Note: If you use the --no-ares option, timeout of DNS lookups cannot be  controlled
              by xymonnet.

       --dns-max-all=N
              Same  as "--dns-timeout=N". The "--dns-max-all" option is deprecated and should not
              be used.

       --dns=[ip|only|standard]
              Determines how xymonnet finds the IP addresses of the hosts to  test.   By  default
              (the  "standard"),  xymonnet  does a DNS lookup of the hostname to determine the IP
              address, unless the host has the "testip" tag, or the DNS lookup fails.
              With "--dns=only" xymonnet will ONLY do the DNS  lookup;  it  it  fails,  then  all
              services on that host will be reported as being down.
              With  "--dns=ip"  xymonnet  will  never do a DNS lookup; it will use the IP adresse
              specified in hosts.cfg for the tests. Thus, this setting is  equivalent  to  having
              the  "testip"  tag  on all hosts. Note that http tests will ignore this setting and
              still perform a DNS lookup for the hostname given in the  URL;  see  the  "xymonnet
              tags for HTTP tests" section in hosts.cfg(5)

       --no-ares
              Disable  the  ARES  resolver  built  into  xymonnet.  This  makes  xymonnet resolve
              hostnames using your system resolver function. You should only use this as  a  last
              resort  if xymonnet cannot resolve the hostnames you use in the normal way (via DNS
              or /etc/hosts). One reason for using this would be if you need to resolve hostnames
              via NIS/NIS+ (a.k.a. Yellow Pages).
              The  system resolver function does not provide a mechanism for controlling timeouts
              of the hostname lookups, so if your DNS or NIS server is down, xymonnet can take  a
              very  long time to run. The --dns-timeout option is effectively disabled when using
              this option.

       --dnslog=FILENAME
              Log failed hostname lookups to  the  file  FILENAME.  FILENAME  should  be  a  full
              pathname.

       --report[=COLUMNNAME]
              With  this  option,  xymonnet  will  send a status message with details of how many
              hosts were processed, how many tests  were  generated,  any  errors  that  occurred
              during the run, and some timing statistics.  The default columnname is "xymonnet".

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

       --frequenttestlimit=N
              Used with the xymonnet-again.sh(1) Xymon extension. This option determines how long
              failed  tests  remain  in  the frequent-test queue. The default is 1800 seconds (30
              minutes).

       --timelimit=N
              Causes xymonnet to generate a  warning  if  the  run-time  of  xymonnet  exceeds  N
              seconds.  By  default  N is set to the value of TASKSLEEP, so a warning triggers if
              the network tests cannot complete in the time given for one cycle of  the  xymonnet
              task. Apart from the warning, this option has no effect, i.e. it will not terminate
              xymonnet prematurely. So to eliminate any such warnings, use  this  option  with  a
              very high value of N.

       --huge=N
              Warn  if  the  response  from a TCP test is more than N bytes.  If you see from the
              xymonnet status report that you are transferring large amounts  of  data  for  your
              tests, you can enable this option to see which tests have large replies.
              Default: 0 (disabled).

       --validity=N
              Make  the  test results valid for N minutes before they go purple.  By default test
              results are valid for 30 minutes; if you run xymonnet less  often  than  that,  the
              results will go purple before the next run of xymonnet. This option lets you change
              how long the status is valid.

       --source-ip=IPADDRESS
              On multi-homed hosts, this option can be used to explicitly select  the  source  IP
              address  used for the network tests.  "IPADDRESS" must be a valid IP-address on the
              host running xymonnet.

       --loadhostsfromxymond
              Instead  of  reading  the  hosts.cfg  file,  xymonnet  will  load   the   hosts.cfg
              configuration  from  the  xymond  daemon.  This eliminates the need for reading the
              hosts.cfg, and if you have xymond and xymonnet running on different hosts, it  also
              eliminates  the  need for copying the hosts.cfg file between systems. Note that the
              "netinclude" option in hosts.cfg is ignored when this option is enabled.

OPTIONS FOR TESTS OF THE SIMPLE TCP SERVICES

       --checkresponse[=COLOR]
              When testing well-known services (e.g. FTP, SSH, SMTP, POP-2, POP-3, IMAP, NNTP and
              rsync),  xymonnet  will look for a valid service-specific "OK" response. If another
              reponse is seen, this will cause the test to  report  a  warning  (yellow)  status.
              Without this option, the response from the service is ignored.
              The  optional color-name is used to select a color other than yellow for the status
              message when the response is wrong.  E.g. "--checkresponse=red" will cause a  "red"
              status message to be sent when the service does not respond as expected.

       --no-flags
              By  default,  xymonnet  sends some extra information in the status messages, called
              "flags". These are used by xymongen e.g. to pick different icons for reversed tests
              when  generating  the  Xymon  webpages. This option makes xymonnet omit these flags
              from the status messages.

       --shuffle
              By default, TCP tests run roughly in the order that the hosts  are  listed  in  the
              hosts.cfg  file.  If  you  have  many  tests  for one server, this may result in an
              exceptionally large load when Xymon is testing it because Xymon will perform a  lot
              of  tests  at  the  same  time.  To  avoid  this, the --shuffle option reorders the
              sequence of tests so they are spread randomly across all of the servers tested.

OPTIONS FOR THE PING TEST

       Note: xymonnet uses the program defined by the FPING environment to execute  ping-tests  -
       by  default, that is the xymonping(1) utility. See xymonserver.cfg(5) for a description of
       how to customize this, e.g. if you need to run it with "sudo" or a similar tool.

       --ping Enables xymonnet's ping test. The column name used for ping test results is defined
              by the PINGCOLUMN environment variable in xymonserver.cfg(5).
              If  not  specified, xymonnet uses the CONNTEST environment variable to determine if
              it should perform the ping test or not. So if you prefer to  use  another  tool  to
              implement  ping  checks,  either set the CONNTEST environment variable to false, or
              run xymonnet with the "--noping".

       --noping
              Disable the connectivity test.

       --trace

       --notrace
              Enable/disable the  use  of  traceroute  when  a  ping-test  fails.   Performing  a
              traceroute  for  failed ping tests is a slow operation, so the default is not to do
              any traceroute, unless it is requested on a per-host basis via the "trace"  tag  in
              the  hosts.cfg(5)  entry  for  each host. The "--trace" option changes this, so the
              default becomes to run traceroute on all hosts where the ping test fails;  you  can
              then disable it on specific hosts by putting a "notrace" tag on the host-entry.

       --ping-tasks=N
              Spread  the  task  of  pinging the hosts over N processes. If you have a very large
              number of hosts the time it takes to ping all of them can be substantial, even with
              the  use  of  tools  like fping or xymonping that ping many hosts in parallel. This
              option causes xymonnet to start N separate ping processes, the IP's that are  being
              ping'ed will be divided evenly between these processes.

OPTIONS FOR HTTP (WEB) TESTS

       --content=CONTENTTESTNAME
              Determines  the  name of the column Xymon displays for content checks.  The default
              is "content".  If you have used the "cont.sh" or "cont2.sh"  scripts  earlier,  you
              may  want to use "--content=cont" to report content checks using the same test name
              as these scripts do.

       --bb-proxy-syntax
              Adhere to the Big Brother syntax for a URL, which allows specifying a HTTP proxy as
              part  of  a URL. See "HTTP Testing via proxy" in the hosts.cfg(5) file for details.
              Beginning with Xymon 4.3.0, this behaviour is disabled by default since URL's  that
              include  other  URL's  are  now  much more common. This option restores the old Big
              Brother-compatible behaviour.

OPTIONS FOR SSL CERTIFICATE TESTS

       --ssl=SSLCERTTESTNAME
              Determines the name of the column Xymon displays for the  SSL  certificate  checks.
              The default is "sslcert".

       --no-ssl
              Disables reporting of the SSL certificate check.

       --sslwarn=N

       --sslalarm=N
              Determines  the  number  of  days before an SSL certificate expires, where xymonnet
              will generate a warning or alarm status for the SSL certificate column.

       --sslbits=N
              Enables checking that  the  encryption  supported  by  the  SSL  protocol  uses  an
              encryption  key  of  at least N bits.  E.g. to trigger an alert if your SSL-enabled
              website supports less than 128 bits of encryption, use "--sslbits=128".  Note: This
              can be enabled on a per-host basis using the "sslbits=N" setting in hosts.cfg(5)

DEBUGGING OPTIONS

       --no-update
              Don't send any status updates to the Xymon server. Instead, all messages are dumped
              to stdout.

       --timing
              Causes xymonnet to collect information about the time spent in different  parts  of
              the  program.   The  information is printed on stdout just before the program ends.
              Note that this information is also included in the  status  report  sent  with  the
              "--report" option.

       --debug
              Dumps a bunch of status about the tests as they progress to stdout.

       --dump[=before|=after|=both]
              Dumps internal memory structures before and/or after the tests have executed.

INFORMATIONAL OPTIONS

       --help or -?
              Provide a summary of available command-line options.

       --version
              Prints the version number of xymonnet

       --services
              Dump  the  list  of defined TCP services xymonnet knows how to test. Do not run any
              tests.

USING COOKIES IN WEB TESTS

       If the file $XYMONHOME/etc/cookies exist, cookies will be read from  this  file  and  sent
       along  with  the HTTP requests when checking websites. This file is in the Netscape Cookie
       format,  see  http://www.netscape.com/newsref/std/cookie_spec.html  for  details  on  this
       format. The curl(1) utility can output a file in this format if run with the "--cookie-jar
       FILENAME" option.

ABOUT SSL CERTIFICATE CHECKS

       When xymonnet tests services that use SSL- or TLS-based protocols, it will check that  the
       server  certificate  has  not  expired. This check happens automatically for https (secure
       web), pop3s, imaps, nntps and all other SSL-enabled services (except ldap, see LDAP  TESTS
       below).

       All certificates found for a host are reported in one status message.

       Note:  On  most  systems, the end-date of the certificate is limited to Jan 19th, 2038. If
       your certificate is valid after this date, xymonnet will report it as valid only until Jan
       19,   2038.  This  is  due  to  limitations  in  your  operating  system  C  library.  See
       http://en.wikipedia.org/wiki/2038_problem .

LDAP TESTS

       ldap testing can be done in two ways. If  you  just  put  an  "ldap"  or  "ldaps"  tag  in
       hosts.cfg,  a simple test is performed that just verifies that it is possible to establish
       a connection to the port running the ldap service (389 for ldap, 636 for ldaps).

       Instead you can put an LDAP URI in hosts.cfg. This will cause xymonnet to initiate a full-
       blown  LDAP  session with the server, and do an LDAP search for the objects defined by the
       URI. This requires that xymonnet was built with LDAP support, and relies  on  an  existing
       LDAP  library  to  be installed.  It has been tested with OpenLDAP 2.0.26 (from Red Hat 9)
       and 2.1.22.  The Solaris 8 system ldap library has also been confirmed  to  work  for  un-
       encrypted (plain ldap) access.

       The format of LDAP URI's is defined in RFC 2255. LDAP URLs look like this:

         ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]]

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

       Example:
         ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*)

       All  "bind"  operations  to LDAP servers use simple authentication.  Kerberos and SASL are
       not supported. If your LDAP server requires a username/password, use the  "ldaplogin"  tag
       to  specify  this,  cf.   hosts.cfg(5) If no username/password information is provided, an
       anonymous bind will be attempted.

       SSL support requires both a client library and an LDAP server that support LDAPv3; it uses
       the LDAP "STARTTLS" protocol request after establishing a connection to the standard (non-
       encrypted) LDAP port (usually port 389). It has only been tested  with  OpenSSL  2.x,  and
       probably will not work with any other LDAP library.

       The  older  LDAPv2  experimental  method  of tunnelling normal LDAP traffic through an SSL
       connection - ldaps, running on port 636 - is not supported, unless someone can explain how
       to  get the OpenLDAP library to support it. This method was never formally described in an
       RFC, and implementations of it are non-standard.

       For a discussion of the various ways of running encrypted ldap, see
       http://www.openldap.org/lists/openldap-software/200305/msg00079.html
       http://www.openldap.org/lists/openldap-software/200305/msg00084.html
       http://www.openldap.org/lists/openldap-software/200201/msg00042.html
       http://www.openldap.org/lists/openldap-software/200206/msg00387.html

       When testing LDAP URI's, all of the  communications  are  handled  by  the  ldap  library.
       Therefore,  it  is not possible to obtain the SSL certificate used by the LDAP server, and
       it will not show up in the "sslcert" column.

USING MULTIPLE NETWORK TEST SYSTEMS

       If you have more than one system running network tests - e.g. if your network is separated
       by firewalls - then is is problematic to maintain multiple hosts.cfg files for each of the
       systems.  xymonnet supports the NET:location tag in hosts.cfg(5)  to  distinguish  between
       hosts  that  should be tested from different network locations. If you set the environment
       variable XYMONNETWORK e.g. to "dmz" before running xymonnet, then it will only test  hosts
       that  have  a "NET:dmz" tag in hosts.cfg. This allows you to keep all of your hosts in the
       same hosts.cfg file, but test  different  sets  of  hosts  by  different  systems  running
       xymonnet.

XYMONNET INTERNALS

       xymonnet  first  reads  the  protocols.cfg file to see which network tests are defined. It
       then scans the hosts.cfg file, and collects information about the TCP service  tests  that
       need to be tested. It picks out only the tests that were listed in the protocols.cfg file,
       plus the "dns", "dig" and "ntp" tests.

       It then runs two tasks in parallel: First, a  separate  process  is  started  to  run  the
       "xymonping"  tool  for  the  connectivity  tests. While xymonping is busy doing the "ping"
       checks, xymonnet runs all of the TCP-based network tests.

       All  of  the  TCP-based  service  checks  are  handled  by  a  connection  tester  written
       specifically  for  this purpose. It uses only standard Unix-style network programming, but
       relies on the  Unix  "select(2)"  system-call  to  handle  many  simultaneous  connections
       happening  in  parallel.  Exactly  how many parallel connections are being used depends on
       your operating system - the default is FD_SETSIZE/4, which amounts to  256  on  many  Unix
       systems.

       You  can  choose the number of concurrent connections with the "--concurrency=N" option to
       xymonnet.

       Connection attempts timeout after 10 seconds - this can be changed with the  "--timeout=N"
       option.

       Both  of these settings play a part in deciding how long the testing takes. A conservative
       estimate for doing N TCP tests is:

          (1 + (N / concurrency)) * timeout

       In real life it will probably be less, as the above formula is for every test to require a
       timeout.  Since the most normal use of Xymon is to check for services that are active, you
       should have a lot less timeouts.

       The "ntp" and "rpcinfo" checks rely on external programs to do each test.

ENVIRONMENT VARIABLES

       XYMONNETWORK
              Defines the network segment where xymonnet is currently running.  This is  used  to
              filter  out  only  the  entries  in  the  hosts.cfg(5)  file  that  have a matching
              "NET:LOCATION" tag, and execute the tests for only those hosts.

       MAXMSGSPERCOMBO
              Defines the maximum number of status  messages  that  can  be  sent  in  one  combo
              message. Default is 0 - no limit.
              In  practice, the maximum size of a single Xymon message sets a limit - the default
              value for the maximum message size is 32 KB, but that will easily  accommodate  100
              status messages per transmission. So if you want to experiment with this setting, I
              suggest starting with a value of 10.

       SLEEPBETWEENMSGS
              Defines a a delay (in microseconds) after each message is transmitted to the  Xymon
              server.  The default is 0, i.e.  send the messages as fast as possible.  This gives
              your Xymon server some time to process the message before the  next  message  comes
              in.  Depending  on  the speed of your Xymon server, it may be necessary to set this
              value to half a second or even 1 or 2 seconds.  Note that the value is specified in
              MICROseconds,  so to define a delay of half a second, this must be set to the value
              "500000"; a delay of 1 second  is  achieved  by  setting  this  to  "1000000"  (one
              million).

       FPING  Command  used  to  run  the xymonping(1) utility. Used by xymonnet for connectivity
              (ping) testing.  See xymonserver.cfg(5) for more information about how to customize
              the program that is executed to do ping tests.

       TRACEROUTE
              Location  of  the  traceroute(8)  utility,  or  an  equivalent  tool  e.g.  mtr(8).
              Optionally used when a connectivity test fails to  pinpoint  the  network  location
              that is causing the failure.

       NTPDATE
              Location  of  the  ntpdate(1)  utility.  Used  by  xymonnet when checking the "ntp"
              service.

       RPCINFO
              Location of the rpcinfo(8) utility. Used by xymonnet for the "rpc" service checks.

FILES

       ~/server/etc/protocols.cfg
              This file contains definitions of TCP services that xymonnet can test.  Definitions
              for  a  default  set  of  common  services is built into xymonnet, but these can be
              overridden or supplemented by defining services  in  the  protocols.cfg  file.  See
              protocols.cfg(5) for details on this file.

       $XYMONHOME/etc/netrc - authentication data for password-protected webs
              If  you  have password-protected sites, you can put the usernames and passwords for
              these here. They will then get picked up automatically when  running  your  network
              tests.   This  works  for  web-sites  that use the "Basic" authentication scheme in
              HTTP.  See ftp(1) for details - a sample entry would look like this
                 machine www.acme.com login fred password Wilma1
              Note that the machine-name must be the name you use in the http://machinename/  URL
              setting - it need not be the one you use for the system-name in Xymon.

       $XYMONHOME/etc/cookies
              This  file  may  contain  website cookies, in the Netscape HTTP Cookie format. If a
              website requires a static cookie to be present in order for the check to  complete,
              then  you can add this cookie to this file, and it will be sent along with the HTTP
              request. To get the cookies into this file, you  can  use  the  "curl  --cookie-jar
              FILE" to request the URL that sets the cookie.

       $XYMONTMP/*.status - test status summary
              Each  time xymonnet runs, if any tests fail (i.e. they result in a red status) then
              they will be listed in a file name TESTNAME.[LOCATION].status.  The  LOCATION  part
              may  be null. This file is used to determine how long the failure has lasted, which
              in  turn  decides  if  this  test  should  be  included  in  the  tests   done   by
              xymonnet-again.sh(1)
              It  is  also  used internally by xymonnet when determining the color for tests that
              use the "badconn" or "badTESTNAME" tags.

       $XYMONTMP/frequenttests.[LOCATION]
              This file contains the hostnames of those hosts that  should  be  retested  by  the
              xymonnet-again.sh(1)  test  tool.  It is updated only by xymonnet during the normal
              runs, and read by xymonnet-again.sh.

SEE ALSO

       hosts.cfg(5),  protocols.cfg(5),  xymonserver.cfg(5),   xymonping(1),   curl(1),   ftp(1),
       fping(1), ntpdate(1), rpcinfo(8)