The format of an entry in the bb-hosts file is as follows:
IP-address hostname # tag1 tag2 ...
The IP-address and hostname are mandatory; all of the tags are optional. Listing a host with only IP-address and hostname will cause a network test to be executed for the host - the connectivity test is enabled by default, but no other tests.
The optional tags are then used to define which tests are relevant for the host, and also to set e.g. the time-interval used for availability reporting by bbgen(1)
An example of setting up the bb-hosts file is in the Hobbit on-line documentation (from the Help menu, choose "Configuring Monitoring"). The following describes the possible settings in a bb-hosts file supported by Hobbit.
The "filename" argument should point to a file that uses the same syntax as bb-hosts. The filename can be an absolute filename (if it begins with a '/'), or a relative filename - relative filenames are prefixed with the directory where the main bb-hosts file is located (usually $BBHOME/etc/).
You can nest include tags, i.e. a file that is included from the main bb-hosts file can itself include other files.
E.g. with this in bb-hosts:
page USA United States
subpage NY New York
subparent NY manhattan Manhattan data centers
subparent manhattan wallstreet Wall Street center
you get this hierarchy of pages:
USA (United States)
NY (New York)
manhattan (Manhattan data centers)
wallstreet (Wall Street center)
Note: The parent page must be defined before you define the subparent. If not, the page will not be generated, and you get a message in the log file.
Note: bbgen is case-sensitive, when trying to match the name of the parent page.
The inspiration for this came from Craig Cook's mkbb.pl script, and I am grateful to Craig for suggesting that I implement it in bbgen. The idea to explicitly list the parent page in the "subparent" tag was what made it easy to implement.
The title tag operates on the next item in the bb-hosts file following the title tag.
If a title tag precedes a host entry, the title is shown just before the host is listed on the status page. The column headings present for the host will be repeated just after the heading.
If a title tag precedes a group entry, the title is show just before the group on the status page.
If a title tag precedes a page/subpage/subparent entry, the title text replaces the normal "Pages hosted locally" heading normally inserted by Hobbit. This appears on the page that links to the subpages, not on the subpage itself. To get a custom heading on the subpage, you may want to use the "--pagetext-heading" when running bbgen(1)
By using the "prefer" tag you tell bbgen that this host definition should be used.
Note: This only applies to hosts that are defined multiple times in the bb-hosts file, although it will not hurt to add it on other hosts as well.
(Historical note: The name "NK" comes from an in-house danish abbreviation for our network monitoring center, "Net Kontrollen").
12.34.56.78 www.acme.com # http://www.acme.com/ NK:http
If you want multiple tests for a host to show up on the bbnk.html page, specify all the tests separated by commas. The test names correspond to the column names (e.g. https tests are covered by an "NK:http" tag).
By default, tests with a red or yellow status that are listed in the "NK:testname" tag will appear on the NK page. However, you may not want the test to be shown outside of normal working hours - if, for example, the host is not being serviced during week-ends.
You can then use the NKTIME tag to define the time periods where the alert will show up on the NK page.
The timespecification consists of
day-of-week: W means Mon-Fri ("weekdays"), * means all days, 0 .. 6 = Sunday .. Saturday. Listing multiple days is possible, e.g. "60" is valid meaning "Saturday and Sunday".
starttime: Time to start showing errors, must be in 24-hour clock format as HHMM hours/minutes. E.g. for 8 am enter "0800", for 9.30 pm enter "2130"
endtime: Time to stop showing errors.
If necessary, multiple periods can be specified. E.g. to monitor a site 24x7, except between noon and 1 pm, use NKTIME=*:0000:1159,*:1300:2359
The interval between starttime and endtime may cross midnight, e.g. *:2330:0200 would be valid and have the same effect as *:2330:2400,*:0000:0200.
The default set of WML tests are taken from the --wml commandline option. If no "WML:" tag is specified, the "NK:" tag is used if present.
If a host-specific tag begins with a '-' or a '+', the host-specific tags are removed/added to the default setting from the command-line option. If the host-specific tag does not begin with a '+' or a '-', the default setting is ignored for this host and the NOPROPRED applies to the tests given with this tag.
E.g.: bbgen runs with "--nopropred=ftp,smtp". "NOPROPRED:+dns,-smtp" gives a NOPROPRED setting of "ftp,dns" (dns is added to the default, ftp is removed). "NOPROPRED:dns" gives a setting of "dns" only (the default is ignored).
Note: If you set use the "--nopropred=*" commandline option to disable propagation of all alerts, you cannot use the "+" and "-" methods to add or remove from the wildcard setting. In that case, do not use the "+" or "-" setting, but simply list the required tests that you want to keep from propagating.
When bbgen generates a report, it computes the availability of each service - i.e. the percentage of time that the service is reported as available (meaning: not red).
By default, this calculation is done on a 24x7 basis, so no matter when an outage occurs, it counts as downtime.
The REPORTTIME tag allows you to specify a period of time
other than 24x7 for the service availability calculation.
If you have systems where you only guarantee availability
from e.g. 7 AM to 8 PM on weekdays, you can use
REPORTTIME=W:0700:2000
and the availability calculation will only be performed
for the service with measurements from this time interval.
The syntax for REPORTTIME is the same as the one used by the NKTIME parameter.
When REPORTTIME is specified, the availability calculation happens like this:
* Only measurements done during the given time period is used for the calculation.
* "blue" time reduces the length of the report interval,
so if you are generating a report for a 10-hour period
and there are 20 minutes of "blue" time, then the
availability calculation will consider the reporting
period to be 580 minutes (10 hours minus 20 minutes).
This allows you to have scheduled downtime during the
REPORTTIME interval without hurting your availability;
this is (I believe) the whole idea of the downtime being
"planned".
* "red" and "clear" status counts as downtime; "yellow"
and "green" count as uptime. "purple" time is ignored.
The availability calculation correctly handles status changes that cross into/out of a REPORTTIME interval.
If no REPORTTIME is given, the standard 24x7 calculation is used.
This option allows you to set the threshold value on a host-by-host basis, instead of using a global setting for all hosts. The threshold is defined as the percentage of the time that the host must be available, e.g. "WARNPCT:98.5" if you want the threshold to be at 98.5%
Note: The "--test-untagged" option modifies this behaviour, see bbtest-net(1)
Note that this behaviour can also be implemented on a per-test basis by putting the "~" flag on any network test.
What happens is that if a test fails during the specified time, it is reported with status BLUE instead of yellow or red. Thus you can still see when the service was unavailable, but alarms will not be triggered and the downtime is not counted in the availability calculations generated by the Hobbit reports.
The syntax for DOWNTIME is the same as the one used by the NKTIME parameter.
This tag works the opposite of the DOWNTIME tag - you use it to specify the periods of the day that the service should be green. Failures OUTSIDE the SLA interval are reported as blue.
depends=(testA:host1/test1,host2/test2)
When deciding the color to report for testA, if either host1/test1 failed or host2/test2 failed, if testA has failed also then the color of testA will be "clear" instead of red or yellow.
Since all tests are actually run before the dependencies are evaluated, you can use any host/test in the dependency - regardless of the actual sequence that the hosts are listed, or the tests run. It is also valid to use tests from the same host that the dependency is for. E.g.
1.2.3.4 foo # http://foo/ webmin depends=(webmin:foo/http)
is valid; if both the http and the webmin tests fail, then webmin will be reported as clear.
Note: The "depends" tag is evaluated on the BBNET server while running the network tests. It can therefore only refer to other network tests that are handled by the same BBNET server - there is currently no way to use the e.g. the status of locally run tests (disk, cpu, msgs) or network tests from other BBNET servers in a dependency definition. Such dependencies are silently ignored.
The optional timespecification can be used to limit this
"badTEST" setting to a particular time of day, e.g. to
require a longer period of downtime before raising an
alarm during out-of-office hours. The time-specification
uses:
* Weekdays: The weekdays this badTEST tag applies, from
0 (Sunday) through 6 (Saturday). Putting "W" here counts
as "12345", i.e. all working days. Putting "*" here
counts as all days of the week, equivalent to "0123456".
* starttime and endtime are specified using 24-hour clocks,
e.g. "badTEST-W-0900-2000" is valid for working days
between 9 AM (09:00) and 8 PM (20:00).
When using multiple badTEST tags, the LAST one specified with a matching time-spec is used.
Note: The "TEST" is replaced by the name of the test, e.g.
12.34.56.78 www.foo.com # http://www.foo.com/ badhttp:1:2:4
defines a http test that goes "clear" after the first failure, "yellow" after two successive failures, and "red" after four successive failures.
For the other network tests, use "badftp", "badssh" etc.
The actual name of the tag - "conn" by default - depends on the "--ping=TESTNAME" option for bbtest-net, as that decides the testname for the connectivity test.
When multiple IP's are pinged, you can choose if ALL IP's must respond (the "worst" method), or AT LEAST one IP must respond (the "best" setting). All of the IP's are reported in a single "conn" status, whose color is determined from the result of pinging the IP's and the best/worst setting. The default method is "best" - so it will report green if just one of the IP's respond to ping.
The router1,router2,... is a comma-separated list of hosts elsewhere in the bb-hosts file. You cannot have any spaces in the list - separate hosts with commas.
This tag changes the color reported for a ping check that fails, when one or more of the hosts in the "route" list is also down. A "red" status becomes "yellow" - other colors are unchanged. The status message will include information about the hosts in the router-list that are down, to aid tracking down which router is the root cause of the problem.
Note: Internally, the ping test will still be handled as "failed", and therefore any other tests run for this host will report a status of "clear".
Hobbit places the modembank information on the page where it is defined. For this to appear correctly, you must make sure that the "dialup" directive is not mixed in with normal hosts - the "dialup" directive should appear immediately following a "page", "subpage", "subparent" or "group" directive.
How these tests operate are configured in the bb-services(5) configuration file, which controls which port to use for the service, whether to send any data to the service, whether to check for a response from the service etc.
You can modify the behaviour of these tests on a per-test basis by adding one or more modifiers to the test: :NUMBER changes the port number from the default to the one you specify for this test. E.g. to test ssh running on port 8022, specify the test as ssh:8022.
:s makes the test silent, i.e. it does not send any data to the service. E.g. to do a silent test of an smtp server, enter smtp:s.
You can combine these two: ftp:8021:s is valid.
The name of the test also determines the columnname that the test result will appear with in the Hobbit webpages.
By prefixing a test with "!" it becomes a reverse test: Hobbit will expect the service NOT to be available, and send a green status if it does NOT respond. If a connection to the service succeeds, the status will go red.
By prefixing a test with "?" errors will be reported with a "clear" status instead of red. This is known as a test for a "dialup" service, and allows you to run tests of hosts that are not always online, without getting alarms while they are off-line.
The second form of the test allows you to perform multiple queries of the DNS server, requesting different types of DNS records. The TYPE defines the type of DNS data: A (IP-address), MX (Mail eXchanger), PTR (reverse), CNAME (alias), SOA (Start-Of-Authority), NS (Name Server) are among the more common ones used. The "lookup" is the query. E.g. to lookup the MX records for the "foo.com" domain, you would use "dns=mx:foo.com". Or to lookup the nameservers for the "bar.org" domain, "dns=ns:bar.org". You can list multiple lookups, separated by commas. For the test to end up with a green status, all lookups must succeed.
If only "rpc" is given, the test only verifies that the portmapper is available on the remote host. If you want to check that one or more RPC services are registered with the portmapper, list the names of the desired RPC services after the equals-sign. E.g. for a working NFS server the "mount", "nlockmgr" and "nfs" services must be available; this can be checked with "rpc=mount,nlockmgr,nfs".
This test uses the rpcinfo tool for the actual test; if this tool is not available in the PATH of bbtest-net, you must define the RPCINFO environment variable to point at this tool. See hobbitserver.cfg(5)
The following items describe more advanced forms of http URL's.
bbtest-net can be told to use specific dialects, by adding one or more "dialect names" to the URL scheme, i.e. the "http" or "https" in the URL:
* "2", e.g. https2://www.sample.com/ : use only SSLv2
* "3", e.g. https3://www.sample.com/ : use only SSLv3
* "m", e.g. httpsm://www.sample.com/ : use only 128-bit ciphers
* "h", e.g. httpsh://www.sample.com/ : use only >128-bit ciphers
* "10", e.g. http10://www.sample.com/ : use HTTP 1.0
* "11", e.g. http11://www.sample.com/ : use HTTP 1.1
These can be combined where it makes sense, e.g to force SSLv2 and HTTP 1.0 you would use "https210".
The reason for this is that it interacts badly with virtual hosts, especially if these are IP-based as is common with https-websites.
Instead the IP-address to connect to can be overridden by specifying it as:
http://www.sample.com=1.2.3.4/index.html
The "=1.2.3.4" will case bbtest-net to run the test against the IP-address "1.2.3.4", but still trying to access a virtual website with the name "www.sample.com".
The "=ip.address.of.host" must be the last part of the hostname, so if you need to combine this with e.g. an explicit portnumber, it should be done as
http://www.sample.com:3128=1.2.3.4/index.html
If the proxy portnumber is not specified, the default HTTP portnumber (80) is used.
If your proxy requires authentication, you can specify the
username and password inside the proxy-part of the URL, e.g.
http://fred:Wilma1@webproxy.sample.com:3128/http://www.foo.com/
will authenticate to the proxy using a username of "fred" and
a password of "Wilma1", before requesting the proxy to fetch
the www.foo.com homepage.
Note that it is not possible to test https-sites via a proxy, nor is it possible to use https for connecting to the proxy itself.
If the URL itself includes a semi-colon, this must be escaped as '%3B' to avoid confusion over which semicolon is part of the URL, and which semicolon acts as a delimiter.
The data that must be returned can be specified either as a regular expression (except that <space> is not allowed) or as a message digest (typically using an MD5 sum or SHA-1 hash).
The regex is pre-processed for backslash "\" escape
sequences. So you can really put any character in this
string by escaping it first:
\n Newline (LF, ASCII 10 decimal)
\r Carriage return (CR, ASCII 13 decimal)
\t TAB (ASCII 8 decimal)
\\ Backslash (ASCII 92 decimal)
\XX The character with ASCII hex-value XX
If you must have whitespace in the regex, use the [[:space:]] syntax, e.g. if you want to test for the string "All is OK", use "All[[:space:]]is[[:space:]]OK". Note that this may depend on your particular implementation of the regex functions found in your C library. Thanks to Charles Goyard for this tip.
Note: If you are migrating from the "cont2.sh" script, you must change the '_' used as wildcards by cont2.sh into '.' which is the regular-expression wildcard character.
Message digests can use whatever digest algorithms your libcrypto implementation (usually OpenSSL) supports. Common message digests are "md5" and "sha1". The digest is calculated on the data portion of the response from the server, i.e. HTTP headers are not included in the digest (as they change from one request to the next).
The expected digest value can be computed with the bbdigest(1) utility.
"cont" tags in bb-hosts result in two status reports: One status with the "http" check, and another with the "content" check.
As with normal URL's, the extended syntax described above can be used e.g. when testing SSL sites that require the use of SSLv2 or strong ciphers.
The column name for the result of the content check is by default called "content" - you can change the default with the "--content=NAME" option to bbtest-net. See bbtest-net(1) for a description of this option.
If more than one content check is present for a host, the first content check is reported in the column "content", the second is reported in the column "content1", the third in "content2" etc.
You can also specify the columnname directly in the test specification, by writing it as "cont=COLUMN;http://...". Column-names cannot include whitespace or semi-colon.
The form-data field must be entered in "application/x-www-form-urlencoded" format, which is the most commonly used format for web forms.
E.g. if you have a web form defined like this:
<form action="/cgi-bin/form.cgi" method="post">
<p>Given name<input type="text" name="givenname"></p>
<p>Surname<input type="text" name="surname"></p>
<input type="submit" value="Send">
</form>
and you want to post the value "John" to the first field and "Doe Jr." to the second field, then the formdata field would be
givenname=John&surname=Doe+Jr.
Note that any spaces in the input value is replaced with '+'.
The [expected_data_regexp|#digesttype:digest] is the expected data returned from the server in response to the POST. See the "cont;" tag above for details. If you are only interested in knowing if it is possible to submit the form (but don't care about the data), this can be an empty string - but the ';' at the end is required.
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.
Note that you need to enable the server-status URL in your Apache configuration. The following configuration is needed:
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
allow from 127.0.0.1
</Location>
ExtendedStatus On
Change "127.0.0.1" to the IP-address of the server that runs your network tests.