Torrus Web Interface Reference

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

HTTP Server configuration

Torrus WebUI supports mod_perl and FastCGI as server engines. FastCGI was introduced in Torrus version 1.0.9, and it is the preferred way of setting up Torrus user interface.

lighttpd with FastCGI handler

Install FastCGI on your server, and also FCGI Perl module from CPAN.

Add user "lighttpd" to group "torrus" (this depends on the user name that is used for lighttpd in your OS).

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>

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>

mod_perl 2.0 handler: Torrus::Apache2Handler

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>

CSS Stylesheets

Additional user-defined stylesheet files may be used with Torrus WebUI. The global configuration variable %Torrus::Renderer::styling defines the stylesheets for various output media ('default', 'printer' for printer-friendly output, and 'report' for monthly traffic HTML reports).

By editing torrus-siteconfig.pl, additional stylesheets can be added as cssoverlay values. An absolute URI pointing to the additional CSS file is required, for example:

  $Torrus::Renderer::styling{'default'}{'cssoverlay'} = '/mystyle.css';

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. The command torrus clearcache would clean the Torrus cache. In addition, you may need to clean your browser's cache.

Site configuration options

The following variables can be set in your /usr/local/etc/torrus/conf/torrus-siteconfig.pl file:

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, Gimgformat, Gborder

Optional vaiables that override the ones defined in the view. Gborder is only supported in RRDtool version 1.3.9 or higher.

Gmaxline

If set to a true value, the renderer tries to draw the maximum value alongside with the average. The aggregation period is 1 day unless specified by Gmaxlinestep. Single-line graphs are all displayed immediately with the maximum line. Multigraphs require maxline-style-X and maxline-color-X parameters to be defined in order for the maximum line to be properly displayed.

Gmaxlinestep

Aggregation period, in seconds, for the maximum line. If the variable is not specified, the line displays daily maximums.

Gcolors

Graph colors, overriding the graph-colors view parameter. This variable defines the values for the --color options in RRD Graph command. The value is an even number of color tags and color values, separated by colon (:). For example, "BACK:00FFFF:FONT:AA55DD" corresponds to an ugly cyan background and magenta text.

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.

RPC interface

The RPC interface is designed for external systems to retrieve Torrus data. The RPC calls are done via URL parameters, and the returned data is in JSON format.

The resulting data size cannot exceed the security limit (by default, 100 items).

The view rpc is responsible for returning RPC data. The following CGI parameters are recognized:

The following RPC calls are supported:

The return data is a JSON map with the following keys:


Author

Copyright (c) 2002-2011 Stanislav Sinyagin <ssinyagin@k-open.com>