[torrus-commit] htdocs/devdoc architecture.pod.html,NONE,1.1 devdiscover.pod.html,NONE,1.1 progstyle

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/torrus/htdocs/devdoc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18841/devdoc

Added Files:
	architecture.pod.html devdiscover.pod.html progstyle.pod.html 
	reqs.0.0.pod.html reqs.0.1.pod.html torrus_roadmap.pod.html 
	wd.distributed.pod.html wd.messaging.pod.html 
	wd.monitor-escalation.pod.html wd.uptime-mon.pod.html 
Log Message:
doc updated

--- NEW FILE: reqs.0.0.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRD Framework Requirements Version 0.0</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrd_framework_requirements_version_0_0">RRD Framework Requirements Version 0.0</a></li>
	<ul>

		<li><a href="#flexible_hierarchical_configuration">Flexible Hierarchical Configuration</a></li>
	</ul>

	<li><a href="#data_monitoring_principles">Data Monitoring Principles</a></li>
	<ul>

		<li><a href="#file_naming_flexibility">File Naming Flexibility</a></li>
		<li><a href="#datasource_naming">Datasource Naming</a></li>
		<li><a href="#monitoring_rules">Monitoring Rules</a></li>
		<li><a href="#event_processing">Event Processing</a></li>
	</ul>

	<li><a href="#data_displaying_principles">Data Displaying Principles</a></li>
	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />


<h1><a name="rrd_framework_requirements_version_0_0">RRD Framework Requirements Version 0.0</a></h1>
Date: Jul 10 2002
This article defines some principles that a supposedly future
RRD framework should have. The framework should consist of 3
independent subsystems:
<dl>
<dt><a name="item_data_collection">Data Collection</a> 
</dt>
<dt><a name="item_data_monitoring">Data Monitoring</a> 
</dt>
<dt><a name="item_data_displaying">Data Displaying</a> 
</dt>
</dl>


<h2><a name="flexible_hierarchical_configuration">Flexible Hierarchical Configuration</a></h2>
Inspired by Cricket hierarchical configuration, we state here that
the configuration should be hierarchical. Child nodes should
inherit the properties from parents.
The format of the configuration files has not to be neccessary
as in Cricket. I'm not sure if it's worth keeping them in a directory
structure representing the hierarchy tree, but it's definitive
that multiple files should be supported.
A good step ahead would be the configuration in XML format.
It is also possible to have a converter from some other formats
(plain text, or an SQL database) into XML which will be consumed by the
framework.
I leave the Data collection uncovered, since all of the existing
RRD frontends do this part already.


<hr />
<h1><a name="data_monitoring_principles">Data Monitoring Principles</a></h1>
At the moment, the only known solution for RRD data monitoring is
Cricket. Its threshold monitoring has certain limitation and drawbacks.
Nevertheless, it may be used as the basis for the ideas in the further
development.
The major idea is to build data monitoring as a part of a bigger RRD
framework, still being the independent part of the whole. The data can come
from many differet sources, from RRDs produced by any of the existing
and future frontends.


<h2><a name="file_naming_flexibility">File Naming Flexibility</a></h2>
In most existing RRD frontends, each RRD datafile should be described
individually. This is not very convenient, especially for the cases
when you have several (dozens) files containing one type of data.
(e.g., input traffic per source autonomous system).
Also the files of same type can be created and deleted by their sourcing
frontend, and it would be more convenient not having to change
the monitoring configuration.
Thus, we need a wildcards language which would allow to specify
multiple files and derive the datasource names from thir names.


<h2><a name="datasource_naming">Datasource Naming</a></h2>
Each data being monitored (for RRDs, its definition specifies the
&lt;filename, DS, RRA&gt; triple) has to have a universal name.
The name can be fully or partly qualified, depending on the
configuration tree. Examples of such data reference follow:
<pre>
 /Netflow/Exporters/63.2.3.224/if3/bps /* Interface #3 on router 63.2.3.224 */
 /Netflow/Subnets/Dialin/bps /* Dial-in address pool */
 /* different grouping for the rack temperature in Server Room 1 */
 /Envmon/RackTemp/SR1
 /SR1/Envmon/RackTemp</pre>
Name aliasing should allow short or symbolic names for data sources:
<pre>
 /* Alias for /Netflow/Exporters/63.2.3.224/if3 */
 /Netflow/Upstream/FranceTelecom1</pre>


<h2><a name="monitoring_rules">Monitoring Rules</a></h2>
Data threshold monitoring should be described in a hierarchical
manner.
It would be interesting to have monitoring rules separate from
the data hierarchy. On the other hand, 1) some data sources might need
special and unique monitoring rules; 2) in some cases, several
data sources need to be combined in order to build a threshold rule.
I'm not yet sure how this must be achieved.


<h2><a name="event_processing">Event Processing</a></h2>
Once the threshold violation occurs, the monitoring system
should produce the alarm event.
Cricket has a good set of ways to report the alarm, and they can be taken
as the basis.
Also what Cricket is really missing, is displaying those data sources
being alarmed. The Monitoring system should produce the instructions
to the Displaying system in order to display the summary of those
data sources which produce alarms within certain time.


<hr />
<h1><a name="data_displaying_principles">Data Displaying Principles</a></h1>
View profiles should be configured in a hierarchical manner.
Again as with data monitoring, some Views should be configured independently
of the data hierarchy, but also some data should be able to define
specific view profiles.
There should be view profiles of different types:
<ul>
<li></li>
HTML Framework. Defines the HTML elements that should be displayed around
the graphs. It also should define the child graphs. Also it should define
the controls which would cause the option changes in the child graphs
(e.g., enabling ``Show Holt-Winters Boundaries'' would produce the
corresponding graph).

<li></li>
Individual Graph. Defines the way the graph should look. It should
also be capable of displaying an arbitrary number of data sources.
It should have tunable options, like color, size, or time period.
</ul>
The Displaying system should allow the following ways of viewing:
1) hierarchical browsing, like Cricket; 2) alarm summary display;
3) individual graph display, without HTML surrounding.
The graph images should be cashed and reused whenever possible.
In alarm summary browsing, these images can be generated at the moment
of the event.


<hr />
<h1><a name="author">Author</a></h1>
Copyright (c) 2002 Stanislav Sinyagin <a href="mailto:ssi...@ya...">ssi...@ya...</a>

</body>

</html>

--- NEW FILE: wd.distributed.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW Working Draft: Distributed collector architecture</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_working_draft__distributed_collector_architecture">RRFW Working Draft: Distributed collector architecture</a></li>
	<ul>

		<li><a href="#introduction">Introduction</a></li>
		<li><a href="#terminology">Terminology</a></li>
		<li><a href="#transport">Transport</a></li>
		<li><a href="#operation">Operation</a></li>
		<li><a href="#message_format">Message format</a></li>
	</ul>

	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />


