doc/rrdcgi.pod

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