# HOBBITSERVER.CFG

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

## NAME

hobbitserver.cfg - Xymon environment variables

## DESCRIPTION

Xymon programs use multiple environment variables beside the normal set of variables. The environment definitions are stored in the ~Xymon/server/etc/hobbitserver.cfg file. Each line in this file is of the form NAME=VALUE and defines one environment variable NAME with the value VALUE.

## ENVIRONMENT AREAS

In some cases it may be useful to have different values for an environment variable, depending on where it is used. This is possible by defining variables with an associated "area". Such definitions have the form AREA/NAME=VALUE.

E.g. to define a special setup of the BBDISPLAY variable when it is used by an application in the "management" area, you would do this:

        BBDISP="127.0.0.1"            # Default definition
        management/BBDISP="10.1.0.5"  # Definition in the "management" area

Areas are invoked by using the "--area" option for all tools, or via the ENVAREA setting in the hobbitlaunch.cfg(5) file.

## GENERAL SETTINGS

BBSERVERHOSTNAME
  The fully-qualified hostname of the server that is running Xymon.

BBSERVERWWWNAME
  The hostname used to access this servers' web-pages, used to construct URL's in the Xymon webpages. Default is the BBSERVERHOSTNAME.

BBSERVERIP
  The public IP-address of the server that is running Xymon.

BBSERVEROS
  A name identifying the operating system of the Xymon server. The known names are currently "linux", "freebsd", "solaris", "hpux", "aix" and "osf".

FQDN
  If set to TRUE, Xymon will use fully-qualified hostnames throughout. If set to FALSE, hostnames are stripped of their domain-part before being processed. It is highly recommended that you keep this set to TRUE. Default: TRUE.

BBLOGSTATUS
  Controls how the HTML page for a status log is generated. If set to DYNAMIC, the HTML logs are generated on-demand by the bb-hostsvc.cgi(1) script. If set to STATIC, you must activate the hobbitd_filestore(8) module (through an entry in the hobbitlaunch.cfg(5) file) to create and store the HTML logs whenever a status update is received. Setting "BBLOGSTATUS=STATIC" is discouraged since the I/O load on the Xymon server will increase significantly.

PINGCOLUMN
  Defines the name of the column for "ping" test status. The data from the "ping" test is used internally by Xymon, so it must be defined here so all of the Xymon tools know which column to watch for this data. The default setting is PINGCOLUMN=conn.

INFOCOLUMN
  Defines the name of the column for the "info" pages.

TRENDSCOLUMN
  Defines the name of the column for the RRD graph pages.

RRDHEIGHT
  The default height (in pixels) of the RRD graph images. Default: 120 pixels.

RRDWIDTH
  The default width (in pixels) of the RRD graph images. Default: 576 pixels.

HTMLCONTENTTYPE
  The Content-type reported by the CGI scripts that generate web pages. By default, this it "text/html". If you have on-line help texts in character sets other than the ISO-8859-1 (western european) character set, it may be necessary to modify this to include a character set. E.g.
  HTMLCONTENTTYPE="text/html; charset=euc-jp"
  for a Japanese character sets. Note: Some webservers will automatically add this, if configured to do so.

## DIRECTORIES

BBSERVERROOT
  The top-level directory for the Xymon installation. The default is the home-directory for the user running Xymon.

BBSERVERLOGS
  The directory for the Xymon's own logfiles (NOT the status-logs from the monitored hosts).

BBHOME
  The Xymon server directory, where programs and configurations are kept. Default: $BBSERVERROOT/server/ .

BBTMP
  Directory used for temporary files. Default: $BBHOME/tmp/

BBWWW
  Directory for Xymon webfiles. The $BBWEB URL must map to this directory. Default: $BBHOME/www/

BBNOTES
  Directory for Xymon notes-files. The $BBNOTESSKIN URL must map to this directory. Default: $BBHOME/www/notes/

BBREP
  Directory for Xymon availability reports. The $BBREPURL URL must map to this directory. Note also that your webserver must have write-access to this directory, if you want to use the bb-rep.cgi(1) CGI script to generate reports on-demand. Default: $BBHOME/www/rep/

BBSNAP
  Directory for Xymon snapshots. The $BBSNAPURL URL must map to this directory. Note also that your webserver must have write-access to this directory, if you want to use the bb-snapshot.cgi(1) CGI script to generate snapshots on-demand. Default: $BBHOME/www/snap/

BBVAR
  Directory for all data stored about the monitored items. Default: $BBSERVERROOT/data/

