Provided by: xymon_4.3.0~beta2.dfsg-9ubuntu1_i386 bug

NAME

       bbtest-net - Xymon network test tool

SYNOPSIS

       bbtest-net -?
       bbtest-net --help
       bbtest-net --version
       bbtest-net [options]
       (See the OPTIONS section for a description of the available commandline
       options).

DESCRIPTION

       bbtest-net(1) handles the network tests of hosts defined in  the  Xymon
       configuration  file,  bb-hosts. It is normally run at regular intervals
       by hobbitlaunch(8) via an entry in the hobbitlaunch.cfg(5) file.

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

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

       In addition, it implements the "dns" and "dig" tests  for  testing  DNS
       servers. This is done in the same way as bb-network.sh does it.

       bbtest-net  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: bbtest-net 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.

GENERAL OPTIONS

       --timeout=N
              Determines  the  timeout  (in  seconds) for each service that is
              tested. For TCP tests (those from BBNETSVCS), 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  bbtest-net  begins to complain about not being able to get a
              "socket", try running bbtest-net with a lower value like  50  or
              100.

       --dns-timeout=N (default: 30 seconds)
              bbtest-net  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 bbtest-net.

       --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 bbtest-net finds the IP adresses of the hosts to
              test.  By default (the "standard"), bbtest-net 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" bbtest-net will ONLY do the DNS lookup; it  it
              fails,  then all services on that host will be reported as being
              down.
              With "--dns=ip" bbtest-net will never do a DNS lookup;  it  will
              use  the  IP  adresse specified in bb-hosts 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
              "bbtest-net tags for HTTP tests" section in bb-hosts(5)

       --no-ares
              Disable  the  ARES  resolver  built  into bbtest-net. This makes
              bbtest-net  resolve  hostnames  using   your   system   resolver
              function.  You  should only use this as a last resort if bbtest-
              net 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, bbtest-net 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,  bbtest-net  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 "bbtest".

       --test-untagged
              When using the BBLOCATION  environment  variable  to  test  only
              hosts  on  a  particular network segment, bbtest-net will ignore
              hosts that do not have any "NET:x" tag.  So only hosts that have
              a NET:$BBLOCATION 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  bbretest-net.sh(1) bbgen extension. This option
              determines how long failed tests  remain  in  the  frequent-test
              queue. The default is 1800 seconds (30 minutes).

       --timelimit=N
              Causes  bbtest-net  to  generate  a  warning  if the run-time of
              bbtest-net exceeds N seconds. By default N is set to  the  value
              of  BBSLEEP,  so  a warning triggers if the network tests cannot
              complete in the time given for one cycle of  the  BBNET  server.
              Apart  from the warning, this option has no effect, i.e. it will
              not terminate bbtest-net 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 bbtest 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
              bbtest-net less often than that,  the  results  will  go  purple
              before  the  next run of bbtest-net. This option lets you change
              how long the status is valid.

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), bbtest-net 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,  bbtest-net  sends  some  extra  information in the
              status messages, called "flags". These are used by bbgen e.g. to
              pick  different  icons  for  reversed  tests when generating the
              Xymon webpages. This option makes bbtest-net  omit  these  flags
              from the status messages.

       --shuffle
              By  default,  TCP  tests run roughly in the order that the hosts
              are listed in the bb-hosts 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:  bbtest-net  uses the program defined by the FPING environment to
       execute ping-tests - by default, that is the hobbitping(1) utility. See
       hobbitserver.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 bbtest-net's ping test. The column name  used  for  ping
              test  results  is defined by the PINGCOLUMN environment variable
              in hobbitserver.cfg(5).
              If  not  specifed,  bbtest-net  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
              bbtest-net 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 bb-
              hosts(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.

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.

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 bbtest-net 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 bb-
              hosts(5)

DEBUGGING OPTIONS

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

       --timing
              Causes bbtest-net 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 commandline options.

       --version
              Prints the version number of bbtest-net

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

USING COOKIES IN WEB TESTS

       If  the  file $BBHOME/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 bbtest-net 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,  bbtest-
       net  will  report  it  as valid only until Jan 19, 2038. This is due to
       limitations in your operating system C library.

LDAP TESTS

       ldap testing can be done in two ways. If you  just  put  an  "ldap"  or
       "ldaps"  tag in bb-hosts, 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 bb-hosts. This will cause bbtest-net
       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 bbtest-
       net 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.   bb-
       hosts(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  bb-hosts  files for each of the systems.  bbtest-net supports
       the NET:location tag in bb-hosts(5) to distinguish between  hosts  that
       should  be  tested  from  different  network  locations. If you set the
       environment variable BBLOCATION e.g. to "dmz"  before  running  bbtest-
       net,  then  it  will  only  test hosts that have a "NET:dmz" tag in bb-
       hosts. This allows you to keep all of your hosts in the  same  bb-hosts
       file, but test different sets of hosts by different BBNET systems.

BBTEST-NET INTERNALS

       bbtest-net  first reads the bb-services file to see which network tests
       are defined. It then scans the bb-hosts 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 bb-services  file,  plus  the  "dns",
       "dig"  and  "ntp" tests - those tests that bb-network.sh would normally
       use the "bbnet" tool to test.

       It then runs two tasks  in  parallel:  First,  a  separate  process  is
       started  to run the "hobbitping" tool for the connectivity tests. While
       hobbitping is busy doing the "ping" checks, bbtest-net 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 bbtest-net.

       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 BB 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. Thus, they perform only marginally better than the  standard  bb-
       network.sh script.

ENVIRONMENT VARIABLES

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

       BBMAXMSGSPERCOMBO
              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  accomodate  100  status  messages  per
              transmission. So if you want to experiment with this setting,  I
              suggest starting with a value of 10.

       BBSLEEPBETWEENMSGS
              Defines  a  a  delay  (in  microseconds)  after  each message is
              transmitted to the BBDISPLAY server.  The  default  is  0,  i.e.
              send  the  messages  as  fast  as  possible.   This  gives  your
              BBDISPLAY server some time to process  the  message  before  the
              next  message comes in. Depending on the speed of your BBDISPLAY
              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 hobbitping(1) utility. Used  by  bbtest-
              net  for  connectivity  (ping) testing.  See hobbitserver.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 bbtest-net when
              checking the "ntp" service.

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

FILES

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

       $BBHOME/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.

       $BBHOME/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.

       $BBTMP/*.status - test status summary
              Each  time  bbtest-net 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 bbretest-net.sh(1)
              It is also used internally by bbtest-net  when  determining  the
              color for tests that use the "badconn" or "badTESTNAME" tags.

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

SEE ALSO

       bb-hosts(5),   bb-services(5),   hobbitserver.cfg(5),    hobbitping(1),
       curl(1), ftp(1), fping(1), ntpdate(1), rpcinfo(8)