Provided by: xymon_4.3.0~beta2.dfsg-9.1_amd64 bug

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)