<h1><a name="rrfw_working_draft__distributed_collector_architecture">RRFW Working Draft: Distributed collector architecture</a></h1>
Status: pending implementation.
Date: May 26, 2004. Last revised: June 14, 2004


<h2><a name="introduction">Introduction</a></h2>
In large installations, one server has often not enough capacity
to collect the data from all the data sources. In other cases,
because of the network bandwidth or security restrictions it is
preferrable to collect (SNMP) data locally on the site, and transfer
the updates to the central location less frequently.


<h2><a name="terminology">Terminology</a></h2>
We call Hub servers those which run the user web interfaces and
optionally threshold monitors. These are normally placed in the central
location or NOC datacenter.
Spoke servers are those running SNMP or other data collectors.
They periodically transfer the data to Hub servers. One Spoke
server may send copies of data to several Hub servers, and one
Hub server may receive data from many Spoke servers.
In general, the property of being a Hub or a Spoke is local to a pair
of servers and their datasource trees, and it only describes the functions
of data collection and transfer. In complex installations, the same
instance of RRFW may function as a Hub for some remote Spokes, and as a
Spoke for some other Hubs simultaneousely.
We call Association a set of attributes that describe a single connection
between Hub and Spoke servers. These attributes are:
<ul>
<li><a name="item_association_id">Association ID</a> 
</li>
Unique symbolic name across the whole range of interconnected servers.

<li><a name="item_hub_server_id_2c_spoke_server_id">Hub server ID, Spoke server ID</a> 
</li>
Names of the servers, usually hostnames.

<li><a name="item_transport_type">Transport type</a> 
</li>
One of SSH, RSH, HTTP, etc.

<li><a name="item_transport_mode">Transport mode</a> 
</li>
PUSH or PULL

<li><a name="item_transport_parameters">Transport parameters</a> 
</li>
Parameters needed for this transport connection, like login name, password,
URL, etc.

<li><a name="item_compression_type_and_level">Compression type and level</a> 
</li>
Optional, gzip or bzip2 or something else, with compression levels from 1 to 9.

<li><a name="item_tree_name_on_hub_server">Tree name on Hub server</a> 
</li>
Target datasource tree that will receive data from Spokes

<li><a name="item_subtree_path_on_hub_server">Subtree path on Hub server</a> 
</li>
The data updates from this association will be placed in a subtree
under the specified path.

<li><a name="item_tree_name_on_spoke_server">Tree name on Spoke server</a> 
</li>
The tree where a collector runs and stores data into this association.

<li><a name="item_path_translation_rules">Path translation rules</a> 
</li>
Datasource paths from Spoke server may be changed to look different
in the tree of Hub server.
</ul>


<h2><a name="transport">Transport</a></h2>
The modular architecture design should allow different types of data
transfer. The default transport is Secure Shell version 2 (SSH). Other
possible transports may be RSH, HTTP/HTTPS, rsync.
Two transport modes should be implemented: PUSH and PULL.
In PUSH mode, Spoke servers initiate the data transfer and push the data to
Hub servers. In PULL mode, Hub servers initiate the data
transfer and ask Spokes for data updates. It should be possible
to mix the transport modes for different Associations on the same
server, but within each Association the mode should be strictly
determined. The choice of transport mode should be based on local security
policies, and server and network performance.
Optionally the compression method and level can be configured. Although
SSH protocol supports its own compression, more aggressive compression
methods may be used for the sake of better bandwidth usage.
Transport agents should notify the operator in cases of delivery failures.


<h2><a name="operation">Operation</a></h2>
For Spoke servers, distributed data transfer will be implemented as
additional storage type. For Hub servers, this will be a new collector
type.
Each data transfer is a concatenation of messages. Messages
may be of one of two types: CONFIG and DATA. Spoke server generates
the messages and stores them for the transfer. Messages are delivered
to Hub servers with a certain delay, but they are guaranteed to
arrive in sequential order. For each pair of servers, messages are
consecutively numbered. These numbers are used for failure detection.
A Spoke server keeps track of its configuration, and after each
configuration change, it sends a CONFIG message. This message contains
information about mapping between Spoke server tokens and datasource paths,
and a limited set of parameters for displaying and monitoring the data.
After each collector cycle, Spoke server sends DATA messages.
These messages contain the following information: timestamp of the
update, token, and value. The format of the message should be designed
to consume minimum bandwidth.
Hub server picks up the messages delivered by the transport agents.
Upon receiving a CONFIG message, it sets a preconfigured delay, in order
to collect as many as possible CONFIG messages. Then the data transfer agent
generates a new XML configuration based on the messages, and starts
the compilation of configuration. The DATA messages are queued for the
collector to pick up and and store the values. It must be ensured that
all DATA messages queued for the old configuration are processed before
the compilation starts.
In case of fatal failure and loss of data, Hub server ignores all DATA
messages until it gets a new CONFIG message. A periodic configuration update
schedule should be defined. If no configuration changes occur within a
certain period of time, Spoke server periodically sends the CONFIG messages
with the same timestamp.


<h2><a name="message_format">Message format</a></h2>
Message is a text in email-like format: it starts with a header, followed by
an empty line and the body. Single dot (.) in a line specifies the end of
the message. Blocks within a CONFIG message are separated with semicolon (;),
each block representing a single datasource leaf.
Example:
<pre>
 MsgID:100001
 Type:CONFIG
 Timestamp:1085528682</pre>
<pre>
 level2-token:T0005
 level2-path:/Routers/RTR1/Interface_Counters/Ethernet0/InOctets
 vertical-label:bps
 ....
 ;
 level2-token:T0006
 level2-path:/Routers/RTR1/Interface_Counters/Ethernet0/OutOctets
 vertical-label:bps
 .
 MsgID:100002
 Type:DATA
 Timestamp:1085528690</pre>
<pre>
 T0005:12345678
 T0006:987654321
 .</pre>


<hr />
<h1><a name="author">Author</a></h1>
Copyright (c) 2004 Stanislav Sinyagin &lt;<a href="mailto:ssi...@ya...">ssi...@ya...</a>&gt;

</body>

</html>

--- NEW FILE: wd.messaging.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW Working Draft: Messaging subsystem</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_working_draft__messaging_subsystem">RRFW Working Draft: Messaging subsystem</a></li>
	<ul>

		<li><a href="#introduction">Introduction</a></li>
		<li><a href="#description">Description</a></li>
	</ul>

	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />


<h1><a name="rrfw_working_draft__messaging_subsystem">RRFW Working Draft: Messaging subsystem</a></h1>
Status: pending implementation.
Date: Jun 30 2004. Last revised:


