Provided by: xymon_4.3.30-1build2_amd64 bug


       xymongen - Xymon webpage generator


       xymongen -?
       xymongen --help
       xymongen --version
       xymongen [options] [output-directory]
       (See the OPTIONS section for a description of the available command-line options).


       xymongen  generates  the  overview  webpages for the Xymon monitor. These are the webpages
       that show the overall status of your hosts, not the detailed status pages for each test.

       Note: The data for the webpages is retrieved from the xymond(8) daemon, and xymongen  uses
       the  values  of  the  XYMSRV  /  XYMSERVERS environment variables to determine the network
       address where xymond can  be  reached.  If  you  have  more  than  one  server  listed  in
       XYMSERVERS,  make  sure  the  first  one  is the local Xymon server - this is the one that
       xymongen will query for data.


       xymongen has a large number of command-line options.  The options can be  used  to  change
       the behaviour of xymongen and affect the web pages generated by it.


       --help or -?
              Provide a summary of available command-line options.

              Prints the version number of xymongen

              This  option  is  deprecated,  use  the  HOSTDOCURL  setting  in xymonserver.cfg(5)

              This option  is  deprecated,  use  the  HOSTDOCURL  setting  in  xymonserver.cfg(5)

              Causes  links  to documentation for hosts and services to open in a new window. The
              default is to show documentation in the same browser window as the Xymon status.

              Sets the filename extension used  for  the  webpages  generated  by  xymongen.   By
              default, an extension of ".html" is used.  Note that you need to specify the "dot".

              With  this  option,  xymongen  will  send a status message with details of how many
              hosts were processed, how many pages  were  generated,  any  errors  that  occurred
              during the run, and some timing statistics. The default columnname is "xymongen".

              Create  .htaccess  files  when new web page directories are created. The content of
              the .htaccess files are determined by the XYMONHTACCESS environment  variable  (for
              the    top-level   directory   with   xymon.html   and   nongreen.html);   by   the
              XYMONPAGEHTACCESS  variable  (for  the  page-level   directories);   and   by   the
              XYMONSUBPAGEHTACCESS  variable  for  subpage- and subparent-level directories.  The
              filename of the .htaccess files default to ".htaccess" if no filename is given with
              this  option.   The  XYMONHTACCESS  variable  is copied verbatim into the top-level
              .htaccess file.  The XYMONPAGEHTACCESS variable may contain a "%s" where  the  name
              of  the  page  is inserted.  The XYMONSUBPAGEHTACCESS variable may contain two "%s"
              instances:  The  first  is  replaced  with  the  pagename,  the  second  with   the

              Limit the eventlog on the "All non-green" page to only N events. Default: 100.

              Limit  the  eventlog on the "All non-green" page to events that happened within the
              past N minutes. Default: 240.

              Disable the eventlog normally displayed on the "All non-green" page

              Limit the acknowledgment log on the "All non-green" page to only N events. Default:

              Limit  the  acknowledgment  log  on  the "All non-green" page to acks that happened
              within the past N minutes. Default: 240.

              Disable the acknowledgement log normally displayed on the "All non-green" page.

       --cricitcallog[=Critical log column]
              This generates a text-based log of what is shown on the critical.html status  page,
              and  sends a status message for the Xymon server itself reflecting the color of the
              Critical status page. This allows you to track when problems have appeared  on  the
              critical status page. The logfile is stored in $XYMONSERVERLOGS/criticalstatus.log

              Instead   of   reading  the  hosts.cfg  file,  xymongen  will  load  the  hosts.cfg
              configuration from the xymond daemon. This eliminates  the  need  for  reading  the
              hosts.cfg,  and if you have xymond and xymongen running on different hosts, it also
              eliminates the need for copying the hosts.cfg file between systems. Note  that  the
              "dispinclude" option in hosts.cfg is ignored when this option is enabled.


       These options affect how the webpages generated by xymongen appear in the browser.

              Put page- and subpage-links after hosts.

              Put page- and subpage-links before hosts (default).

              These  two  options decide whether a page with links to subpages and hosts have the
              hosts or the subpages first.

              Determines the number of columns used for links to pages and subpages. The  default
              is N=1.

              Column  headings  on  a  page are by default only shown at the beginning of a page,
              subpage or group of hosts. This options causes the column headings  to  repeat  for
              every N hosts shown.


              When  groups are hosts are made, display the table and host names even if there are
              no tests present for any of the hosts  in  question.  Use  --no-showemptygroups  to
              hide.  (Default: yes)

              Normally,  only  the  colored  "dots" next to a page or subpage act as links to the
              page itself. With this option, the page title will link to the page also.

              Use the description text from the "page" or "subpage" tags as  a  heading  for  the
              page, instead of the "Pages hosted locally" or other standard heading.

              Normally,  page  headings are underlined using an HTML "horizontal ruler" tag. This
              option disables the underlining of headings.

              Use images named COLOR-recent.gif for tests, where  the  test  status  has  changed
              within   the  past  24  hours.  These  GIF  files  need  to  be  installed  in  the
              $XYMONHOME/www/gifs/ directory. By default, the threshold is set to 24 hours  -  if
              you   want   it   differently,   you   can  specify  the  time  limit  also.   E.g.
              "--recentgifs=3h" will show the recent GIFs for only 3 hours after a status change.

              In a normal "group-only" directive, you can specify the order in  which  the  tests
              are  displayed,  from  left  to  right.  If  you prefer to have the tests listed in
              alphabetical order, use this option - the  page  will  then  generate  "group-only"
              groups like it generates normal groups, and sort the tests alphabetically.

              If you want to visually show that a test is a dialup-test, you can use an alternate
              set of icons for the green/red/yellow>/etc. images by specifying this  option.  The
              URL  parameter  specified  here  overrides  the  normal  setting from the XYMONSKIN
              environment variable, but only for dialup tests.

              Same as "--dialupskin", but for reverse tests (tests with '!' in front).

              Determines which pages use tooltips to show the description of the host  (from  the
              COMMENT entry in the hosts.cfg(5) file). If set to always, tooltips are used on all
              pages. If set to never, tooltips are never used. If set to main, tooltips are  used
              on the main pages, but not on the "All non-green" or "Critical systems" pages.


       These  options  affect  which  columns  (tests)  are included in the webpages generated by

              The given columns will be completely ignored by xymongen when generating  webpages.
              Can  be  used to generate reports where you eliminate some of the more noisy tests,
              like "msgs".

              Only red status columns will be included on the  Critical  page.  By  default,  the
              Critical page will contain hosts with red, yellow and clear status.

              Defines  which  colors  cause  a test to appear on the "All non-green" status page.
              COLOR is red, yellow or purple.  The default is to include all three.

              Same as the --ignorecolumns, but applies to hosts on the "All non-green" page only.

              Deprecated, use "--nongreen-colors" instead.

              Ignore all dialup hosts on the "All non-green" page, including the eventlog.

              Do not generate the normal pages (normally used  to  generate  only  the  non-green

              Do not generate the "All non-green" page.

              Always  include  these columns on "All non-green" page Will include certain columns
              on the nongreen.html page, regardless of its color. Normally, nongreen.html drops a
              test-column, if all tests are green. This can be used e.g. to always have a link to
              the trends column (with the RRD graphs) from your nongreen.html page.

              Ignore these tests in the "All non-green" event log display.


       These options suppress the normal propagation of a status upwards in the  page  hierarchy.
       Thus, you can have a test with status yellow or red, but still have the entire page green.
       It is useful for tests that need not cause an alarm, but where you still want to know  the
       actual status.  These options set global defaults for all hosts; you can use the NOPROPRED
       and NOPROPYELLOW tags in the hosts.cfg(5) file to  apply  similar  limits  on  a  per-host

       --nopropyellow=test[,test] or --noprop=test[,test]
              Disable upwards status propagation when YELLOW. The "--noprop" option is deprecated
              and should not be used.

              Disable upwards status propagation when PURPLE.

              Disable upwards status propagation when RED or YELLOW.

              Disable upwards status propagation when status has been acknowledged. If  you  want
              to disable all acked tests from being propageted, use "--nopropack=*".


       Purple statuses occur when reporting of a test status stops.  A test status is valid for a
       limited amount of time - normally 30 minutes - and  after  this  time,  the  test  becomes

              Generate a logfile of all purple status messages.


              Build  webpages for an alternate pageset than the default. See the PAGESETS section

              Use an alternate template for header and footer files. Typically used together  the
              the "--pageset" option; see the PAGESETS section below.


              This  option  causes  xymongen  to  generate  a set of WML "card" files that can be
              accessed by a WAP device (cell phone, PDA etc.) The  generated  files  contain  the
              hosts  that have a RED or YELLOW status on tests specified.  This option can define
              the default tests to include - the defaults can be overridden or amended using  the
              "WML:" or "NK:" tags in the hosts.cfg(5) file. If no tests are specified, all tests
              will be included.

              Generate an HTML file suitable for a Netscape 6/Mozilla sidebar entry. To  actually
              enable  your users to obtain such a sidebar entry, you need this Javascript code in
              a webpage (e.g. you can include it in the $XYMONHOME/web/stdnormal_header file):

              <SCRIPT TYPE="text/javascript">
              function addNetscapePanel() {
                 if ((typeof window.sidebar == "object") &&
                     (typeof window.sidebar.addPanel == "function"))
                    window.sidebar.addPanel ("Xymon",
                    alert("Sidebar only for Mozilla or Netscape 6+");

              and then you can include a "Add this to sidebar" link using this as a template:

                 <A HREF="javascript:addNetscapePanel();">Add to Sidebar</A>

              or if you prefer to have the standard Netscape "Add tab" button, you  would  do  it

                 <A HREF="javascript:addNetscapePanel();">
                    <IMG SRC="/gifs/add-button.gif" HEIGHT=45 WIDTH=100
                         ALT="[Add Sidebar]" STYLE="border:0">

              The       "add-button.gif"       is       available      from      Netscape      at

              If FILENAME does not begin with a slash, the Netscape sidebar file is placed in the
              $XYMONHOME/www/ directory.

              The  minimum  color  to include in the Netscape Sidebar - default is "red", meaning
              only critical alerts are included. If  you  want  to  include  warnings  also,  use

       --rss  Generate  RSS/RDF  content delivery stream of your Xymon alerts. This output format
              can be dynamically embedded in other web pages, much like the live newsfeeds  often
              seen  on  web  sites.  Two  RSS files will be generated, one reflects the "All non-
              green" page,  the  other  reflects  the  "Critical"  page.  They  will  be  in  the
              "nongreen.rss"  and  "critical.rss"  files, respectively.  In addition, an RSS file
              will be generated for each page and/or subpage listing the hosts  present  on  that
              page or subpage.
              The FILENAME parameter previously allowed on the --rss option is now obsolete.
              For    more    information    about    RSS/RDF    content    feeds,    please   see

              Sets the filename extension used for the  RSS  files  generated  by  xymongen.   By
              default, an extension of ".rss" is used.  Note that you need to specify the "dot".

              The  desired output format of the RSS/RDF feed. Version 0.91 appears to be the most
              commonly used format, and is the default if this option is omitted.

              The minimum color to include in the RSS feed  -  default  is  "red",  meaning  only
              critical   alerts  are  included.  If  you  want  to  include  warnings  also,  use


              Invoke  xymongen  in  report-generation  mode.  This  is  normally  used   by   the
              report.cgi(1)  CGI  script,  but  may  also  be  used  directly when pre-generating
              reports.  The START parameter is the start-time  for  the  report  in  Unix  time_t
              format  (seconds since Jan 1st 1970 00:00 UTC); END is the end-time for the report;
              DYNAMIC is 0 for a pre-built report and 1 for a dynamic (on-line) report; STYLE  is
              "crit"  to  include  only  critical  (red) events, "nongr" to include all non-green
              events, and "all" to include all events.

              Used together with --reportopts, this causes xymongen to generate  an  availability
              report in the form of a comma-separated values (CSV) file.  This format is commonly
              used for importing into spreadsheets for further processing.
              The CSV file includes Unix timestamps. To display these as human readable times  in
              Excel,  the formula =C2/86400+DATEVALUE(1-jan-1970) (if you have the Unix timestamp
              in the cell C2) can be used. The result cell should be  formatted  as  a  date/time
              field.  Note  that  the timestamps are in UTC, so you may also need to handle local
              timezone and DST issues yourself.

              By default, a comma is used to delimit fields in the CSV output.  Some  non-english
              spreadsheets  use  a  different delimiter, typically semi-colon.  To generate a CSV
              file with the proper delimiter, you can use this option to set the  character  used
              as  delimiter.  E.g.  "--csvdelim=;"  - note that this normally should be in double
              quotes, to prevent the Unix shell from interpreting the delimiter  character  as  a
              command-line delimiter.

              Generate  a snapshot of the Xymon pages, as they appeared at TIME. TIME is given as
              seconds since Jan 1st 1970 00:00 UTC. Normally used  via  the  snapshot.cgi(1)  CGI


              Causes  xymongen  to  dump  large  amounts of debugging output to stdout, if it was
              compiled with the -DDEBUG enabled. When reporting a problem with  xymongen,  please
              try to reproduce the problem and provide the output from running xymongen with this

              Dump information about the time spent by various parts of xymongen to stdout.  This
              is  useful  to  see  what part of the processing is responsible for the run-time of
              Note: This information is also provided in the output sent  to  the  Xymon  display
              when using the "--report" option.


       With version 1.4 of xymongen comes the possibility to generate multiple sets of pages from
       the same data.
       Suppose you have two groups of people looking at the Xymon webpages.   Group  A  wants  to
       have  the hosts grouped by the client, they belong to. This is how you have Xymon set up -
       the default pageset.  Now group B wants to have the hosts grouped by  operating  system  -
       let us call it the "os" set.  Then you would add the page layout to hosts.cfg like this:

       ospage    win          Microsoft Windows
       ossubpage   win-nt4      MS Windows NT 4
       osgroup NT4 File servers
       osgroup NT4 Mail servers
       ossubpage   win-xp       MS Windows XP
       ospage    unix         Unix
       ossubpage   unix-sun     Solaris
       ossubpage   unix-linux   Linux

       This  defines  a  set  of  pages  with one top-level page (the xymon.html page), two pages
       linked from xymon.html (win.html and unix.html), and from e.g. the win.html page there are
       subpages win-nt4.html and win-xp.html
       The  syntax  is  identical to the normal "page" and "subpage" directives in hosts.cfg, but
       the directive is prefixed with the pageset name. Don't put any hosts in-between  the  page
       and subpage directives - just add all the directives at the top of the hosts.cfg file.
       How  do you add hosts to the pages, then ? Simple - just put a tag "OS:win-xp" on the host
       definition line. The "OS" must be the same as prefix used for the pageset  names,  but  in
       uppercase.  The  "win-xp"  must  match  one  of  the pages or subpages defined within this
       pageset.  E.g. # OS:win-xp # OS:unix-sun

       If you want the host to appear inside a group defined on that page, you must identify  the
       group  by number, starting at 1. E.g. to put a host inside the "NT4 Mail servers" group in
       the example above, use "OS:win-nt4,2" (the second group on the "win-nt4" page).
       If you want the host to show up on the frontpage instead of a subpage, use "OS:*" .

       All of this just defines the layout of the new pageset.  To  generate  it,  you  must  run
       xymongen once for each pageset you define - i.e. create an extension script like this:


              XYMONWEB="/xymon/os" $XYMONHOME/bin/xymongen \
                   --pageset=os --template=os \

       Save  this  to  $XYMONHOME/ext/, and set this up to run as a Xymon extension;
       this means addng an extra section to tasks.cfg to run it.

       This generates the pages. There are some important options used here:
       * XYMONWEB="/xymon/os" environment variable, and the
         "$XYMONHOME/www/os/" option work together, and places the
         new pageset HTML files in a subdirectory off the normal
         Xymon webroot. If you normally access the Xymon pages as
         "", you will then access
         the new pageset as ""
         NB: The directory given as XYMONWEB must contain a symbolic
         link to the $XYMONHOME/www/html/ directory, or links to
         individual status messages will not work. Similar links
         should be made for the gifs/, help/ and notes/
       * "--pageset=os" tells xymongen to structure the webpages
         using the "os" layout, instead of the default layout.
       * "--template=os" tells xymongen to use a different set of
         header- and footer-templates. Normally xymongen uses the
         standard template in $XYMONHOME/web/stdnormal_header and
         .../stdnormal_footer - with this option, it will instead use
         the files "os_header" and "os_footer" from the
         $XYMONHOME/web/ directory. This allows you to customize
         headers and footers for each pageset. If you just want
         to use the normal template, you can omit this option.


       xymongen reporting  is  implemented  via  drop-in  replacements  for  the  standard  Xymon
       reporting  scripts  (  and  installed  in  your webservers cgi-bin

       These two shell script have been replaced with two very small shell-scripts,  that  merely
       setup  the  Xymon  environment variables, and invoke the report.cgi(1) or reportlog.cgi(1)
       scripts in $XYMONHOME/bin/

       You can use xymongen command-line options when generating reports, e.g. to exclude certain
       types  of tests (e.g. "--ignorecolumns=msgs") from the reports, to specify the name of the
       trends- and info- columns that should not be in  the  report,  or  to  format  the  report
       differently  (e.g.  "--subpagecolumns=2").  If  you want certain options to be used when a
       report  is  generated  from   the   web   interface,   put   these   options   into   your
       $XYMONHOME/etc/xymonserver.cfg file in the XYMONGENREPOPTS environment variable.

       The  report  files  generated  by  xymongen  are stored in individual directories (one per
       report) below the $XYMONHOME/www/rep/ directory.  These should be automatically cleaned up
       - as new reports are generated, the old ones get removed.

       After  installing,  try  generating  a report. You will probably see that the links in the
       upper left corner (to ack.html, nongreen.html etc.)  no longer works. To fix these, change
       your  $XYMONHOME/web/repnormal_header  file so these links do not refer to "&XYMONWEB" but
       to the normal URL prefix for your Xymon pages.


       xymongen reporting allows for  the  generation  of  true  SLA  (Service  Level  Agreement)
       reports,  also  for  service  periods  that  are  not  24x7. This is enabled by defining a
       "REPORTTIME:timespec" tag for the hosts to define the service  period,  and  optionally  a
       "WARNPCT:level" tag to define the agreed availability.

       Note: See hosts.cfg(5) for the exact syntax of these options.

       "REPORTTIME:timespec"  specifies the time of day when the service is expected to be up and
       running. By default this is 24 hours a day, all days of the week. If your SLA only  covers
       Mon-Fri  7am  - 8pm, you define this as "REPORTTIME=W:0700:2000", and the report generator
       will then compute both the normal 24x7 availability but also a  "SLA  availability"  which
       only takes the status of the host during the SLA period into account.

       The  DOWNTIME:timespec  parameter  affects  the SLA availability calculation. If an outage
       occurs during the time defined as possible "DOWNTIME", then the failure is reported with a
       status  of  "blue".  (The  same  color  is used if you "disable" then host using the Xymon
       "disable" function). The time when the test status is "blue" is not included  in  the  SLA
       calculation,  neither  in the amount of time where the host is considered down, nor in the
       total amount of time that the report covers. So "blue" time is effectively ignored by  the
       SLA  availability calculation, allowing you to have planned downtime without affecting the
       reported SLA availability.

       Example: A host has "DOWNTIME:*:0700:0730 REPORTTIME=W:0600:2200" because it  is  rebooted
       every  day between 7am and 7.30am, but the service must be available from 6am to 10pm. For
       the day of the report, it was down from 7:10am to 7:15am (the planned  reboot),  but  also
       from 9:53pm to 10:15pm. So the events for the day are:

          0700 : green for 10 minutes (600 seconds)
          0710 : blue for 5 minutes (300 seconds)
          0715 : green for 14 hours 38 minutes (52680 seconds)
          2153 : red for 22 minutes (1320 seconds)
          2215 : green

       The  service  is available for 600+52680 = 53280 seconds. It is down (red) for 420 seconds
       (the time from 21:53 until 22:00 when the SLA period ends). The total time included in the
       report  is  15  hours  (7am - 10pm) except the 5 minutes blue = 53700 seconds.  So the SLA
       availability is 53280/53700 = 99,22%

       The "WARNPCT:level" tag is supported in  the  hosts.cfg  file,  to  set  the  availability
       threshold on a host-by-host basis. This threshold determines whether a test is reported as
       green, yellow or red in the reports. A default value can be set for all hosts with the via
       the  XYMONREPWARN environment variable, but overridden by this tag.  The level is given as
       a percentage, e.g. "WARNPCT:98.5"


       Normally, xymongen produce reports that link to dynamically generated  webpages  with  the
       detailed status of a test (via the CGI script).

       It  is  possible  to  have  xymongen  produce a report without these dynamic links, so the
       report can be exported to another server.  It may  also  be  useful  to  pre-generate  the
       reports, to lower the load by having multiple users generate the same reports.

       To  do  this,  you  must  run  xymongen  with the "--reportopts" option to select the time
       interval that the report covers, the reporting style (critical, non-green, or all events),
       and to request that no dynamic pages are to be generated.

       The syntax is:

          xymongen --reportopts=starttime:endtime:nodynamic:style

       "starttime"  and "endtime" are specified as Unix time_t values, i.e. seconds since Jan 1st
       1970 00:00 GMT. Fortunately, this can easily be computed with the GNU date utility if  you
       use  the  "+%s" output option. If you don't have the GNU date utility, either pick that up
       from; or you can use the "etime"  utility  for  the  same  purpose,  which  is
       available from the archive at

       "nodynamic"  is  either 0 (for dynamic pages, the default) or 1 (for no dynamic, i.e. pre-
       generated, pages).

       "style" is either "crit" (include critical i.e. red events  only),  "nongr"  (include  all
       non-green events), or "all" (include all events).

       Other  xymongen options can be used, e.g. "--ignorecolumns" if you want to exclude certain
       tests from the report.

       You will normally also need to specify the XYMONWEB environment variable  (it  must  match
       the  base  URL for where the report will be made accessible from), and an output directory
       where the report files are saved.  If you  specify  XYMONWEB,  you  should  probably  also
       define  the XYMONHELPSKIN and XYMONNOTESSKIN environment variables.  These should point to
       the URL where your Xymon help- and notes-files are located; if they are not  defined,  the
       links  to  help-  and notes-files will point inside the report directory and will probably
       not work.

       So a typical invocation of xymongen for a static report would be:

         START=`date +%s --date="22 Jun 2003 00:00:00"`
         END=`date +%s --date="22 Jun 2003 23:59:59"`
         XYMONWEB=/reports/bigbrother/daily/2003/06/22 \
         XYMONHELPSKIN=/xymon/help \
         XYMONNOTESSKIN=/xymon/notes \
         xymongen --reportopts=$START:$END:1:crit \
               --subpagecolumns=2 \

       The  "XYMONWEB"  setting  means  that  the  report  will  be  available  with  a  URL   of
       "".    The  report  contains  internal
       links that use this URL, so it cannot be easily moved to another location.

       The last parameter is the corresponding physical directory on your webserver matching  the
       XYMONWEB  URL.  You  can  of course create the report files anywhere you like - perhaps on
       another machine - and then move them to the webserver later on.

       Note how the date(1) utility is used to calculate the start- and end-time parameters.


              Filter used to select what hosts / tests are included in the webpages, by filtering
              the data retrieved from xymond vi the xymondboard command. See xymon(1) for details
              on the filter syntax. By default, no filtering is done.


       hosts.cfg(5), xymonserver.cfg(5), tasks.cfg(5), report.cgi(1), snapshot.cgi(1), xymon(7)