-----------------------------------------------------------------------------
RWS Package for OpenNMS                                OpenNMS/RANCID Project

Copyright (c) 2009+ Rocco Rionero
Copyright (c) 2009+ The OpenNMS Group, Inc.
All rights reserved everywhere.

This program was developed and is maintained by Rocco RIONERO
("the author") and is subject to dual-copyright according to
the terms set in "The OpenNMS Project Contributor Agreement".

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.

The author can be contacted at the following email address:

	Rocco RIONERO
	rock (at) rionero.com

(please, specify "rws-application-software" in the subject of your message)

-----------------------------------------------------------------------------
OpenNMS Network Management System is Copyright by The OpenNMS Group, Inc.

RANCID application is Copyright by Terrapin Communications, Inc.
=============================================================================


-----------------------------------------------------------------------------
                 UNSUPPORTED BETA-RELEASE SOFTWARE VERSION
-----------------------------------------------------------------------------




1. INTRODUCTION

rancid (Really Awesome New Cisco confIg Differ) is a tool for monitoring
network devices (i.e. routers, switches, etc.) to track software and
hardware configuration changes and to maintain a complete history of them by
the means of a revision's control system (i.e. CVS or Subversion) repository.
It is distributed by Shrubbery Networks, Inc (http://www.shrubbery.net/)

As most "good-old-school" unix-based tools, rancid's configuration is
performed by editing a set of configuration files on the hosting system;
rancid's execution is started from the system's command line or automatically
scheduled via the unix cron daemon; the information repositories generated by
rancid can be accessed by any CVS or Subversion browsing tool.

In order to perform a consistent integration into a general network management
system (NMS), a proper application program interface (API) to rancid's
configuration and information repository, was developed. It was designed
according to a resource-oriented client-server model following a
Representational State Transfer (REST) style of software architecture based on
the Hyper Text Transfer Protocol version 1.1, that is -as commonly defined- a
resource-oriented RESTful web service API.

This package contains the first pre-release of such RESTful web service API
implementation, which was mainly designed for the enterprise-grade open-source
network management system OpenNMS, managed by The OpenNMS Group, Inc.

During the development process the API evolved in a general-purpose, modular
RESTful interface core named RWS (standing for RESTful Web Services), capable
of loading (in dynamic way) several different RESTful "services"; according
to this architecture, the rancid's specific functions were moved into a
"service" module by itself, the RWS RANCID-API.

In addition to a RESTful interface to rancid's functions, the RANCID-API
includes the ability to extract from the device's configurations downloaded
by rancid all the available hardware inventory data, which are processed,
correlated and returned to the client in an uniform and device-independent
representation. This feature, currently supported for Cisco and Juniper
families of network devices, brings to OpenNMS a powerful set of device
inventory management functions.

The overall framework developed is quite generic and flexible to implement
any sort of RESTful-based interface and can be easily used by any client
tool able to "speak" the HTTP/1.1 message protocol.

This release of the RWS package includes an additional RWS service module
named "storage" which implements a basic yet quite flexible remote storage
service with ability of directories creation/deletion to any level of depth,
directory listing (sorted by name/size/date in both increasing/decreasing
order), file download and upload (in both custom raw-binary-encoding or
standard multipart-encoding).

The RWS main module and the RWS service modules are written as Tcl
(Tool Command Language) scripts; this gives the package high portability as
almost any current Operating System environment supports Tcl, and it is also
the scripting language of choiche for several kind of embedded systems. 




2. CONTENTS OF THIS PACKAGE

- README

  The instruction file you are reading right now.


- CHANGES

  A brief description of changes over previous releases of the package.


- rws-cgi.tcl

  The core RWS CGI executable script module.


- rancid.rws

  The RANCID-API RWS Service Module, dynamically loaded by the RWS main module.


- rancid.rws.rc

  The RANCID-API configuration file.


- storage.rws

  The STORAGE RWS Service Module, dynamically loaded by the RWS main module.




3. PRE-REQUISITES

A general knowledge of CGI concepts and httpd configuration is assumed. The
instructions will also assume that Apache HTTPD (version >= 1.3.27) is used
as httpd server daemon. As the RWS servlet is a Tcl script, a working Tcl
environment (version >= Tcl 8.3.4) is needed on the hosting system.

PLEASE NOTE: the rws-cgi.tcl script now requires by default a TclX (Extended
Tcl) interpreter; the only eXtensions actually used are POSIX signals
manipulation abilities. The TclX interpreter is expected in /usr/local/bin,
that is, the first line of the script reads as follows:

	#!/usr/local/bin/tcl

The TclX extended interpreter "tcl" is usually deployed with the Tcl standard
interpreter "tclsh": if the hosting system does not have the "tcl" executable
(meaning that either it does not support TclX or that -as seen on some custom
implementations- TclX extensions are included in the "tclsh" executable),
you may revert the first line of the rws-cgi.tcl script to the following one
(as on the previously released script):

	#!/usr/local/bin/tclsh

The RWS code will automatically detect the availability of TclX extensions
(namely, POSIX signals manipulation) and will avoid to use them if not
supported by the hosting interpreter (reverting to previous behaviour); in
such a case a "warning" message will be logged.

You may also edit the above first line of the script to accomodate different
interpreter's location on your system (if you don't want or are not able to
use symbolic links).

