


RRDCGI(1)                    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 head-
       ers.

       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 consid-
               ered 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.



2000-03-26                    1.0.25                            1





RRDCGI(1)                    rrdtool                    RRDCGI(1)


                <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 out-
               put 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 speci-
               fied 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.

               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



2000-03-26                    1.0.25                            2





RRDCGI(1)                    rrdtool                    RRDCGI(1)


               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.















2000-03-26                    1.0.25                            3





RRDCGI(1)                    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>










2000-03-26                    1.0.25                            4