<h2><a name="introduction">Introduction</a></h2>
Due to the modular and flexible architecture of RRFW, nothing prevents
us from having the possibility of user messages displayed in RRFW pages.
This design document describes the concept of this functionality.


<h2><a name="description">Description</a></h2>
The messaging subsystem will allow the RRFW users to leave comments and
short messages directly at the RRFW pages. Those may be remarks about the
graph contents, troubleshooting journal, etc.
Each user is uniquely identified by RRFW ACL susbsystem. We introduce several
new attributes and privileges for messaging functionality. Privilege objects
are the tree names.
Attributes:
<ul>
<li><a name="item_email">email</a> 
</li>
The user's e-mail where the notifications will be sent

<li><a name="item_msgnotify">msgnotify</a> 
</li>
When set to true value, e-mail notifications will be sent to this users.
</ul>
Privileges:
<ul>
<li><a name="item_postmessages">PostMessages</a> 
</li>
allows the user to add messages to the tree objects.

<li><a name="item_displaymessages">DisplayMessages</a> 
</li>
allows the user to see all messages for the tree

<li><a name="item_receivenotifications">ReceiveNotifications</a> 
</li>
allows the user to receive e-mail notifications. For those notifications
generated by Messages, <a href="#item_displaymessages"><code>DisplayMessages</code></a> must be granted too.

<li><a name="item_deletemessages">DeleteMessages</a> 
</li>
allows the user to delete messages from the tree objects

<li><a name="item_editmessages">EditMessages</a> 
</li>
allows the user to change any message

<li><a name="item_editownmessages">EditOwnMessages</a> 
</li>
allows the user to change his/her own messages
</ul>
The <code>acledit</code> program will have two additional options that simplify
administration: <code>--msguser</code> will grant all privileges except <a href="#item_deletemessages"><code>DeleteMessages</code></a>
and <a href="#item_editmessages"><code>EditMessages</code></a>, and <code>--msgadmin</code> will grant all messaging privileges.
The messaging options database will contain parameters that each user can tune
for himself or herself:
<ul>
<li><a name="item_notify_when">Notify when</a> 
</li>
a) any new message in all trees; b) (default) new message for
objects that I commented only.

<li><a name="item_notification_format">Notification format</a> 
</li>
a) plain text (default); b) HTML; c) RSS 2.0

<li><a name="item_subject_line_format">Subject line format</a> 
</li>
The format pattern with keywords like <code>$TREE</code>, <code>$PATH</code>, <code>$AUTHOR</code>,
<code>$MSGID</code>, etc.
Default:
<pre>
 [rrfw $MSGID] $TREE $AUTHOR: $PATH</pre>
</ul>
Each message will have the status of Read/Unread per each user in the system.
On the tree chooser page in RRFW Web interface, the user will be shown
the unread messages.
RRS 2.0 feed will be provided for messages export and for integration with
other messaging systems.


<hr />
<h1><a name="author">Author</a></h1>
Copyright (c) 2004 Stanislav Sinyagin &lt;<a href="mailto:ssi...@ya...">ssi...@ya...</a>&gt;

</body>

</html>

--- NEW FILE: torrus_roadmap.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW to Torrus transition roadmap</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_to_torrus_transition_roadmap">RRFW to Torrus transition roadmap</a></li>
	<ul>

		<li><a href="#introduction">Introduction</a></li>
		<li><a href="#releases_roadmap">Releases roadmap</a></li>
		<li><a href="#multiple_xml_cofiguration_directories">Multiple XML cofiguration directories</a></li>
		<li><a href="#separated_directories_for_templates_and_configuration">Separated directories for templates and configuration</a></li>
		<li><a href="#commandline_launcher">Commandline launcher</a></li>
		<li><a href="#new_directory_hierarchy">New directory hierarchy</a></li>
		<ul>

			<li><a href="#default_layout">Default layout</a></li>
			<li><a href="#fhs_compliant_layout">FHS compliant layout</a></li>
		</ul>

		<li><a href="#new_plugins_design">New plugins design</a></li>
		<li><a href="#authors">Authors</a></li>
	</ul>

</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="rrfw_to_torrus_transition_roadmap">RRFW to Torrus transition roadmap</a></h1>
<p>
</p>
<h2><a name="introduction">Introduction</a></h2>
<p>The name ``RRFW'' appeared to be quite difficult to remember and to pronounce.
There has been a call for a new name, and recently a good suggestion came
from Francois Mikus:</p>
<pre>
    --- Francois Mikus &lt;fmikus[at]acktomic.com&gt; wrote:
    &gt; Here is my humble flash, which I think may be appropriate. Which I will 
    &gt; explain why below...
    &gt; 
    &gt; The name I would suggest is;
    &gt; 
    &gt; Torrus
    &gt; 
    &gt; Has a mythical sounding name without the actual history. Has a resonance 
    &gt; with Torrent, where rrfw deals with a torrent of information. A google 
    &gt; search comes up with near nothing, and nothing commercial. Has a 
    &gt; resonance with Taurus, which is mythical, astrological and has an 
    &gt; underlying strength connotation.
    &gt; 
    &gt; Anyway, this is the best I could think of. And it provides an opening to 
    &gt; have a semi-mythical/comic style yet serious mascot.
    &gt; 
    &gt; You have a LOT of documentation. web pages, code, etc.. But marketing is 
    &gt; the way to win hearts and minds, create a following and get rabid 
    &gt; developpers on-board!</pre>
<p>Thus the project will be renamed to Torrus, and few other structural changes
will accompany the transition.</p>
<p>
</p>
<h2><a name="releases_roadmap">Releases roadmap</a></h2>
<p>Version 0.1.8 will be the last of RRFW, unless some urgencies arise.</p>
<p>The first Torrus release will be 1.0.0.</p>
<p>
</p>
<h2><a name="multiple_xml_cofiguration_directories">Multiple XML cofiguration directories</a></h2>
<p>During XML compilation, the datasource configuration files will be searched in
multiple directories. The list of directories and the search sequence
will be configurable. This will allow not to mix the distribution XML files
and the ones created locally.</p>
<p>
</p>
<h2><a name="separated_directories_for_templates_and_configuration">Separated directories for templates and configuration</a></h2>
<p>Perl configuration files and HTML templates will also be separated into
different directories, so that user-editable files don't mix with the
ones from distribution.</p>
<p>
</p>
<h2><a name="commandline_launcher">Commandline launcher</a></h2>
<p>A small shell script will be installed as <code>/usr/local/bin/torrus</code>,
and it will pass all arguments to appropriate torrus executables. For example,</p>
<pre>
  torrus compile --tree=main</pre>
