# 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"     => "/usr/share/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 /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.

## 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:

- RPCCALL

  The RPC call to execute. This is a mandatory parameter. Below see the list of supported values.

- GET_PARAMS

  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.

- PRETTY

  Optional. If set to 1, the resulting JSON data is sorted and formatted for human reading.

- DATAONLY

  Optional parameter in TIMESERIES RPC call. If it's set to a true value, the call would return only the data rows, without decorations and RRDgraph command arguments.

The following RPC calls are supported:

- WALK_LEAVES

  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.

- AGGREGATE_DS

  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:

  - START, END

    Unix timestamps of the calculated time interval.

  - AVG, MAX

    Average and maximum values calculated for the given interval.

  - AVAIL

    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.

- TIMESERIES

  This RPC call retrieves the numerical data for a leaf, and returns it in tabular form. In addition to standard URL parameters, `Gstep` and `Gmaxrows` are supported as described in rrdxport manual page. The returned data contains also "rrgraph_args" map element, which presents the arguments for RRD Tool rrgraph command.

- SEARCH_NODEID

  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:

- success

  If the value is nonzero, the RPC call was successful.

- error

  In case of a failure, this value returns athe error string.

- data

  This is a map of objects, with datasource tokens as keys. Each object represents the data as specified by the RPC call.

# Author

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