<HTML>
<HEAD>
<TITLE>rrdcgi</TITLE>
<LINK REV="made" HREF="mailto:karrer@iis.ee.ethz.ch">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<!--
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<UL>
<LI><A HREF="#pass 1">Pass 1</A></LI>
<LI><A HREF="#pass 2">Pass 2</A></LI>
<LI><A HREF="#pass 3">Pass 3</A></LI>
</UL>
<LI><A HREF="#example 1">EXAMPLE 1</A></LI>
<LI><A HREF="#example 2">EXAMPLE 2</A></LI>
<LI><A HREF="#example 3">EXAMPLE 3</A></LI>
<LI><A HREF="#author">AUTHOR</A></LI>
</UL>
-->
<!-- INDEX END -->
<P>
<H1><A NAME="name">NAME</A></H1>
<P>rrdcgi - create web pages containing RRD graphs based on templates</P>
<div align="right"><a href="rrdcgi.pdf">PDF</a> version.</div><P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<P>#!/path/to/<STRONG>rrdcgi</STRONG>
[<STRONG>--goodfor</STRONG>|<STRONG>-g</STRONG> <EM>seconds</EM>]
[<STRONG>--filter</STRONG>]
[<STRONG>--refresh</STRONG>|<STRONG>-r</STRONG>]</P>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P><STRONG>rrdcgi</STRONG> is a sort of very limited script interpreter. Its purpose
is to run as a cgi-program and parse a web page template containing special
<RRD:: tags. <STRONG>rrdcgi</STRONG> will interpret and act according to these tags.
In the end it will printout a web page including the necessary CGI headers.</P>
<P><STRONG>rrdcgi</STRONG> parses the contents of the template in 2 steps. In each step it looks
only for a subset of tags. This allows to nest tags.</P>
<P>The argument parser uses the same semantics as you are used from your c shell.</P>
<DL>
<DT><STRONG><A NAME="item_%2D%2Dfilter"><STRONG>--filter</STRONG></A></STRONG><BR>
<DD>
Assume that rrdcgi is being run as a filter and not as a cgi.
<P></P>
<DT><STRONG><A NAME="item_%2D%2Drefresh%7C%2Dr"><STRONG>--refresh</STRONG>|<STRONG>-r</STRONG></A></STRONG><BR>
<DD>
If the <STRONG>--goodfor</STRONG> flag is specified, then <STRONG>--refresh</STRONG> will cause rrdcgi
to output a Refresh header with the value of the <STRONG>--goodfor</STRONG> value.
<P></P></DL>
<P>
<H2><A NAME="pass 1">Pass 1</A></H2>
<DL>
<DT><STRONG><A NAME="item_RRD%3A%3ACV_name">RRD::CV <EM>name</EM></A></STRONG><BR>
<DD>
Inserts the CGI variable of the given name.
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3ACV%3A%3AQUOTE_name">RRD::CV::QUOTE <EM>name</EM></A></STRONG><BR>
<DD>
Inserts the CGI variable of the given name but quotes it, ready for
use as an argument in another RRD:: tag. So even when there are spaces in the
value of the CGI variable it will still be considered as one argument.
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3ACV%3A%3APATH_name">RRD::CV::PATH <EM>name</EM></A></STRONG><BR>
<DD>
Inserts the CGI variable of the given name, quotes it and makes sure
the it starts neither with a '/' nor contains '..'. This is to make
sure that no problematic pathnames can be introduced through the
CGI interface.
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3AGETENV_variable">RRD::GETENV <EM>variable</EM></A></STRONG><BR>
<DD>
Get the value of an environment variable.
<PRE>
<RRD::GETENV REMOTE_USER></PRE>
<P>might give you the name of the remote user given you are using
some sort of access control on the directory</P>
<P></P></DL>
<P>
<H2><A NAME="pass 2">Pass 2</A></H2>
<DL>
<DT><STRONG><A NAME="item_RRD%3A%3AGOODFOR_seconds">RRD::GOODFOR <EM>seconds</EM></A></STRONG><BR>
<DD>
Specify the number of seconds this page should remain valid. This will prompt
the rrdcgi to output a Last-Modified, an Expire and if the number of
seconds is <EM>negative</EM> a Refresh headers.
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3AINCLUDE_filename">RRD::INCLUDE <EM>filename</EM></A></STRONG><BR>
<DD>
Include the contents of the given file into the page returned from the cgi
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3ASETENV_variable_value">RRD::SETENV <EM>variable</EM> <EM>value</EM></A></STRONG><BR>
<DD>
If you want to present your graphs in another time zone than your own, you
could use
<PRE>
<RRD::SETENV TZ UTC></PRE>
<P>to make sure everything is presented in Universal Time. Note that the
values permitted to TZ depend on your OS.</P>
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3ATIME%3A%3ALAST_rrd%2Dfile_strftime%2Dform">RRD::TIME::LAST <EM>rrd-file</EM> <EM>strftime-format</EM></A></STRONG><BR>
<DD>
This gets replaced by the last modification time of the selected RRD. The
time is <EM>strftime</EM>-formated with the string specified in the second argument.
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3ATIME%3A%3ANOW_strftime%2Dformat">RRD::TIME::NOW <EM>strftime-format</EM></A></STRONG><BR>
<DD>
This gets replaced by the current time of day. The
time is <EM>strftime</EM>-formated with the string specified in the argument.
<P></P></DL>
<P>
<H2><A NAME="pass 3">Pass 3</A></H2>
<DL>
<DT><STRONG><A NAME="item_RRD%3A%3AGRAPH_rrdgraph_arguments">RRD::GRAPH <EM>rrdgraph arguments</EM></A></STRONG><BR>
<DD>
This tag creates the RRD graph defined in its argument and then gets
replaced by an appropriate <IMG> tag referring to the graph.
The <STRONG>--lazy</STRONG> option in RRD graph can be used to make sure that graphs
are only regenerated when they are out of date. The arguments
to the <STRONG>RRD::GRAPH</STRONG> tag work as described in the <STRONG>rrdgraph</STRONG> manual page.
<P>Use the <STRONG>--lazy</STRONG> option in your RRD::GRAPH tags, to reduce the load
on your server. This option makes sure that graphs are only regenerated when
the old ones are out of date.</P>
<P>If you do not specify your own <STRONG>--imginfo</STRONG> format, the following will
be used:</P>
<PRE>
<IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu"></PRE>
<P>Note that %s stands for the filename part of the graph generated, all
directories given in the GIF file argument will get dropped.</P>
<P></P>
<DT><STRONG><A NAME="item_RRD%3A%3APRINT_number">RRD::PRINT <EM>number</EM></A></STRONG><BR>
<DD>
If the preceding <STRONG>RRD::GRAPH</STRONG> tag contained and <STRONG>PRINT</STRONG> arguments,
then you can access their output with this tag. The <EM>number</EM> argument refers to the
number of the <STRONG>PRINT</STRONG> argument. This first <STRONG>PRINT</STRONG> has <EM>number</EM> 0.
<P></P></DL>
<P>
<HR>
<H1><A NAME="example 1">EXAMPLE 1</A></H1>
<P>The example below creates a web pages with a single RRD graph.</P>
<PRE>
#!/usr/local/bin/rrdcgi
<HTML>
<HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
<BODY>
<H1>RRDCGI Example Page</H1>
<P>
<RRD::GRAPH demo.gif --lazy --title="Temperatures"
DEF:cel=demo.rrd:exhaust:AVERAGE
LINE2:cel#00a000:"D. Celsius"></PRE>
<PRE>
</P>
</BODY>
</HTML></PRE>
<P>
<HR>
<H1><A NAME="example 2">EXAMPLE 2</A></H1>
<P>This script is slightly more elaborate, it allows you to run it from
a form which sets RRD_NAME. RRD_NAME is then used to select which RRD
you want to use a source for your graph.</P>
<PRE>
#!/usr/local/bin/rrdcgi
<HTML>
<HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
<BODY>
<H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
<H2>Selection</H2>
<FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
<INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
<INPUT TYPE=SUBMIT></FORM>
<H2>Graph</H2>
<P>
<RRD::GRAPH <RRD::CV::PATH RRD_NAME>.gif --lazy
--title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
LINE2:cel#00a000:"D. Celsius"></PRE>
<PRE>
</P>
</BODY>
</HTML></PRE>
<P>
<HR>
<H1><A NAME="example 3">EXAMPLE 3</A></H1>
<P>This example shows how to handle the case where the RRD, graphs and
cgi-bins are seperate directories</P>
<PRE>
#!/.../bin/rrdcgi
<HTML>
<HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
<BODY>
<H1>RRDCGI test Page</H1>
<RRD::GRAPH
/.../web/gifs/testhvt.gif
--imginfo '<IMG SRC=/.../gifs/%s WIDTH=%lu HEIGHT=%lu >'
--lazy --start -1d --end now
DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
AREA:http_src#00ff00:http_src
>
</BODY>
</HTML></PRE>
<P>Note 1: Replace /.../ with the relevant directories</P>
<P>Note 2: The SRC=/.../gifs should be paths from the view of the
webserver/browser</P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Tobias Oetiker <<A HREF="mailto:oetiker@ee.ethz.ch">oetiker@ee.ethz.ch</A>></P>
</BODY>
</HTML>
