
1. How do I report bugs in Torrus for Debian GNU/Linux?
2. How do I manually configure the Apache web server to use Torrus?
3. Why does stopping the Torrus daemons sometimes take forever? 
4. Where should I put my own XML templates and tree definitions?
5. How do quickly have torrus plot statistics for the local host
6. File locations are completely different from the original
   (non-Debian) Torrus installation. Why and where are the files now?
7. What other changes have been done to the original source?

======================================================================

1. How do I report bugs in Torrus packages for Debian GNU/Linux?

In order to package Torrus for the Debian GNU/Linux distribution
certain minor modifications to the original source have been made (see
question 6 for a list). It is therefore important, that the bugs
discovered in Torrus on a Debian GNU/Linux system would be first
reported to the Torrus Debian package maintainer, using the Debian
bug-tracking system [1.1] (preferably, using reportbug utility). There
is also a chance that the bug you've discovered is already known, so
please consult the existing bug list [1.2] before reporting. You can
also have a look at the pkg-torrus project homepage [1.3] or contact
the pkg-torrus-general mailing list [1.4] with your problems or concerns.

Before reporting a bug please make sure that this is a real problem.
A typical example is a situation in which Torrus displays incorrect or
erroneous information due to some misconfiguration. The incorrectly
generated web pages get cached both by Torrus and your browser, so it
might appear that the problem still persists, even after the
configuration has been corrected. To make sure that there is really a
bug in Torrus, please do the following:

* Stop the Apache web server by running '/etc/init.d/apache2 stop'.
* Stop Torrus daemons by running '/etc/init.d/torrus-common stop'.
* Clear the Torrus Renderer cache by running the 'torrus clearcache'
  command.
* Start Torrus daemons ('/etc/init.d/torrus-common start').
* Start the Apache daemon ('/etc/init.d/apache2 start').
* Clear your browser's cache before viewing Torrus pages. If browser
  supports different profiles, create one from scratch. This will
  guarantee that no old data is left in the cache.

[1.1] http://bugs.debian.org
[1.2] http://bugs.debian.org/torrus-common
[1.3] http://pkg-torrus.alioth.debian.org
[1.4] pkg-torrus-general@lists.alioth.debian.org 

======================================================================

2. How do I manually configure the Apache web server to use Torrus?

As of version 1.0.9 Torrus provides and recommends the FastCGI 
interface to the web server. It is implemented by a number of
webservers including Apache 2.x and lighttpd. 

One possible configuration is the use of the Apache 2.x fcgid-module
as following:

* install the libapache2-mod-fcgid package
* enable the module using a2enmod(8) ('a2enmod fcgid')
* put the following line into your favourite vhost configuration:
	ScriptAlias /torrus "/usr/share/torrus/bin/torrus.fcgi"

If you are migrating from torrus-apache2, don't forget to purge 
torrus-apache2 before adding the ScriptAlias.

Further information and sample configurations for lighttpd and 
apache2-mod-fastcgi can be found in the Torrus Web Interface
Reference [2.1]

[2.1] /usr/share/doc/torrus-common/webintf.html

======================================================================

3. Why does it take forever to stop the Torrus daemons sometimes? 

The recommended way to start and stop Torrus daemons is using the
/etc/init.d/torrus-common script. It will start/stop the daemons for
all trees which are configured. It uses a few parameters, which may be
customized by setting the variables in the configuration file
/etc/torrus/conf/initscript.siteconf. See the comment in this file
for more information.

======================================================================

4. Where should I put my own XML templates and tree definitions?

The configuration files which are meant to be edited to customize Torrus
behavior are located in or under /etc/torrus directory:

/etc/torrus/conf/torrus-siteconfig.pl
/etc/torrus/conf/snmptrap-siteconfig.pl	
/etc/torrus/conf/devdiscover-siteconfig.pl
/etc/torrus/conf/email-siteconfig.pl
/etc/torrus/xmlconfig/site-global.xml

Your own XML tree definitions should be placed into /etc/torrus/xmlconfig,
that's where 'torrus devdiscover' will place its output file by default.
The directory /etc/torrus/discovery is provided for storage of the SNMP
discovery files, generated by 'torrus genddx'.

======================================================================

5. How do quickly have torrus plot statistics for the local host

- install snmpd
- enable the "rocommunity public localhost" line in snmpd.conf
- run torrus genddx --host=localhost --out=localhost.ddx
  --discout=localhost.xml --version=2c --community=public --subtree=/local
- run torrus dd --in=localhost.ddx
- change /etc/torrus/conf/torrus-siteconfig.pl to enable treeConfig
  and point xmlfiles to localhost.xml
- run torrus compilexml --tree=main
- start torrus collector

======================================================================

6. File locations are completely different from the original
   (non-Debian) Torrus installation. Why and where are the files now?

To ensure compliance with Filesystem Hierarchy Standard (FHS) [5.1]
required by the Debian Policy Manual [5.2], the Torrus directory locations
on a Debian GNU/Linux system had to be chosen to be somewhat different
from the defaults used by Torrus when installing from the distribution
tarball.  By default Torrus installs its directory tree under /usr/local.
The table below contains the new locations of the default Torrus
directories (/u/l/ is short for /usr/local/).

Old location		   New location(s)
--------------------------------------------------------------------
/u/l/torrus/bin		   /usr/sbin
				torrus executable. This is a wrapper
				script which may be used to invoke
				any Torrus command. See 'man torrus'
				for details.
			   /usr/share/torrus/bin
				Command scripts and action_* 
				executables, which are designed to be
				used from the monitor actions only.
/u/l/etc/torrus		   /etc/torrus 
				Configuration files.
/u/l/torrus/examples	   /usr/share/doc/torrus-common/examples
				Configuration and template examples.
/u/l/torrus/doc		   /usr/share/doc/torrus-common
				Documentation directory.
/u/l/torrus/perllib	   /usr/share/perl5
				Perl modules.
/var/torrus/cache	   /var/cache/torrus
/var/torrus/db		   /var/lib/torrus/db
				BerkeleyDB files.
/var/log/torrus		   /var/log/torrus
				Log files.
/var/run/torrus		   /var/run/torrus
				Process ID (PID) file for Torrus daemons.
/var/torrus/session_data   /var/lib/torrus/session_data
				Session data storage and lock files.
/srv/torrus/collector_rrd  /var/lib/torrus/collector_rrd
				RRD data collector directory.

[5.1] http://www.pathname.com/fhs/
[5.2] http://www.debian.org/doc/debian-policy/

======================================================================

7. What other changes have been done to the original source?

All the changes made to the original Torrus source are available in
the form of the individual patches in the debian/patches directory of
the torrus source package, which can be obtained using the command
'apt-get source torrus'. Apart from modifying the directory layout,
the following minor changes are worth mentioning:

* The user documentation (except the developer documentation in [6.1] 
  and the Torrus installation guide [6.2], irrelevant for Debian) has
  been edited to reflect the new file locations.
* The Torrus Debian package uses its own initialization script, placed in
  /etc/init.d/torrus-common. It is based on the upstream's initialization
  script but has been edited to include Debian-specific startup commands.

[6.1] /usr/share/doc/torrus-common/devdoc
[6.2] /usr/share/doc/torrus-common/install.*

