Remstats Home


  About remstats
  Release Notes
  FAQ
  Conventions
  Prerequisites
  Installation
  Configuration
  Configuration Tools
  Servers
  Collectors
  Updater
  Monitors
  run-remstats
  CGIs
      alert-cgi
      availability-report-cgi
      dataimage-cgi
      datapage-cgi
      graph-cgi
      log-event-cgi
      ping-cgi
      showlog-cgi
      traceroute-cgi
      whois-cgi
  do-traceroutes
  Miscellany
  Thank-you
  Index


  Live Data

  Remstats was written by
  Thomas Erskine at the
  CRC in Canada and now
  at SourceWorks.

[Top] [Prev] [Next]

datapage.cgi - dynamic data in web-pages

Usage:

	<A HREF="/remstats/datapage.cgi?pagename">whatever</A>

Data Collection

Datapage.cgi looks for the page definition in the file @@DATAPAGEDIR@@/pagename.page The page definition is in two parts, separated by a line like:

	BEGIN-PAGE

The first part's purpose is to define variables to be included in the second part, which is an HTML template, with magic cookies.

All lines in the first or definition part are subject to variable interpolation. Any ocurrance of ${variablename} will be replaced by the current contents of the variable variablename. This will be done up to five levels, permitting expansion of ${${h}_${interface}}, providing that you've got values for the variables h and interface. N.B. variable names must be lower case.

In addition, within a macro expansion, macro-arguments will also be interpolated, before variable interpolation, for all ocurrances of ${ARGNAME}, assuming that there is an argument for the current macro called ARGNAME. N.B. macro argument names must be UPPER case.

Common Commands

The commands permitted in the first part are:

	oid, rrd, status, eval, debug, macro, macroend,
	alertstatus, alertvalue and *EOD*

These commands are in common with the dataimage.cgi script, but are only documented here.

  • oid

    This fetches an SNMP value into a datapage variable. The command looks like:

    	oid VARNAME HOSTNAME OIDNAME

    The VARNAME is the name of the datapage variable (let's just call them variables from now on).

    The HOSTNAME is the name of the host to query. The SNMP community-string is usually supplied in that host's config-file, but can be supplied in usual MRTG fashion by giving COMMUNITY@HOSTNAME or even COMMUNITY@HOSTNAME:PORTNUMBER instead of the HOSTNAME.

    The OIDNAME must be defined in the oids config-file, but can be suffixed by the usual numbers. E.G. you can use ifName.4 to get the ifName for interface 4.

  • rrd

    This fetches a value from an RRD database into a variable. It looks like:

    	rrd VARNAME HOSTNAME RRDNAME DSNAME CF

    The RRDNAME is the name of the rrd, as remstats knows it, not fully qualified. I.E. it will be under the config-file defined datadir, and under the host's directory under that.

    The DSNAME is the ds-name within that RRD file and the CF is the usual RRD consolidation-function to be applied.

  • status

    This is so-named because it fetches remstats status files, usually written by the various collectors and monitors. It looks like:

    	status VARNAME HOSTNAME STATUSNAME

    The STATUSNAME is the name of the status file, as named in the host's data directory. There is a standard mapping applied by the function to_filename from the remstats.pl</t file to munge the filename so that it won't conflict with the filesystem. Either look for the name in the data directory, use the function (see eval) or look at the code. I am planning on changing the mapping when I figure out the best way to do it.

  • eval

    The eval command lets you modify the values fetched by previous oid, rrd, status and eval commands with arbitrary perl code. It looks like:

    	eval VARNAME PERLEXPRESSION

    The PERLEXPRESSION is a perl expression and can be arbitrarily complex, but gets messy quickly with the datapage.cgi and perl both doing variable interpolation.

    Note: datapage.cgi uses private.pl, so you can include commonly used functions here to make your datapage creation easier.

  • debug

    The debug command takes a number which is the level to set debugging to. It causes extra output which may be helpful in figuring out why your page isn't working the way you expected.

  • alertstatus

    This lets you fetch the alert level for a given (host, rrd, dsname, cf) combination. The command looks like:

    	alertstatus VARNAME HOSTNAME RRDNAME DSNAME [CF]

    This will fetch the alert status and put it in the datapage variable VARNAME. The status will be the same set of values shown on the alerts report for status. The CF parameter is optional and is rrdtool's consolidation function. It will be set to AVERAGE if it's not supplied.

  • alertvalue

    This is the same as alertstatus except that it sets the variable to the current value of the (host, rrd, variable, cf) combination.

The HTML template

This is almost just HTML with a few magic cookies inserted. The difference is that the beginning must include HTTP headers. If you don't want anything fancy, just begin like:

	------ cut here ------
	BEGIN-PAGE
	content-type: text/html
	------ cut here ------

Note: the empty line after content-type: is not optional. It's necessary to end the HTTP headers.

The magic cookies are:

  • <DATAPAGE::STATUS host statusfile>

    inserts a specified status file

  • <DATAPAGE::VAR varname>

    interpolates the value of a datapage variable

  • <DATAPAGE::HEADER title>

    generates a standard remstats header

  • <DATAPAGE::STATUSHEADER hostname>

    generates the status headers for the named host

  • <DATAPAGE::TOOLBAR hostname>

    generates the toolbar for the named host

  • <DATAPAGE::FOOTER>

    generates a standard remstats footer

  • <DATAPAGE::INCLUDE filename>

    include the contents of a file from the datapage directory, for imagemaps ...

  • <DATAPAGE::PATHINCLUDE filename-with-path>

    include contents of a file specified with a complete path

  • <DATAPAGE::MACRO macroname [argvalue] ...>

    include boilerplate HTML with substitutions

  • <DATAPAGE::GRAPH host rrd graph time>

    generate the specified remstats graph

  • <DATAPAGE::CUSTOMGRAPH graph time>

    generate the specified remstats customgraph

  • <DATAPAGE::ERRORS>

    inserts the text of errors encountered in generating the page. Without this one, you won't see any errors. That way you include the errors and debugging output (see next item), which you're creating/debugging the datapage and afterwards turn them off. The errors and debugging output may include information you don't want to reveal to outsiders. Also, collecting all the error output together avoids spoiling the formatting of the page.

  • <DATAPAGE::DEBUG>

    inserts debugging output. Without it, you won't see any debugging output.


Last updated Thu Mar 17 16:58:55 UTC 2005 by
<thomas.erskine@sourceworks.com>.
[SourceWorks] [Top] [RRDtool]