1 # webintf.pod - Torrus web interface reference
2 # Copyright (C) 2002 Stanislav Sinyagin
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.
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.
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.
18 # $Id: webintf.pod.in,v 1.1 2010-12-27 00:04:33 ivan Exp $
19 # Stanislav Sinyagin <ssinyagin@yahoo.com>
23 =head1 Torrus Web Interface Reference
25 B<Warning:> This documentation is relevant to Torrus version 1.0.9.
26 It is incompatible with previous versions.
28 =head2 Directory structure
30 By default, the directory F<@webplaindir@/> is the place
31 for static HTML, CSS stylesheets and images.
33 The default CSS stylesheet files are installed in this directory.
34 This directory must be configured with I<SetHandler default-handler>
37 =head2 CSS Stylesheets
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>.
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:
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.
57 =head2 Site configuration options
59 The following variables may need to be set in your
60 F<@siteconfdir@/torrus-siteconfig.pl> file:
64 =item * C<$Torrus::Renderer::companyName>
66 The text that you specify here will appear in the top left corner
69 =item * C<$Torrus::Renderer::companyURL>
71 The company name text will be clickable with the URL specified in
74 =item * C<$Torrus::Renderer::rendererURL>
76 Default: C<'/torrus'>. A URL that points to Torrus renderer.
78 =item * C<$Torrus::Renderer::plainURL>
80 Default: C<'/torrus/plain'>. A URL that points to Torrus plain files directory.
81 Normally CSS stylesheet files are resided there..
83 =item * C<$Torrus::CGI::authorizeUsers>
85 Default: C<1>. When true, the web interface users are required to log in.
90 =head2 mod_perl 1.0 handler: Torrus::ApacheHandler
92 For more documentation, see E<lt>http://perl.apache.org/E<gt>.
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:
99 PerlRequire "@cfgdefdir@/webmux.pl"
101 SetHandler perl-script
102 PerlHandler Torrus::ApacheHandler
105 The base URL would be in this case:
107 http://yourhost/torrus/
110 =head2 mod_perl 2.0 handler: Torrus::Apache2Handler
112 I<Note:> Apache 2.0 support in Torrus is currently in its early
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
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.
122 Make sure you use C<webmux2.pl> and C<Torrus::Apache2Handler> in your
125 C<SetHandler modperl> directive should give better performance
126 than C<SetHandler perl-script>. Both Perl handlers work the same way
129 Typical Apache 2.0 configuration follows:
131 PerlRequire "@cfgdefdir@/webmux2.pl"
133 SetHandler perl-script
134 PerlResponseHandler Torrus::Apache2Handler
137 The base URL would be in this case:
139 http://yourhost/torrus/
142 =head2 lighttpd with FastCGI handler
144 As of version 1.0.9, Torrus supports FastCGI server module. It is also often
145 used together with B<lighttpd> HTTP server.
147 Install FastCGI on your server, and also F<FCGI> module from CPAN.
149 Add user "lighttpd" to group "torrus".
151 The following configuration creates a virtual host, so that any URL which
152 starts with "tor" would result in Torrus display:
154 # Uncomment mod_redirect and mod_fastcgi. Other modules might be needed too.
159 # virtual server configuration
160 $HTTP["host"] =~ "^tor" {
161 url.redirect = ( "^/$" => "/torrus" )
165 "socket" => "/tmp/Torrus_FCGI.socket",
166 "check-local" => "disable",
167 "bin-path" => "@pkgbindir@/torrus.fcgi",
175 =head2 Apache 2.0.x with FastCGI handler
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.
180 The following is an example of a virtual host with four FastCGI child processes
184 DocumentRoot "/var/www/vhosts/test01.torrus.net"
185 ServerName test01.torrus.net
186 AddHandler fastcgi-script fcgi
187 FastCgiServer @pkgbindir@/torrus.fcgi \
189 ScriptAlias /torrus "@pkgbindir@/torrus.fcgi"
198 =head2 Known CGI parameters
200 The following CGI parameters are recognized by mod_perl handler:
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.
211 Optional. Alternatively to token reference, the full path of the tree element
216 Optional. A subtree which has a unique I<nodeid> can be referred
221 Optional. Specifies the C<view> name for displaying the tree element.
222 If not specified, the defaul view is used.
226 Optional. Synonym for C<view> parameter.
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.
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.
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
248 =item Gstart, Gend, Gwidth, Gheight
250 Optional vaiables that override the ones defined in the view.
254 Optional. If true, turns on the debug level of logging. The debug messages
255 are sent to HTTP server's error log.
259 Optional. If true, makes the grapher display those subtree and leaves
260 which have C<hidden> parameter set to C<yes>.
264 Optional. If true, disables the displaying of Holt-Winters
265 boundaries and failures.
269 Optional. When user authorization is enabled, causes the current user
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.
280 Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>