Warning: This documentation is relevant to Torrus version 1.0.9. It is incompatible with previous versions.
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.
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/share/torrus/bin/torrus.fcgi", "max-procs" => 2, ) ) ) }
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/share/torrus/bin/torrus.fcgi \ -processes 4 ScriptAlias /torrus "/usr/share/torrus/bin/torrus.fcgi" <Location /torrus> Order Allow,Deny Allow from all </Location> </VirtualHost>
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/share/torrus/conf_defaults/webmux.pl" <Location /torrus> SetHandler perl-script PerlHandler Torrus::ApacheHandler </Location>
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/share/torrus/conf_defaults/webmux2.pl" <Location /torrus> SetHandler perl-script PerlResponseHandler Torrus::Apache2Handler </Location>
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';
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.
The following variables can be set in your /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.
The following CGI parameters are recognized by mod_perl handler:
Optional. Each configuration tree element is referenced by a token, a short
unique identifier. If not given, the root of the tree (/
) is displayed.
Optional. Alternatively to token reference, the full path of the tree element may be referenced.
Optional. A subtree which has a unique nodeid can be referred with this parameter.
Optional. Specifies the view
name for displaying the tree element.
If not specified, the defaul view is used.
Optional. Synonym for view
parameter.
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.
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.
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).
Optional vaiables that override the ones defined in the view.
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.
Aggregation period, in seconds, for the maximum line. If the variable is not specified, the line displays daily maximums.
Optional. If true, turns on the debug level of logging. The debug messages are sent to HTTP server's error log.
Optional. If true, makes the grapher display those subtree and leaves
which have hidden
parameter set to yes
.
Optional. If true, disables the displaying of Holt-Winters boundaries and failures.
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.
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 RPC call to execute. This is a mandatory parameter. Below see the list of supported values.
Optional comma-separated list of datasource leaf parameters that are
going to be retrieved from the configuration
tree. @Torrus::Renderer::RPC::default_leaf_params
in
torrus-config.pl defines the list of parameters that are always
queried, and GET_PATAMS would add parameter names to that list. Several
parameter names, such as snmp-community, are blacklisted because of
security concern.
Optional. If set to 1, the resulting JSON data is sorted and formatted for human reading.
The following RPC calls are supported:
This RPC call walks down the tree from the node specified by the URL,
and returns all the leaves with their respective parameters. In
addition to parameters, the entry path
presents the path information
in the datasource tree.
This RPC call is applicable to any datasource leaf with "leaf-type" set
to "rrd-def". It fetches the average and maximum values for a given
period. The URL parameters Gstart
and Gend
are used to define the
time interval. Returned data is a map of the following keys and values:
Unix timestamps of the calculated time interval.
Average and maximum values calculated for the given interval.
Percentage of time for which the data is not NaN. Accuracy of this value depends on the time interval and RRA's being used to produce the value. Consolidated RRA's may already screen out some unavailable data samples.
This RPC call performs a prefix search for nodeid values among all
leaves in the tree. The prefix string is expected in PREFIX
CGI
argument. The call returns the same data format as WALK_LEAVES.
The return data is a JSON map with the following keys:
If the value is nonzero, the RPC call was successful.
In case of a failure, this value returns athe error string.
This is a map of objects, with datasource tokens as keys. Each object represents the data as specified by the RPC call.
Copyright (c) 2002-2011 Stanislav Sinyagin <ssinyagin@yahoo.com>