BB-HOSTS

Section: File Formats (5)
Updated: Version 4.2.2: 15 Dec 2008
Index Return to Main Contents
 

NAME

bb-hosts - Main Xymon configuration file

 

SYNOPSIS

bb-hosts

 

DESCRIPTION

The bb-hosts(5) file is the most important configuration file for all of the Xymon programs. This file contains the full list of all the systems monitored by Xymon, including the set of tests and other configuration items stored for each host.

 

FILE FORMAT

Each line of the file defines a host. Blank lines and lines starting with a hash mark (#) are treated as comments and ignored. Long lines can be broken up by putting a backslash at the end of the line and continuing the entry on the next line.

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 Xymon on-line documentation (from the Help menu, choose "Configuring Monitoring"). The following describes the possible settings in a bb-hosts file supported by Xymon.

 

TAGS RECOGNIZED BY ALL TOOLS

include filename
This tag is used to include another file into the bb-hosts file at run-time, allowing for a large bb-hosts file to be split up into more manageable pieces.

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.

dispinclude filename
Acts like the "include" tag, but only on the BBDISPLAY server. Can be used e.g. to put a group of hosts on multiple subpages, without having to repeat the host definitions.

netinclude filename
Acts like the "include" tag, but only on the BBNET server.

 

BBGEN DISPLAY OPTIONS

These tags are processed by the bbgen(1) tool when generating the Xymon webpages or reports.

page NAME [Page-title]
This defines a page at the level below the entry page. All hosts following the "page" directive appear on this page, until a new "page", "subpage" or "subparent" line is found.

subpage NAME [Page-title]
This defines a subpage in the second level below the entry page. You must have a previous "page" line to hook this subpage to.

subparent parentpage newpage [Page-title]
This is used to define subpages in whatever levels you may wish. Just like the standard "subpage" tag, "subparent" defines a new Xymon webpage; however with "subparent" you explicitly list which page it should go as a subpage to. You can pick any page as the parent - pages, subpages or even other subparent pages. So this allows you to define any tree structure of pages that you like.

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.

group [group-title]
group-compress [group-title]
Defines a group of hosts, that appear together on the webpage, with a single header-line listing all of the columns. Hosts following the "group" line appear inside the group, until a new "group" or page-line is found. The two group-directives are handled identically by Xymon and bbgen, but both forms are allowed for backwards compatibility.

group-only COLUMN1|COLUMN2|COLUMN3 [group-title]
Same as the "group" and "group-compress" lines, but includes only the columns explicitly listed in the group. Any columns not listed will be ignored for these hosts.

group-except COLUMN1|COLUMN2|COLUMN3 [group-title]
Same as the "group-only" lines, but includes all columns EXCEPT those explicitly listed in the group. Any columns listed will be ignored for these hosts - all other columns are shown.

title Page, group or host title text
The "title" tag is used to put custom headings into the pages generated by bbgen, in front of page/subpage links, groups or hosts.

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

NAME:hostname
Overrides the default hostname used on the overview web pages. If "hostname" contains spaces, it must be enclosed in double quotes, e.g. NAME:"R&D Oracle Server"

CLIENT:hostname
Defines an alias for a host, which will be used when identifying status messages. This is typically used to accomodate a local client that sends in status reports with a different hostname, e.g. if you use hostnames with domains in your Xymon configuration, but the client is a silly Window box that does not include the hostname. Or vice versa. Whatever the reason, this can be used to match status reports with the hosts you define in your bb-hosts file. It causes incoming status reports with the specified hostname to be filed using the hostname defined in bb-hosts.

NOCOLUMNS:column[,column]
Used to drop certain of the status columns generated by the Xymon client. column is one of cpu, disk, files, memory, msgs, ports, procs. This setting stops these columns from being updated for the host. Note: If the columns already exist, you must use the bb(1) utility to drop them, or they will go purple.

COMMENT:Host comment
Adds a small text after the hostname on the webpage. This can be used to describe the host, without completely changing its display-name as the NAME: tag does. If the comment includes whitespace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple time in the bb-hosts file, bbgen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other bbgen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority.

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.

TRENDS:[*,][![graph,...]]
Defines the RRD graphs to include in the "trends" column generated by bbgen. This option syntax is complex.
If this option is not present, bbgen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail
* If this option is specified, the list of graphs to include start out as being empty (no graphs).
* To include all default graphs, use an asterisk. E.g. "TRENDS:*"
* To exclude a certain graph, speficy it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"
* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be speficied like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

 

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the hobbit-nkview.cgi(1) viewer, which has a separate configuration tool, hobbit-nkedit.cgi(1) with more facilities than the NK tags in bb-hosts.

bbgen will create three sets of pages: The main page bb.html, the all-non-green-statuses page (bb2.html), and a specially reduced version of bb2.html with only selected tests (bbnk.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]
Define the tests that you want included on the bbnk page. E.g. if you have a host where you only want to see the http tests on bbnk.html, you specify it as


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

NKTIME=day:starttime:endtime[,day:starttime:endtime]
This tag limits the time when an active alert is presented on the NK webpage.

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.

 

XYMON TAGS FOR THE WML (WAP) CARDS

If bbgen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]
This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag.

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.

 

