#  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 <ssinyagin@yahoo.com>
#
#

=head1 Torrus Web Interface Reference

B<Warning:> 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<SetHandler default-handler>
directive.

=head2 CSS Stylesheets

Additional user-defined stylesheet files may be added in
F<webplain> 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<torrus-config.pl> and may be overwritten in F<torrus-siteconfig.pl>.

=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 E<lt>http://perl.apache.org/E<gt>.

The whole output generation is performed by the C<Torrus::ApacheHandler> class.
However, you still need access to the F<plain> 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"
  <Location /torrus>
    SetHandler perl-script
    PerlHandler Torrus::ApacheHandler
  </Location>

The base URL would be in this case:

  http://yourhost/torrus/


=head2 mod_perl 2.0 handler: Torrus::Apache2Handler

I<Note:> Apache 2.0 support in Torrus is currently in its early
development stage.

I<Note:> As of now, C<libapreq2> 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<libapreq2> version C<2.04_03-dev> is tested.

Make sure you use C<webmux2.pl> and C<Torrus::Apache2Handler> in your
configuration.

C<SetHandler modperl> directive should give better performance
than C<SetHandler perl-script>. Both Perl handlers work the same way
with Torrus.

Typical Apache 2.0 configuration follows:

  PerlRequire "@cfgdefdir@/webmux2.pl"
  <Location /torrus>
    SetHandler perl-script
    PerlResponseHandler Torrus::Apache2Handler
  </Location>

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<lighttpd> HTTP server.

Install FastCGI on your server, and also F<FCGI> 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<Apache 2.x> HTTP server.

The following is an example of a virtual host with four FastCGI child processes


    <VirtualHost *:80>
     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"
    <Location /torrus>
        Order           Allow,Deny
        Allow           from all
    </Location>
    </VirtualHost>



=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<token>, 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<nodeid> can be referred
with this parameter.

=item view

Optional. Specifies the C<view> name for displaying the tree element.
If not specified, the defaul view is used.

=item v

Optional. Synonym for C<view> 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<rrdtool> (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<hidden> parameter set to C<yes>.

=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 E<lt>ssinyagin@yahoo.comE<gt>
