


rrdtool                                                 RRDCGI(1)



NNNNAAAAMMMMEEEE
     rrdcgi - create web pages containing RRD graphs based on
     templates

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #!/path/to/rrrrrrrrddddccccggggiiii [--------ggggooooooooddddffffoooorrrr|----gggg _s_e_c_o_n_d_s] [--------ffffiiiilllltttteeeerrrr]
     [--------rrrreeeeffffrrrreeeesssshhhh|----rrrr]

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     rrrrrrrrddddccccggggiiii 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. rrrrrrrrddddccccggggiiii will
     interpret and act according to these tags.  In the end it
     will printout a web page including the necessary CGI
     headers.

     rrrrrrrrddddccccggggiiii 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.

     --------ffffiiiilllltttteeeerrrr
             Assume that rrdcgi is being run as a filter and not
             as a cgi.

     --------rrrreeeeffffrrrreeeesssshhhh|----rrrr
             If the --------ggggooooooooddddffffoooorrrr flag is specified, then --------rrrreeeeffffrrrreeeesssshhhh
             will cause rrdcgi to output a Refresh header with
             the value of the --------ggggooooooooddddffffoooorrrr value.

     PPPPaaaassssssss 1111

     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

     PPPPaaaassssssss 2222

     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.

     PPPPaaaassssssss 3333

     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 --------llllaaaazzzzyyyy 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 RRRRRRRRDDDD::::::::GGGGRRRRAAAAPPPPHHHH tag work as described in
             the rrrrrrrrddddggggrrrraaaapppphhhh manual page.




2001-02-20             Last change: 1.0.33                      2






rrdtool                                                 RRDCGI(1)



             Use the --------llllaaaazzzzyyyy 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 --------iiiimmmmggggiiiinnnnffffoooo 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  RRRRRRRRDDDD::::::::GGGGRRRRAAAAPPPPHHHH tag contained and PPPPRRRRIIIINNNNTTTT
             arguments, then you can access their output with
             this tag. The _n_u_m_b_e_r argument refers to the number
             of the PPPPRRRRIIIINNNNTTTT argument. This first PPPPRRRRIIIINNNNTTTT has _n_u_m_b_e_r
             0.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE 1111
     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>


EEEEXXXXAAAAMMMMPPPPLLLLEEEE 2222
     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>


EEEEXXXXAAAAMMMMPPPPLLLLEEEE 3333
     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

AAAAUUUUTTTTHHHHOOOORRRR
     Tobias Oetiker <oetiker@ee.ethz.ch>








2001-02-20             Last change: 1.0.33                      4