BBLOGS
  Directory for storing the raw status-logs. Not used unless "hobbitd_filestore --status" is running, which is discouraged since it increases the load on the Xymon server significantly. Default: $BBVAR/logs/

BBHTML
  Directory for storing HTML status-logs. Not used unless "hobbitd_filestore --status --html" is running, which is discouraged since it increases the load on the Xymon server significantly. Default: $BBHOME/www/html/

BBHIST
  Directory for storing the history of monitored items. Default: $BBVAR/hist/

BBHISTLOGS
  Directory for storing the detailed status-log of historical events. Default: $BBVAR/histlogs/

BBACKS
  Directory for storing information about alerts that have been acknowledged. Default: $BBVAR/acks/

BBDISABLED
  Directory for storing information about tests that have been disabled. Default: $BBVAR/disabled/

BBDATA
  Directory for storing incoming "data" messages. Default: $BBVAR/data/

BBRRDS
  Top-level directory for storing RRD files (the databases with trend-information used to generate graphs). Default: $BBVAR/rrd/

CLIENTLOGS
  Directory for storing the data sent by a Xymon client around the time a status changes to a warning (yellow) or critical (red) state. Used by the hobbitd_hostdata(8) module. Default: $BBVAR/hostdata/

## SYSTEM FILES

BBHOSTS
  Full path to the Xymon bb-hosts(5) configuration file. Default: $BBHOME/etc/bb-hosts.

BB
  Full path to the bb(1) client program. Default: $BBHOME/bin/bb.

BBGEN
  Full path to the bbgen(1) webpage generator program. Default: $BBHOME/bin/bbgen.

## URLS

BBSERVERWWWURL
  The root URL for the Xymon webpages, without the hostname. This URL must be mapped to the ~/server/www/ directory in your webserver configuration. See the sample Apache configuration in ~/server/etc/hobbit-apache.conf.

BBSERVERCGIURL
  The root URL for the Xymon CGI-scripts, without the hostname. This directory must be mapped to the ~/cgi-bin/ directory in your webserver configuration, and must be flagged as holding executable scripts. See the sample Apache configuration in ~/server/etc/hobbit-apache.conf.

BBWEBHOST
  Initial part of the Xymon URL, including just the protocol and the hostname, e.g. "http://www.foo.com"

BBWEBHOSTURL
  Prefix for all of the static Xymon webpages, e.g. "http://www.foo.com/xymon"

BBWEBHTMLLOGS
  URL prefix for the static HTML status-logs generated when BBLOGSTATUS=STATIC. Note that this setting is discouraged so this setting should not be used.

BBWEB
  URL prefix (without hostname) of the Xymon webpages. E.g. "/xymon".

BBSKIN
  URL prefix (without hostname) of the Xymon graphics. E.g. "/xymon/gifs".

BBHELPSKIN
  URL prefix (without hostname) of the Xymon on-line help files. E.g "/xymon/help".

BBMENUSKIN
  URL prefix (without hostname) of the Xymon menu files. E.g "/xymon/menu".

BBNOTESSKIN
  URL prefix (without hostname) of the Xymon on-line notes files. E.g "/xymon/notes".

BBREPURL
  URL prefix (without hostname) of the Xymon availability reports. E.g. "/xymon/rep".

BBSNAPURL
  URL prefix (without hostname) of the Xymon snapshots. E.g. "/xymon/snap".

BBWAP
  URL prefix (without hostname) of the Xymon WAP/WML files. E.g. "/xymon/wml".

CGIBINURL
  URL prefix (without hostname) of the Xymon CGI-scripts. Default: $BBSERVERCGIURL .

COLUMNDOCURL
  Format string used to build a link to the documentation for a column heading. Default: "$CGIBINURL/hobbitcolumn.sh?%s", which causes links to use the hobbitcolumn.sh(1) script to document a column.

## SETTINGS FOR SENDING MESSAGES TO HOBBIT

BBDISP
  The IP-address used to contact the hobbitd(8) service. Used by clients and the tools that perform network tests. Default: $BBSERVERIP

BBDISPLAYS
  List of IP-adresses. Clients and network test tools will try to send status reports to a Xymon server running on each of these adresses. This setting is only used if BBDISP=0.0.0.0.

PAGELEVELS
  Compatibility setting for Big Brother: List of colors that are considered "critical" and therefore will trigger an alert. Not used by Xymon.

BBPAGE
  Compatibility setting for Big Brother: This is the IP-address of the server where a BBPAGER service is running. It is not used by Xymon.

