src/doc/webintf.pod.in

   1 #  webintf.pod - Torrus web interface reference
   2 #  Copyright (C) 2002  Stanislav Sinyagin
   3 #
   4 #  This program is free software; you can redistribute it and/or modify
   5 #  it under the terms of the GNU General Public License as published by
   6 #  the Free Software Foundation; either version 2 of the License, or
   7 #  (at your option) any later version.
   8 #
   9 #  This program is distributed in the hope that it will be useful,
  10 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 #  GNU General Public License for more details.
  13 #
  14 #  You should have received a copy of the GNU General Public License
  15 #  along with this program; if not, write to the Free Software
  16 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17
  18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  19 #
  20 #
  21
  22 =head1 Torrus Web Interface Reference
  23
  24 B<Warning:> This documentation is relevant to Torrus version 1.0.9.
  25 It is incompatible with previous versions.
  26
  27
  28 =head2 HTTP Server configuration
  29
  30 Torrus WebUI supports mod_perl and FastCGI as server engines. FastCGI was
  31 introduced in Torrus version 1.0.9, and it is the preferred way of setting up
  32 Torrus user interface.
  33
  34
  35 =head3 lighttpd with FastCGI handler
  36
  37 Install FastCGI on your server, and also F<FCGI> Perl module from CPAN.
  38
  39 Add user "lighttpd" to group "torrus" (this depends on the user name that is
  40 used for lighttpd in your OS).
  41
  42 The following configuration creates a virtual host, so that any URL which
  43 starts with "tor" would result in Torrus display:
  44
  45   # Uncomment mod_redirect and mod_fastcgi. Other modules might be needed too.
  46   server.modules              = (
  47                                   "mod_redirect",
  48                                   "mod_fastcgi",
  49                                 )
  50   # virtual server configuration
  51   $HTTP["host"] =~ "^tor" {
  52     url.redirect = ( "^/$" => "/torrus" )
  53     fastcgi.server = (
  54             "/torrus" => (
  55                 "Torrus" => (
  56                     "socket"       => "/tmp/Torrus_FCGI.socket",
  57                     "check-local"  => "disable",
  58                     "bin-path"     => "@pkgbindir@/torrus.fcgi",
  59                     "max-procs"    => 2,
  60                 )
  61             )
  62         )
  63   }
  64
  65
  66
  67
  68 =head3 Apache 2.0.x with FastCGI handler
  69
  70 As of version 1.0.9, Torrus supports the FastCGI server module.
  71 It is also often used together with B<Apache 2.x> HTTP server.
  72
  73 The following is an example of a virtual host with four FastCGI child processes
  74
  75
  76     <VirtualHost *:80>
  77      DocumentRoot "/var/www/vhosts/test01.torrus.net"
  78      ServerName test01.torrus.net
  79      AddHandler fastcgi-script fcgi
  80      FastCgiServer   @pkgbindir@/torrus.fcgi \
  81         -processes 4
  82      ScriptAlias /torrus "@pkgbindir@/torrus.fcgi"
  83     <Location /torrus>
  84         Order           Allow,Deny
  85         Allow           from all
  86     </Location>
  87     </VirtualHost>
  88
  89
  90
  91
  92 =head3 mod_perl 1.0 handler: Torrus::ApacheHandler
  93
  94 For more documentation, see E<lt>http://perl.apache.org/E<gt>.
  95
  96 The whole output generation is performed by the C<Torrus::ApacheHandler> class.
  97 However, you still need access to the F<plain> directory where your CSS
  98 resides. Typical Apache configuration would look like follows. Make sure
  99 your configuration does not contain tab characters:
 100
 101   PerlRequire "@cfgdefdir@/webmux.pl"
 102   <Location /torrus>
 103     SetHandler perl-script
 104     PerlHandler Torrus::ApacheHandler
 105   </Location>
 106
 107
 108
 109
 110
 111 =head3 mod_perl 2.0 handler: Torrus::Apache2Handler
 112
 113 Make sure you use C<webmux2.pl> and C<Torrus::Apache2Handler> in your
 114 configuration.
 115
 116 C<SetHandler modperl> directive should give better performance
 117 than C<SetHandler perl-script>. Both Perl handlers work the same way
 118 with Torrus.
 119
 120 Typical Apache 2.0 configuration follows:
 121
 122   PerlRequire "@cfgdefdir@/webmux2.pl"
 123   <Location /torrus>
 124     SetHandler perl-script
 125     PerlResponseHandler Torrus::Apache2Handler
 126   </Location>
 127
 128
 129
 130
 131 =head2 CSS Stylesheets
 132
 133 Additional user-defined stylesheet files may be used with Torrus WebUI.
 134 The global configuration variable C<%Torrus::Renderer::styling> defines the
 135 stylesheets for various output media ('default', 'printer' for
 136 printer-friendly output, and 'report' for monthly traffic HTML reports).
 137
 138 By editing F<torrus-siteconfig.pl>, additional stylesheets can be added as
 139 C<cssoverlay> values. An absolute URI pointing to the additional CSS file
 140 is required, for example:
 141
 142   $Torrus::Renderer::styling{'default'}{'cssoverlay'} = '/mystyle.css';
 143
 144 =head2 Cache files
 145
 146 All generated HTML and graphical images are cached twice: first on the server,
 147 and then in your browser. Thus, if you change somehow the HTML
 148 appearance of your Torrus installation, you need to clean both caches. The
 149 command C<torrus clearcache> would clean the Torrus cache. In addition, you
 150 may need to clean your browser's cache.
 151
 152
 153 =head2 Site configuration options
 154
 155 The following variables can be set in your
 156 F<@siteconfdir@/torrus-siteconfig.pl> file:
 157
 158 =over 4
 159
 160 =item * C<$Torrus::Renderer::companyName>
 161
 162 The text that you specify here will appear in the top left corner
 163 of all HTML pages.
 164
 165 =item * C<$Torrus::Renderer::companyURL>
 166
 167 The company name text will be clickable with the URL specified in
 168 this variable.
 169
 170 =item * C<$Torrus::Renderer::rendererURL>
 171
 172 Default: C<'/torrus'>. A URL that points to Torrus renderer.
 173
 174 =item * C<$Torrus::Renderer::plainURL>
 175
 176 Default: C<'/torrus/plain'>. A URL that points to Torrus plain files directory.
 177 Normally CSS stylesheet files are resided there.
 178
 179 =item * C<$Torrus::CGI::authorizeUsers>
 180
 181 Default: C<1>. When true, the web interface users are required to log in.
 182
 183 =back
 184
 185
 186
 187
 188 =head2 Known CGI parameters
 189
 190 The following CGI parameters are recognized by mod_perl handler:
 191
 192 =over 4
 193
 194 =item token
 195
 196 Optional. Each configuration tree element is referenced by a I<token>, a short
 197 unique identifier. If not given, the root of the tree (C</>) is displayed.
 198
 199 =item path
 200
 201 Optional. Alternatively to token reference, the full path of the tree element
 202 may be referenced.
 203
 204 =item nodeid
 205
 206 Optional. A subtree which has a unique I<nodeid> can be referred
 207 with this parameter.
 208
 209 =item view
 210
 211 Optional. Specifies the C<view> name for displaying the tree element.
 212 If not specified, the defaul view is used.
 213
 214 =item v
 215
 216 Optional. Synonym for C<view> parameter.
 217
 218
 219 =item hostauth
 220
 221 Mandatory for host-based authentication. The value is treated as a password
 222 and the user name is the client's IP address with non-alphanumerics
 223 replaced with underscores.
 224
 225
 226 =item TZ
 227
 228 Optional. If given, specifies the timezone that you want the graphs to be
 229 displayed for. This must be the URL-encoded zone name which is understood by
 230 your server system. You may use zdump(8) for testing.
 231
 232 =item NOW
 233
 234 Optional. If given, presents the output for the given moment, instead of the
 235 current time. Must be of the form understood by C<rrdtool> (see
 236 RRDTool manuals).
 237
 238 =item Gstart, Gend, Gwidth, Gheight, Gimgformat
 239
 240 Optional vaiables that override the ones defined in the view.
 241
 242 =item Gmaxline
 243
 244 If set to a true value, the renderer tries to draw the maximum value
 245 alongside with the average. The aggregation period is 1 day unless
 246 specified by C<Gmaxlinestep>. Single-line graphs are all displayed
 247 immediately with the maximum line. Multigraphs require
 248 C<maxline-style-X> and C<maxline-color-X> parameters to be defined in
 249 order for the maximum line to be properly displayed.
 250
 251 =item Gmaxlinestep
 252
 253 Aggregation period, in seconds, for the maximum line. If the variable is
 254 not specified, the line displays daily maximums.
 255
 256 =item DEBUG
 257
 258 Optional. If true, turns on the debug level of logging. The debug messages
 259 are sent to HTTP server's error log.
 260
 261 =item SHOWHIDDEN
 262
 263 Optional. If true, makes the grapher display those subtree and leaves
 264 which have C<hidden> parameter set to C<yes>.
 265
 266 =item NOHW
 267
 268 Optional. If true, disables the displaying of Holt-Winters
 269 boundaries and failures.
 270
 271 =item LOGOUT
 272
 273 Optional. When user authorization is enabled, causes the current user
 274 session to log out.
 275
 276 =back
 277
 278 All other parameters whose name starts with capital letter, are passed
 279 to the HTML template as-is, and may be used for your custom purposes.
 280
 281
 282 =head2 RPC interface
 283
 284 The RPC interface is designed for external systems to retrieve Torrus
 285 data. The RPC calls are done via URL parameters, and the returned data
 286 is in JSON format.
 287
 288 The resulting data size cannot exceed the security limit (by default,
 289 100 items).
 290
 291 The view C<rpc> is responsible for returning RPC data. The following CGI
 292 parameters are recognized:
 293
 294 =over 4
 295
 296 =item * RPCCALL
 297
 298 The RPC call to execute. This is a mandatory parameter. Below see the
 299 list of supported values.
 300
 301 =item * GET_PARAMS
 302
 303 Optional comma-separated list of datasource leaf parameters that are
 304 going to be retrieved from the configuration
 305 tree. C<@Torrus::Renderer::RPC::default_leaf_params> in
 306 F<torrus-config.pl> defines the list of parameters that are always
 307 queried, and GET_PATAMS would add parameter names to that list. Several
 308 parameter names, such as I<snmp-community>, are blacklisted because of
 309 security concern.
 310
 311 =item * PRETTY
 312
 313 Optional. If set to 1, the resulting JSON data is sorted and formatted
 314 for human reading.
 315
 316 =back
 317
 318
 319 The following RPC calls are supported:
 320
 321 =over 4
 322
 323 =item * WALK_LEAVES
 324
 325 This RPC call walks down the tree from the node specified by the URL,
 326 and returns all the leaves with their respective parameters.  In
 327 addition to parameters, the entry C<path> presents the path information
 328 in the datasource tree.
 329
 330 =item * AGGREGATE_DS
 331
 332 This RPC call is applicable to any datasource leaf with "leaf-type" set
 333 to "rrd-def". It fetches the average and maximum values for a given
 334 period. The URL parameters C<Gstart> and C<Gend> are used to define the
 335 time interval. Returned data is a map of the following keys and values:
 336
 337 =over 8
 338
 339 =item * START, END
 340
 341 Unix timestamps of the calculated time interval.
 342
 343 =item * AVG, MAX
 344
 345 Average and maximum values calculated for the given interval.
 346
 347 =item * AVAIL
 348
 349 Percentage of time for which the data is not NaN. Accuracy of this
 350 value depends on the time interval and RRA's being used to produce
 351 the value. Consolidated RRA's may already screen out some unavailable
 352 data samples.
 353
 354 =back
 355
 356 =item * SEARCH_NODEID
 357
 358 This RPC call performs a prefix search for I<nodeid> values among all
 359 leaves in the tree. The prefix string is expected in C<PREFIX> CGI
 360 argument. The call returns the same data format as WALK_LEAVES.
 361
 362 =back
 363
 364
 365 The return data is a JSON map with the following keys:
 366
 367 =over 4
 368
 369 =item * success
 370
 371 If the value is nonzero, the RPC call was successful.
 372
 373 =item * error
 374
 375 In case of a failure, this value returns athe error string.
 376
 377 =item * data
 378
 379 This is a map of objects, with datasource tokens as keys. Each object
 380 represents the data as specified by the RPC call.
 381
 382 =back
 383
 384
 385
 386
 387
 388 =head1 Author
 389
 390 Copyright (c) 2002-2011 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>