If all of the above is satisfied, then go ahead with the installation.




4. INSTALLATION

- uncompress/untar the distribution package into a directory of your choice;
  if you are reading this README file you almost surely already completed
  this step :-) ... I will assume that you untarred the package in the /tmp
  directory of your system;


- the untar process created in /tmp the directory "rws-opennms-pkg-X.Y"
  (the trailing string "X.Y" being the version of the package); from now
  on I will refer to the /tmp/rws-opennms-pkg-X.Y directory as "the package
  directory"


- create a directory on your system from which execute the RWS CGI script; I
  will assume that the directory will be "/usr/local/apache/rws-cgi"; from
  now on I will refer to it as "the rws-cgi directory"


- copy in the rws-cgi directory the following four files from the package
  directory:

	rws-cgi.tcl
	rancid.rws
	rancid.rws.rc
	storage.rws


- give the "rws-cgi.tcl" main module proper ownership and execution permissions
  compatible with the local user which runs the Apache daemon; to simplify the
  initial setup I suggest you to install/configure rancid to be executed as
  the same user which runs Apache (further improvements might be to properly
  configure Apache to use the "suEXEC" feature so to run the rws-cgi script
  with a different identity, being namely the identity of the user running
  rancid). The other files DO NOT need execution permission but must be just
  readable by the user above.


- configure Apache with an "alias" for the rws-cgi script; assuming that the
  URL for the RWS servlet will be "http://<yourservername>/rws", you should
  add the following line in the main server section (or in the virtual server
  section corresponding to <yourservername>) of your httpd.conf:

	ScriptAlias /rws	/usr/local/apache/rws-cgi/rws-cgi.tcl


- it is advisable to restrict the access to the rws-cgi directory by adding
  the following directive in the same section of the httpd.conf file where
  you created the ScriptAlias above:

	<Directory "/usr/local/apache/rws-cgi">
	  Order          Allow,Deny
	  Allow          from All
	  AllowOverride  None
	  Options        None
	</Directory>

  so that no directory indexing is allowed if the rws-cgi directory resides
  in the http document tree of your server (normally not needed and not
  suggested); it will not hurt, anyway. Please note that in such a case
  additional measures could be needed to secure your setup.
  Note also that it is usually NOT required to set the "ExecCGI" option for
  the rws-cgi directory as the ScriptAlias directive alone will do the job;
  this is due to a "back-compatibility kludge" usually implemented in the
  standard Apache's "mod_cgi" module. YMMV.


- create a directory on your system for the RWS logfile; I will assume that
  the directory will be /var/log/rws-cgi; give the directory proper ownership
  and access permissions so to be writeable by the user which runs the RWS
  CGI script (that is, if no suEXEC feature is used, the user running Apache)


- configure the logfile name and the desired logfile level by addind the
  following directives in the same section of the httpd.conf file where
  you created the ScriptAlias above:

	SetEnv RWS_LOGFILE  /var/log/rws-cgi/rws-cgi.log
	SetEnv RWS_LOGLEVEL <loglevel>

  where <loglevel> is one of the following keywords (case IS sensitive):

	debug, info, notice, warning, error

  If the variable RWS_LOGLEVEL is not defined, the default loglevel will be
  "info" (i.e. all messages with a priority >= info will be logged).

  If the variable RWS_LOGFILE is not defined, the RWS will write its messages
  in /tmp/rws-cgi.log


