Provided by: xymon_4.3.25-1_amd64 bug

NAME

       xymond - Master network daemon for a Xymon server

SYNOPSIS

       xymond [options]

DESCRIPTION

       xymond  is the core daemon in the Xymon Monitor.  It is designed to handle monitoring of a
       large  number  of  hosts,  with  a  strong  focus  on  being  a  high-speed,  low-overhead
       implementation of a Big Brother compatible server.

       To achieve this, xymond stores all information about the state of the monitored systems in
       memory, instead of storing it in the host filesystem. A number of plug-ins can be  enabled
       to enhance the basic operation; e.g. a set of plugins are provided to implement persistent
       storage in a way that is compatible with the Big Brother daemon. However, even with  these
       plugins enabled, xymond still performs much faster than the standard bbd daemon.

       xymond is normally started and controlled by the xymonlaunch(8) tool, and the command used
       to invoke xymond should therefore be in the tasks.cfg file.

OPTIONS

       --hosts=FILENAME
              Specifies the path to the Xymon hosts.cfg file. This is used to check  if  incoming
              status  messages refer to known hosts; depending on the "--ghosts" option, messages
              for unknown hosts may be dropped.  If this option is omitted, the default path used
              is set by the HOSTSCFG environment variable.

       --checkpoint-file=FILENAME
              With  regular  intervals, xymond will dump all of its internal state to this check-
              point file. It is also dumped when xymond terminates, or when it receives a SIGUSR1
              signal.

       --checkpoint-interval=N
              Specifies  the  interval  (in  seconds)  between dumps to the check-point file. The
              default is 900 seconds (15 minutes).

       --restart=FILENAME
              Specifies an existing file containing a  previously  generated  xymond  checkpoint.
              When  starting  up,  xymond will restore its internal state from the information in
              this file. You can use the same filename for "--checkpoint-file" and "--restart".

       --ghosts={allow|drop|log|match}
              How to handle status messages from unknown hosts. The "allow" setting  accepts  all
              status  messages,  regardless of whether the host is known in the hosts.cfg file or
              not. "drop" silently ignores reports from unknown hosts. "log" works like drop, but
              logs  the  event  in the xymond output file.  "match" will try to match the name of
              the unknown host reporting with the known names by ignoring any domain-names - if a
              match  is  found,  then  a  temporary  client alias is automatically generated. The
              default is "log".

       --no-purple
              Prevent status messages from going purple when they are no  longer  valid.   Unlike
              the standard bbd daemon, purple-handling is done by xymond.

       --merge-clientconfig
              The  client-local.cfg(5)  file  contains  client-configuration  which  can be found
              matching a client against its hostname, its classname, or the name of  the  OS  the
              client  is  running.  By  default xymond will return one entry from the file to the
              client, looking for a hostname, classname or OS match (in that order).  This option
              causes  xymond to merge all matching entries together into one and return all of it
              to the client.

       --listen=IP[:PORT]
              Specifies  the  IP-address  and  port  where  xymond  will  listen   for   incoming
              connections.  By  default,  xymond  listens  on  IP 0.0.0.0 (i.e. all IP- addresses
              available on the host) and port 1984.

       --lqueue=NUMBER
              Specifies the listen-queue for incoming connections. You don't need  to  tune  this
              unless you have a very busy xymond daemon.

       --no-bfq
              Tells  xymond  to  NOT  use  the local messagequeue interface for receiving status-
              updates from xymond_client and xymonnet.

       --daemon
              xymond is  normally  started  by  xymonlaunch(8).   If  you  do  not  want  to  use
              xymonlaunch,  you  can  start xymond with this option; it will then detach from the
              terminal and continue running as a background task.

       --timeout=N
              Set the timeout used for incoming connections. If a status has  not  been  received
              more  than  N  seconds  after  the  connection was accepted, then the connection is
              dropped and any status message is discarded.  Default: 10 seconds.

       --flap-count=N
              Track the N latest status-changes for flap-detection. See the --flap-seconds option
              also.  To  disable  flap-checks  globally, set N to zero. To disable for a specific
              host, you must use the "noflap" option in hosts.cfg(5).  Default: 5

       --flap-seconds=N
              If a status changes more than flap-count times in N seconds or  less,  then  it  is
              considered  to  be  flapping. In that case, the status is locked at the most severe
              level until the flapping stops. The history information is not  updated  after  the
              flapping  is  detected.   NOTE:  If  this is set higher than the default value, you
              should also use the --flap-count option to ensure that  enough  status-changes  are
              stored  for  flap  detection  to  work.  The  flap-count setting should be at least
              (N/300)-1, e.g. if you set flap-seconds to 3600 (1 hour), then flap-count should be
              at least (3600/300)-1, i.e. 11.  Default: 1800 seconds (30 minutes).

       --delay-red=N

       --delay-yellow=N
              Sets  the delay before a red/yellow status causes a change in the web page display.
              Is usually controlled on a per-host basis via the delayred and delayyellow settings
              in  hosts.cfg(5) but these options allow you to set a default value for the delays.
              The value N is in minutes. Default: 0 minutes (no delay).  Note: Since  most  tests
              only  execute  once  every  5  minutes,  it will usually not make sense to set N to
              anything but a multiple of 5.

       --env=FILENAME
              Loads the content of FILENAME as environment settings before starting xymond.  This
              is  mostly  used  when  running  as  a  stand-alone daemon; if xymond is started by
              xymonlaunch, the environment settings are controlled by the  xymonlaunch  tasks.cfg
              file.

       --pidfile=FILENAME
              xymond  writes  the process-ID it is running with to this file.  This is for use in
              automated startup scripts. The default file is $XYMONSERVERLOGS/xymond.pid.

       --log=FILENAME
              Redirect all output from xymond to FILENAME.

       --store-clientlogs[=[!]COLUMN]
              Determines which status columns can cause a client message to be broadcast  to  the
              CLICHG channel. By default, no client messages are pushed to the CLICHG channel. If
              this option is specified with no parameter list, all status columns that go into an
              alert  state  will  trigger  the client data to be sent to the CLICHG channel. If a
              parameter list is added to this option, only those status  columns  listed  in  the
              list  will  cause  the client data to be sent to the CLICHG channel. Several column
              names  can  be  listed,  separated  by  commas.  If  all  columns  are   given   as
              "!COLUMNNAME",  then  all  status columns except those listed will cause the client
              data to be sent.

       --status-senders=IP[/MASK][,IP/MASK]
              Controls which hosts may send "status", "combo", "config" and "query"  commands  to
              xymond.

              By  default, any host can send status-updates. If this option is used, then status-
              updates are accepted only if they are sent by one of the IP-addresses listed  here,
              or  if  they  are sent from the IP-address of the host that the updates pertains to
              (this is to allow Xymon clients to send in their own status updates, without having
              to  list all clients here). So typically you will need to list your servers running
              network tests here.

              The format of this option is a list of IP-addresses, optionally with a network mask
              in  the  form of the number of bits. E.g. if you want to accept status-updates from
              the host 172.16.10.2, you would use
                  --status-senders=172.16.10.2
              whereas if you want to accept status updates from both 172.16.10.2 and from all  of
              the hosts on the 10.0.2.* network (a 24-bit IP network), you would use
                  --status-senders=172.16.10.2,10.0.2.0/24

       --maint-senders=IP[/MASK][,IP/MASK]
              Controls  which hosts may send maintenance commands to xymond. Maintenance commands
              are the "enable", "disable", "ack" and "notes" commands. Format of this  option  is
              as for the --status-senders option. It is strongly recommended that you use this to
              restrict access to these commands, so that monitoring of a host cannot be  disabled
              by a rogue user - e.g. to hide a system compromise from the monitoring system.

              Note:  If  messages  are  sent  through a proxy, the IP-address restrictions are of
              little use, since the messages will appear  to  originate  from  the  proxy  server
              address.  It  is therefore strongly recommended that you do NOT include the address
              of a server running xymonproxy in the list of allowed addresses.

       --www-senders=IP[/MASK][,IP/MASK]
              Controls which hosts may send commands to retrieve the state of xymond.  These  are
              the  "xymondlog",  "xymondboard"  and  "xymondxboard"  commands,  which are used by
              xymongen(1) and combostatus(1) to retrieve the state of the Xymon  system  so  they
              can generate the Xymon webpages.

              Note:  If  messages  are  sent  through a proxy, the IP-address restrictions are of
              little use, since the messages will appear  to  originate  from  the  proxy  server
              address.  It  is therefore strongly recommended that you do NOT include the address
              of a server running xymonproxy in the list of allowed addresses.

       --admin-senders=IP[/MASK][,IP/MASK]
              Controls which hosts may send administrative commands to xymond. These commands are
              the  "drop" and "rename" commands. Access to these should be restricted, since they
              provide an un-authenticated means of completely disabling monitoring of a host, and
              can  be  used  to  remove  all  traces  of e.g.  a system compromise from the Xymon
              monitor.

              Note: If messages are sent through a proxy,  the  IP-address  restrictions  are  of
              little  use,  since  the  messages  will  appear to originate from the proxy server
              address. It is therefore strongly recommended that you do NOT include  the  address
              of a server running xymonproxy in the list of allowed addresses.

       --no-download
              Disable  the "download" command which can be used by clients to pull files from the
              Xymon server. The use of these may be seen as a security risk since they allow file
              downloads.

       --ack-each-color
              By  default,  sending an ACK for a yellow status stops alerts from being sent while
              the status remains yellow or red. A status change from yellow to red will  not  re-
              enable alerts - the ACK covers all non-green statuses.  With this option, an ACK is
              valid only for the color of the status when the ACK was  sent.  So  an  ACK  for  a
              yellow  status  is ignored if the status later changes to red, but an ACK for a red
              status covers both yellow and red.
              Note: An ACK for a red status will clear any existing yellow acks. This means  that
              a  long-lived ack for yellow is lost when you send a short-lived ack for red. Hence
              alerts will restart when the red ack expires,  even  if  the  status  by  then  has
              changed to yellow.

       --ack-log=FILENAME
              Log  acknowledgements  created  on  the  Critical  Systems  page  to FILENAME.  NB,
              acknowledgements created by the Acknowledge Alert CGI are automatically written  to
              acknowledge.log  in  the  Xymon  server  log  directory.   Alerts from the Critical
              Systems page can be directed to the same log.

       --debug
              Enable debugging output.

       --dbghost=HOSTNAME
              For troubleshooting problems with a specific host, it may be useful  to  track  the
              exact  communications  from  a  single  host. This option causes xymond to dump all
              traffic from a single host to the file "/tmp/xymond.dbg".