BBPAGERS
  Compatibility setting for Big Brother: List of servers running the BBPAGER service, used if BBPAGE=0.0.0.0. It is not used by Xymon.

BBPORT
  The portnumber for used to contact the hobbitd(8) service. Used by clients and the tools that perform network tests. Default: 1984.

DOCOMBO
  Compatibility setting for Big Brother. Controls whether so send combo-messages or not. Ignored by Xymon.

BBMAXMSGSPERCOMBO
  The maximum number of status messages to combine into one combo message. You may need to lower this number of your BBDISPLAY server has trouble keeping up with the incoming status messages from bbtest-net. Default: 100.

BBSLEEPBETWEENMSGS
  Length of a pause introduced between each successive transmission of a combo-message by bbtest-net. You may have to increase this value to give your BBDISPLAY server time to process one combo message before the next one arrives. This number defines how many microseconds to wait between the messages. Default: 0 (send messages as quickly as possible).

## HOBBITD SETTINGS

ALERTCOLORS
  Comma-separated list of the colors that may trigger an alert-message. The default is "red,yellow,purple". Note that alerts may further be generated or suppresed based on the configuration in the hobbit-alerts.cfg(5) file.

OKCOLORS
  Comma-separated list of the colors that may trigger a recovery-message. The default is "green,clear,blue".

ALERTREPEAT
  How often alerts get repeated while a status is in an alert state. This is the default setting, which may be changed in the hobbit-alerts.cfg(5) file.

BBGHOSTS
  Controls how status messages from unknown hosts (i.e. hosts not listed in the bb-hosts file) are handled.

  BBGHOSTS=1: Causes the status report to be silently discarded. This is the default behaviour in Xymon.

  BBGHOSTS=2: Discards the status report, but keep track of the hostname and report it on the hobbitd status page.

  When BBGHOSTS is set to 1 or 2, the hostnames in incoming status-messages is matched without any case-sensitivity, unlike normal Big Brother which is case-sensitive in hostnames. So with BBGHOSTS set to 1 or 2, "WWW.FOO.COM" and "www.foo.com" are considered to be the same host. If necessary, the incoming hostname will be changed to match the way it is written in the bb-hosts file, changing case as needed.

MAXMSG_STATUS
  The maximum size of a "status" message in kB, default: 256. Status messages are the ones that end up as columns on the web display. The default size should be adequate in most cases, but some extension scripts can generate very large status messages - close to 1024 kB. You should only change this if you see messages in the hobbitd log file about status messages being truncated.

MAXMSG_CLIENT
  The maximum size of a "client" message in kB, default: 512. "client" messages are generated by the Xymon client, and often include large process-listings. You should only change this if you see messages in the hobbitd log file about client messages being truncated.

MAXMSG_DATA
  The maximum size of a "data" message in kB, default: 256. "data" messages are typically used for client reports of e.g. netstat or vmstat data. You should only change this setting if you see messages in the hobbitd log file about data messages being truncated.

MAXMSG_NOTES
  The maximum size of a "notes" message in kB, default: 256. "notes" messages provide a way for uploading documentation about a host to Xymon; it is not enabled by default. If you want to upload large documents, you may need to change this setting.

MAXMSG_STACHG
  The maximum size of a "status change" message in kB, default: Current value of the MAXMSG_STATUS setting. Status-change messages occur when a status changes color. There is no reason to change this setting.

MAXMSG_PAGE
  The maximum size of a "page" message in kB, default: Current value of the MAXMSG_STATUS setting. "page" messages are alerts, and include the status message that triggers the alert. There is no reason to change this setting.

MAXMSG_ENADIS
  The maximum size of an "enadis" message in kB, default: 32. "enadis" are small messages used when enabling or disabling hosts and tests, so the default size should be adequate.

MAXMSG_CLICHG
  The maximum size of a "client change" message in kB, default: Current value of the MAXMSG_CLIENT setting. Client-change messages occur when a status changes color to one of the alert-colors, usually red, yellow and purple. There is no reason to change this setting.

## HOBBITD_HISTORY SETTINGS

BBALLHISTLOG
  If set to TRUE, hobbitd_history(8) will update the $BBHIST/allevents file logging all changes to a status. The allevents file is used by the bb-eventlog.cgi(1) tool to show the list of recent events on the BB2 webpage.

BBHOSTHISTLOG
  If set to TRUE, hobbitd_history(8) will update the host-specific eventlog that keeps record of all status changes for a host. This logfile is not used by any Xymon tool.

