#  webintf.pod - Torrus web interface reference
#  Copyright (C) 2002  Stanislav Sinyagin
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

# Stanislav Sinyagin <ssinyagin@k-open.com>
#
#

=head1 Torrus Web Interface Reference

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


=head2 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.


=head3 lighttpd with FastCGI handler

Install FastCGI on your server, and also F<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"     => "@pkgbindir@/torrus.fcgi",
                    "max-procs"    => 2,
                )
            )
        )
  }




=head3 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 B<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   @pkgbindir@/torrus.fcgi \
        -processes 4
     ScriptAlias /torrus "@pkgbindir@/torrus.fcgi"
    <Location /torrus>
        Order           Allow,Deny
        Allow           from all
    </Location>
    </VirtualHost>




=head3 mod_perl 1.0 handler: Torrus::ApacheHandler 

For more documentation, see E<lt>http://perl.apache.org/E<gt>.

The whole output generation is performed by the C<Torrus::ApacheHandler> class.
However, you still need access to the F<plain> directory where your CSS
resides. Typical Apache configuration would look like follows. Make sure
your configuration does not contain tab characters:

  PerlRequire "@cfgdefdir@/webmux.pl"
  <Location /torrus>
    SetHandler perl-script
    PerlHandler Torrus::ApacheHandler
  </Location>





=head3 mod_perl 2.0 handler: Torrus::Apache2Handler

Make sure you use C<webmux2.pl> and C<Torrus::Apache2Handler> in your
configuration.

C<SetHandler modperl> directive should give better performance
than C<SetHandler perl-script>. Both Perl handlers work the same way
with Torrus.

Typical Apache 2.0 configuration follows:

  PerlRequire "@cfgdefdir@/webmux2.pl"
  <Location /torrus>
    SetHandler perl-script
    PerlResponseHandler Torrus::Apache2Handler
  </Location>




=head2 CSS Stylesheets

Additional user-defined stylesheet files may be used with Torrus WebUI.
The global configuration variable C<%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 F<torrus-siteconfig.pl>, additional stylesheets can be added as
C<cssoverlay> values. An absolute URI pointing to the additional CSS file
is required, for example:

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

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


=head2 Site configuration options

The following variables can be set in your
F<@siteconfdir@/torrus-siteconfig.pl> file:

=over 4

=item * C<$Torrus::Renderer::companyName>

The text that you specify here will appear in the top left corner
of all HTML pages.

=item * C<$Torrus::Renderer::companyURL>

The company name text will be clickable with the URL specified in
this variable.

=item * C<$Torrus::Renderer::rendererURL>

Default: C<'/torrus'>. A URL that points to Torrus renderer.

=item * C<$Torrus::Renderer::plainURL>

Default: C<'/torrus/plain'>. A URL that points to Torrus plain files directory.
Normally CSS stylesheet files are resided there.

=item * C<$Torrus::CGI::authorizeUsers>

Default: C<1>. When true, the web interface users are required to log in.

=back




=head2 Known CGI parameters

The following CGI parameters are recognized by mod_perl handler:

=over 4

=item token

Optional. Each configuration tree element is referenced by a I<token>, a short
unique identifier. If not given, the root of the tree (C</>) is displayed.

=item path

Optional. Alternatively to token reference, the full path of the tree element
may be referenced.

=item nodeid

Optional. A subtree which has a unique I<nodeid> can be referred
with this parameter.

=item view

Optional. Specifies the C<view> name for displaying the tree element.
If not specified, the defaul view is used.

=item v

Optional. Synonym for C<view> parameter.


=item 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.


=item 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.

=item NOW

Optional. If given, presents the output for the given moment, instead of the
current time. Must be of the form understood by C<rrdtool> (see
RRDTool manuals).

=item 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.

=item 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 C<Gmaxlinestep>. Single-line graphs are all displayed
immediately with the maximum line. Multigraphs require
C<maxline-style-X> and C<maxline-color-X> parameters to be defined in
order for the maximum line to be properly displayed.

=item Gmaxlinestep

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

=item Gcolors

Graph colors, overriding the C<graph-colors> view parameter. This
variable defines the values for the C<--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.

=item DEBUG

Optional. If true, turns on the debug level of logging. The debug messages
are sent to HTTP server's error log.

=item SHOWHIDDEN

Optional. If true, makes the grapher display those subtree and leaves
which have C<hidden> parameter set to C<yes>.

=item NOHW

Optional. If true, disables the displaying of Holt-Winters
boundaries and failures.

=item LOGOUT

Optional. When user authorization is enabled, causes the current user
session to log out.

=back

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.


=head2 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 C<rpc> is responsible for returning RPC data. The following CGI
parameters are recognized:

=over 4

=item * RPCCALL

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

=item * GET_PARAMS

Optional comma-separated list of datasource leaf parameters that are
going to be retrieved from the configuration
tree. C<@Torrus::Renderer::RPC::default_leaf_params> in
F<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 I<snmp-community>, are blacklisted because of
security concern.

=item * PRETTY

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

=item * 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.

=back


The following RPC calls are supported:

=over 4

=item * 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 C<path> presents the path information
in the datasource tree.

=item * 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 C<Gstart> and C<Gend> are used to define the
time interval. Returned data is a map of the following keys and values:

=over 8

=item * START, END

Unix timestamps of the calculated time interval.

=item * AVG, MAX

Average and maximum values calculated for the given interval.

=item * 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.

=back

=item * TIMESERIES

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


=item * SEARCH_NODEID

This RPC call performs a prefix search for I<nodeid> values among all
leaves in the tree. The prefix string is expected in C<PREFIX> CGI
argument. The call returns the same data format as WALK_LEAVES.

=back


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

=over 4

=item * success

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

=item * error

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

=item * data

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

=back





=head1 Author

Copyright (c) 2002-2011 Stanislav Sinyagin E<lt>ssinyagin@k-open.comE<gt>