Torrus Web Interface Reference
    Warning: This documentation is relevant to Torrus version 1.0.9. It is
    incompatible with previous versions.

  Directory structure
    By default, the directory /usr/local/torrus/sup/webplain/ 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 *SetHandler default-handler*
    directive.

  CSS Stylesheets
    Additional user-defined stylesheet files may be added in webplain
    directory. The default HTML templates that come with the Torrus
    distribution use the global configuration variable
    $Torrus::Renderer::stylesheet, which is set in torrus-config.pl and may
    be overwritten in torrus-siteconfig.pl.

  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.

  Site configuration options
    The following variables may need to be set in your
    /usr/local/etc/torrus/conf/torrus-siteconfig.pl file:

    *   $Torrus::Renderer::companyName

        The text that you specify here will appear in the top left corner of
        all HTML pages.

    *   $Torrus::Renderer::companyURL

        The company name text will be clickable with the URL specified in
        this variable.

    *   $Torrus::Renderer::rendererURL

        Default: '/torrus'. A URL that points to Torrus renderer.

    *   $Torrus::Renderer::plainURL

        Default: '/torrus/plain'. A URL that points to Torrus plain files
        directory. Normally CSS stylesheet files are resided there..

    *   $Torrus::CGI::authorizeUsers

        Default: 1. When true, the web interface users are required to log
        in.

  mod_perl 1.0 handler: Torrus::ApacheHandler
    For more documentation, see <http://perl.apache.org/>.

    The whole output generation is performed by the "Torrus::ApacheHandler"
    class. However, you still need access to the plain directory where your
    CSS resides. Typical Apache configuration would look like follows. Make
    sure your configuration does not contain tab characters:

      PerlRequire "/usr/local/torrus/conf_defaults/webmux.pl"
      <Location /torrus>
        SetHandler perl-script
        PerlHandler Torrus::ApacheHandler
      </Location>

    The base URL would be in this case:

      http://yourhost/torrus/

  mod_perl 2.0 handler: Torrus::Apache2Handler
    *Note:* Apache 2.0 support in Torrus is currently in its early
    development stage.

    *Note:* As of now, "libapreq2" library is not released yet, and only the
    development version is available. You have to download and install it
    manually.

    mod_perl version 1.99_15 or later is supported. To the moment,
    "libapreq2" version "2.04_03-dev" is tested.

    Make sure you use "webmux2.pl" and "Torrus::Apache2Handler" in your
    configuration.

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

    Typical Apache 2.0 configuration follows:

      PerlRequire "/usr/local/torrus/conf_defaults/webmux2.pl"
      <Location /torrus>
        SetHandler perl-script
        PerlResponseHandler Torrus::Apache2Handler
      </Location>

    The base URL would be in this case:

      http://yourhost/torrus/

  lighttpd with FastCGI handler
    As of version 1.0.9, Torrus supports FastCGI server module. It is also
    often used together with lighttpd HTTP server.

    Install FastCGI on your server, and also 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"     => "/usr/local/torrus/bin/torrus.fcgi",
                        "max-procs"    => 2,
                    )
                )
            )
      }

  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 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   /usr/local/torrus/bin/torrus.fcgi \
            -processes 4
         ScriptAlias /torrus "/usr/local/torrus/bin/torrus.fcgi"
        <Location /torrus>
            Order           Allow,Deny
            Allow           from all
        </Location>
        </VirtualHost>

  Known CGI parameters
    The following CGI parameters are recognized by mod_perl handler:

    token
        Optional. Each configuration tree element is referenced by a
        *token*, a short unique identifier. If not given, the root of the
        tree ("/") is displayed.

    path
        Optional. Alternatively to token reference, the full path of the
        tree element may be referenced.

    nodeid
        Optional. A subtree which has a unique *nodeid* can be referred with
        this parameter.

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

    v   Optional. Synonym for "view" parameter.

    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.

    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.

    NOW Optional. If given, presents the output for the given moment,
        instead of the current time. Must be of the form understood by
        "rrdtool" (see RRDTool manuals).

    Gstart, Gend, Gwidth, Gheight
        Optional vaiables that override the ones defined in the view.

    DEBUG
        Optional. If true, turns on the debug level of logging. The debug
        messages are sent to HTTP server's error log.

    SHOWHIDDEN
        Optional. If true, makes the grapher display those subtree and
        leaves which have "hidden" parameter set to "yes".

    NOHW
        Optional. If true, disables the displaying of Holt-Winters
        boundaries and failures.

    LOGOUT
        Optional. When user authorization is enabled, causes the current
        user session to log out.

    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.

Author
    Copyright (c) 2002-2005 Stanislav Sinyagin <ssinyagin@yahoo.com>

