> disman API
> Smurf
> Schedule-MIB
> Tcl Engine
> Policy Mgmt

The Jasmin Project

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
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.


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


W.r.t. the sub-agent, there are alternatives to some points, you may

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

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

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.


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,
     NET-SNMP (at least version 4.2) source code,
   o the W3C libwww installed at the agent machine
     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

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


   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


   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


   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


   See also


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

			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

--with-spool=DIR        use DIR to store retrieved scripts temporarily

			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

			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

			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

--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''

--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

   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

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

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.


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


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 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


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