www.pudn.com > sxg.rar > README
SXG - A SNMP-XML GATEWAY
===================================
Copyright (c) 2003 Jens Mueller
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, 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; see the file COPYING. If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
SXG is a Java servlet that generates XML-documents containing
SNMP-data of a specific agent. Requests to the gateway are made
using a XPath-style syntax, the gateway performs accordant SNMP-
get(next)-requests to retrieve the requested data. The requests
are sent to the gateway using the HTTP-GET method, see sections
REQUESTS and EXAMPLES for an overview of requests' syntax.
The gateway also provides the possibility of modifing values of
SNMP-objects. set-requests to the gateway are sent using the
HTTP-POST method. The data to be set in the specified agent is
transferred in the form of a XML-document.
MANIFEST
========
README this file
COPYING the SXG license terms (GPL)
Makefile the Makefile to build the code on UNIX systems
sxg/ the sources of the SXG classes
GatewayClient.java the sources of a commandline test-client
web.xml example of a deployment descriptor
EXTERNAL LIBRARIES
==================
SXG needs two external API-jars:
- dom4j-full.jar
API for handling XML-documents, available at http://www.dom4j.org/
(developed and tested with version 1.3)
- jmgmt.jar
API for SNMP-communication, available at
http://i31www.ira.uka.de/~sd/mgmt/jmgmt-1.1b.zip
BUILDING SXG
============
SXG consists of pure Java code. It can be compiled and packaged as
any other Java code with your favorite Java development environment.
On UNIX systems you might want to use the supplied Makefile:
$ automake
$ autoconf --with-java-home=DIR --with-classpath=PATH
$ configure
$ make
will compile the SXG classes and the GatewayClient.class.
Make sure to include the dom4j and jmgmt jars into the classpath.
SETTING UP
==========
Install the compiled class-files to your Tomcat installation, make
sure the needed libs are added to Tomcat's classpath.
If you are using an earlier version than 4.0.2 of Tomcat, you
will not be able to receive the custom HTTP-status-messages sent
by the gateway used to describe occured errors and only receive
the default messages. For more information about Tomcat and
the changes in version 4.0.2 refer to
http://jakarta.apache.org/tomcat/index.html and
http://jakarta.apache.org/builds/jakarta-tomcat-4.0/archives/
v4.0.2/RELEASE-NOTES
Modify the deployment descriptor 'web.xml', the most important
setting is 'repositoryURL'.Here you have to point to the
container-schema used by SXG as an information base for translating
SNMP- to XML-adressing and vice versa. For a first installation
check you can use the container-schema located at
http://www.ibr.cs.tu-bs.de/arbeiten/snmp-xml-gw/xsd/container.xsd
However, only a few objects are provided in this schema, so it is
strongly recommended to set up your own repository. To do so,
get the application 'smidump' based upon the 'libsmi'-library
by Frank Strauss from
http://www.ibr.cs.tu-bs.de/projects/libsmi/
Refer to smidump's documentation how to create XML-schemata
to represent SNMP-MIB-modules and how to create the container-
schema.
Once created, make the new files accessible by HTTP and modify
web.xml to set up SXG to use the newly created container-schema.
REQUESTS
========
You can query managed data by using the provied client
'GatewayClient.class' or by using any web browser.
Get-request are made by submitting an URL to the Gateway,
requests's syntax is described by the following EBNF:
REQUEST-STRING := '/snmp-data' REQUESTS
REQUESTS := CONTEXTREQUEST | '('CONTEXTS')'
CONTEXTS := CONTEXTS '|' CONTEXTS | CONTEXTREQUEST
CONTEXTREQUEST := '/context[' NODE OPTCONTEXTATTR ']'
NODE := '@ipaddr="' '" ' |
'@hostname="' '" ' |
'@ipaddr="' '"' '
' and @hostname="' '" '
OPTCONTEXTATTR := '' | OPTCONTEXTATTR OPTCONTEXTATTR |
'and @community="' '" '
'and @port="' '" ' |
'and @caching="' TRUTH-VALUE '" ' |
'and @trapdata="' TRUTH-VALUE '" ' |
TRUTH-VALUE := 'yes' | 'no'
Defaults for the optional attributes are:
@community: public
@port: 161
@caching: yes
@trapdata: no
In the current implementation requesting of notification
data ist not provided, so the '@trapdata'-attribute is of no use.
Set-requests are made by submitting a valid XML-document using
the HTTP-method POST, the document should be set as value of
the parameter 'set'.
EXAMPLES
========
get-requests:
The following request queries all objects of the table 'ifEntry'
of the specified SNMP-Agent:
/snmp-data/context[@hostname=""]/ifEntry
Using the provided client, execute:
java -cp CLASSPATH GatewayClient http:// get
'/snmp-data/context[@hostname=""]/ifEntry'
Make sure to have 'dom4j' included in CLASSPATH.
Using a web browser, just type the following URL:
http://?get=/snmp-data/
context[@hostname%3D""]/ifEntry'
Make sure to rewrite any equationsigns '=' to '%3D' in the
request-string.
Some other request-string examples:
/snmp-data/context[@hostname="" and @port=""]
/tcpConnEntry[tcpConnState="listen"]
requests all tcp-connections with state 'listen' from a SNMP-Agent
running on at port .
/snmp-data/context[@hostname="" and @caching="no"]/system
requests objects provided in scalargroup 'system' from a SNMP-Agent
running on with explicitly advising the gateway not to
resolve the requested data from its cache.
set-requests:
To issue a set-reuqest, save the retrieved XML-document to a file,
modify it and submit it back to the gateway by executing
java -cp CLASSPATH GatewayClient http:// set
The current implementation does not provide creation/deletion of
tablerows. Only modifications to existing instances are possible.
CONTACT
=======
jmueller@ibr.cs.tu-bs.de
strauss@ibr.cs.tu-bs.de