Implementation
Testing
Add-Ons
> disman API
> Smurf
> JAX
> Schedule-MIB
> Tcl Engine
> Policy Mgmt
Documentation
Download
Mailinglist
People
The Jasmin Project
README
JASMIN - A JAVA SCRIPT MIB IMPLEMENTATION
=========================================
Copyright (c) 1999-2001 NEC Europe Ltd. & Technical University of Braunschweig.
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.
@(#) $Id: README,v 1.28 2001/09/05 11:33:34 strauss Exp $
Jasmin is an implementation of the IETF Script-MIB [RFC 3165],
developed in a joint project by the Technical University of
Braunschweig and NEC C&C Research Laboritories, Europe. Its
primary goal is providing an implemention for further evaluation of
the concepts of management by delegation in general and the Script-MIB
in particular.
The heart of the Jasmin software is the Script-MIB agent implementation
contained in this package. Other packages contain a Java Script-MIB
manager API and application (jasmin-manager) and a set of sample
scripts (jasmin-scripts).
Getting this agent code highly portable, secure, and fool proof are
currently only secondary goals. However, bug reports and feedback are
welcome, of course.
Jasmin is an abbreviation of `Java Script-MIB Implementation'. In
fact, the current Jasmin implementation supports Java as the only
Script language. However, other languages may easily be added in
future releases, since the Script-MIB extensibilty protocol SMX [RFC
2593; update to appear] is used.
MANIFEST
========
The following list shows the most important files for reading and
building the code and the Jasmin directory structure.
README this file
COPYING the Jasmin license terms
configure configure script, build from configure.in
agent/ the Jasmin Script-MIB sub-agent implementation
floyd/ the SNMP toolkit independent Script-MIB code
runtime/ the agent's runtime engine code
java/ code and related files of the Java runtime engine
jasmin/ code of the Java package `jasmin'
policyMgmt/ code of the Java package `policyMgmt'
diffServ/ code of the Java package `policyMgmt.diffServ'
jtc/ code of the Java package `jtc'
tcl/ tcl runtime engine stub (the actual RTE is part of scotty)
perl/ Perl runtime support (contributed by Luis F Balbinot)
toolkit/ SNMP toolkit dependent Script-MIB code
emanate/ code of the EMANATE based agent (not in free distribution)
ucd/ NET-SNMP dlmod source code (not needed if EMANATE is used)
wget/ patched version of GNU wget (not needed if libwww is used)
scripts/ sample scripts for use with the Jasmin sub-agent
java/ Java sample scripts
manager/ stuff that supports Script-MIB managers
api/ Script-MIB manager API implemention
java/ the `disman' Java API
disman/ the `disman' API source code
jmgmt/ the (patched) JMGMT SNMP package from Sven Doerr
snmpmonitor/ a small package to support SNMP monitoring scripts
test/ a Script-MIB API and agent test suite
smurf/ the Java Script-MIB user interface application
ALTERNATIVES
============
W.r.t. the sub-agent, there are alternatives to some points, you may
choose.
Agent Platform
--------------
The Jasmin SNMP (sub)agent is being developed on Sun Solaris 2.x SPARC
workstations and on Linux x86 PCs. However, the use of GNU
automake/autoconf and other standard tools makes the Jasmin code rather
portable across many UNIX platforms.
SNMP Toolkit
------------
The Jasmin SNMP agent has to be built with one of two SNMP toolkits.
The first implementation has been done with SNMP Research's EMANATE
toolkit, since this was the only one in 1998 that supported SNMPv3
which is required for the Script-MIB. In mid 1999 Jasmin has been
ported to the free NET-SNMP 4.x code, which is now the prefered SNMP
toolkit.
If EMANATE is used, it must be installed before building and running
Jasmin. The EMANATE based Jasmin agent is implemented as an EMANATE
sub-agent running as a separate process. EMANATE support may be dropped
in future releases.
If the NET-SNMP toolkit is used, you have to install it before
building the Jasmin sub-agent. The Jasmin module is implemented as a
dynamically loadable MIB module (dlmod). Therefore, you need at least
NET-SNMP 4.2.
How to Fetch Scripts from URLs
------------------------------
There are two ways to make the Jasmin agent fetch scripts from URLs,
either by invoking the external program `wget' or by using the WWW
library by the W3 Consortium (libwww).
If wget is used, you need a patched version, because the error codes
of the original wget are not very expressive. A patch is included with
the Jasmin source code. If libwww is used, it must be installed
before building and running Jasmin.
JASMIN AGENT INSTALLATION
=========================
For the installation of the Jasmin agent you need:
o Java JDK 1.1.X or JRE 1.1.X,
o the Jasmin sources from jasmin-*.tar.gz,
o the EMANATE SNMP SDK
*or*
NET-SNMP (at least version 4.2) source code,
o the W3C libwww installed at the agent machine
*or*
the GNU wget version 1.5.3 source code,
o some development tools like gcc, awk, lex, yacc, patch.
If you are building even the Makefiles from scratch using
automake and autoconf, you will need at least automake 1.4
and autoconf 2.13.
o an SMX aware scotty installation, if you want to run Tcl
scripts.
1. Prerequisites
----------------
1.a Install Java JDK 1.1.X or JRE 1.1.X
---------------------------------------
In order to run Java programs as management scripts (Don't confuse
with Java Script!) you need to install Java. Jasmin requires
a JDK version 1.1.X with X=5 or higher. Note that the Jasmin agent
does *not* work with JDK version 1.2.X or higher.
1.b Install the NET-SNMP toolkit and agent
------------------------------------------
If you want to build the Jasmin agent with the free NET-SNMP code
and/or if you do not have an SNMP Research EMANATE license, you have
to get the NET-SNMP 4.2 source code from
http://www.netsnmp.org/
http://sourceforge.net/project/showfiles.php?group_id=12694
and install it. Please follow the instructions that come with the
NET-SNMP code. Note that the NET-SNMP agent must be configured with
``--enable-shared'' (or other hacks) to export all required agent
symbols so that their references in the jasmin.so module can be
resolved during runtime.
NET-SNMP was formerly named UCD-SNMP. At some places in the Jasmin
project we still use the old name `ucd' or `ucd-snmp'.
1.c Install the W3C libwww version 5.2.8 library
------------------------------------------------
If you want to use libwww instead of wget to fetch scripts from URLs,
libwww must be installed as usual. It may be part of your desitribution,
if you run a Linux box. Otherwise, you may get it from
http://www.w3.org/Library/Distribution/w3c-libwww-5.2.8.tar.gz
ftp://ftp.ibr.cs.tu-bs.de/local/jasmin/w3c-libwww-5.2.8.tar.gz
1.d Get the GNU wget version 1.5.3 source code
----------------------------------------------
If you prefer to use GNU wget for fetching scripts from URLs, you have
to get the wget source code from
ftp://prep.ai.mit.edu/pub/gnu/wget/wget-1.5.3.tar.gz
ftp://ftp.ibr.cs.tu-bs.de/local/jasmin/wget-1.5.3.tar.gz
and untar it in the agent/wget directory and apply the Jasmin patch:
$ cd agent/wget
$ tar xvzf DIR/wget-1.5.3.tar.gz
$ patch -p0 < wget-1.5.3.patch
This patch makes wget return more detailed exit codes if a HTTP
or FTP retrieval fails.
1.e Install the Scotty Tcl extension for network management
-----------------------------------------------------------
If you want to make use of Tcl as a Script-MIB language, you need to
have a version of Scotty installed that is aware of the Tnm::smx
command. You may get it from
http://wwwhome.cs.utwente.nl/~schoenw/scotty/
ftp://ftp.ibr.cs.tu-bs.de/local/jasmin/
See also
http://www.ibr.cs.tu-bs.de/projects/jasmin/tcl.html
2. Configure, Build and Install Jasmin
--------------------------------------
There is a GNU configure script. See configure --help for parameters
that may get tuned.
The most important configure options are:
--prefix=PREFIX install files in PREFIX [/usr/local]
E.g. this prefix can be changed to /usr for full
integration with the operating system distribution
or to your $HOME directory if you want to install
Jasmin under normal user priviledges.
--with-scripturl=URL use URL as URL prefix to fetch scripts
[http://www.ibr.cs.tu-bs.de/projects/jasmin/scripts/]
This is only used to setup the jasmin.conf file.
The default setting makes the agent load some scripts
of the default configuration from the Jasmin web
site. These scripts are also part of this Jasmin
distribution and can be installed on your local
system, if you have a running web server. Then you
should set this prefix and the following option
appropriately.
--with-spool=DIR use DIR to store retrieved scripts temporarily
[/usr/local/var/jasmin/scripts]
This option specifies the directory where the
agent stores the scripts that have been retrieved
from script repositories. Note that this directory
must be writable if you intend to run the agent
with non-root priviledges.
--with-jdk11-home=DIR use DIR for JDK 1.1.X toplevel directory
[/usr/local/jdk1.1.5]
This option must be used to specify the Java 1.1.x
top level directory. The JDK programs and classes
are looked up under this directory to build the
Java components of the Jasmin runtime engine. Note
that you MUST NOT use JDK 1.2.x here, since some
thread support required by the runtime engine
has been dropped since JDK 1.2.
--with-jdk12-home=DIR use DIR for JDK 1.2.X toplevel directory
[/usr/local/jdk1.2.2]
This option must be used to specify the Java 1.2.x
top level directory. The JDK programs and classes
are looked up under this directory to build the
Java components of the Jasmin manager side stuff.
In contrast to the runtime engine, you need JDK 1.2.x
here to be able to use Swing for the Smurf
application.
--with-logdir=DIR use DIR to store logfiles [/var/log]
This option can be used to specify the directory
where Jasmin writes its logfiles. Note that you
have to specify a writable directory if you intend
to run the agent with non-root priviledges.
--with-fetch=METHOD use METHOD (wget or libwww) to fetch scripts [wget]
See section ``How to Fetch Scripts from URLs''
above.
--with-toolkit=TOOLKIT use TOOLKIT (emanate or ucd) for SNMP [ucd]
See section ``SNMP Toolkit'' above. You should
use the default.
--with-emanatedir=DIR use DIR as the home of EMANATE [/usr/local/emanate]
This option is only required when you use EMANATE.
--with-dlmoddir=DIR use DIR to install dynamically loadable NET-SNMP
modules [/usr/local/lib/snmp/dlmod]
This option is only required when you use the
NET-SNMP 4.2 master agent. It specifies where
the Jasmin module shall be installed, that is
to be loaded dynamically on agent startup.
If you have choosen the right set of options run
$ ./configure [options...]
If this leads to failures, check the reasons. Did you choose to use
wget and did not follow 1.d above? Did you choose to use libwww and
did not follow 1.c above? Did you choose to use the NET-SNMP toolkit
and did not follow 1.b above? Did you install the JDK 1.1.x and
specify its root directory by --with-jdk11-home?
If everything gets configured well, build the code by typing
$ make
If this succeeds, install all the files by running
$ make install
This might require superuser privileges.
If this is done successfully, go on with the configuration.
3. Configuring the SNMP (master) agent
--------------------------------------
If you are using the EMANATE based master agent, follow section 3.1.
Otherwise, if you are using the NET-SNMP based agent, follow section 3.2.
3.1. The EMANATE Master Agent Configuration
-------------------------------------------
Since the EMANATE SNMP agent is an SNMPv3 agent, it requires some
configuration of file /usr/local/etc/snmpd.cnf. The file format
is explained in the man page /usr/local/emanate/man/man5/snmpdcnf.5
The distribution contains the files used for the Jasmin test agent at
the TU Braunschweig (see http://www.ibr.cs.tu-bs.de/projects/jasmin/).
Two users called `junior' and `senior' are configured with different
access rights. For a first test it might be appropriate to use these
settings.
3.1.1. Edit general settings
----------------------------
The first entries of file /usr/local/etc/snmpd.cnf are self-explanatory
entries, such as sysLocation, which you should add appropriately.
3.1.2. Set up USM
-----------------
Then you have to set up USM (User-based Security Model).
Therefore, you must create an userNameEntry and an usmUserEntry for
each SNMPv3 user in the configuration file. Further information on
how to configure USM can be found in RFC 2574.
3.1.3. Set up VACM
------------------
This is probably the most complex part of the installation (if you are
not satisfied with the preconfigured `junior' and `senior' users).
For each SNMPv3 user or SNMPv1 community, you have to define views of
the MIB in the configuration file. How such views are defined is
explained in RFC 2575.
3.2. The NET-SNMP snmpd Configuration
-------------------------------------
To make the NET-SNMP agent aware of the Jasmin Script-MIB
sub-agent you have to add some lines to the snmpd.conf file or specify
an additional ``-c /usr/local/etc/snmpd_jasmin.conf'' option when
the agent is started. The locations of the snmpd.conf file and the
agent startup script depend on your environment.
The new configuration commands should be (a) ``dlmod jasmin
<path>'' to load Jasmin module; (b) ``jasminconf <path>'' to
specify the path where the Jasmin configuration file is found; and
(c) a set of VACM configuration commands to setup the access rights
for the various Script-MIB variables. See the
agent/toolkit/ucd/snmpd_jasmin.conf File for an example.
4. Edit the Configuration File for the Jasmin Sub-Agent jasmin.conf
-------------------------------------------------------------------
The configuration file for the sub-agent is /usr/local/etc/jasmin.conf.
What you should edit in this file is the list of supported languages,
the lists of pre-installed scripts and launch buttons, and the OS
profiles. Syntax and semantics of these entries are documented in the
man page jasmin.conf(5).
When the sub-agent starts up, it downloads all so-called pre-installed
scripts from the URLs given in the configuration file. If you leave
everything unchanged, a set of test scripts are loaded from the Jasmin
home site.
But since all test scripts are also part of the distribution (default
install path: /usr/local/lib/jasmin/scripts), you should change these
entries and prefer URLs representing the according local script
repository files.
For a launch button, the required script must be in the list of
pre-installed scripts. There are already several launch buttons in the
configuration file.
The OS profiles define the parameters associated with the operating
system process executing a script. The account parameter sets the UNIX
user identity under which the runtime system will be executing. If the
rte_starter program (see section 5 below) is installed suid root, this
account parameter must be present for security reasons. Otherwise, it
may be omitted and the runtime system's uid will be inherited from the
Jasmin agent. The maxfiles, maxcpu and maxfsize parameters correspond
to setrlimit() system call parameters. The chroot parameter sets the
file system root for the runtime system. Note that this may lead to
missing libraries and other problems. Map entries map Script-MIB
owners (snmpProfile) to operating system profiles (osProfile) and
runtime system profiles (runtimeProfile).
5. Configuring the `rte_starter' Program
----------------------------------------
One program, the security wrapper `rte_starter' for starting runtime
engines from the Jasmin sub-agent, is usually installed suid root to
be able to switch to configurable OS profiles. This has to be done
manually for security reasons. Switch to superuser permissions and
type:
The configuration file /usr/local/etc/rte_starter.conf controls which
programs can be executed this way via rte_starter. So you should
consider to chown this file also (and ensure that nobody else but root
can write to it):
Note that for many experiments with Jasmin you don't need OS profiles
and hence you don't have to fiddle with these security concerns.
In this case, note also if neither the agent runs with root
privileges nor rte_starter is installed suid root, you must not use
``account'' and ``chroot'' options in your jasmin.conf file.
6. Adjust the EMANATE Startup Script
------------------------------------
This section is only relevant for the EMANAGE version.
You may wish to change some settings in /usr/local/sbin/jasmin. This
is a SysV-init style script that accepts `start' and `stop' arguments
to startup or shutdown the master and subagent.
JAVA_HOME # Java 1.1.X home directory, e.g. /usr/local/jdk1.1.5
SR_LOG_DIR # The directory where the master agent writes
SR_SNMP_TEST_PORT # the port on which the SNMP agent receives requests,
SR_TRAP_TEST_PORT # the port on which SNMP notifications are sent,
MASTEROPTS # Options for the master agent. See snmpdm(l)
JASMINCONF # Path to the Jasmin configuration file.
7. Changes to the Jasmin Java Runtime Engine Startup Script
-----------------------------------------------------------
For starting a runtime engine (so far, Jasmin only support a runtime
engine for Java scripts), the Jasmin agent calls the security wrapper
program /usr/local/lib/jasmin/rte_starter. This small program is
usually installed suid root so that it can switch to OS profiles
configured in /usr/local/etc/jasmin.conf without the need to run the
whole Jasmin (sub-)agent with superuser permissions (see section
``Configuring the `rte_starter' Program''). After applying OS profile
settings, rte_starter calls a runtime engine like
/usr/local/lib/jasmin/rte_java. This is a shell script that finally
starts the Java engine after applying some environment settings. You
might wish to enable/disable the Java runtime engine debugging output
by setting JRE_DEBUG.
8. Write Jasmin scripts
-----------------------
A set of test scripts is contained in the Jasmin source code
distribution. These scripts come with their source code and a
Makefile.in which should explain the process of compiling scripts. For
more detailed information please read the Jasmin script tutorial that
con be found on the Jasmin home page at
http://www.ibr.cs.tu-bs.de/projects/jasmin/.
9. Start the Jasmin Agent
-------------------------
If you use the EMANATE agent, the easiest way to start and
stop the agent is to use the script /usr/local/sbin/jasmin with the
`start' or `stop' argument. Hence, this may be integrated with your
system's init(8) configuration to automate Jasmin startup at boot time.
If you use the NET-SNMP way, the Jasmin module will be loaded dynamically
at runtime when you start the NET-SNMP snmpd the next time. Note section
3.2 above.
10. Adding Script-MIB extensions to the Java Runtime Engine
-----------------------------------------------------------
The Jasmin distribution comes with three Java packages added to the
Jasmin Java runtime engine: JMGMT, the disman package, and a simple
snmpmonitor package. To reflect this in the smExtsnTable appropriate
entries are present in the jasmin.conf file.
If you wish to add further extensions, you should add entries to the
jasmin.conf file and add your classes to the rte_java.jar runtime
engine. Note that in the current ditribution it is not sufficient to store
additional classes or archives in /usr/local/lib/jasmin and add them
to the CLASSPATH, since the runtime engine uses a non-standard class
loader to ensure Script-MIB security issues.
THE DISMAN PACKAGE AND THE SCRIPT-MIB USER INTERFACE (SMURF)
============================================================
This is a Java package that implements a set of mid level and high
level classes to facilitate the development of Script-MIB management
applications. Based on this package an application named `Smurf' is
also included. It allows to monitor and alter Script-MIB agents.
If you want to use it, note that it is based on the package JMGMT
(version 1.1b) from Sven Doerr. Since the current JMGMT version has a
slight problem, we have included and patched JMGMT jar file with
Sven's permission as well as a patch if you prefer to build your JMGMT
package yourself. To build the patched jmgmt.jar yourself retrieve the
JMGMT sources from
http://i31www.ira.uka.de/~sd/mgmt/
http://i31www.ira.uka.de/~sd/mgmt/jmgmt-1.1b.zip
Then go to the jmgmt directory, unzip the sources, apply the patch and
finally build the patched jmgmt.jar file:
$ cd manager/api/java/jmgmt
$ unzip DIR/jmgmt-1.1b.zip
$ patch -p0 < jmgmt-1.1b.patch
$ make jmgmt.jar
Now, to build disman.jar, and then build and run the test programm
DismanSmallTest.class, you should call
$ cd ..
$ make disman.jar
$ make test
This would call the DismanSmallTest test program without any
parameters so that it tries to talk to the Jasmin home agent which is
running most of the time on osborne.ibr.cs.tu-bs.de. You may also call
the test program with optional arguments:
java -classpath /usr/local/jdk1.2.2/lib/classes.zip:jmgmt/jmgmt.jar:. DismanSmallTest [agenthost [community [port]]]
To run a more complete test suite, type
$ cd test
$ make test
SMURF - A SCRIPT MIB MANAGEMENT APPLICATION
===========================================
Smurf is a JDK 1.2.x GUI management application. For communication
with Script-MIB agents it uses the disman package. To build the
application, you should
$ cd manager/smurf
$ make
Then you start and play with it:
$ make start
USING JASMIN FOR POLICY-BASED CONFIGURATION MANAGEMENT
======================================================
As a research effort, we have investigated how the Script-MIB and
the Jasmin implementation can be used for policy-based configuration
management. These efforts are described in papers available from the
Jasmin web pages. Research prototype implementations of three class
packages are part of this software distribution: the policyMgmt package,
the diffServ package and the jtc package. Please note that these parts
of the distribution have significant limitations. They are not applicable
for real world scenarios.
Good Luck!
© 2000 TU Braunschweig, NEC C&C Europe -
Wed Sep 5 13:33:52 2001