XYMON STATUS PROPAGATION OPTIONS

These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]
This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to bb.html or bb2.html

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)w York)
&espace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple time in the bb-hosts file, bbgen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other bbgen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority.

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.

TRENDS:[*,][![graph,...]]
Defines the RRD graphs to include in the "trends" column generated by bbgen. This option syntax is complex.
If this option is not present, bbgen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail
* If this option is specified, the list of graphs to include start out as being empty (no graphs).
* To include all default graphs, use an asterisk. E.g. "TRENDS:*"
* To exclude a certain graph, speficy it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"
* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be speficied like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

 

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the hobbit-nkview.cgi(1) viewer, which has a separate configuration tool, hobbit-nkedit.cgi(1) with more facilities than the NK tags in bb-hosts.

bbgen will create three sets of pages: The main page bb.html, the all-non-green-statuses page (bb2.html), and a specially reduced version of bb2.html with only selected tests (bbnk.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]
Define the tests that you want included on the bbnk page. E.g. if you have a host where you only want to see the http tests on bbnk.html, you specify it as


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

NKTIME=day:starttime:endtime[,day:starttime:endtime]
This tag limits the time when an active alert is presented on the NK webpage.

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.

 

XYMON TAGS FOR THE WML (WAP) CARDS

If bbgen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]
This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag.

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.

 

XYMON STATUS PROPAGATION OPTIONS

These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]
This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to bb.html or bb2.html

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)w York)
&espace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple time in the bb-hosts file, bbgen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other bbgen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority.

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.

TRENDS:[*,][![graph,...]]
Defines the RRD graphs to include in the "trends" column generated by bbgen. This option syntax is complex.
If this option is not present, bbgen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail
* If this option is specified, the list of graphs to include start out as being empty (no graphs).
* To include all default graphs, use an asterisk. E.g. "TRENDS:*"
* To exclude a certain graph, speficy it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"
* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be speficied like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

 

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the hobbit-nkview.cgi(1) viewer, which has a separate configuration tool, hobbit-nkedit.cgi(1) with more facilities than the NK tags in bb-hosts.

bbgen will create three sets of pages: The main page bb.html, the all-non-green-statuses page (bb2.html), and a specially reduced version of bb2.html with only selected tests (bbnk.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]
Define the tests that you want included on the bbnk page. E.g. if you have a host where you only want to see the http tests on bbnk.html, you specify it as


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

NKTIME=day:starttime:endtime[,day:starttime:endtime]
This tag limits the time when an active alert is presented on the NK webpage.

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.

 

XYMON TAGS FOR THE WML (WAP) CARDS

If bbgen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]
This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag.

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.

 

XYMON STATUS PROPAGATION OPTIONS

These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]
This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to bb.html or bb2.html

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)w York)
&espace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple time in the bb-hosts file, bbgen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other bbgen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority.

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.

TRENDS:[*,][![graph,...]]
Defines the RRD graphs to include in the "trends" column generated by bbgen. This option syntax is complex.
If this option is not present, bbgen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail
* If this option is specified, the list of graphs to include start out as being empty (no graphs).
* To include all default graphs, use an asterisk. E.g. "TRENDS:*"
* To exclude a certain graph, speficy it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"
* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be speficied like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

 

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the hobbit-nkview.cgi(1) viewer, which has a separate configuration tool, hobbit-nkedit.cgi(1) with more facilities than the NK tags in bb-hosts.

bbgen will create three sets of pages: The main page bb.html, the all-non-green-statuses page (bb2.html), and a specially reduced version of bb2.html with only selected tests (bbnk.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]
Define the tests that you want included on the bbnk page. E.g. if you have a host where you only want to see the http tests on bbnk.html, you specify it as


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

NKTIME=day:starttime:endtime[,day:starttime:endtime]
This tag limits the time when an active alert is presented on the NK webpage.

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.

 

XYMON TAGS FOR THE WML (WAP) CARDS

If bbgen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]
This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag.

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.

 

XYMON STATUS PROPAGATION OPTIONS

These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]
This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to bb.html or bb2.html

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)w York)
&espace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple time in the bb-hosts file, bbgen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other bbgen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority.

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.

TRENDS:[*,][![graph,...]]
Defines the RRD graphs to include in the "trends" column generated by bbgen. This option syntax is complex.
If this option is not present, bbgen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail
* If this option is specified, the list of graphs to include start out as being empty (no graphs).
* To include all default graphs, use an asterisk. E.g. "TRENDS:*"
* To exclude a certain graph, speficy it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"
* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be speficied like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

 

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the hobbit-nkview.cgi(1) viewer, which has a separate configuration tool, hobbit-nkedit.cgi(1) with more facilities than the NK tags in bb-hosts.

