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/libexec/torrus/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/libexec/torrus/torrus.fcgi \
            -processes 4
         ScriptAlias /torrus "/usr/local/libexec/torrus/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/share/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/share/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:

    *   $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-2011 Stanislav Sinyagin <ssinyagin@k-open.com>