SAVESTATUSLOG
  If set to TRUE, hobbitd_history(8) will save historical detailed status-logs to the $BBHISTLOGS directory.

## HOBBITD_ALERT SETTINGS

MAIL
  Command used to send alerts via e-mail, including a "Subject:" header in the mail. Default: "mail -s"

MAILC
  Command used to send alerts via e-mail in a form that does not have a "Subject" in the mail. Default: "mail"

SVCCODES
  Maps status-columns to numeric service-codes. The numeric codes are used when sending an alert using a script, where the numeric code of the service is provided in the BBSVCNUM variable.

## HOBBITD_RRD SETTINGS

TEST2RRD
  List of "COLUMNNAME[=RRDSERVICE]" settings, that define which status- and data-messages have a corresponding RRD graph. You will normally not need to modify this, unless you have added a custom TCP-based test to the bb-services file, and want to collect data about the response-time, OR if you are using the hobbitd_rrd(8) external script mechanism to collect data from custom tests. Note: All TCP tests are automatically added.

  This is also used by the bb-hostsvc.cgi(1) script to determine if the detailed status view of a test should include a graph.

GRAPHS
  List of the RRD databases, that should be shown as a graph on the "trends" column.

NORRDDISKS
  This is used to disable the tracking of certain filesystems. By default all filesystems reported by a client are tracked. In some cases you may want to disable this for certain filesystems, e.g. database filesystems since they are always completely full. This setting is a regular expression that is matched against the filesystem name (the Unix mount-point, or the Windows disk-letter) - if the filesystem name matches this expression, then it will not be tracked by Xymon.
  Note: Setting this does not affect filesystems that are already being tracked by Xymon - to remove them, you must remove the RRD files for the unwanted filesystems from the ~xymon/data/rrd/HOSTNAME/ directory.

RRDDISKS
  This is used to enable tracking of only selected filesystems (see the NORRDDISKS setting above). By default all filesystems are being tracked, setting this changes that default so that only those filesystems that match this pattern will be tracked.

## BBTEST-NET NETWORK TEST SETTINGS

BBLOCATION
  If this variable is defined, then only the hosts that have been tagged with "NET:$BBLOCATION" will be tested by the bbtest-net tool.

CONNTEST
  If set to TRUE, the connectivity (ping) test will be performed.

IPTEST_2_CLEAR_ON_FAILED_CONN
  If set to TRUE, then failing network tests go CLEAR if the conn-test fails.

NONETPAGE
  List of network services (separated with <space>) that should go yellow upon failure instead of red.

BBROUTERTEXT
  When using the "router" or "depends" tags for a host, a failure status will include text that an "Intermediate router is down". With todays network topologies, the router could be a switch or another network device; if you define this environment variable the word "router" will be replaced with whatever you put into the variable. So to inform the users that an intermediate switch or router is down, use BBROUTERTEXT="switch or router". This can also be set on a per-host basis using the "DESCR:hosttype:description" tag in the bb-hosts(5) file.

NETFAILTEXT
  When a network test fails, the status message reports "SERVICENAME not OK". The "not OK" message can be changed via this variable, e.g. you can change it to "FAILED" or customize it as you like.

FPING
  The command used to run the hobbitping(1) tool for the connectivity test. (The name FPING is due to the fact that the "fping" utility was used until Xymon version 4.2). This may include suid-root wrappers and hobbitping options. Default: "hobbitping"

TRACEROUTE
  Defines the location of the "traceroute" tool and any options needed to run it. traceroute it used by the connectivity test when the ping test fails; if requested via the "trace" tag, the TRACEROUTE command is executed to try to determine the point in the network that is causing the problem. By default the command executed is "traceroute -n -q 2 -w 2 -m 15" (no DNS lookup, max. 2 probes, wait 2 seconds per hop, max 15 hops).

  If you have the mtr(8) tool installed - available from http://www.bitwizard.nl/mtr/ - I strongly recommend using this instead. The recommended setting for mtr is "/usr/sbin/mtr -c 2 -n --report" (the exact path to the mtr utility may be different on your system). Note that mtr needs to be installed suid-root on most systems.

NTPDATE
  Defines the ntpdate(1) program used for the "ntp" test. Default: "ntpdate"

RPCINFO
  Defines the rpcinfo(8) program used for "rpc" tests. Default: "rpcinfo"

## BBGEN WEBPAGE GENERATOR SETTINGS