<p>will execute <code>compilexml</code> torrus utility with the argument <code>--tree=main</code>.</p>
<p>
</p>
<h2><a name="new_directory_hierarchy">New directory hierarchy</a></h2>
<p>Filesystem Hierarchy Standard &lt;<a href="http://www.pathname.com/fhs/">http://www.pathname.com/fhs/</a>&gt;
proposes to put the software add-on packages into <code>/opt</code> directory
and user services data, such as database contents or RRD files, in
<code>/srv</code> directory.</p>
<p>However, FreeBSD and some other systems are not FHS-compliant, and require
to install all additional software into <code>/usr/local</code> hierarchy.</p>
<p>We propose that Torrus distribution will support three different directory
layouts, and the system administrator will decide the most suitable one:</p>
<ol>
<li></li>
Default layout based in <code>/usr/local</code>;
<p></p>
<li></li>
FHS compliant layout, set by running <code>./configure_fhs</code> instead
of <code>./configure</code>;
<p></p>
<li></li>
Custom layout, tunable with standard options and variables in <code>./configure</code>.
<p></p></ol>
<p>
</p>
<h3><a name="default_layout">Default layout</a></h3>
<p>Although many systems like FreeBSD discourage creation of new
package-specific subdirectories in /usr/local, we find it quite a common
practice, and quite convenient for keeping the files together.</p>
<pre>
  /usr/local/torrus/    Home directory for Torrus distribution files
        |
        +- conf_defaults/  torrus-config.pl and others
        |
        +- bin/         Command-line executables
        |
        +- doc/         POD and TXT documentation files
        |
        +- examples/    Miscelaneous example files
        |
        +- perllib/     Perl libraries
        |
        +- plugins/     Plugins configuration
        |
        +- scripts/     Scripts
        |
        +- sup/         Supplementary files, DTDs, MIBs, color schemas,
        |               Web plain files
        |
        +- templates/   Renderer output templates
        |
        +- xmlconfig/   Distrubution XML files</pre>
<pre>
  /usr/local/etc/torrus/   Site configurable files
        |
        +- conf/        Place for torrus-siteconfig.pl and other siteconfigs
        |
        +- discovery/   Devdiscover input files
        |
        +- templates/   User-defined Renderer output templates
        |
        +- xmlconfig/   User XML configuration files</pre>
<pre>
  /usr/local/man/       Place for man pages. All articles will have the
                        prefix C&lt;torrus_&gt;</pre>
<pre>
  /var/log/torrus/      Daemon logfiles</pre>
<pre>
  /var/run/torrus/      Daemon PID files</pre>
<pre>
  /var/torrus/cache/    Renderer cache</pre>
<pre>
  /var/torrus/db/       Configuration databases</pre>
<pre>
  /var/torrus/session_data/  Web interface session files</pre>
<pre>
  /srv/torrus/collector_rrd/  Default directory for collector
                              generated RRD files</pre>
<p>
</p>
<h3><a name="fhs_compliant_layout">FHS compliant layout</a></h3>
<pre>
  /opt/torrus/          Home directory for Torrus distribution files
        |
        +- conf_defaults/  torrus-config.pl and others
        |
        +- bin/         Command-line executables
        |
        +- doc/         POD and TXT documentation files
        |
        +- examples/    Miscelaneous example files
        |
        +- perllib/     Perl libraries
        |
        +- plugins/     Plugins configuration
        |
        +- scripts/     Scripts
        |
        +- sup/         Supplementary files, DTDs, MIBs, color schemas
        |
        +- templates/   Renderer output templates
        |
        +- xmlconfig/   Distrubution XML files</pre>
<pre>
  /etc/opt/torrus/   Site configurable files
        |
        +- conf/        Place for torrus-siteconfig.pl and other siteconfigs
        |
        +- discovery/   Devdiscover input files
        |
        +- xmlconfig/   User XML configuration files</pre>
<pre>
  /opt/torrus/share/man/  Place for man pages. All articles will have the
                          prefix C&lt;torrus_&gt;</pre>
<pre>
  /var/log/torrus/      Daemon logfiles</pre>
<pre>
  /var/run/torrus/      Daemon PID files</pre>
<pre>
  /var/torrus/cache/    Renderer cache</pre>
<pre>
  /var/torrus/session_data/  Web interface session files</pre>
<pre>
  /srv/torrus/db/       Configuration databases</pre>
<pre>
  /srv/torrus/collector_rrd/  Default directory for collector
                              generated RRD files</pre>
<p>
</p>
<h2><a name="new_plugins_design">New plugins design</a></h2>
<p>Unlike RRFW, the plugins in Torrus will be installed independently.
This will allow to easily add new plugins to an existing installation.</p>
<p>The Torrus installer stores all important variable settings in a special
file, <em>conf_defaults/instvars</em>. Then the plugin installer is able
to access the settings without accessing the Torrus distribution
directory.</p>
<p>There is a helper utility, <code>install_plugin</code>, which applies all
<em>configure</em> variables to the plugin configuration utility.
It follows then the standard installation way:</p>
<pre>
 ./configure &amp;&amp; make &amp;&amp; make install</pre>
<p>Thus the OS-dependent package installators may follow the standard
configuration procedure, while those who manually install the software,
will use the helper.</p>
<p>There are two special directories: <em>/usr/local/torrus/plugins/torrus-config</em>
and <em>/usr/local/torrus/plugins/devdiscover-config</em>. Plugins are
allowed to add Perl files there. They will be automatically <em>require</em>'d by
<em>torrus-config.pl</em> and <em>devdiscover-config.pl</em>.</p>
<p>
</p>
<h2><a name="authors">Authors</a></h2>
<p>Copyright (c) 2004 Stanislav Sinyagin</p>

</body>

</html>

--- NEW FILE: reqs.0.1.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW Requirements Version 0.1</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_requirements_version_0_1">RRFW Requirements Version 0.1</a></li>
	<li><a href="#independent_datasource_trees">Independent datasource trees</a></li>
	<ul>

		<li><a href="#changes_in_rrfwsiteconfig_pl">Changes in rrfw-siteconfig.pl</a></li>
		<li><a href="#configtree_object_internals">ConfigTree object internals</a></li>
		<li><a href="#database_structure">Database structure</a></li>
		<li><a href="#user_interface">User interface</a></li>
		<li><a href="#daemons_launch_master">Daemons launch master</a></li>
	</ul>

	<li><a href="#separate_database_for_nondatasource_objects">Separate database for non-datasource objects</a></li>
	<li><a href="#user_privileges">User privileges</a></li>
	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="rrfw_requirements_version_0_1">RRFW Requirements Version 0.1</a></h1>