- if you want to restrict the access to the RANCID-API service to authenticated
  users only (which is suggested) first create a directory for the user's file;
  I will assume that you will use the name "/usr/local/apache/rws-auth"; then
  use the "htpasswd" utility (in the apache binaries) to create in such
  directory the user's file and to add any username/password you need; I will
  assume that you will name the file "rws-users"; finally add the following
  directive in the same section of the httpd.conf file where you created the
  ScriptAlias above:

	<LocationMatch /rws/rancid*>
	  AuthName        "RWS RANCID-API"
	  AuthType        Basic
	  AuthUserFile    /usr/local/apache/rws-auth/rws-users
	  require         valid-user
	</LocationMatch>

  The directive above will require authenticated access for the RANCID-API
  only, and will let any user to access the RWS service without authentication
  (so to verify that the servlet is installed, obtain the version number and a
  list of installed RWS services, etc.). You may specify additional "Location"
  directives to further restrict sub-trees of the RANCID-API resource's
  hierarchy. This is left as an exercise to the reader... :-)


- create a directory on your system to be used as "root location" for the
  STORAGE service repository; I will assume that the directory will be
  /mnt/rws-storage-root; give the directory proper ownership and access
  permissions so to be writeable by the user which runs the RWS CGI script
  (that is, if no suEXEC feature is used, the user running Apache)


- configure the STORAGE service by adding the following directive in the same
  section of the httpd.conf file where you created the ScriptAlias above:

	SetEnv RWS_STORAGE_ROOT  /mnt/rws-storage-root

- you can restrict access to the STORAGE root directory above and/or require
  authorization to the RWS STORAGE URIs by adding the already described
  <Directory> and <LocationMatch> directives to the usual section of the
  httpd.conf file; this is, again, left as an exercise to the reader... :-)


- restart Apache by executing "apachectl graceful" and verify that the daemon
  re-starts correctly (if it doesn't, double check your httpd.conf)




5. TESTING YOUR INSTALLATION

Open a browser and access (GET request) the following URL:

	http://<yourservername>/rws?responsetype=text

and verify that a response reporting some information about the RWS service
and your hosting environment is correctly returned; then obtain a list of the
RWS services installed, by accessing the following URL:

	http://<yourservername>/rws/?responsetype=text

verify that a correct response is returned and that both the "rancid" and
"storage" resources are listed.


Finally verify that the both the RANCID-API and the STORAGE services are
correctly loaded and executed by accessing the following URLs (note: this
might require authentication if you enabled it):

	http://<yourservername>/rws/rancid?responsetype=text
	http://<yourservername>/rws/storage?responsetype=text


verify that in both cases a correct response is returned.

The response returned by the "rancid" service (first URL above) will include
some "Config" parameters with a value of "undefined". This is CORRECT as this
is your first setup and the rancid service needs to be configured.

The response returned by the "storage" service (second URL above) will include
a single "ReadOnlyConfig" parameter named "pathBucketsRoot"; verify that its
value matches the expected pathname of the storage root directory.


If everything did as described above, both the RWS CGI and the RANCID-API /
STORAGE services were installed correctly. You just need to configure the
RANCID-API according to your rancid's setup. The STORAGE service does not
require additional configuration steps and is ready to be used.




6. CONFIGURING THE RANCID-API

The RANCID-API configuration is stored in the "rancid.rws.rc" file that must
be present in the rws-cgi directory. You can change the configuration by
manually editing the file (which is, for this first time, the suggested way)
OR by using the RANCID-API itself (a POST on the /rws/rancid resource will
do the trick). So open the rancid.rws.rc file with your favourite text editor
and follow the instructions contained therein. When you're done with the
configuration send a GET request again to the rancid resource:

	http://<yourservername>/rws/rancid?responsetype=text

and verify the the value you assigned are correctly returned in place of
the previous "undefined" tokens.

If you made it so far, you have done. Move to your client (i.e. OpenNMS) and
start working with the RANCID-API and the STORAGE service.




7. CONCLUSION

There is still a LOT to say, I know. But this is again a beta-release of the
RWS package essentially directed to the people involved in the OpenNMS/RANCID
Project. Please, wait for the stable release of the package, which will
include a complete documentation.

Although there is absolutely NO SUPPORT on this package, you can contact me
at the above listed email address.

Have fun, make love, live in peace.



					Rocco "rock" Rionero
					RIONERO ThinkOut Solutions
					OpenNMS/RANCID Project Team