HOBBITLOGO
  HTML code that is inserted on all standard headers. The default is to add the text "Xymon" in the upper-left corner of the page, but you can easily replace this with e.g. a company logo. If you do, I suggest that you keep it at about 30-35 pixels high, and 100-150 pixels wide.

MKBBLOCAL
  The string "Pages hosted locally" that appears above all of the pages linked from the main Xymon webpage.

MKBBSUBLOCAL
  The string "Subpages hosted locally" that appears above all of the sub-pages linked from pages below the main Xymon webpage.

MKBBREMOTE
  The string "Remote status display" that appears about the summary statuses displayed on the min Xymon webpage.

MKBBTITLE
  HTML tags designed to go in a <FONT> tag, to choose the font for titles of the webpages.

MKBBROWFONT
  HTML tags designed to go in a <FONT> tag, to choose the font for row headings (hostnames) on the webpages.

MKBBCOLFONT
  HTML tags designed to go in a <FONT> tag, to chose the font for column headings (test names) on the webpages.

MKBBACKFONT
  HTML tags designed to go in a <FONT> tag, to chose the font for the acknowledgement text displayed on the status-log HTML page for an acknowledged status.

ACKUNTILMSG
  When displaying the detailed status of an acknowledged test, Xymon will include the time that the acknowledge expires using the print-format defined in this setting. You can define the timeformat using the controls in your systems strftime(3) routine, and add the text suitable for your setup.

BBDATEFORMAT
  On webpages generated by bbgen, the default header includes the current date and time. Normally this looks like "Tue Aug 24 21:59:47 2004". The BBDATEFORMAT controls the format of this timestamp - you can define the format using the controls in the strftime(3) routine. E.g. to have it show up as "2004-08-24 21:59:47 +0200" you would set BBDATEFORMAT="%Y-%m-%d %H:%M:%S %z"

MKBB2COLREPEAT
  Inspired by Jeff Stoner's col_repeat_patch.tgz patch, this defines the maximum number of rows before repeating the column headings on a webpage. This sets the default value for the bbgen(1) "--maxrows" option; if the command-line option is also specifed, then it overrides this environment variable. Note that unlike Jeff's patch, bbgen implements this for both the bb2.html page and all other pages (bb.html, subpages, bbnk.html).

SUMMARY_SET_BKG
  If set to TRUE, then summaries will affect the color of the main Xymon webpage. Default: FALSE.

DOTHEIGHT
  The height (in pixels) of the icons showing the color of a status. Default: 16, which matches the default icons.

DOTWIDTH
  The width (in pixels) of the icons showing the color of a status. Default: 16, which matches the default icons.

CLIENTSVCS
  List of the status logs fed by data from the Xymon client. These status logs will - if there are Xymon client data available for the host - include a link to the raw data sent by the client. Default: cpu,disk,memory,procs,svcs.

BBRSSTITLE
  If defined, this is the title of the RSS/RDF documents generated when bbgen(1) is invoked with the "--rss" option. The default value is "Xymon Alerts".

WMLMAXCHARS
  Maximum size of a WAP/WML output "card" when generating these. Default: 1500.

BBMKBB2EXT
  List of scripts to run as extensions to the BB2 page. Note that two scripts, "eventlog.sh" and "acklog.sh" are handled specially: They are handled internally by bbgen, but the script names must be listed in this variable for this function to be enabled.

BBHISTEXT
  List of scripts to run as extensions to a history page.

BBREPWARN
  Default threshold for listing the availability as "critical" (red) when generating the availability report. This can be set on a per-host basis with the WARNPCT setting in bb-hosts(5). Default: 97 (percent)

BBGENREPOPTS
  Default bbgen options used for reports. This will typically include such options as "--subpagecolumns", and also "--ignorecolumns" if you wish to exclude certain tests from reports by default.

BBGENSNAPOPTS
  Default bbgen options used by snapshots. This should be identical to the options you normally used when building Xymon webpages.

## FILES

~xymon/server/etc/hobbitserver.cfg

## SEE ALSO

xymon(7)

## Index

NAME
DESCRIPTION
ENVIRONMENT AREAS
GENERAL SETTINGS
DIRECTORIES
SYSTEM FILES
URLS
SETTINGS FOR SENDING MESSAGES TO HOBBIT
HOBBITD SETTINGS
HOBBITD_HISTORY SETTINGS
HOBBITD_ALERT SETTINGS
HOBBITD_RRD SETTINGS
BBTEST-NET NETWORK TEST SETTINGS
BBGEN WEBPAGE GENERATOR SETTINGS
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 12:54:30 GMT, December 15, 2008