HOW ALERTS TRIGGER

       When a status arrives, xymond matches the old and new color  against  the  "alert"  colors
       (from  the  "ALERTCOLORS"  setting) and the "OK" colors (from the "OKCOLORS" setting). The
       old and new color falls into one of three categories:

       OK: The color is one of the "OK" colors (e.g. "green").

       ALERT: The color is one of the "alert" colors (e.g. "red").

       UNDECIDED: The color is neither an "alert" color nor an "OK" color (e.g. "yellow").

       If the new status shows an ALERT state, then a message to the  xymond_alert(8)  module  is
       triggered.  This may be a repeat of a previous alert, but xymond_alert(8) will handle that
       internally, and only send alert messages with the interval configured in alerts.cfg(5).

       If the status goes from a not-OK state (ALERT or UNDECIDED) to OK, and there is  a  record
       of having been in a ALERT state previously, then a recovery message is triggered.

       The use of the OK, ALERT and UNDECIDED states make it possible to avoid being flooded with
       alerts when a status flip-flops between e.g yellow and red, or green and yellow.

CHANNELS

       A lot of functionality in the Xymon server is delegated to "worker modules" that  are  fed
       various events from xymond via a "channel". Programs access a channel using IPC mechanisms
       -  specifically,  shared  memory  and  semaphores  -  or  by  using  an  instance  of  the
       xymond_channel(8)  intermediate  program. xymond_channel enables access to a channel via a
       simple file I/O interface.

       A skeleton program for hooking into a xymond channel is provided as part of Xymon  in  the
       xymond_sample(8) program.

       The following channels are provided by xymond:

       status This channel is fed the contents of all incoming "status" and "summary" messages.

       stachg  This  channel is fed information about tests that change status, i.e. the color of
       the status-log changes.

       page This channel is fed information about tests where the color changes between an  alert
       color and a non-alert color. It also receives information about "ack" messages.

       data This channel is fed information about all "data" messages.

       notes This channel is fed information about all "notes" messages.

       enadis  This  channel  is  fed information about hosts or tests that are being disabled or
       enabled.

       client This channel is fed the contents of the  client  messages  sent  by  Xymon  clients
       installed on the monitored servers.

       clichg  This  channel is fed the contents of a host client messages, whenever a status for
       that host goes red, yellow or purple.

       Information about the data stream passed on these channels is in  the  Xymon  source-tree,
       see the "xymond/new-daemon.txt" file.

SIGNALS

       SIGHUP Re-read the hosts.cfg configuration file.

       SIGUSR1
              Force an immediate dump of the checkpoint file.

BUGS

       Timeout  of  incoming  connections are not strictly enforced. The check for a timeout only
       triggers during the normal network handling loop, so  a  connection  that  should  timeout
       after N seconds may persist until some activity happens on another (unrelated) connection.

FILES

       If  ghost-handling  is  enabled  via  the "--ghosts" option, the hosts.cfg file is read to
       determine the names of all known hosts.

SEE ALSO

       xymon(7), xymonserver.cfg(5).