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.
TRENDSECONDS
The graphs on the "trends" page show data for the past
TRENDSECONDS seconds. Default: 172800 seconds, i.e. 48 hours.
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.
HOLIDAYS
Defines the default set of holidays used if there is no
"holidays" tag for a host in the bb-hosts file. Holiday sets are
defined in the hobbit-holidays.cfg(5) file. If not defined, only
the default holidays (those defined outside a named holiday set)
will be considered as holidays.
WEEKSTART
Defines which day is the first day of the week. Set to "0" for
Sunday, "1" for Monday. Default: 1 (Monday).
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"
HOLIDAYFORMAT
How holiday dates are displayed. The default is "%d/%m" which
show the day and month. American users may want to change this
to "%m/%d" to suit their preferred date-display style. This is a
formatting string for the system strftime(3) routine, so any
controls available for this routine may be used.
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 b.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)