RRDCGI(1)                           rrdtool                          RRDCGI(1)



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

SSYYNNOOPPSSIISS
       #!/path/to/rrrrddccggii [----ffiilltteerr]

DDEESSCCRRIIPPTTIIOONN
       rrrrddccggii 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. rrrrddccggii will interpret and act according to these tags.  In
       the end it will printout a web page including the necessary CGI head-
       ers.

       rrrrddccggii parses the contents of the template in 3 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.

       PPaassss 11


       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.

       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

       PPaassss 22


       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 head-
               ers.

       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.

       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 for-
               mat _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 figure out than
               "-2weeks".

       PPaassss 33


       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 ----llaazzyy 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 RRRRDD::::GGRRAAPPHH tag work as described in the rrrrdd--
               ggrraapphh manual page.

               Use the ----llaazzyy 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 ----iimmggiinnffoo format, the following
               will be used:

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

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

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

EEXXAAMMPPLLEE 11
       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>

EEXXAAMMPPLLEE 22
       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.

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

EEXXAAMMPPLLEE 33
       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 web-
       server/browser

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



1.0.45                            2003-05-21                         RRDCGI(1)