<p>Date: Jun 29 2003; Last revised: Aug 05 2003</p>
<p>In this article, I describe the important changes that are planned
for RRFW version 0.1.X.</p>
<p>
</p>
<hr />
<h1><a name="independent_datasource_trees">Independent datasource trees</a></h1>
<p>As noted by many users, RRFW lacks the scalability when the number of
network devices is more than 100. The XML compiler takes minutes to
process the configuration, and the Collector process initialization time
is too long.</p>
<p>Christian Schnidrig &lt;<a href="mailto:chr...@gm...">chr...@gm...</a>&gt; has proposed
a solution to split the database into several subsystems, each
being compiled separately, and with separate collector process.
In his concept, there is a ``global'' datasource tree, and
``subsystem'' trees, each making a subset of global datasource nodes.</p>
<p>I propose to have a number of independent datasource trees, without
any superset. This would ease the administrator's work, and add more
security.</p>
<p>
</p>
<h2><a name="changes_in_rrfwsiteconfig_pl">Changes in rrfw-siteconfig.pl</a></h2>
<p>Instead of <code>@RRFW::Global::xmlFiles</code>, the following hash will contain
the information about the trees:</p>
<pre>
  %RRFW::Global::treeConfig = (
    'tree_A' =&gt; {
      'description' =&gt; 'The First Tree',
      'xmlfiles' =&gt; ['a1.xml', 'a2.xml', 'a3.xml'],
      'run' =&gt; { 'collector' =&gt; 1, 'monitor' =&gt; 1 } },
    'tree_B' =&gt; {
      'description' =&gt; 'The Second Tree',
      'xmlfiles' =&gt; ['b1.xml', 'b2.xml'],
      'run' =&gt; {} }
   );</pre>
<p>In this hash, the keys give the tree names, <em>xmlfiles</em> points to an array
of source XML files, <em>run</em> points to the names of the daemons that
would be automatically launched for the tree.</p>
<p>Two additional arrays: <code>@RRFW::Global::xmlAlwaysIncludeFirst</code> and
<code>@RRFW::Global::xmlAlwaysIncludeLast</code> will give a list of source XML
files that are included in every tree, in the beginning or in the end of
the XML files list.</p>
<p>
</p>
<h2><a name="configtree_object_internals">ConfigTree object internals</a></h2>
<p>There will be no such thing as globalInstance. All methods and procedures
that need to reference the current ConfigTree object will have it as
argument.</p>
<p><code>RRFW::ConfigTree::new()</code> will have a mandatory argument ``TreeName''.</p>
<p>
</p>
<h2><a name="database_structure">Database structure</a></h2>
<p>All datasource trees will share one BerkeleyDB environment. The
BDB environment home directory will stay the same, defined by <em>dbhome</em>
config variable.</p>
<p>For each tree, the database files will be placed in a separate subdirectory
of a subdirectory of <em>dbhome</em>.</p>
<p>
</p>
<h2><a name="user_interface">User interface</a></h2>
<p>All relevant command-line executables will support the following
options:</p>
<ul>
<li><strong><a name="item__2d_2dtree__3ctree_name_3e">--tree &lt;tree_name&gt;</a></strong><br />
</li>
Specifies the datasource tree for processing;
<p></p>
<li><strong><a name="item__2d_2dall">--all</a></strong><br />
</li>
If applicable, performs the operation on all available trees.
<p></p></ul>
<p>When in verbose mode (<strong>--verbose</strong>), the command-line programs must
print the tree names they operate with.</p>
<p>The web interface will take the PATH_INFO string as the tree name.
For mod_perl handler, it will be also possible to prohibit
PATH_INFO selection, and to configure the tree name in Apache
configuration.</p>
<p>When no PATH_INFO is given to the web interface handler,
a special superlevel menu may be shown with the list of available trees.</p>
<p>It will also be possible to specify tree-specific renderer attributes, like
<code>%RRFW::Renderer::styling</code>, <code>$RRFW::Renderer::companyName</code>, etc.</p>
<p><strong>Plain CGI interface will not be supported</strong> As Renderer gets more complex,
CGI initialization time will increase. Also it will become harder to support
two user interfaces with similar functionality.</p>
<p>
</p>
<h2><a name="daemons_launch_master">Daemons launch master</a></h2>
<p>There will be a master process that will launch collector and monitor
daemons for each tree. It will be configurable from a separate file,
specifying the daemons and execution parameters for each tree.</p>
<p>The master process will watch the child processes and issue warnings in the
events of child process termination.</p>
<p>Stopping the master process will stop all child daemons gracefully.</p>
<p>
</p>
<hr />
<h1><a name="separate_database_for_nondatasource_objects">Separate database for non-datasource objects</a></h1>
<p>In RRFW version 0.0.X, all the parameters for datasources, views,
monitors, and tokensets are stored in <em>configuration.db</em> database.</p>
<p>As proposed by Christian Schnidrig, storing all non-datasource
objects information in a separate database would improve the scalability.</p>
<p>In RRFW version 0.1.X, datasource parameters will be stored in
<em>ds_config.db</em>, and all other object's parameters in <em>other_config.db</em>.</p>
<p>The XML compiler will have a new option, <strong>--nods</strong>, which disables
processing of &lt;datasources&gt; elements in the input XML files.</p>
<p>In addition to <code>ConfigurationReady</code> flag, there will be a flag that indicates
the readiness of datasource tree only.</p>
<p>All these measures will allow faster administration and testing of
non-datasource objects, and will prevent the collector from unneeded
interruptions.</p>
<p>
</p>
<hr />
<h1><a name="user_privileges">User privileges</a></h1>
<p>User privileges will apply to the tree level: across one datasource tree
a given user will have uniform privileges.</p>
<p>Each user belongs to one or more groups. Privileges are assigned to
groups only, not to individual users. Groups are one-level deep: they
consist of users only. Probably in the future groups will consist
of groups too.</p>
<p>In the beginning, only one privilege will be implemented: <em>DisplayTree</em>.
The design should be flexible enough to add more privileges in the future.
Examples: <em>GenerateReport</em>, <em>Debug</em>, <em>ScheduleTask</em>, and so on.</p>
<p>Privileges maintenance interface will include a command-line utility.
In the future, a web interface is also possible. In this case, a new
privilege will be added: <em>EditPrivileges</em>.</p>
<p>Privileges editor will include the following functions:</p>
<ul>
<li><strong><a name="item_add_2fdelete_group">add/delete group</a></strong><br />
</li>
<li><strong><a name="item_add_2fdelete_user">add/delete user</a></strong><br />
</li>
<li><strong><a name="item_change_user_password">change user password</a></strong><br />
</li>
<li><strong><a name="item_add_2fdelete_user_membership_in_a_group">add/delete user membership in a group</a></strong><br />
</li>
<li><strong><a name="item_edit_privileges_for_groups_and_trees">edit privileges for groups and trees</a></strong><br />
</li>
<li><strong><a name="item_list_group_members">list group members</a></strong><br />
</li>
<li><strong><a name="item_list_groups_a_user_belongs_to">list groups a user belongs to</a></strong><br />
</li>
<li><strong><a name="item_list_privileges_for_a_given_group_or_user">list privileges for a given group or user</a></strong><br />
</li>
<li><strong><a name="item_groups">list privileges and groups (or users) for a given tree</a></strong><br />
</li>
<li><strong><a name="item_export_2fimport_the_privileges_database_to_2ffrom_">export/import the privileges database to/from XML</a></strong><br />
</li>
</ul>
<p>Privileges logics implementation must be separate from the database backend.
At first, BerkeleyDB backend will be supported. In the future, LDAP
backend is possible.</p>
<p>
</p>
<hr />
<h1><a name="author">Author</a></h1>
<p>Copyright (c) 2003 Stanislav Sinyagin <a href="mailto:ssi...@ya...">ssi...@ya...</a></p>

