doc/rrdcgi.pod

   1 =head1 NAME
   2
   3 rrdcgi - Create web pages containing RRD graphs based on templates
   4
   5 =head1 SYNOPSIS
   6
   7 C<#!/path/to/>B<rrdcgi> S<[B<--filter>]>
   8
   9 =head1 DESCRIPTION
  10
  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.
  15
  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 nesting of tags.
  18
  19 The argument parser uses the same semantics as you are used from your C-shell.
  20
  21 =over 8
  22
  23 =item B<--filter>
  24
  25 Assume that rrdcgi is run as a filter and not as a cgi.
  26
  27 =back
  28
  29 =head2 Keywords
  30
  31 =over 8
  32
  33 =item RRD::CV I<name>
  34
  35 Inserts the CGI variable of the given name.
  36
  37 =item RRD::CV::QUOTE I<name>
  38
  39 Inserts the CGI variable of the given name but quotes it, ready for
  40 use as an argument in another RRD:: tag. So even when there are spaces in the
  41 value of the CGI variable it will still be considered to be one argument.
  42
  43 =item RRD::CV::PATH I<name>
  44
  45 Inserts the CGI variable of the given name, quotes it and makes sure
  46 it starts neither with a '/' nor contains '..'. This is to make
  47 sure that no problematic pathnames can be introduced through the
  48 CGI interface.
  49
  50 =item RRD::GETENV I<variable>
  51
  52 Get the value of an environment variable.
  53
  54  <RRD::GETENV REMOTE_USER>
  55
  56 might give you the name of the remote user given you are using
  57 some sort of access control on the directory.
  58
  59
  60 =item RRD::GOODFOR I<seconds>
  61
  62 Specify the number of seconds this page should remain valid. This will prompt
  63 the rrdcgi to output a Last-Modified, an Expire and if the number of
  64 seconds is I<negative> a Refresh header.
  65
  66 =item RRD::INCLUDE I<filename>
  67
  68 Include the contents of the specified file into the page returned from the cgi.
  69
  70 =item RRD::SETENV I<variable> I<value>
  71
  72 If you want to present your graphs in another time zone than your own, you
  73 could use
  74
  75  <RRD::SETENV TZ UTC>
  76
  77 to make sure everything is presented in Universal Time. Note that the
  78 values permitted to TZ depend on your OS.
  79
  80 =item RRD::SETVAR I<variable> I<value>
  81
  82 Analog to SETENV but for local variables.
  83
  84 =item RRD::GETVAR I<variable>
  85
  86 Analog to GETENV but for local variables.
  87
  88 =item RRD::TIME::LAST I<rrd-file> I<strftime-format>
  89
  90 This gets replaced by the last modification time of the selected RRD. The
  91 time is I<strftime>-formatted with the string specified in the second argument.
  92
  93 =item RRD::TIME::NOW I<strftime-format>
  94
  95 This gets replaced by the current time of day. The time is
  96 I<strftime>-formatted with the string specified in the argument.
  97
  98 Note that if you return : (colons) from your strftime format you may
  99 have to escape them using \ if the time is to be used as an argument
 100 to a GRAPH command.
 101
 102 =item RRD::TIME::STRFTIME I<START|END> I<start-spec> I<end-spec> I<strftime-format>
 103
 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".
 110
 111 Note that again, if you return : (colon) from your strftime format,
 112 you may have to escape them using \ if the time is to be used as an
 113 argument to a GRAPH command.
 114
 115 =item RRD::GRAPH I<rrdgraph arguments>
 116
 117 This tag creates the RRD graph defined by its argument and then is
 118 replaced by an appropriate E<lt>IMG ... E<gt> tag referring to the graph.
 119 The B<--lazy> option in RRD graph can be used to make sure that graphs
 120 are only regenerated when they are out of date. The arguments
 121 to the B<RRD::GRAPH> tag work as described in the B<rrdgraph> manual page.
 122
 123 Use the B<--lazy> option in your RRD::GRAPH tags, to reduce the load
 124 on your server. This option makes sure that graphs are only regenerated when
 125 the old ones are out of date.
 126
 127 If you do not specify your own B<--imginfo> format, the following will
 128 be used:
 129
 130  <IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">
 131
 132 Note that %s stands for the filename part of the graph generated, all
 133 directories given in the PNG file argument will get dropped.
 134
 135 =item RRD::PRINT I<number>
 136
 137 If the preceding  B<RRD::GRAPH> tag contained and B<PRINT> arguments,
 138 then you can access their output with this tag. The I<number> argument refers to the
 139 number of the B<PRINT> argument. This first B<PRINT> has I<number> 0.
 140
 141 =item RRD::INTERNAL <var>
 142
 143 This tag gets replaced by an internal var. Currently these vars are known:
 144 VERSION, COMPILETIME.
 145 These vars represent the compiled-in values.
 146
 147 =back
 148
 149 =head1 EXAMPLE 1
 150
 151 The example below creates a web pages with a single RRD graph.
 152
 153  #!/usr/local/bin/rrdcgi
 154  <HTML>
 155  <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
 156  <BODY>
 157  <H1>RRDCGI Example Page</H1>
 158  <P>
 159  <RRD::GRAPH demo.png --lazy --title="Temperatures"
 160           DEF:cel=demo.rrd:exhaust:AVERAGE
 161           LINE2:cel#00a000:"D. Celsius">
 162
 163  </P>
 164  </BODY>
 165  </HTML>
 166
 167 =head1 EXAMPLE 2
 168
 169 This script is slightly more elaborate, it allows you to run it from
 170 a form which sets RRD_NAME. RRD_NAME is then used to select which RRD
 171 you want to use as source for your graph.
 172
 173  #!/usr/local/bin/rrdcgi
 174  <HTML>
 175  <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
 176  <BODY>
 177  <H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
 178  <H2>Selection</H2>
 179  <FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
 180        <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
 181        <INPUT TYPE=SUBMIT></FORM>
 182  <H2>Graph</H2>
 183  <P>
 184  <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
 185           --title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
 186           DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
 187           LINE2:cel#00a000:"D. Celsius">
 188
 189  </P>
 190  </BODY>
 191  </HTML>
 192
 193 =head1 EXAMPLE 3
 194
 195 This example shows how to handle the case where the RRD, graphs and
 196 cgi-bins are seperate directories
 197
 198  #!/.../bin/rrdcgi
 199  <HTML>
 200  <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
 201  <BODY>
 202  <H1>RRDCGI test Page</H1>
 203  <RRD::GRAPH
 204   /.../web/pngs/testhvt.png
 205   --imginfo '<IMG SRC=/.../pngs/%s WIDTH=%lu HEIGHT=%lu >'
 206   --lazy --start -1d --end now
 207   DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
 208   AREA:http_src#00ff00:http_src
 209  >
 210  </BODY>
 211  </HTML>
 212
 213 Note 1: Replace /.../ with the relevant directories
 214
 215 Note 2: The SRC=/.../pngs should be paths from the view of the
 216 webserver/browser
 217
 218 =head1 AUTHOR
 219
 220 Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 221
 222
 223
 224
 225