


rrdtool                                                 RRDCGI(1)



NNNNAAAAMMMMEEEE
     rrdcgi - create web pages containing RRD graphs based on
     templates

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #!/path/to/rrrrrrrrddddccccggggiiii [--------ggggooooooooddddffffoooorrrr|----gggg _s_e_c_o_n_d_s] [--------ffffiiiilllltttteeeerrrr]
     [--------rrrreeeeffffrrrreeeesssshhhh|----rrrr]

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     rrrrrrrrddddccccggggiiii is a sort of very limited script interpreter. Its
     purpose is to run as a cgi-program and parse a web page
     template containing special <RRD:: tags. rrrrrrrrddddccccggggiiii will
     interpret and act according to these tags.  In the end it
     will printout a web page including the necessary CGI
     headers.

     rrrrrrrrddddccccggggiiii parses the contents of the template in 2 steps. In
     each step it looks only for a subset of tags. This allows to
     nest tags.

     The argument parser uses the same semantics as you are used
     from your c shell.

     --------ffffiiiilllltttteeeerrrr
             Assume that rrdcgi is being run as a filter and not
             as a cgi.

     --------rrrreeeeffffrrrreeeesssshhhh|----rrrr
             If the --------ggggooooooooddddffffoooorrrr flag is specified, then --------rrrreeeeffffrrrreeeesssshhhh
             will cause rrdcgi to output a Refresh header with
             the value of the --------ggggooooooooddddffffoooorrrr value.

     PPPPaaaassssssss 1111

     RRD::CV _n_a_m_e
             Inserts the CGI variable of the given name.

     RRD::CV::QUOTE _n_a_m_e
             Inserts the CGI variable of the given name but
             quotes it, ready for use as an argument in another
             RRD:: tag. So even when there are spaces in the
             value of the CGI variable it will still be
             considered as one argument.

     RRD::CV::PATH _n_a_m_e
             Inserts the CGI variable of the given name, quotes
             it and makes sure the it starts neither with a '/'
             nor contains '..'. This is to make sure that no
             problematic pathnames can be introduced through the
             CGI interface.





2001-02-20             Last change: 1.0.33                      1






rrdtool                                                 RRDCGI(1)



     RRD::GETENV _v_a_r_i_a_b_l_e
             Get the value of an environment variable.

              <RRD::GETENV REMOTE_USER>

             might give you the name of the remote user given you
             are using some sort of access control on the
             directory

     PPPPaaaassssssss 2222

     RRD::GOODFOR _s_e_c_o_n_d_s
             Specify the number of seconds this page should
             remain valid. This will prompt the rrdcgi to output
             a Last-Modified, an Expire and if the number of
             seconds is _n_e_g_a_t_i_v_e a Refresh headers.

     RRD::INCLUDE _f_i_l_e_n_a_m_e
             Include the contents of the given file into the page
             returned from the cgi

     RRD::SETENV _v_a_r_i_a_b_l_e _v_a_l_u_e
             If you want to present your graphs in another time
             zone than your own, you could use

              <RRD::SETENV TZ UTC>

             to make sure everything is presented in Universal
             Time. Note that the values permitted to TZ depend on
             your OS.

     RRD::TIME::LAST _r_r_d_-_f_i_l_e _s_t_r_f_t_i_m_e_-_f_o_r_m_a_t
             This gets replaced by the last modification time of
             the selected RRD. The time is _s_t_r_f_t_i_m_e-formated with
             the string specified in the second argument.

     RRD::TIME::NOW _s_t_r_f_t_i_m_e_-_f_o_r_m_a_t
             This gets replaced by the current time of day. The
             time is _s_t_r_f_t_i_m_e-formated with the string specified
             in the argument.

     PPPPaaaassssssss 3333

     RRD::GRAPH _r_r_d_g_r_a_p_h _a_r_g_u_m_e_n_t_s
             This tag creates the RRD graph defined in its
             argument and then gets replaced by an appropriate
             <IMG> tag referring to the graph.  The --------llllaaaazzzzyyyy option
             in RRD graph can be used to make sure that graphs
             are only regenerated when they are out of date. The
             arguments to the RRRRRRRRDDDD::::::::GGGGRRRRAAAAPPPPHHHH tag work as described in
             the rrrrrrrrddddggggrrrraaaapppphhhh manual page.




2001-02-20             Last change: 1.0.33                      2






rrdtool                                                 RRDCGI(1)



             Use the --------llllaaaazzzzyyyy option in your RRD::GRAPH tags, to
             reduce the load on your server. This option makes
             sure that graphs are only regenerated when the old
             ones are out of date.

             If you do not specify your own --------iiiimmmmggggiiiinnnnffffoooo format, the
             following will be used:

              <IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">

             Note that %s stands for the filename part of the
             graph generated, all directories given in the GIF
             file argument will get dropped.

     RRD::PRINT _n_u_m_b_e_r
             If the preceding  RRRRRRRRDDDD::::::::GGGGRRRRAAAAPPPPHHHH tag contained and PPPPRRRRIIIINNNNTTTT
             arguments, then you can access their output with
             this tag. The _n_u_m_b_e_r argument refers to the number
             of the PPPPRRRRIIIINNNNTTTT argument. This first PPPPRRRRIIIINNNNTTTT has _n_u_m_b_e_r
             0.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE 1111
     The example below creates a web pages with a single RRD
     graph.

      #!/usr/local/bin/rrdcgi
      <HTML>
      <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
      <BODY>
      <H1>RRDCGI Example Page</H1>
      <P>
      <RRD::GRAPH demo.gif --lazy --title="Temperatures"
               DEF:cel=demo.rrd:exhaust:AVERAGE
               LINE2:cel#00a000:"D. Celsius">

      </P>
      </BODY>
      </HTML>


EEEEXXXXAAAAMMMMPPPPLLLLEEEE 2222
     This script is slightly more elaborate, it allows you to run
     it from a form which sets RRD_NAME. RRD_NAME is then used to
     select which RRD you want to use a source for your graph.











2001-02-20             Last change: 1.0.33                      3






rrdtool                                                 RRDCGI(1)



      #!/usr/local/bin/rrdcgi
      <HTML>
      <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
      <BODY>
      <H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
      <H2>Selection</H2>
      <FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
            <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
            <INPUT TYPE=SUBMIT></FORM>
      <H2>Graph</H2>
      <P>
      <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.gif --lazy
               --title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
               DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
               LINE2:cel#00a000:"D. Celsius">

      </P>
      </BODY>
      </HTML>


EEEEXXXXAAAAMMMMPPPPLLLLEEEE 3333
     This example shows how to handle the case where the RRD,
     graphs and cgi-bins are seperate directories

      #!/.../bin/rrdcgi
      <HTML>
      <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
      <BODY>
      <H1>RRDCGI test Page</H1>
      <RRD::GRAPH
       /.../web/gifs/testhvt.gif
       --imginfo '<IMG SRC=/.../gifs/%s WIDTH=%lu HEIGHT=%lu >'
       --lazy --start -1d --end now
       DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
       AREA:http_src#00ff00:http_src
      >
      </BODY>
      </HTML>

     Note 1: Replace /.../ with the relevant directories

     Note 2: The SRC=/.../gifs should be paths from the view of
     the webserver/browser

AAAAUUUUTTTTHHHHOOOORRRR
     Tobias Oetiker <oetiker@ee.ethz.ch>








2001-02-20             Last change: 1.0.33                      4



