doc/rrdcgi.txt

   1 RRDCGI(1)                           rrdtool                          RRDCGI(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdcgi - Create web pages containing RRD graphs based on templates
   7
   8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   9        "#!/path/to/"r\brr\brd\bdc\bcg\bgi\bi [-\b--\b-f\bfi\bil\blt\bte\ber\br]
  10
  11 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  12        r\brr\brd\bdc\bcg\bgi\bi is a sort of very limited script interpreter. Its purpose is to
  13        run as a cgi-program and parse a web page template containing special
  14        <RRD:: tags. r\brr\brd\bdc\bcg\bgi\bi will interpret and act according to these tags.  In
  15        the end it will printout a web page including the necessary CGI head-
  16        ers.
  17
  18        r\brr\brd\bdc\bcg\bgi\bi parses the contents of the template in 3 steps. In each step it
  19        looks only for a subset of tags. This allows nesting of tags.
  20
  21        The argument parser uses the same semantics as you are used from your
  22        C-shell.
  23
  24        -\b--\b-f\bfi\bil\blt\bte\ber\br
  25                Assume that rrdcgi is run as a filter and not as a cgi.
  26
  27        K\bKe\bey\byw\bwo\bor\brd\bds\bs
  28
  29
  30        RRD::CV _\bn_\ba_\bm_\be
  31                Inserts the CGI variable of the given name.
  32
  33        RRD::CV::QUOTE _\bn_\ba_\bm_\be
  34                Inserts the CGI variable of the given name but quotes it, ready
  35                for use as an argument in another RRD:: tag. So even when there
  36                are spaces in the value of the CGI variable it will still be
  37                considered to be one argument.
  38
  39        RRD::CV::PATH _\bn_\ba_\bm_\be
  40                Inserts the CGI variable of the given name, quotes it and makes
  41                sure it starts neither with a '/' nor contains '..'. This is to
  42                make sure that no problematic pathnames can be introduced
  43                through the CGI interface.
  44
  45        RRD::GETENV _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be
  46                Get the value of an environment variable.
  47
  48                 <RRD::GETENV REMOTE_USER>
  49
  50                might give you the name of the remote user given you are using
  51                some sort of access control on the directory.
  52
  53        RRD::GOODFOR _\bs_\be_\bc_\bo_\bn_\bd_\bs
  54                Specify the number of seconds this page should remain valid.
  55                This will prompt the rrdcgi to output a Last-Modified, an
  56                Expire and if the number of seconds is _\bn_\be_\bg_\ba_\bt_\bi_\bv_\be a Refresh
  57                header.
  58
  59        RRD::INCLUDE _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  60                Include the contents of the specified file into the page
  61                returned from the cgi.
  62
  63        RRD::SETENV _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\bv_\ba_\bl_\bu_\be
  64                If you want to present your graphs in another time zone than
  65                your own, you could use
  66
  67                 <RRD::SETENV TZ UTC>
  68
  69                to make sure everything is presented in Universal Time. Note
  70                that the values permitted to TZ depend on your OS.
  71
  72        RRD::SETVAR _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\bv_\ba_\bl_\bu_\be
  73                Analog to SETENV but for local variables.
  74
  75        RRD::GETVAR _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be
  76                Analog to GETENV but for local variables.
  77
  78        RRD::TIME::LAST _\br_\br_\bd_\b-_\bf_\bi_\bl_\be _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt
  79                This gets replaced by the last modification time of the
  80                selected RRD. The time is _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be-formatted with the string
  81                specified in the second argument.
  82
  83        RRD::TIME::NOW _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt
  84                This gets replaced by the current time of day. The time is
  85                _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be-formatted with the string specified in the argument.
  86
  87                Note that if you return : (colons) from your strftime format
  88                you may have to escape them using \ if the time is to be used
  89                as an argument to a GRAPH command.
  90
  91        RRD::TIME::STRFTIME _\bS_\bT_\bA_\bR_\bT_\b|_\bE_\bN_\bD _\bs_\bt_\ba_\br_\bt_\b-_\bs_\bp_\be_\bc _\be_\bn_\bd_\b-_\bs_\bp_\be_\bc _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt
  92                This gets replaced by a strftime-formatted time using the for-
  93                mat _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt on either _\bs_\bt_\ba_\br_\bt_\b-_\bs_\bp_\be_\bc or _\be_\bn_\bd_\b-_\bs_\bp_\be_\bc depending
  94                on whether _\bS_\bT_\bA_\bR_\bT or _\bE_\bN_\bD is specified.  Both _\bs_\bt_\ba_\br_\bt_\b-_\bs_\bp_\be_\bc and _\be_\bn_\bd_\b-
  95                _\bs_\bp_\be_\bc must be supplied as either could be relative to the other.
  96                This is intended to allow pretty titles on graphs with times
  97                that are easier for non RRDtool folks to figure out than
  98                "-2weeks".
  99
 100                Note that again, if you return : (colon) from your strftime
 101                format, you may have to escape them using \ if the time is to
 102                be used as an argument to a GRAPH command.
 103
 104        RRD::GRAPH _\br_\br_\bd_\bg_\br_\ba_\bp_\bh _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs
 105                This tag creates the RRD graph defined by its argument and then
 106                is replaced by an appropriate <IMG ... > tag referring to the
 107                graph.  The -\b--\b-l\bla\baz\bzy\by option in RRD graph can be used to make sure
 108                that graphs are only regenerated when they are out of date. The
 109                arguments to the R\bRR\bRD\bD:\b::\b:G\bGR\bRA\bAP\bPH\bH tag work as described in the r\brr\brd\bd-\b-
 110                g\bgr\bra\bap\bph\bh manual page.
 111
 112                Use the -\b--\b-l\bla\baz\bzy\by option in your RRD::GRAPH tags, to reduce the
 113                load on your server. This option makes sure that graphs are
 114                only regenerated when the old ones are out of date.
 115
 116                If you do not specify your own -\b--\b-i\bim\bmg\bgi\bin\bnf\bfo\bo format, the following
 117                will be used:
 118
 119                 <IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">
 120
 121                Note that %s stands for the filename part of the graph gener-
 122                ated, all directories given in the PNG file argument will get
 123                dropped.
 124
 125        RRD::PRINT _\bn_\bu_\bm_\bb_\be_\br
 126                If the preceding  R\bRR\bRD\bD:\b::\b:G\bGR\bRA\bAP\bPH\bH tag contained and P\bPR\bRI\bIN\bNT\bT arguments,
 127                then you can access their output with this tag. The _\bn_\bu_\bm_\bb_\be_\br
 128                argument refers to the number of the P\bPR\bRI\bIN\bNT\bT argument. This first
 129                P\bPR\bRI\bIN\bNT\bT has _\bn_\bu_\bm_\bb_\be_\br 0.
 130
 131        RRD::INTERNAL <var>
 132                This tag gets replaced by an internal var. Currently these vars
 133                are known: VERSION, COMPILETIME.  These vars represent the
 134                compiled-in values.
 135
 136 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 1\b1
 137        The example below creates a web pages with a single RRD graph.
 138
 139         #!/usr/local/bin/rrdcgi
 140         <HTML>
 141         <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
 142         <BODY>
 143         <H1>RRDCGI Example Page</H1>
 144         <P>
 145         <RRD::GRAPH demo.png --lazy --title="Temperatures"
 146                  DEF:cel=demo.rrd:exhaust:AVERAGE
 147                  LINE2:cel#00a000:"D. Celsius">
 148
 149         </P>
 150         </BODY>
 151         </HTML>
 152
 153 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 2\b2
 154        This script is slightly more elaborate, it allows you to run it from a
 155        form which sets RRD_NAME. RRD_NAME is then used to select which RRD you
 156        want to use as source for your graph.
 157
 158         #!/usr/local/bin/rrdcgi
 159         <HTML>
 160         <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
 161         <BODY>
 162         <H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
 163         <H2>Selection</H2>
 164         <FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
 165               <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
 166               <INPUT TYPE=SUBMIT></FORM>
 167         <H2>Graph</H2>
 168         <P>
 169         <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
 170                  --title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
 171                  DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
 172                  LINE2:cel#00a000:"D. Celsius">
 173
 174         </P>
 175         </BODY>
 176         </HTML>
 177
 178 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 3\b3
 179        This example shows how to handle the case where the RRD, graphs and
 180        cgi-bins are seperate directories
 181
 182         #!/.../bin/rrdcgi
 183         <HTML>
 184         <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
 185         <BODY>
 186         <H1>RRDCGI test Page</H1>
 187         <RRD::GRAPH
 188          /.../web/pngs/testhvt.png
 189          --imginfo '<IMG SRC=/.../pngs/%s WIDTH=%lu HEIGHT=%lu >'
 190          --lazy --start -1d --end now
 191          DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
 192          AREA:http_src#00ff00:http_src
 193         >
 194         </BODY>
 195         </HTML>
 196
 197        Note 1: Replace /.../ with the relevant directories
 198
 199        Note 2: The SRC=/.../pngs should be paths from the view of the web-
 200        server/browser
 201
 202 A\bAU\bUT\bTH\bHO\bOR\bR
 203        Tobias Oetiker <tobi@oetiker.ch>
 204
 205
 206
 207 1.2.27                            2008-02-17                         RRDCGI(1)