X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=torrus%2Fdoc%2Fwebintf.pod.in;fp=torrus%2Fdoc%2Fwebintf.pod.in;h=f85d99435154b63543685ebb73a9c69b0058c70e;hp=0000000000000000000000000000000000000000;hb=74e058c8a010ef6feb539248a550d0bb169c1e94;hpb=35359a73152b3d7a9ad5e3d37faf81f6fedb76e8 diff --git a/torrus/doc/webintf.pod.in b/torrus/doc/webintf.pod.in new file mode 100644 index 000000000..f85d99435 --- /dev/null +++ b/torrus/doc/webintf.pod.in @@ -0,0 +1,280 @@ +# webintf.pod - Torrus web interface reference +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: webintf.pod.in,v 1.1 2010-12-27 00:04:33 ivan Exp $ +# Stanislav Sinyagin +# +# + +=head1 Torrus Web Interface Reference + +B This documentation is relevant to Torrus version 1.0.9. +It is incompatible with previous versions. + +=head2 Directory structure + +By default, the directory F<@webplaindir@/> is the place +for static HTML, CSS stylesheets and images. + +The default CSS stylesheet files are installed in this directory. +This directory must be configured with I +directive. + +=head2 CSS Stylesheets + +Additional user-defined stylesheet files may be added in +F directory. +The default HTML templates that come with the Torrus distribution use the +global configuration variable C<$Torrus::Renderer::stylesheet>, which is set +in F and may be overwritten in F. + +=head2 Cache files + +All generated HTML and graphical images are cached twice: first on the server, +and then in your browser. Thus, if you change somehow the HTML +appearance of your Torrus installation, you need to clean both caches: + + torrus clearcache + +This will clear the cache on the server. Then you may use your browser's +"reload" button, or clear the whole browser cache. + + +=head2 Site configuration options + +The following variables may need to be set in your +F<@siteconfdir@/torrus-siteconfig.pl> file: + +=over 4 + +=item * C<$Torrus::Renderer::companyName> + +The text that you specify here will appear in the top left corner +of all HTML pages. + +=item * C<$Torrus::Renderer::companyURL> + +The company name text will be clickable with the URL specified in +this variable. + +=item * C<$Torrus::Renderer::rendererURL> + +Default: C<'/torrus'>. A URL that points to Torrus renderer. + +=item * C<$Torrus::Renderer::plainURL> + +Default: C<'/torrus/plain'>. A URL that points to Torrus plain files directory. +Normally CSS stylesheet files are resided there.. + +=item * C<$Torrus::CGI::authorizeUsers> + +Default: C<1>. When true, the web interface users are required to log in. + +=back + + +=head2 mod_perl 1.0 handler: Torrus::ApacheHandler + +For more documentation, see Ehttp://perl.apache.org/E. + +The whole output generation is performed by the C class. +However, you still need access to the F directory where your CSS +resides. Typical Apache configuration would look like follows. Make sure +your configuration does not contain tab characters: + + PerlRequire "@cfgdefdir@/webmux.pl" + + SetHandler perl-script + PerlHandler Torrus::ApacheHandler + + +The base URL would be in this case: + + http://yourhost/torrus/ + + +=head2 mod_perl 2.0 handler: Torrus::Apache2Handler + +I Apache 2.0 support in Torrus is currently in its early +development stage. + +I As of now, C library is not released yet, and only the +development version is available. You have to download and install it +manually. + +mod_perl version B<1.99_15> or later is supported. To the moment, +C version C<2.04_03-dev> is tested. + +Make sure you use C and C in your +configuration. + +C directive should give better performance +than C. Both Perl handlers work the same way +with Torrus. + +Typical Apache 2.0 configuration follows: + + PerlRequire "@cfgdefdir@/webmux2.pl" + + SetHandler perl-script + PerlResponseHandler Torrus::Apache2Handler + + +The base URL would be in this case: + + http://yourhost/torrus/ + + +=head2 lighttpd with FastCGI handler + +As of version 1.0.9, Torrus supports FastCGI server module. It is also often +used together with B HTTP server. + +Install FastCGI on your server, and also F module from CPAN. + +Add user "lighttpd" to group "torrus". + +The following configuration creates a virtual host, so that any URL which +starts with "tor" would result in Torrus display: + + # Uncomment mod_redirect and mod_fastcgi. Other modules might be needed too. + server.modules = ( + "mod_redirect", + "mod_fastcgi", + ) + # virtual server configuration + $HTTP["host"] =~ "^tor" { + url.redirect = ( "^/$" => "/torrus" ) + fastcgi.server = ( + "/torrus" => ( + "Torrus" => ( + "socket" => "/tmp/Torrus_FCGI.socket", + "check-local" => "disable", + "bin-path" => "@pkgbindir@/torrus.fcgi", + "max-procs" => 2, + ) + ) + ) + } + + +=head2 Apache 2.0.x with FastCGI handler + +As of version 1.0.9, Torrus supports the FastCGI server module. +It is also often used together with B HTTP server. + +The following is an example of a virtual host with four FastCGI child processes + + + + DocumentRoot "/var/www/vhosts/test01.torrus.net" + ServerName test01.torrus.net + AddHandler fastcgi-script fcgi + FastCgiServer @pkgbindir@/torrus.fcgi \ + -processes 4 + ScriptAlias /torrus "@pkgbindir@/torrus.fcgi" + + Order Allow,Deny + Allow from all + + + + + +=head2 Known CGI parameters + +The following CGI parameters are recognized by mod_perl handler: + +=over 4 + +=item token + +Optional. Each configuration tree element is referenced by a I, a short +unique identifier. If not given, the root of the tree (C) is displayed. + +=item path + +Optional. Alternatively to token reference, the full path of the tree element +may be referenced. + +=item nodeid + +Optional. A subtree which has a unique I can be referred +with this parameter. + +=item view + +Optional. Specifies the C name for displaying the tree element. +If not specified, the defaul view is used. + +=item v + +Optional. Synonym for C parameter. + + +=item hostauth + +Mandatory for host-based authentication. The value is treated as a password +and the user name is the client's IP address with non-alphanumerics +replaced with underscores. + + +=item TZ + +Optional. If given, specifies the timezone that you want the graphs to be +displayed for. This must be the URL-encoded zone name which is understood by +your server system. You may use zdump(8) for testing. + +=item NOW + +Optional. If given, presents the output for the given moment, instead of the +current time. Must be of the form understood by C (see +RRDTool manuals). + +=item Gstart, Gend, Gwidth, Gheight + +Optional vaiables that override the ones defined in the view. + +=item DEBUG + +Optional. If true, turns on the debug level of logging. The debug messages +are sent to HTTP server's error log. + +=item SHOWHIDDEN + +Optional. If true, makes the grapher display those subtree and leaves +which have C parameter set to C. + +=item NOHW + +Optional. If true, disables the displaying of Holt-Winters +boundaries and failures. + +=item LOGOUT + +Optional. When user authorization is enabled, causes the current user +session to log out. + +=back + +All other parameters whose name starts with capital letter, are passed +to the HTML template as-is, and may be used for your custom purposes. + + +=head1 Author + +Copyright (c) 2002-2005 Stanislav Sinyagin Essinyagin@yahoo.comE