</body>

</html>

--- NEW FILE: wd.monitor-escalation.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW Working Draft: Monitor escalation levels</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_working_draft__monitor_escalation_levels">RRFW Working Draft: Monitor escalation levels</a></li>
	<ul>

		<li><a href="#introduction">Introduction</a></li>
		<li><a href="#monitor_events">Monitor events</a></li>
		<li><a href="#monitor_parameters">Monitor parameters</a></li>
		<li><a href="#action_parameters">Action parameters</a></li>
		<li><a href="#implementation">Implementation</a></li>
	</ul>

	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="rrfw_working_draft__monitor_escalation_levels">RRFW Working Draft: Monitor escalation levels</a></h1>
<p>Status: pending implementation.
Date: Nov 5 2003. Last revised: Nov 10 2003</p>
<p>
</p>
<h2><a name="introduction">Introduction</a></h2>
<p>The initial idea comes from Francois Mikus in Cricket development team.
His proposal was to raise the alarm only after several true consecutive
monitor conditions.</p>
<p>The idea has developed into the concept of escalation levels.</p>
<p>
</p>
<h2><a name="monitor_events">Monitor events</a></h2>
<p>Current implementation supports four types of monitor events: <code>set</code>,
<code>repeat</code>, <code>clear</code>, and <code>forget</code>. New event type will be <code>escalate(X)</code>.
<code>X</code> designates a symbolic name for a certain escalation level. Each level
is associated with the escalation time interval.</p>
<p>Given <code>Te</code> as the escalation interval, <code>Ta</code> as the monitor condition age,
and <code>P</code> as period, the escalation event will occur simultaneously with
one of <code>repeat</code> events, when the following condition is true:</p>
<pre>
  Te &gt;= Ta</pre>
<p>New event types <code>clear(X)</code> and <code>forget(X)</code> will occur at the same
time as <code>clear</code> and <code>forget</code> respectively,
for each escalated level.</p>
<p>
</p>
<h2><a name="monitor_parameters">Monitor parameters</a></h2>
<p>New parameter will be introduced: <code>escalation</code>. Value will
be a comma-separated list of <code>name=interval</code> parts, where <code>name</code>
designates the escalation level, and <code>interval</code> specifies the escalation
interval in seconds.</p>
<p>Example:</p>
<pre>
  &lt;monitor name=&quot;rate-limits&quot;&gt;
    &lt;param name=&quot;escalation value=&quot;Medium=1800, High=7200, Critical=14400&quot; /&gt;
    ...
  &lt;/monitor&gt;</pre>
<p>Another example would be Cisco TAC style priorities: P3, P2, P1.</p>
<p>
</p>
<h2><a name="action_parameters">Action parameters</a></h2>
<p><code>launch-when</code> parameter will be valid not for <code>exec</code> actions only, but also
for <code>tset</code> actions. New valid values will be <code>escalate(X)</code>, <code>clear(X)</code>,
and <code>forget(X)</code>.</p>
<p>XML configuration validator will not verify if escalation levels in
action definition match those in datasource configuration.</p>
<p>New optional action parameter: <code>allowed-time</code>. Contains an RPN expression
which must be true at the time when the action is allowed to execute.
Two new RPN functions may be used here: <code>TOD</code> and <code>DOW</code>.</p>
<p><code>TOD</code> returns the current time of day as integer: <code>HH*100+MM</code>. For example,
830 means 8:30 AM, and 1945 means 7:45 PM.</p>
<p><code>DOW</code> returns the current day of the week as integer between and including
0 and 6, with 0 corresponding to Sunday, 1 to Monday, and 6 to Saturday.</p>
<p>In this example, the action is allowed between 8 AM and 6 PM from Monday
to Friday:</p>
<pre>
  &lt;param name=&quot;allowed-time&quot;&gt;
    TOD,800,GE, TOD,1800,LE, AND,
    DOW,1,GE, AND,
    DOW,5,LE, AND
  &lt;/param&gt;</pre>
<p>
</p>
<h2><a name="implementation">Implementation</a></h2>
<p><strong>monitor_alarms.db</strong> database format will change: The values will consist
of five colon-separated fields. The first four fields will be as earilier,
and the fifth one will be a comma-separated list of escalation level names
that have already fired.</p>
<p>The implementation of this feature is preferred after the planned redesign of
the monitor daemon. The new monitor design would support individual
schedule for each datasource leaf, analogous to collector schedules.</p>
<p>In turn, the monitor daemon  redesign is better to do after
the collector daemon redesign. Then it would allow to keep similar design
and architecture where possible.</p>
<p>
</p>
<hr />
<h1><a name="author">Author</a></h1>
<p>Copyright (c) 2003 Stanislav Sinyagin &lt;<a href="mailto:ssi...@ya...">ssi...@ya...</a>&gt;</p>

</body>

</html>

--- NEW FILE: wd.uptime-mon.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW Working Draft: Service uptime monitoring and reporting</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_working_draft__service_uptime_monitoring_and_reporting">RRFW Working Draft: Service uptime monitoring and reporting</a></li>
	<ul>

		<li><a href="#definitions">Definitions</a></li>
		<li><a href="#event_datasource_type">Event datasource type</a></li>
		<li><a href="#event_summary_reports">Event summary reports</a></li>
		<li><a href="#events_generation">Events generation</a></li>
	</ul>

	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />


<h1><a name="rrfw_working_draft__service_uptime_monitoring_and_reporting">RRFW Working Draft: Service uptime monitoring and reporting</a></h1>
Status: in pre-design phase.
Date: Sep 26 2003; Last revised:


<h2><a name="definitions">Definitions</a></h2>
It is often required to monitor the service level in networks.
Service level is normally covered by Service Level Agreement (SLA),
which defines the following parameters:
<ul>
<li><a name="item_service_definition">Service definition</a> 
</li>
Describes the particular service in terms of functionality and means of
monitoring. Examples are: IP VPN connectivity, WAN uplink, SQL database engine.

