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