| XYMONGEN(1) | General Commands Manual | XYMONGEN(1) |
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.
These options affect how the webpages generated by xymongen appear in the browser.
These two options decide whether a page with links to subpages and hosts have the hosts or the subpages first.
These options affect which columns (tests) are included in the webpages generated by xymongen.
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.
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.
<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.
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.
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.
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 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.
hosts.cfg(5), xymonserver.cfg(5), tasks.cfg(5), report.cgi(1), snapshot.cgi(1), xymon(7)
| Version 4.3.30: 4 Sep 2019 | Xymon |