1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
=cut
TITLE=datapage.cgi
DESCRIPTION=displays web-pages with dynamic data in them
KEYWORDS=datapage.cgi
DOCTOP=index
DOCPREV=dataimage.cgi
DOCNEXT=log-event.cgi
=pod
=head1 datapage.cgi - dynamic data in web-pages
=head2 Usage:
<A HREF="@@HTMLURL@@/datapage.cgi?pagename">whatever</A>
=head2 Data Collection
C<Datapage.cgi> looks for the page definition in the file
C<@@DATAPAGEDIR@@/pagename.page> The page definition is in two parts,
separated by a line like:
BEGIN-PAGE
The first part's purpose is to define variables to be included in the
second part, which is an HTML template, with magic cookies.
All lines in the first or definition part are subject to variable interpolation.
Any ocurrance of C<${variablename}> will be replaced by the current
contents of the variable C<variablename>. This will be done up to
five levels, permitting expansion of ${${h}_${interface}}, providing that
you've got values for the variables C<h> and C<interface>.
N.B. variable names must be lower case.
In addition, within a macro expansion, macro-arguments will also be
interpolated, before variable interpolation, for all ocurrances of
C<${ARGNAME}>, assuming that there is an argument for the
current macro called C<ARGNAME>. N.B. macro argument names must
be UPPER case.
=head2 Common Commands
The commands permitted in the first part are:
oid, rrd, status, eval, debug, macro, macroend,
alertstatus, alertvalue and *EOD*
These commands are in common with the L<dataimage.cgi|dataimage-cgi>
script, but are only documented here.
=over 4
=item oid
This fetches an SNMP value into a datapage variable. The command looks like:
oid VARNAME HOSTNAME OIDNAME
The C<VARNAME> is the name of the datapage variable (let's just call
them variables from now on).
The C<HOSTNAME> is the name of the host
to query. The SNMP community-string is usually supplied in
that host's config-file, but can be supplied in usual MRTG fashion by
giving C<COMMUNITY@HOSTNAME> or even C<COMMUNITY@HOSTNAME:PORTNUMBER>
instead of the C<HOSTNAME>.
The C<OIDNAME> must be defined in the
L<oids config-file|configfile-oids>, but can be suffixed by the usual
numbers. E.G. you can use ifName.4 to get the ifName for interface 4.
=item rrd
This fetches a value from an RRD database into a variable. It looks like:
rrd VARNAME HOSTNAME RRDNAME DSNAME CF
The C<RRDNAME> is the name of the rrd, as remstats knows it, not fully
qualified. I.E. it will be under the config-file defined C<datadir>,
and under the host's directory under that.
The C<DSNAME> is the ds-name within that RRD file and the C<CF>
is the usual RRD consolidation-function to be applied.
=item status
This is so-named because it fetches remstats status files, usually written
by the various L<collectors> and L<monitors>. It looks like:
status VARNAME HOSTNAME STATUSNAME
The C<STATUSNAME> is the name of the status file, as named in the
host's data directory. There is a standard mapping applied by the
function C<to_filename> from the C<remstats.pl</t> file to
munge the filename so that it won't conflict with the filesystem. Either
look for the name in the data directory, use the function (see eval) or
look at the code. I B<am> planning on changing the mapping when I
figure out the best way to do it.
=item eval
The eval command lets you modify the values fetched by previous C<oid>,
C<rrd>, C<status> and C<eval> commands with arbitrary perl code.
It looks like:
eval VARNAME PERLEXPRESSION
The C<PERLEXPRESSION> is a perl expression and can be arbitrarily complex,
but gets messy quickly with the C<datapage.cgi> and perl both doing variable
interpolation.
Note: C<datapage.cgi> uses L<private.pl|private>, so you can include commonly
used functions here to make your datapage creation easier.
=item debug
The C<debug> command takes a number which is the level to set debugging to.
It causes extra output which may be helpful in figuring out why your page
isn't working the way you expected.
=item alertstatus
This lets you fetch the alert level for a given (host, rrd, dsname, cf)
combination. The command looks like:
alertstatus VARNAME HOSTNAME RRDNAME DSNAME [CF]
This will fetch the alert status and put it in the datapage variable C<VARNAME>.
The status will be the same set of values shown on the L<alerts report|alerts-cgi>
for status.
The C<CF> parameter is optional and is rrdtool's consolidation function.
It will be set to C<AVERAGE> if it's not supplied.
=item alertvalue
This is the same as C<alertstatus> except that it sets the variable to the
current value of the (host, rrd, variable, cf) combination.
=back 4
=head2 The HTML template
This is almost just HTML with a few magic cookies inserted. The difference is
that the beginning must include HTTP headers. If you don't want anything
fancy, just begin like:
------ cut here ------
BEGIN-PAGE
content-type: text/html
------ cut here ------
Note: the empty line after C<content-type:> is B<not> optional. It's
necessary to end the HTTP headers.
The magic cookies are:
=over 4
=item <DATAPAGE::STATUS host statusfile>
inserts a specified status file
=item <DATAPAGE::VAR varname>
interpolates the value of a datapage variable
=item <DATAPAGE::HEADER title>
generates a standard remstats header
=item <DATAPAGE::STATUSHEADER hostname>
generates the status headers for the named host
=item <DATAPAGE::TOOLBAR hostname>
generates the toolbar for the named host
=item <DATAPAGE::FOOTER>
generates a standard remstats footer
=item <DATAPAGE::INCLUDE filename>
include the contents of a file from the datapage directory, for imagemaps ...
=item <DATAPAGE::PATHINCLUDE filename-with-path>
include contents of a file specified with a complete path
=item <DATAPAGE::MACRO macroname [argvalue] ...>
include boilerplate HTML with substitutions
=item <DATAPAGE::GRAPH host rrd graph time>
generate the specified remstats graph
=item <DATAPAGE::CUSTOMGRAPH graph time>
generate the specified remstats customgraph
=item <DATAPAGE::ERRORS>
inserts the text of errors encountered in generating the page. Without
this one, you won't see any errors. That way you include the errors and
debugging output (see next item), which you're creating/debugging the
datapage and afterwards turn them off. The errors and debugging output
may include information you don't want to reveal to outsiders. Also,
collecting all the error output together avoids spoiling the formatting
of the page.
=item <DATAPAGE::DEBUG>
inserts debugging output. Without it, you won't see any debugging output.
=back 4
|
