torrus/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 # $Id: webintf.pod.in,v 1.1 2010-12-27 00:04:33 ivan Exp $
  19 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  20 #
  21 #
  22
  23 =head1 Torrus Web Interface Reference
  24
  25 B<Warning:> This documentation is relevant to Torrus version 1.0.9.
  26 It is incompatible with previous versions.
  27
  28 =head2 Directory structure
  29
  30 By default, the directory F<@webplaindir@/> is the place
  31 for static HTML, CSS stylesheets and images.
  32
  33 The default CSS stylesheet files are installed in this directory.
  34 This directory must be configured with I<SetHandler default-handler>
  35 directive.
  36
  37 =head2 CSS Stylesheets
  38
  39 Additional user-defined stylesheet files may be added in
  40 F<webplain> directory.
  41 The default HTML templates that come with the Torrus distribution use the
  42 global configuration variable C<$Torrus::Renderer::stylesheet>, which is set
  43 in F<torrus-config.pl> and may be overwritten in F<torrus-siteconfig.pl>.
  44
  45 =head2 Cache files
  46
  47 All generated HTML and graphical images are cached twice: first on the server,
  48 and then in your browser. Thus, if you change somehow the HTML
  49 appearance of your Torrus installation, you need to clean both caches:
  50
  51    torrus clearcache
  52
  53 This will clear the cache on the server. Then you may use your browser's
  54 "reload" button, or clear the whole browser cache.
  55
  56
  57 =head2 Site configuration options
  58
  59 The following variables may need to be set in your
  60 F<@siteconfdir@/torrus-siteconfig.pl> file:
  61
  62 =over 4
  63
  64 =item * C<$Torrus::Renderer::companyName>
  65
  66 The text that you specify here will appear in the top left corner
  67 of all HTML pages.
  68
  69 =item * C<$Torrus::Renderer::companyURL>
  70
  71 The company name text will be clickable with the URL specified in
  72 this variable.
  73
  74 =item * C<$Torrus::Renderer::rendererURL>
  75
  76 Default: C<'/torrus'>. A URL that points to Torrus renderer.
  77
  78 =item * C<$Torrus::Renderer::plainURL>
  79
  80 Default: C<'/torrus/plain'>. A URL that points to Torrus plain files directory.
  81 Normally CSS stylesheet files are resided there..
  82
  83 =item * C<$Torrus::CGI::authorizeUsers>
  84
  85 Default: C<1>. When true, the web interface users are required to log in.
  86
  87 =back
  88
  89
  90 =head2 mod_perl 1.0 handler: Torrus::ApacheHandler
  91
  92 For more documentation, see E<lt>http://perl.apache.org/E<gt>.
  93
  94 The whole output generation is performed by the C<Torrus::ApacheHandler> class.
  95 However, you still need access to the F<plain> directory where your CSS
  96 resides. Typical Apache configuration would look like follows. Make sure
  97 your configuration does not contain tab characters:
  98
  99   PerlRequire "@cfgdefdir@/webmux.pl"
 100   <Location /torrus>
 101     SetHandler perl-script
 102     PerlHandler Torrus::ApacheHandler
 103   </Location>
 104
 105 The base URL would be in this case:
 106
 107   http://yourhost/torrus/
 108
 109
 110 =head2 mod_perl 2.0 handler: Torrus::Apache2Handler
 111
 112 I<Note:> Apache 2.0 support in Torrus is currently in its early
 113 development stage.
 114
 115 I<Note:> As of now, C<libapreq2> library is not released yet, and only the
 116 development version is available. You have to download and install it
 117 manually.
 118
 119 mod_perl version B<1.99_15> or later is supported. To the moment,
 120 C<libapreq2> version C<2.04_03-dev> is tested.
 121
 122 Make sure you use C<webmux2.pl> and C<Torrus::Apache2Handler> in your
 123 configuration.
 124
 125 C<SetHandler modperl> directive should give better performance
 126 than C<SetHandler perl-script>. Both Perl handlers work the same way
 127 with Torrus.
 128
 129 Typical Apache 2.0 configuration follows:
 130
 131   PerlRequire "@cfgdefdir@/webmux2.pl"
 132   <Location /torrus>
 133     SetHandler perl-script
 134     PerlResponseHandler Torrus::Apache2Handler
 135   </Location>
 136
 137 The base URL would be in this case:
 138
 139   http://yourhost/torrus/
 140
 141
 142 =head2 lighttpd with FastCGI handler
 143
 144 As of version 1.0.9, Torrus supports FastCGI server module. It is also often
 145 used together with B<lighttpd> HTTP server.
 146
 147 Install FastCGI on your server, and also F<FCGI> module from CPAN.
 148
 149 Add user "lighttpd" to group "torrus".
 150
 151 The following configuration creates a virtual host, so that any URL which
 152 starts with "tor" would result in Torrus display:
 153
 154   # Uncomment mod_redirect and mod_fastcgi. Other modules might be needed too.
 155   server.modules              = (
 156                                   "mod_redirect",
 157                                   "mod_fastcgi",
 158                                 )
 159   # virtual server configuration
 160   $HTTP["host"] =~ "^tor" {
 161     url.redirect = ( "^/$" => "/torrus" )
 162     fastcgi.server = (
 163             "/torrus" => (
 164                 "Torrus" => (
 165                     "socket"       => "/tmp/Torrus_FCGI.socket",
 166                     "check-local"  => "disable",
 167                     "bin-path"     => "@pkgbindir@/torrus.fcgi",
 168                     "max-procs"    => 2,
 169                 )
 170             )
 171         )
 172   }
 173
 174
 175 =head2 Apache 2.0.x with FastCGI handler
 176
 177 As of version 1.0.9, Torrus supports the FastCGI server module.
 178 It is also often used together with B<Apache 2.x> HTTP server.
 179
 180 The following is an example of a virtual host with four FastCGI child processes
 181
 182
 183     <VirtualHost *:80>
 184      DocumentRoot "/var/www/vhosts/test01.torrus.net"
 185      ServerName test01.torrus.net
 186      AddHandler fastcgi-script fcgi
 187      FastCgiServer   @pkgbindir@/torrus.fcgi \
 188         -processes 4
 189      ScriptAlias /torrus "@pkgbindir@/torrus.fcgi"
 190     <Location /torrus>
 191         Order           Allow,Deny
 192         Allow           from all
 193     </Location>
 194     </VirtualHost>
 195
 196
 197
 198 =head2 Known CGI parameters
 199
 200 The following CGI parameters are recognized by mod_perl handler:
 201
 202 =over 4
 203
 204 =item token
 205
 206 Optional. Each configuration tree element is referenced by a I<token>, a short
 207 unique identifier. If not given, the root of the tree (C</>) is displayed.
 208
 209 =item path
 210
 211 Optional. Alternatively to token reference, the full path of the tree element
 212 may be referenced.
 213
 214 =item nodeid
 215
 216 Optional. A subtree which has a unique I<nodeid> can be referred
 217 with this parameter.
 218
 219 =item view
 220
 221 Optional. Specifies the C<view> name for displaying the tree element.
 222 If not specified, the defaul view is used.
 223
 224 =item v
 225
 226 Optional. Synonym for C<view> parameter.
 227
 228
 229 =item hostauth
 230
 231 Mandatory for host-based authentication. The value is treated as a password
 232 and the user name is the client's IP address with non-alphanumerics
 233 replaced with underscores.
 234
 235
 236 =item TZ
 237
 238 Optional. If given, specifies the timezone that you want the graphs to be
 239 displayed for. This must be the URL-encoded zone name which is understood by
 240 your server system. You may use zdump(8) for testing.
 241
 242 =item NOW
 243
 244 Optional. If given, presents the output for the given moment, instead of the
 245 current time. Must be of the form understood by C<rrdtool> (see
 246 RRDTool manuals).
 247
 248 =item Gstart, Gend, Gwidth, Gheight
 249
 250 Optional vaiables that override the ones defined in the view.
 251
 252 =item DEBUG
 253
 254 Optional. If true, turns on the debug level of logging. The debug messages
 255 are sent to HTTP server's error log.
 256
 257 =item SHOWHIDDEN
 258
 259 Optional. If true, makes the grapher display those subtree and leaves
 260 which have C<hidden> parameter set to C<yes>.
 261
 262 =item NOHW
 263
 264 Optional. If true, disables the displaying of Holt-Winters
 265 boundaries and failures.
 266
 267 =item LOGOUT
 268
 269 Optional. When user authorization is enabled, causes the current user
 270 session to log out.
 271
 272 =back
 273
 274 All other parameters whose name starts with capital letter, are passed
 275 to the HTML template as-is, and may be used for your custom purposes.
 276
 277
 278 =head1 Author
 279
 280 Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>