table of contents
- NAME
- SYNOPSIS
- DESCRIPTION
- GENERAL OPTIONS
- OPTIONS FOR TESTS OF THE SIMPLE TCP SERVICES
- OPTIONS FOR THE PING TEST
- OPTIONS FOR HTTP (WEB) TESTS
- OPTIONS FOR SSL CERTIFICATE TESTS
- DEBUGGING OPTIONS
- INFORMATIONAL OPTIONS
- USING COOKIES IN WEB TESTS
- ABOUT SSL CERTIFICATE CHECKS
- LDAP TESTS
- USING MULTIPLE NETWORK TEST SYSTEMS
- BBTEST-NET INTERNALS
- ENVIRONMENT VARIABLES
- FILES
- SEE ALSO
other versions
- wheezy 4.3.0~beta2.dfsg-9.1
BBTEST-NET(1) | General Commands Manual | BBTEST-NET(1) |
NAME¶
bbtest-net - Xymon network test toolSYNOPSIS¶
bbtest-net -?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.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.
- --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.
- --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).
- --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.
- --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.
- --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.
- --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).
- --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).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).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=*)
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.(1 + (N / concurrency)) * timeout
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.
- 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
- $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)
- $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)Version 4.2.3: 4 Feb 2009 | Xymon |