3 rrdcgi - Create web pages containing RRD graphs based on templates
7 C<#!/path/to/>B<rrdcgi> S<[B<--filter>]>
11 B<rrdcgi> is a sort of very limited script interpreter. Its purpose
12 is to run as a cgi-program and parse a web page template containing special
13 E<lt>RRD:: tags. B<rrdcgi> will interpret and act according to these tags.
14 In the end it will printout a web page including the necessary CGI headers.
16 B<rrdcgi> parses the contents of the template in 3 steps. In each step it looks
17 only for a subset of tags. This allows to nest tags.
19 The argument parser uses the same semantics as you are used from your c shell.
26 Assume that rrdcgi is being run as a filter and not as a cgi.
36 Inserts the CGI variable of the given name.
38 =item RRD::CV::QUOTE I<name>
40 Inserts the CGI variable of the given name but quotes it, ready for
41 use as an argument in another RRD:: tag. So even when there are spaces in the
42 value of the CGI variable it will still be considered as one argument.
44 =item RRD::CV::PATH I<name>
46 Inserts the CGI variable of the given name, quotes it and makes sure
47 the it starts neither with a '/' nor contains '..'. This is to make
48 sure that no problematic pathnames can be introduced through the
51 =item RRD::GETENV I<variable>
53 Get the value of an environment variable.
55 <RRD::GETENV REMOTE_USER>
57 might give you the name of the remote user given you are using
58 some sort of access control on the directory
61 =item RRD::GOODFOR I<seconds>
63 Specify the number of seconds this page should remain valid. This will prompt
64 the rrdcgi to output a Last-Modified, an Expire and if the number of
65 seconds is I<negative> a Refresh headers.
67 =item RRD::INCLUDE I<filename>
69 Include the contents of the given file into the page returned from the cgi
71 =item RRD::SETENV I<variable> I<value>
73 If you want to present your graphs in another time zone than your own, you
78 to make sure everything is presented in Universal Time. Note that the
79 values permitted to TZ depend on your OS.
81 =item RRD::SETVAR I<variable> I<value>
83 Analog to SETENV but for local variables
85 =item RRD::GETVAR I<variable>
87 Analog to GETENV but for local variables
89 =item RRD::TIME::LAST I<rrd-file> I<strftime-format>
91 This gets replaced by the last modification time of the selected RRD. The
92 time is I<strftime>-formatted with the string specified in the second argument.
94 =item RRD::TIME::NOW I<strftime-format>
96 This gets replaced by the current time of day. The time is
97 I<strftime>-formatted with the string specified in the argument.
99 Note that if you return : from your strftime format you may have to escape
100 them using \ if the time is to be used as an argument to a GRAPH command.
102 =item RRD::TIME::STRFTIME I<START|END> I<start-spec> I<end-spec> I<strftime-format>
104 This gets replaced by a strftime-formatted time using the format
105 I<strftime-format> on either I<start-spec> or I<end-spec> depending on
106 whether I<START> or I<END> is specified. Both I<start-spec> and I<end-spec>
107 must be supplied as either could be relative to the other. This is intended
108 to allow pretty titles on graphs with times that are easier for non RRDtool
109 folks to figure out than "-2weeks".
111 Note that if you return : from your strftime format you may have to escape
112 them using \ if the time is to be used as an argument to a GRAPH command.
114 =item RRD::GRAPH I<rrdgraph arguments>
116 This tag creates the RRD graph defined in its argument and then gets
117 replaced by an appropriate E<lt>IMGE<gt> tag referring to the graph.
118 The B<--lazy> option in RRD graph can be used to make sure that graphs
119 are only regenerated when they are out of date. The arguments
120 to the B<RRD::GRAPH> tag work as described in the B<rrdgraph> manual page.
122 Use the B<--lazy> option in your RRD::GRAPH tags, to reduce the load
123 on your server. This option makes sure that graphs are only regenerated when
124 the old ones are out of date.
126 If you do not specify your own B<--imginfo> format, the following will
129 <IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">
131 Note that %s stands for the filename part of the graph generated, all
132 directories given in the PNG file argument will get dropped.
134 =item RRD::PRINT I<number>
136 If the preceding B<RRD::GRAPH> tag contained and B<PRINT> arguments,
137 then you can access their output with this tag. The I<number> argument refers to the
138 number of the B<PRINT> argument. This first B<PRINT> has I<number> 0.
144 The example below creates a web pages with a single RRD graph.
146 #!/usr/local/bin/rrdcgi
148 <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
150 <H1>RRDCGI Example Page</H1>
152 <RRD::GRAPH demo.png --lazy --title="Temperatures"
153 DEF:cel=demo.rrd:exhaust:AVERAGE
154 LINE2:cel#00a000:"D. Celsius">
162 This script is slightly more elaborate, it allows you to run it from
163 a form which sets RRD_NAME. RRD_NAME is then used to select which RRD
164 you want to use a source for your graph.
166 #!/usr/local/bin/rrdcgi
168 <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
170 <H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
172 <FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
173 <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
174 <INPUT TYPE=SUBMIT></FORM>
177 <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
178 --title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
179 DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
180 LINE2:cel#00a000:"D. Celsius">
188 This example shows how to handle the case where the RRD, graphs and
189 cgi-bins are seperate directories
193 <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
195 <H1>RRDCGI test Page</H1>
197 /.../web/pngs/testhvt.png
198 --imginfo '<IMG SRC=/.../pngs/%s WIDTH=%lu HEIGHT=%lu >'
199 --lazy --start -1d --end now
200 DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
201 AREA:http_src#00ff00:http_src
206 Note 1: Replace /.../ with the relevant directories
208 Note 2: The SRC=/.../pngs should be paths from the view of the
213 Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>