Torrus Web Interface Reference

HTTP Server configuration

Torrus WebUI supports FastCGI as a server engine.

Apache 2.x with mod_fcgid

The following example assumes that /opt/pm/share/www contains index.html which redirects the client to /torrus.

 <VirtualHost *:80>
  DocumentRoot "/opt/pm/share/www"
  ServerName test01.torrus.net
  ScriptAlias /torrus "/opt/pm/torrus/bin/torrus.fcgi"
  FcgidMaxProcessesPerClass 10
  FcgidMaxRequestsPerProcess 100
  <Location />
   Options Indexes
   Require all granted
  </Location>
  <Location /torrus>
    Options       +ExecCGI
    Order         Allow,Deny
    Allow         from all
  </Location>
 </VirtualHost>

lighttpd with FastCGI handler

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"     => "/opt/t3/t/torrus/bin/torrus.fcgi",
                    "max-procs"    => 2,
                )
            )
        )
  }

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 /opt/t3/t/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-2017 Stanislav Sinyagin <ssinyagin@k-open.com>