Code

604bbcc0a59303266bdb396e90d7b753cbfc0d06
[pkg-rrdtool.git] / doc / rrdcgi.txt
1 RRDCGI(1)                           rrdtool                          RRDCGI(1)
5 N\bNA\bAM\bME\bE
6        rrdcgi - Create web pages containing RRD graphs based on templates
8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
9        "#!/path/to/"r\brr\brd\bdc\bcg\bgi\bi [-\b--\b-f\bfi\bil\blt\bte\ber\br]
11 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
12        r\brr\brd\bdc\bcg\bgi\bi is a sort of very limited script interpreter. Its purpose is to
13        run as a cgi-program and parse a web page template containing special
14        <RRD:: tags. r\brr\brd\bdc\bcg\bgi\bi will interpret and act according to these tags.  In
15        the end it will printout a web page including the necessary CGI head-
16        ers.
18        r\brr\brd\bdc\bcg\bgi\bi parses the contents of the template in 3 steps. In each step it
19        looks only for a subset of tags. This allows nesting of tags.
21        The argument parser uses the same semantics as you are used from your
22        C-shell.
24        -\b--\b-f\bfi\bil\blt\bte\ber\br
25                Assume that rrdcgi is run as a filter and not as a cgi.
27        K\bKe\bey\byw\bwo\bor\brd\bds\bs
30        RRD::CV _\bn_\ba_\bm_\be
31                Inserts the CGI variable of the given name.
33        RRD::CV::QUOTE _\bn_\ba_\bm_\be
34                Inserts the CGI variable of the given name but quotes it, ready
35                for use as an argument in another RRD:: tag. So even when there
36                are spaces in the value of the CGI variable it will still be
37                considered to be one argument.
39        RRD::CV::PATH _\bn_\ba_\bm_\be
40                Inserts the CGI variable of the given name, quotes it and makes
41                sure it starts neither with a '/' nor contains '..'. This is to
42                make sure that no problematic pathnames can be introduced
43                through the CGI interface.
45        RRD::GETENV _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be
46                Get the value of an environment variable.
48                 <RRD::GETENV REMOTE_USER>
50                might give you the name of the remote user given you are using
51                some sort of access control on the directory.
53        RRD::GOODFOR _\bs_\be_\bc_\bo_\bn_\bd_\bs
54                Specify the number of seconds this page should remain valid.
55                This will prompt the rrdcgi to output a Last-Modified, an
56                Expire and if the number of seconds is _\bn_\be_\bg_\ba_\bt_\bi_\bv_\be a Refresh
57                header.
59        RRD::INCLUDE _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
60                Include the contents of the specified file into the page
61                returned from the cgi.
63        RRD::SETENV _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\bv_\ba_\bl_\bu_\be
64                If you want to present your graphs in another time zone than
65                your own, you could use
67                 <RRD::SETENV TZ UTC>
69                to make sure everything is presented in Universal Time. Note
70                that the values permitted to TZ depend on your OS.
72        RRD::SETVAR _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\bv_\ba_\bl_\bu_\be
73                Analog to SETENV but for local variables.
75        RRD::GETVAR _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be
76                Analog to GETENV but for local variables.
78        RRD::TIME::LAST _\br_\br_\bd_\b-_\bf_\bi_\bl_\be _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt
79                This gets replaced by the last modification time of the
80                selected RRD. The time is _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be-formatted with the string
81                specified in the second argument.
83        RRD::TIME::NOW _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt
84                This gets replaced by the current time of day. The time is
85                _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be-formatted with the string specified in the argument.
87                Note that if you return : (colons) from your strftime format
88                you may have to escape them using \ if the time is to be used
89                as an argument to a GRAPH command.
91        RRD::TIME::STRFTIME _\bS_\bT_\bA_\bR_\bT_\b|_\bE_\bN_\bD _\bs_\bt_\ba_\br_\bt_\b-_\bs_\bp_\be_\bc _\be_\bn_\bd_\b-_\bs_\bp_\be_\bc _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt
92                This gets replaced by a strftime-formatted time using the for-
93                mat _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be_\b-_\bf_\bo_\br_\bm_\ba_\bt on either _\bs_\bt_\ba_\br_\bt_\b-_\bs_\bp_\be_\bc or _\be_\bn_\bd_\b-_\bs_\bp_\be_\bc depending
94                on whether _\bS_\bT_\bA_\bR_\bT or _\bE_\bN_\bD is specified.  Both _\bs_\bt_\ba_\br_\bt_\b-_\bs_\bp_\be_\bc and _\be_\bn_\bd_\b-
95                _\bs_\bp_\be_\bc must be supplied as either could be relative to the other.
96                This is intended to allow pretty titles on graphs with times
97                that are easier for non RRDtool folks to figure out than
98                "-2weeks".
100                Note that again, if you return : (colon) from your strftime
101                format, you may have to escape them using \ if the time is to
102                be used as an argument to a GRAPH command.
104        RRD::GRAPH _\br_\br_\bd_\bg_\br_\ba_\bp_\bh _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs
105                This tag creates the RRD graph defined by its argument and then
106                is replaced by an appropriate <IMG ... > tag referring to the
107                graph.  The -\b--\b-l\bla\baz\bzy\by option in RRD graph can be used to make sure
108                that graphs are only regenerated when they are out of date. The
109                arguments to the R\bRR\bRD\bD:\b::\b:G\bGR\bRA\bAP\bPH\bH tag work as described in the r\brr\brd\bd-\b-
110                g\bgr\bra\bap\bph\bh manual page.
112                Use the -\b--\b-l\bla\baz\bzy\by option in your RRD::GRAPH tags, to reduce the
113                load on your server. This option makes sure that graphs are
114                only regenerated when the old ones are out of date.
116                If you do not specify your own -\b--\b-i\bim\bmg\bgi\bin\bnf\bfo\bo format, the following
117                will be used:
119                 <IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">
121                Note that %s stands for the filename part of the graph gener-
122                ated, all directories given in the PNG file argument will get
123                dropped.
125        RRD::PRINT _\bn_\bu_\bm_\bb_\be_\br
126                If the preceding  R\bRR\bRD\bD:\b::\b:G\bGR\bRA\bAP\bPH\bH tag contained and P\bPR\bRI\bIN\bNT\bT arguments,
127                then you can access their output with this tag. The _\bn_\bu_\bm_\bb_\be_\br
128                argument refers to the number of the P\bPR\bRI\bIN\bNT\bT argument. This first
129                P\bPR\bRI\bIN\bNT\bT has _\bn_\bu_\bm_\bb_\be_\br 0.
131        RRD::INTERNAL <var>
132                This tag gets replaced by an internal var. Currently these vars
133                are known: VERSION, COMPILETIME.  These vars represent the
134                compiled-in values.
136 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 1\b1
137        The example below creates a web pages with a single RRD graph.
139         #!/usr/local/bin/rrdcgi
140         <HTML>
141         <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
142         <BODY>
143         <H1>RRDCGI Example Page</H1>
144         <P>
145         <RRD::GRAPH demo.png --lazy --title="Temperatures"
146                  DEF:cel=demo.rrd:exhaust:AVERAGE
147                  LINE2:cel#00a000:"D. Celsius">
149         </P>
150         </BODY>
151         </HTML>
153 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 2\b2
154        This script is slightly more elaborate, it allows you to run it from a
155        form which sets RRD_NAME. RRD_NAME is then used to select which RRD you
156        want to use as source for your graph.
158         #!/usr/local/bin/rrdcgi
159         <HTML>
160         <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
161         <BODY>
162         <H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
163         <H2>Selection</H2>
164         <FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
165               <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
166               <INPUT TYPE=SUBMIT></FORM>
167         <H2>Graph</H2>
168         <P>
169         <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
170                  --title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
171                  DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
172                  LINE2:cel#00a000:"D. Celsius">
174         </P>
175         </BODY>
176         </HTML>
178 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 3\b3
179        This example shows how to handle the case where the RRD, graphs and
180        cgi-bins are seperate directories
182         #!/.../bin/rrdcgi
183         <HTML>
184         <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
185         <BODY>
186         <H1>RRDCGI test Page</H1>
187         <RRD::GRAPH
188          /.../web/pngs/testhvt.png
189          --imginfo '<IMG SRC=/.../pngs/%s WIDTH=%lu HEIGHT=%lu >'
190          --lazy --start -1d --end now
191          DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
192          AREA:http_src#00ff00:http_src
193         >
194         </BODY>
195         </HTML>
197        Note 1: Replace /.../ with the relevant directories
199        Note 2: The SRC=/.../pngs should be paths from the view of the web-
200        server/browser
202 A\bAU\bUT\bTH\bHO\bOR\bR
203        Tobias Oetiker <tobi@oetiker.ch>
207 1.2.27                            2008-02-17                         RRDCGI(1)