<li><a name="item_maintenance_window">Maintenance window</a> 
</li>
Describes the periodic time intervals when service outage is possible
due to some maintenance work. It may be unconditional (outage is always
possible within the window), or conditional (customer confirmation required
for outage within the window). Notification period is normally defined
for maintenance outages.
Example: every 1st Tuesday of the month between 6AM and 8 AM, with 96 hours
notification time.

<li><a name="item_outage_types">Outage types</a> 
</li>
Outages may be caused by: 1). system failure; 2). service provider's
infrastructure failure; 3). customer activity.

<li><a name="item_service_level_objectives">Service level objectives</a> 
</li>
These are the guarantees that the sevice provider gives to the customer.
Violation of these guarantees is compensated by penalties defined.
These may include: Maxium maintenance downtime per specified period;
Maximum downtime period due to failures on the service provider side;
Minimum service availability per specified period.
</ul>


<h2><a name="event_datasource_type">Event datasource type</a></h2>
In order to store the service level information, we need a new datasource
type in RRFW: event. It represents an atomic information
about a single event in time, e.g. it canot be devided into more specific
elements or sub-events. Its attributes are as follows:
<ul>
<li><a name="item_event_group_name">Event group name</a> 
</li>
Several events belong to one and only one group. Event group is a unique
entity that describes the service.

<li><a name="item_event_name">Event name</a> 
</li>
Unique name within the event group. Describes the type of the event, such as
<code>maintenance</code>, <code>downtime</code>. Events with the same names cannot overlap in
time.

<li><a name="item_start_time">Start time</a> 
</li>
Timestamp of the event start.

<li><a name="item_duration">Duration</a> 
</li>
Positive integer that specifies the length of the event in seconds.
Zero duration means that the event has not yet finished.

<li><a name="item_parameters">Parameters</a> 
</li>
Event-specific (name, value) pairs.
</ul>
Events are uniquely identified by (Event group, Event name, Start time)
triple.


<h2><a name="event_summary_reports">Event summary reports</a></h2>
Renderer should be able to display the events at different summary levels
and in different combinations. Event reports should be specified by
expressions, as follows:
<ul>
<li><a name="item_boolean_operators">Boolean operators</a> 
</li>
<code>downtime AND NOT maintenance</code>.

<li><a name="item_time_period">Time period</a> 
</li>
<code>(downtime AND NOT maintenance)[-2DAYS,NOW]</code>
<code>(downtime[-2DAYS,NOW] AND NOT maintenance AND
NOT downtime[200309151200,200309151300])</code>

<li><a name="item_arithmetic_operations">Arithmetic operations</a> 
</li>
Sum of durations, substract of durations...
</ul>


<h2><a name="events_generation">Events generation</a></h2>
Events may be generated by the following sources:
<ul>
<li><a name="item_collector">Collector</a> 
</li>
SNMP collector may create events on some faulty conditions, like host
unreacheable, or on SNMP variables change, like interface status.
Also it's possible to create an ICMP Echo collector type,
which would generate events based on pinging the hosts.

<li><a name="item_monitor">Monitor</a> 
</li>
Obviously, a new monitor action will be to create events.

<li><a name="item_human_operator">Human operator</a> 
</li>
First from commandline interface, and later from thr Web interface,
the human operators may create the scheduled events, like maintenance
outages. Security policy should protect certain types of events
from human intervention.
</ul>


<hr />
<h1><a name="author">Author</a></h1>
Copyright (c) 2003 Stanislav Sinyagin &lt;<a href="mailto:ssi...@ya...">ssi...@ya...</a>&gt;

</body>

</html>

--- NEW FILE: progstyle.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW Programming Style Guide</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_programming_style_guide">RRFW Programming Style Guide</a></li>
	<ul>

		<li><a href="#perl_indentation_style">Perl indentation style</a></li>
		<li><a href="#common_file_properties">Common file properties</a></li>
		<li><a href="#gnu_emacs_settings">GNU Emacs settings</a></li>
		<li><a href="#xemacs_settings">X-Emacs settings</a></li>
		<li><a href="#normalizing_multiple_files">Normalizing multiple files</a></li>
	</ul>

	<li><a href="#author">Author</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="rrfw_programming_style_guide">RRFW Programming Style Guide</a></h1>
<p>
</p>
<h2><a name="perl_indentation_style">Perl indentation style</a></h2>
<p>The indentation style is a kind of BSD/Allman style:</p>
<pre>
    while( not $success and time() &lt; $waitingTimeout )
    {
        $self-&gt;clearReader();</pre>
<pre>
        Info('Sleeping ' . $RRFW::Global::ConfigReadyRetryPeriod .
              ' seconds');
        sleep $RRFW::Global::ConfigReadyRetryPeriod;</pre>
<pre>
        $self-&gt;setReader();</pre>
<pre>
        if( $self-&gt;isReady() )
        {
            $success = 1;
            Info('Now configuration is ready');
        }
        else
        {
            Info('Configuration is still not ready');
        }
    }</pre>
<p>Indentation is 4 characters. Opening and closing braces are aligned.
There's no space between the keyword (<code>while</code>, <code>if</code>, etc.) and the opening
parenthesis.</p>
<p>Tab characters are prohibited.</p>
<p>Page width is strictly 80 characters. All longer lines must be wrapped.</p>
<p>When possible, leave space between parentheses and the inside content.
This is not necessary for debug or print statements.</p>
<p>There's always space around the equal sign (<code>=</code>).</p>
<p>The object method calls always have parentheses, even if no arguments are
reqiured.</p>
<p>Use keywords for logical operations instead of C operators: <code>and</code>, <code>or</code>,
<code>not</code>.</p>
<p>Use single quotes in hash references: <code>$a-&gt;{'abc'}</code>.</p>
<p>
</p>
<h2><a name="common_file_properties">Common file properties</a></h2>
<p>With the exception of special-purpose files, each source file
must ontain the GNU copying statement, CVS <code>Id</code> tag, and author's name and
e-mail address.</p>
<p>C, Perl, and Bourne shell files must contain Gnu Emacs variables
at the end of the file:</p>
<pre>
 # Local Variables:
 # mode: perl
 # indent-tabs-mode: nil
 # perl-indent-level: 4
 # End:</pre>
