Provided by: xymon_4.3.30-1build3_amd64 
NAME
xymongen - Xymon webpage generator
SYNOPSIS
xymongen -?
xymongen --help
xymongen --version
xymongen [options] [output-directory]
(See the OPTIONS section for a description of the available command-line options).
DESCRIPTION
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.
OPTIONS
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.
GENERAL OPTIONS
--help or -?
Provide a summary of available command-line options.
--version
Prints the version number of xymongen
--docurl=URL
This option is deprecated, use the HOSTDOCURL setting in xymonserver.cfg(5)
instead.
--doccgi=URL
This option is deprecated, use the HOSTDOCURL setting in xymonserver.cfg(5)
instead.
--doc-window
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.
--htmlextension=.EXTENSION
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".
--report[=COLUMNNAME]
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".
--htaccess[=htaccess-filename]
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
subpagename.
--max-eventcount=N
Limit the eventlog on the "All non-green" page to only N events. Default: 100.
--max-eventtime=N
Limit the eventlog on the "All non-green" page to events that happened within the
past N minutes. Default: 240.
--no-eventlog
Disable the eventlog normally displayed on the "All non-green" page
--max-ackcount=N
Limit the acknowledgment log on the "All non-green" page to only N events. Default:
25.
--max-acktime=N
Limit the acknowledgment log on the "All non-green" page to acks that happened
within the past N minutes. Default: 240.
--no-acklog
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
--loadhostsfromxymond
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.
PAGE LAYOUT OPTIONS
These options affect how the webpages generated by xymongen appear in the browser.
--pages-last
Put page- and subpage-links after hosts.
--pages-first
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.
--subpagecolumns=N
Determines the number of columns used for links to pages and subpages. The default
is N=1.
--maxrows=N
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.
--showemptygroups
--no-showemptygroups
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)
--pagetitle-links
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.
--pagetext-headings
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.
--no-underline-headings
Normally, page headings are underlined using an HTML "horizontal ruler" tag. This
option disables the underlining of headings.
--recentgifs[=MINUTES]
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.
--sort-group-only-items
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.
--dialupskin=URL
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.
--reverseskin=URL
Same as "--dialupskin", but for reverse tests (tests with '!' in front).
--tooltips=[always,never,main]
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.
COLUMN SELECTION OPTIONS
These options affect which columns (tests) are included in the webpages generated by
xymongen.
--ignorecolumns=test[,test]
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".
--critical-reds-only
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.
--nongreen-colors=COLOR[,COLOR]
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.
--nongreen-ignorecolumns=test[,test]
Same as the --ignorecolumns, but applies to hosts on the "All non-green" page only.
--nongreen-ignorepurples
Deprecated, use "--nongreen-colors" instead.
--nongreen-ignoredialups
Ignore all dialup hosts on the "All non-green" page, including the eventlog.
--no-pages
Do not generate the normal pages (normally used to generate only the non-green
page).
--no-nongreen
Do not generate the "All non-green" page.
--includecolumns=test[,test]
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.
--eventignore=test[,test]
Ignore these tests in the "All non-green" event log display.
STATUS PROPAGATION OPTIONS
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
basis.
--nopropyellow=test[,test] or --noprop=test[,test]
Disable upwards status propagation when YELLOW. The "--noprop" option is deprecated
and should not be used.
--noproppurple=test[,test]
Disable upwards status propagation when PURPLE.
--nopropred=test[,test]
Disable upwards status propagation when RED or YELLOW.
--nopropack=test[,test]
Disable upwards status propagation when status has been acknowledged. If you want
to disable all acked tests from being propageted, use "--nopropack=*".
PURPLE STATUS OPTIONS
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
purple.
--purplelog=FILENAME
Generate a logfile of all purple status messages.
ALTERNATE PAGESET OPTIONS
--pageset=PAGESETNAME
Build webpages for an alternate pageset than the default. See the PAGESETS section
below.
--template=TEMPLATE
Use an alternate template for header and footer files. Typically used together the
the "--pageset" option; see the PAGESETS section below.
ALTERNATE OUTPUT FORMATS
--wml[=test1,test2,...]
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.
--nstab=FILENAME
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",
"http://your.server.com/nstab.html","");
else
alert("Sidebar only for Mozilla or Netscape 6+");
}
//-->
</SCRIPT>
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
with
<A HREF="javascript:addNetscapePanel();">
<IMG SRC="/gifs/add-button.gif" HEIGHT=45 WIDTH=100
ALT="[Add Sidebar]" STYLE="border:0">
</A>
The "add-button.gif" is available from Netscape at
http://developer.netscape.com/docs/manuals/browser/sidebar/add-button.gif.
If FILENAME does not begin with a slash, the Netscape sidebar file is placed in the
$XYMONHOME/www/ directory.
--nslimit=COLOR
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
"--nslimit=yellow".
--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
http://www.syndic8.com/.
--rssextension=.EXTENSION
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".
--rssversion={0.91|0.92|1.0|2.0}
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.
--rsslimit=COLOR
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
"--rsslimit=yellow".
OPTIONS USED BY CGI FRONT-ENDS
--reportopts=START:END:DYNAMIC:STYLE
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.
--csv=FILENAME
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.
--csvdelim=DELIMITER
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.
--snapshot=TIME
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
script.
DEBUGGING OPTIONS
--debug
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
option.
--timing
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
xymongen.
Note: This information is also provided in the output sent to the Xymon display
when using the "--report" option.
BUILDING ALTERNATE PAGESETS
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.
207.46.249.190 www.microsoft.com # OS:win-xp http://www.microsoft.com/
64.124.140.181 www.sun.com # OS:unix-sun http://www.sun.com/
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:
#!/bin/sh
XYMONWEB="/xymon/os" $XYMONHOME/bin/xymongen \
--pageset=os --template=os \
$XYMONHOME/www/os/
Save this to $XYMONHOME/ext/os-display.sh, 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
"http://xymon.acme.com/xymon/", you will then access
the new pageset as "http://xymon.acme.com/xymon/os/"
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/
directories.
* "--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.
USING XYMONGEN FOR REPORTS
xymongen reporting is implemented via drop-in replacements for the standard Xymon
reporting scripts (report.sh and reportlog.sh) installed in your webservers cgi-bin
directory.
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.
SLA REPORTING
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"
PRE-GENERATED REPORTS
Normally, xymongen produce reports that link to dynamically generated webpages with the
detailed status of a test (via the reportlog.sh 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 www.gnu.org; or you can use the "etime" utility for the same purpose, which is
available from the archive at www.deadcat.net.
"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 \
/var/www/docroot/reports/xymon/daily/2003/06/22
The "XYMONWEB" setting means that the report will be available with a URL of
"http://www.server.com/reports/xymon/daily/2003/06/22". 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.
ENVIRONMENT VARIABLES
BOARDFILTER
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.
SEE ALSO
hosts.cfg(5), xymonserver.cfg(5), tasks.cfg(5), report.cgi(1), snapshot.cgi(1), xymon(7)