bbgen will create three sets of pages: The main page bb.html, the all-non-green-statuses page (bb2.html), and a specially reduced version of bb2.html with only selected tests (bbnk.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]
Define the tests that you want included on the bbnk page. E.g. if you have a host where you only want to see the http tests on bbnk.html, you specify it as


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

NKTIME=day:starttime:endtime[,day:starttime:endtime]
This tag limits the time when an active alert is presented on the NK webpage.

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.

 

XYMON TAGS FOR THE WML (WAP) CARDS

If bbgen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]
This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag.

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.

 

XYMON STATUS PROPAGATION OPTIONS

These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]
This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to bb.html or bb2.html

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)w York)
&espace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple time in the bb-hosts file, bbgen tries to guess which definition is the best to use for the information used on the "info" column, or for the NOPROPRED and other bbgen-specific settings. Host definitions that have a "noconn" tag or an IP of 0.0.0.0 get lower priority.

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.

TRENDS:[*,][![graph,...]]
Defines the RRD graphs to include in the "trends" column generated by bbgen. This option syntax is complex.
If this option is not present, bbgen provides graphs matching the standard set of RRD files: la, disk, memory, users, vmstat, iostat, netstat, tcp, bind, apache, sendmail
* If this option is specified, the list of graphs to include start out as being empty (no graphs).
* To include all default graphs, use an asterisk. E.g. "TRENDS:*"
* To exclude a certain graph, speficy it prefixed with '!'. E.g. to see all graphs except users: "TRENDS:*,!users"
* The netstat, vmstat and tcp graphs have many "subgraphs". Which of these are shown can be speficied like this: "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn" This will show all graphs, but instead of the normal netstat graph, there will be two: The netstat2 and netstat3 graphs. Instead of the combined tcp graphs showing all services, there will be three: One for each of the http, conn and smtp services.

 

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

NOTE: The "NK" set of tags is deprecated. They will be supported for Xymon 4.x, but will be dropped in version 5. It is recommended that you move your critical systems view to the hobbit-nkview.cgi(1) viewer, which has a separate configuration tool, hobbit-nkedit.cgi(1) with more facilities than the NK tags in bb-hosts.

bbgen will create three sets of pages: The main page bb.html, the all-non-green-statuses page (bb2.html), and a specially reduced version of bb2.html with only selected tests (bbnk.html). This page includes selected tests that currently have a red or yellow status.

NK:testname[,testname]
Define the tests that you want included on the bbnk page. E.g. if you have a host where you only want to see the http tests on bbnk.html, you specify it as


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

NKTIME=day:starttime:endtime[,day:starttime:endtime]
This tag limits the time when an active alert is presented on the NK webpage.

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.

 

XYMON TAGS FOR THE WML (WAP) CARDS

If bbgen is run with the "--wml" option, it will generate a set of WAP-format output "cards" that can be viewed with a WAP-capable device, e.g. a PDA or cell-phone.

WML:[+|-]testname[,[+|-]testname]
This tag determines which tests for this hosts are included in the WML (WAP) page. Syntax is identical to the NK: tag.

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.

 

XYMON STATUS PROPAGATION OPTIONS

These tags affect how a status propagates upwards from a single test to the page and higher. This can also be done with the command-line options --nopropyellow and --nopropred, but the tags apply to individual hosts, whereas the command line options are global.

NOPROPRED:[+|-]testname[,[+|-]testname]
This tag is used to inhibit a yellow or red status from propagating upwards - i.e. from a test status color to the (sub)page status color, and further on to bb.html or bb2.html

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)w York)
&espace, it must be in double-quotes, e.g. COMMENT:"Sun webserver"

DESCR:Hosttype:Description
Define some informational text about the host. The "Hosttype" is a text describing the type of this device - "router", "switch", "hub", "server" etc. The "Description" is an informational text that will be shown on the "Info" column page; this can e.g. be used to store information about the physical location of the device, contact persons etc. If the text contain whitespace, you must enclose it in double-quotes, e.g. DESCR:"switch:4th floor Marketing switch"

CLASS:Classname
Force the host to belong to a specific class. Class-names are used when configuring log-file monitoring (they can be used as references in client-local.cfg(5) and hobbit-clients.cfg(5) to group logfile checks). Normally, class-names are controlled on the client by starting the Xymon client with the "--class=Classname" option. If you specify it in the bb-hosts file on the Xymon server, it overrides any classname that the client reports.

dialup
The keyword "dialup" for a host means that it is OK for it to be off-line - this should not trigger an alert. All network tests will go "clear" upon failure, and any missing reports from e.g. cpu- and disk-status will not go purple when they are not updated.

nobb2
Ignore this host on the BB2 page. Even if it has an active alert, it will not be included in the BB2 page. This also removes the host from the event-log display.

nodisp
Ignore this host completely when generating the Xymon webpages. Can be useful for monitoring a host without having it show up on the webpages, e.g. because it is not yet in production use. Or for hiding a host that is shown only on a second pageset.

prefer
When a single host is defined multiple tim