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