<p>Each file must always end with the linebreak. Otherwise it might conflict
with CVS. All files must have Unix linebreak format.</p>
<p>
</p>
<h2><a name="gnu_emacs_settings">GNU Emacs settings</a></h2>
<p>Standard <code>perl-mode.el</code> does the thing:</p>
<pre>
 ;; Set up Perl mode
 (autoload 'perl-mode &quot;perl-mode&quot;)
 (setq auto-mode-alist
     (append (list (cons &quot;\\.pl$&quot; 'perl-mode)
                   (cons &quot;\\.pm$&quot; 'perl-mode)
                   (cons &quot;\\.pl\\.cgi$&quot; 'perl-mode))
             auto-mode-alist))</pre>
<pre>
 (custom-set-variables
   ;; custom-set-variables was added by Custom -- don't edit or cut/paste it!
   ;; Your init file should contain only one such instance.
  '(indent-tabs-mode nil)
  '(tab-width 8)
  )</pre>
<p>
</p>
<h2><a name="xemacs_settings">X-Emacs settings</a></h2>
<p>In X-Emacs, the default handler for Perl files is <code>cperl-mode.el</code>.
The following custom variables must be set in order to comply to our styling
standards:</p>
<pre>
 (custom-set-variables
   ;; custom-set-variables was added by Custom -- don't edit or cut/paste it!
   ;; Your init file should contain only one such instance.
  '(cperl-brace-offset -4)
  '(cperl-continued-statement-offset 4)
  '(cperl-indent-level 4)
  '(indent-tabs-mode nil)
  '(tab-width 8)
  )</pre>
<p>
</p>
<h2><a name="normalizing_multiple_files">Normalizing multiple files</a></h2>
<p>In RRFW CVS repository, in the root of module <code>src</code>, there is a small
utility that fixes some styling issues for all the sources in
current directory and subdirectories:</p>
<pre>
  perl normalize-all-sources.pl</pre>
<p>It replaces tabs with spaces, deletes space at the end of line,
and removes empty lines at the start and the end of file.</p>
<p>
</p>
<hr />
<h1><a name="author">Author</a></h1>
<p>Copyright (c) 2003 Stanislav Sinyagin &lt;<a href="mailto:ssi...@ya...">ssi...@ya...</a>&gt;</p>

</body>

</html>

--- NEW FILE: devdiscover.pod.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RRFW SNMP Device Discovery Developer's Guide</title>
<link rel="stylesheet" href="../torrusdoc.css" type="text/css" />
<link rev="made" href="mailto:gp...@fa..." />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#rrfw_snmp_device_discovery_developer_s_guide">RRFW SNMP Device Discovery Developer's Guide</a></li>
	<ul>

		<li><a href="#devdiscover_overview"><code>devdiscover</code> overview</a></li>
		<li><a href="#discovery_module_internals">Discovery Module Internals</a></li>
		<ul>

			<li><a href="#module_registration">Module Registration</a></li>
			<li><a href="#oid_definitions">OID Definitions</a></li>
			<li><a href="#template_references">Template References</a></li>
			<li><a href="#interface_filtering">Interface filtering</a></li>
		</ul>

		<li><a href="#authors">Authors</a></li>
	</ul>

</ul>
<!-- INDEX END -->

<hr />


<h1><a name="rrfw_snmp_device_discovery_developer_s_guide">RRFW SNMP Device Discovery Developer's Guide</a></h1>


<h2><a name="devdiscover_overview"><code>devdiscover</code> overview</a></h2>
<code>devdiscover</code> is an extensible, module based, SNMP device discovery
utility. It is intended to automatically generate RRFW configuration
files, based on SNMP discovery results and templates.
See RRFW Command Reference for command usage and functionality overview.
In general, <code>devdiscover</code> consists of the following files and functional
parts:
<ul>
<li><a name="item_bin_2fdevdiscover_2ein"><code>bin/devdiscover.in</code></a> 
</li>
This file is installed as <code>bin/devdiscover</code> in RRFW installation directory,
with certain variables substituted. The program provides all the commandline
functionality and options processing. Once the CLI options are processed and
verified, the control is passed to an <a href="#item_rrfw_3a_3adevdiscover"><code>RRFW::DevDiscover</code></a> object.

<li><a name="item_rrfw_3a_3adevdiscover"><code>RRFW::DevDiscover</code></a> 
</li>
This Perl module is responsible for the SNMP discovery process organization:
<ul>
<li></li>
registers the discovery modules;

<li></li>
establishes an SNMP session to the target host;

<li></li>
initiates a new <a href="#item_rrfw_3a_3adevdiscover_3a_3adevdetails"><code>RRFW::DevDiscover::DevDetails</code></a> object for the target host;

<li></li>
stores the connection-specific parameters to the device object;

<li></li>
for each registered discovery module, executes <a href="#item_checkdevtype"><code>checkdevtype()</code></a> in
sequential order;

<li></li>
for those discovery modules which paid interest in this target host,
executes <a href="#item_discover"><code>discover()</code></a> in sequential order;

<li></li>
upon request from <code>bin/devdiscover</code>, builds the configuration
XML tree, by calling <a href="#item_buildconfig"><code>buildConfig()</code></a> in sequential order for each
relevant discovery module for each target host.
</ul>
<li><a name="item_rrfw_3a_3adevdiscover_3a_3adevdetails"><code>RRFW::DevDiscover::DevDetails</code></a> 
</li>
This Perl module is defined in lib/RRFW/DevDiscover.pm, and provides
the functionality to store the results of SNMP device discovery.

<li><a name="item_rrfw_3a_3aconfigbuilder"><code>RRFW::ConfigBuilder</code></a> 
</li>
This module is an encapsulation wrapper for XML configuration builder.
It provides methods for every element of RRFW configuration.

<li><a name="item_discovery_modules">Discovery Modules</a> 
</li>
These provide all the functionality for SNMP discovery. Normally
one module covers one MIB, or sometimes several vendor-specific MIBs,
and it is responsible for finding out the device details necessary
for RRFW configuration building. Usually a discovery module refers to one or
several template definition files. A module may depend on
other modules' discovery results. This is controlled by its
<code>sequence number</code>. Vendor-independent discovery modules are normally named
as <code>RRFW::DevDiscover::RFCXXXX_SOME_HUMAN_NAME</code>, and vendor-specific
ones are named as <code>RRFW::DevDiscover::VendorProduct[Subsystem]</code>.

<li><a name="item_template_definition_files">Template definition files</a> 
</li>
These are XML documents residing in xmlconfig/vendor and
xmlconfig/generic directories. Each file is a piece of RRFW configuration,
and contains definitions and templates for particular MIB or vendor.
Generic template definition files are for vendor-independent MIBs,
and normally they are named as rfcXXXX.some-human-name.xml.
Vendor-specific files are named as vendor.product[.subsystem].xml.
</ul>


<h2><a name="discovery_module_internals">Discovery Module Internals</a></h2>
Discovery modules are Perl packages with few required components.
Before creating your own modules, please read and follow
RRFW Programming Style Guide.
Upon initialization, <a href="#item_rrfw_3a_3adev...

[truncated message content]