


     RRRRRRRRDDDDCCCCGGGGIIII((((1111))))              1111....2222....11113333 ((((2222000000006666----00005555----00004444))))              RRRRRRRRDDDDCCCCGGGGIIII((((111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 [--------ffffiiiilllltttteeeer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 3 steps. In
          each step it looks only for a subset of tags. This allows
          nesting of 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 run as a filter and not as a
                  cgi.

          KKKKeeeeyyyywwwwoooorrrrddddssss

          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 to be one argument.

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

          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



     Page 1                                          (printed 6/13/06)






     RRRRRRRRDDDDCCCCGGGGIIII((((1111))))              1111....2222....11113333 ((((2222000000006666----00005555----00004444))))              RRRRRRRRDDDDCCCCGGGGIIII((((1111))))



                  directory.

          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 header.

          RRD::INCLUDE _f_i_l_e_n_a_m_e
                  Include the contents of the specified 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::SETVAR _v_a_r_i_a_b_l_e _v_a_l_u_e
                  Analog to SETENV but for local variables.

          RRD::GETVAR _v_a_r_i_a_b_l_e
                  Analog to GETENV but for local variables.

          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-formatted
                  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-formatted with the string specified
                  in the argument.

                  Note that if you return : (colons) from your
                  strftime format you may have to escape them using \
                  if the time is to be used as an argument to a GRAPH
                  command.

          RRD::TIME::STRFTIME _S_T_A_R_T|_E_N_D _s_t_a_r_t-_s_p_e_c _e_n_d-_s_p_e_c _s_t_r_f_t_i_m_e-
                  _f_o_r_m_a_t
                  This gets replaced by a strftime-formatted time
                  using the format _s_t_r_f_t_i_m_e-_f_o_r_m_a_t on either _s_t_a_r_t-
                  _s_p_e_c or _e_n_d-_s_p_e_c depending on whether _S_T_A_R_T or _E_N_D
                  is specified.  Both _s_t_a_r_t-_s_p_e_c and _e_n_d-_s_p_e_c must be
                  supplied as either could be relative to the other.
                  This is intended to allow pretty titles on graphs
                  with times that are easier for non RRDtool folks to



     Page 2                                          (printed 6/13/06)






     RRRRRRRRDDDDCCCCGGGGIIII((((1111))))              1111....2222....11113333 ((((2222000000006666----00005555----00004444))))              RRRRRRRRDDDDCCCCGGGGIIII((((1111))))



                  figure out than "-2weeks".

                  Note that again, if you return : (colon) from your
                  strftime format, you may have to escape them using \
                  if the time is to be used as an argument to a GRAPH
                  command.

          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 by its
                  argument and then is 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.

                  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 PNG
                  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.

          RRD::INTERNAL <var>
                  This tag gets replaced by an internal var. Currently
                  these vars are known:  VERSION, COMPILETIME.  These
                  vars represent the compiled-in values.

     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.










     Page 3                                          (printed 6/13/06)






     RRRRRRRRDDDDCCCCGGGGIIII((((1111))))              1111....2222....11113333 ((((2222000000006666----00005555----00004444))))              RRRRRRRRDDDDCCCCGGGGIIII((((1111))))



           #!/usr/local/bin/rrdcgi
           <HTML>
           <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
           <BODY>
           <H1>RRDCGI Example Page</H1>
           <P>
           <RRD::GRAPH demo.png --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 as source for your graph.

           #!/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>.png --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













     Page 4                                          (printed 6/13/06)






     RRRRRRRRDDDDCCCCGGGGIIII((((1111))))              1111....2222....11113333 ((((2222000000006666----00005555----00004444))))              RRRRRRRRDDDDCCCCGGGGIIII((((1111))))



           #!/.../bin/rrdcgi
           <HTML>
           <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
           <BODY>
           <H1>RRDCGI test Page</H1>
           <RRD::GRAPH
            /.../web/pngs/testhvt.png
            --imginfo '<IMG SRC=/.../pngs/%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=/.../pngs 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 <tobi@oetiker.ch>

































     Page 5                                          (printed 6/13/06)



