Internet-Draft Script MIB November 1997
Definitions of Managed Objects for the
Delegation of Management Scripts
November 21, 1997
<draft-ietf-disman-script-mib-02.txt>
David B. Levi
SNMP Research, Inc.
levi@snmp.com
Juergen Schoenwaelder
TU Braunschweig
schoenw@ibr.cs.tu-bs.de
Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as ``work in progress.''
To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net
(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
Rim).
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
Expires May 1998 [Page 1]
Internet-Draft Script MIB November 1997
1. Abstract
This memo defines an experimental portion of the Management
Information Base (MIB) for use with network management protocols in
the Internet community. In particular, it describes a set of managed
objects that allows the delegation of management scripts to mid-level
managers.
This memo does not specify a standard for the Internet community.
2. The SNMPv2 Network Management Framework
The SNMP Network Management Framework presently consists of three
major components. They are:
o the SMI, described in RFC 1902 [1] - the mechanisms used for
describing and naming objects for the purpose of management.
o the MIB-II, STD 17, RFC 1213 [2] - the core set of managed
objects for the Internet suite of protocols.
o the protocol, RFC 1157 [3] and/or RFC 1905 [4], - the protocol
for accessing managed objects.
The Framework permits new objects to be defined for the purpose of
experimentation and evaluation.
2.1. Object Definitions
Managed objects are accessed via a virtual information store, termed
the Management Information Base or MIB. Objects in the MIB are
defined using the subset of Abstract Syntax Notation One (ASN.1)
defined in the SMI[1]. In particular, each object type is named by an
OBJECT IDENTIFIER, an administratively assigned name. The object type
together with an object instance serves to uniquely identify a
specific instantiation of the object. For human convenience, we often
use a textual string, termed the object descriptor, to refer to the
object type.
Expires May 1998 [Page 2]
Internet-Draft Script MIB November 1997
3. Overview
The Script MIB module defined in this memo can be used to delegate
management functions to mid-level managers. Management functions are
defined as management scripts written in a management scripting
language. This MIB makes no assumptions about the language itself and
even allows distribution of compiled native code, if the mid-level
manager is able to execute native code under the control of this MIB.
The Script MIB defines a standard interface for the delegation of
management functions based on the Internet management framework. In
particular, it provides the following capabilities:
1. Capabilities to transfer management scripts to a mid-level
manager.
2. Capabilities for initiating, suspending, resuming and
terminating management scripts.
3. Capabilities to transfer arguments for management scripts.
4. Capabilities to monitor and control running management scripts.
5. Capabilities to transfer the results produced by running
management scripts.
This memo does not address any additional topics like the generation
of notifications or how to address remote agents from a mid-level
manager.
3.1. Terms
This section defines the terms used throughout this memo.
o A mid-level manager is a processing entity which is capable of
performing network management functions. For the scope of this
memo, a mid-level manager is assumed to implement the Script
MIB.
o A higher-level manager is a processing entity or human who
initiates and controls the operations performed by the mid-level
manager.
o A management script is a set of instructions written in an
executable language which implements a management function.
Expires May 1998 [Page 3]
Internet-Draft Script MIB November 1997
o A management scripting language is a language used to write
management scripts. Note, that the term scripting language does
not imply that the language must have the characteristics of
script languages.
o A mid-level manager can be decomposed into an agent entity which
implements the Script MIB defined in this memo and the runtime
system that executes scripts. The Script MIB sees the runtime
system as the managed resource which is controlled by this MIB.
4. Requirements and Design Issues
This section discusses some general requirements that have influenced
the design of the Script MIB.
o The Script MIB must not make assumptions about specific
languages.
o The Script MIB must provide mechanisms that help to avoid new
management problems (e.g. script version problems).
o The Script MIB must provide SNMP interfaces to all functions
required to delegate management scripts. However, other
protocols might be used in addition if they provide a
significant improvement in terms of convenience for
implementation or performance.
The following sections discuss some design issues in more detail.
4.1. Script Languages
The Script MIB defined in this memo makes no assumption about the
script language. This MIB can therefore be used in combination with
different languages (such as Tcl or Java) and/or different versions
of the same language. No assumptions are made about the format in
which management scripts are transferred.
The Script MIB makes information about the languages supported by a
mid-level manager available so that a higher-level manager can learn
about the capabilities provided by a Script MIB mid-level manager. A
version number is attached to a language so that a higher-level
manager can either select the language version required to execute a
particular script or select a script that fits the language supported
Expires May 1998 [Page 4]
Internet-Draft Script MIB November 1997
by the mid-level manager.
An additional table lists language extensions that provide features
not covered in the core language. Language extensions are usually
required to turn a general purpose language into a management
language. In many cases, language extensions will come in the form of
libraries that provide capabilities like sending SNMP requests to
remote SNMP agents or accessing the local MIB instrumentation. Every
extension is associated with a language and carries its own version
number.
4.2. Script Transfer
There are two different ways to transfer management scripts to the
mid-level manager. The first approach requires that the higher-level
manager pushes the script to the mid-level manager. This is therefore
called the 'push model'. The second approach is a 'pull model' where
the higher-level manager tells the mid-level manager where the script
is located and the mid-level manager retrieves the script itself.
The MIB defined in this memo supports both models. The 'push model'
is realized by a table which allows a manager to write scripts by
using a sequence of SNMP set requests. The script can be split into
several fragments in order to deal with SNMP packet size limitations.
The 'pull model' is realized by the use of Uniform Resource Locators
(URLs) [6] that point to the script source. The higher-level manager
writes the URL pointing to the script source to the mid-level manager
by sending a SNMP set request. The agent is then responsible for
retrieving the document using the protocol specified in the URL. This
allows the use of protocols like FTP [7] or HTTP [8] to transfer
large management scripts efficiently.
Scripts can be stored in non-volatile storage provided by the mid-
level manager. This allows a mid-level manager to restart scripts if
it is forced to reset itself (off-line restart) without requiring a
higher-level manager to push scripts back into the mid-level manager
after it resets itself.
Scripts have an attached version number so that it is possible to
differentiate between different versions of the same management
script.
Every management script has an administrative name which can be used
to refer to a particular script. This administrative name may be used
Expires May 1998 [Page 5]
Internet-Draft Script MIB November 1997
to derive the name which is used to access the script in non-volatile
memory. This mapping is implementation specific. However, the mapping
must ensure that the mid-level manager can handle multiple versions
of the same script as well as different scripts with the same
administrative name owned by independent higher-level managers. One
way to achieve this is to use the script version number and the
script owner in addition to the script name in order to derive the
internal name used to refer to a particular script.
4.3. Script Execution
The Script MIB permits execution of several instances of the same or
different management scripts. Script arguments are passed as an OCTET
STRING value and scripts return a single result value which is also
an OCTET STRING value. The semantic interpretation of these values is
left to the higher-level manager and the management script. A runtime
error stops the active script. An error code is left and error
specific information is stored as the result value.
Executing scripts have a status object attached which allows them to
be disabled and enabled.
A history of finished scripts is kept in the MIB to allow higher-
level managers to collect results at a later point in time (offline
operation). Control objects can be used to control how entries in the
history are aged out if the table fills up.
5. The Structure of the MIB
This section presents the structure of the MIB. The objects are
arranged into the following groups:
o language group (smLanguage)
o script group (smScript)
o executing script group (smExec)
5.1. The smLanguage Group
The smLanguage group is used to provide information about the
languages and the language extensions supported by the mid-level
manager. This group includes two tables and a directory of well known
Expires May 1998 [Page 6]
Internet-Draft Script MIB November 1997
management scripting languages. The smLanguageTable lists all
languages supported by a mid-level manager and the smExtensionTable
lists the extensions that are available for a given script language.
Well known scripting languages are listed in the smLanguageDir
subtree.
5.2. The smScript Group
The smScript group consists of two tables called smScriptTable and
smCodeTable. The smScriptTable lists all the scripts known to a mid-
level manager. This table defines objects that support the following
operations:
o download scripts via SNMP (push model)
o download scripts from a URL (pull model)
o read scripts from local non-volatile storage
o store scripts in local non-volatile storage
o delete scripts from local non-volatile storage
o list permanent scripts (that can't be changed or removed)
o control whether a script is readable or writable via SNMP
A status object called smScriptStatus allows a manager to read the
current status of a script. It is also used to provide error
information to a higher-level manager if an attempt to invoke one of
the operations listed above fails.
The source of a script is defined by the smScriptSource object. This
object may contain a URL pointing to a remote location which provides
access to the management script. The script source is read from the
smCodeTable described below or from non-volatile storage if the
smScriptSource object contains an empty URL. The smScriptStorageType
object is used to distinguish between scripts read from stable
storage and scripts read from the smCodeTable.
Scripts are automatically loaded into the run-time system by the
mid-level manager once the row status object is set to active.
Loading a script includes retrieving the script (probably from a
remote location), compiling the script for languages that require a
compilation step, and making the code available to the runtime
Expires May 1998 [Page 7]
Internet-Draft Script MIB November 1997
system. The smScriptStatus object is used to indicate the status of
the loading process. This object will start in the state
'retrieving', switch to the state 'compiling' and finally reach the
state result in an error state such as 'compilationFailed'.
The smCodeTable is used to access and modify the source code of a
script via SNMP. A script can be fragmented over multiple rows of the
smCodeTable in order to handle SNMP message size limitations. The
mid-level manager loads the modified code into the runtime system
once the smScriptRowStatus is set to 'active' again.
5.3. The smExec Group
The smExec group contains two tables. The smLaunchTable describes
pre-configured scripts that are waiting for an event which triggers
the invocation of pre-configured scripts. An entry in the
smLaunchTable attaches an argument to a script and a control variable
which defines the maximum number of times that this pre-configured
script may be concurrently running. The entry also defines the owner
of the scripts that are started from this entry.
The smRunTable lists all scripts that are currently running or have
finished recently. Every row contains the argument, result and exit
code as well as information about the current status and the start
and end time-stamps. There are three writable objects in the
smRunTable. The smRunLifeTime object defines the maximum time a
running script may run before it is terminated. The smRunExpireTime
object defines the time that a completed script can stay in the
smRunTable before it is removed automatically. The smRunAdminStatus
object can be used to suspend, continue, or abort a running script.
Expires May 1998 [Page 8]
Internet-Draft Script MIB November 1997
6. Definitions
SCRIPT-MIB DEFINITIONS ::= BEGIN
IMPORTS
MODULE-IDENTITY,
OBJECT-TYPE,
OBJECT-IDENTITY,
Integer32,
experimental
FROM SNMPv2-SMI
TEXTUAL-CONVENTION,
DisplayString,
RowStatus,
TimeStamp,
TimeInterval,
StorageType
FROM SNMPv2-TC
MODULE-COMPLIANCE,
OBJECT-GROUP
FROM SNMPv2-CONF;
scriptMIB MODULE-IDENTITY
LAST-UPDATED "9711210000Z"
ORGANIZATION "IETF DISMAN Working Group"
CONTACT-INFO
"David B. Levi
SNMP Research, Inc.
3001 Kimberlin Heights Road
Knoxville, TN 37920-9716
U.S.A.
Tel: +1 423 573 1434
E-mail: levi@snmp.com
Juergen Schoenwaelder
TU Braunschweig
Bueltenweg 74/75
38106 Braunschweig
Germany
Tel: +49-531-391-3283
E-mail: schoenw@ibr.cs.tu-bs.de"
DESCRIPTION
"This MIB module defines a MIB which provides mechanisms to
download, execute and control management scripts on remote
agents."
Expires May 1998 [Page 9]
Internet-Draft Script MIB November 1997
REVISION "9711210000Z"
DESCRIPTION
"The initial revision."
-- Get real registration number from IANA.
-- ::= { mib-2 XXXX }
::= { experimental 5678 }
--
-- The various groups defined within this MIB definition:
--
smObjects OBJECT IDENTIFIER ::= { scriptMIB 1 }
smConformance OBJECT IDENTIFIER ::= { scriptMIB 2 }
smLanguage OBJECT IDENTIFIER ::= { smObjects 1 }
smScript OBJECT IDENTIFIER ::= { smObjects 2 }
smExec OBJECT IDENTIFIER ::= { smObjects 3 }
--
-- Textual Conventions:
--
OwnerString ::= TEXTUAL-CONVENTION
DISPLAY-HINT "127a"
STATUS current
DESCRIPTION
"An owner string identifies the initiator or owner of a row
in a table. This label is set by the initiator to provide
for the following possibilities:
o A management station may recognize resources it owns
and no longer needs.
o A network operator can find the management station
that owns the resource and negotiate for it to be
freed.
o A network operator may decide to unilaterally free
resources another network operator has reserved.
o Upon initialization, a management station may
recognize resources it had reserved in the past. With
this information it may free the resources if it no
longer needs them.
Management stations and probes should support any format of
the owner string dictated by the local policy of the
organization. It is suggested that this name contain one or
more of the following: IP address, management station name,
network manager's name, location, or phone number. This
Expires May 1998 [Page 10]
Internet-Draft Script MIB November 1997
information will help users to share the resources more
effectively."
SYNTAX DisplayString (SIZE (0..127))
UniformResourceLocator ::= TEXTUAL-CONVENTION
DISPLAY-HINT "1023a"
STATUS current
DESCRIPTION
"This TC describes an object which holds a reference to a
(remote) resource by using the Uniform Resource Locator
(URL) notation as defined in RFC 1738. The allowed
character set and the encoding rules for this textual
convention are defined in RFC 1738 section 2.2."
SYNTAX OCTET STRING (SIZE (0..1023))
VersionString ::= TEXTUAL-CONVENTION
DISPLAY-HINT "31a"
STATUS current
DESCRIPTION
"This TC describes version strings that are used to
distinguish between different versions of a language, a
language extension or a script.
It is suggested that the version strings consist of one or
more decimal numbers separated by dots, where the first
number is called the major version number."
SYNTAX DisplayString (SIZE (0..31))
--
-- Script language and language extensions.
--
-- This group defines tables which list the languages and the
-- language extensions supported by the mid-level manager.
-- Languages are uniquely identified by object identifier values.
--
smLanguageDir OBJECT IDENTIFIER ::= { smLanguage 1 }
smLanguageJavaVM OBJECT-IDENTITY
STATUS current
DESCRIPTION
"The Java virtual machine."
REFERENCE
"The Java Virtual Machine Specification.
ISBN 0-201-63452-X"
::= { smLanguageDir 1 }
Expires May 1998 [Page 11]
Internet-Draft Script MIB November 1997
smLanguageTcl OBJECT-IDENTITY
STATUS current
DESCRIPTION
"The Tool Command Language (Tcl)."
REFERENCE
"Tcl and the Tk Toolkit.
ISBN 0-201-63337-X"
::= { smLanguageDir 2 }
smLanguagePerl OBJECT-IDENTITY
STATUS current
DESCRIPTION
"The Perl Language."
REFERENCE
"Programming Perl.
ISBN 1-56592-149-6"
::= { smLanguageDir 3 }
smLanguageScheme OBJECT-IDENTITY
STATUS current
DESCRIPTION
"The Scheme Language."
REFERENCE
"The Revised^4 Report on the Algorithmic Language Scheme.
MIT Press"
::= { smLanguageDir 4 }
smLanguageSNMPScriptLanguage OBJECT-IDENTITY
STATUS current
DESCRIPTION
"The SNMP Script Language defined by SNMP Research."
::= { smLanguageDir 5 }
smLanguageTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmLanguageEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This table lists supported script languages."
::= { smLanguage 2 }
smLanguageEntry OBJECT-TYPE
SYNTAX SmLanguageEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
Expires May 1998 [Page 12]
Internet-Draft Script MIB November 1997
"A smLanguageTable entry."
INDEX { smLanguageIndex }
::= { smLanguageTable 1 }
SmLanguageEntry ::= SEQUENCE {
smLanguageIndex Integer32,
smLanguageID OBJECT IDENTIFIER,
smLanguageVersion VersionString,
smLanguageDescr DisplayString
}
smLanguageIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this script language entry.
The value is expected to remain constant at least from one
re-initialization of the entity's network management system
to the next re-initialization."
::= { smLanguageEntry 1 }
smLanguageID OBJECT-TYPE
SYNTAX OBJECT IDENTIFIER
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The globally unique identification of the scripting
language."
::= { smLanguageEntry 2 }
smLanguageVersion OBJECT-TYPE
SYNTAX VersionString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The version of the scripting language."
::= { smLanguageEntry 3 }
smLanguageDescr OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"A textual description of the scripting language."
Expires May 1998 [Page 13]
Internet-Draft Script MIB November 1997
::= { smLanguageEntry 4 }
smExtensionTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmExtensionEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This table lists supported script language extensions."
::= { smLanguage 3 }
smExtensionEntry OBJECT-TYPE
SYNTAX SmExtensionEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A smExtensionTable entry."
INDEX { smLanguageIndex, smExtensionIndex }
::= { smExtensionTable 1 }
SmExtensionEntry ::= SEQUENCE {
smExtensionIndex Integer32,
smExtensionID OBJECT IDENTIFIER,
smExtensionVersion VersionString,
smExtensionDescr DisplayString
}
smExtensionIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this script language extension entry.
The value is expected to remain constant at least from one
re-initialization of the entity's network management system
to the next re-initialization."
::= { smExtensionEntry 1}
smExtensionID OBJECT-TYPE
SYNTAX OBJECT IDENTIFIER
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The globally unique identification of an extension for a
scripting language."
Expires May 1998 [Page 14]
Internet-Draft Script MIB November 1997
::= { smExtensionEntry 2 }
smExtensionVersion OBJECT-TYPE
SYNTAX VersionString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The version number of the extension of a scripting
language."
::= { smExtensionEntry 3 }
smExtensionDescr OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"A textual description of the extension of the
scripting language."
::= { smExtensionEntry 4 }
--
-- Scripts known by the mid-level manager.
--
-- This group defines a table which lists every script known to the
-- mid-level manager. Scripts may be loaded and removed through
-- manipulation of the smScriptTable. The source of the script
-- can be written to or read from the mid-level manager by means
-- of the smCodeTable.
--
smScriptNext OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"This variable is used for creating rows in the
smScriptTable. When retrieved, the value of this scalar
should be a value for smScriptIndex which does not
currently exist in the smScriptTable. If no new rows can
be created, this object will have a value of 0."
::= { smScript 1 }
smScriptTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmScriptEntry
MAX-ACCESS not-accessible
STATUS current
Expires May 1998 [Page 15]
Internet-Draft Script MIB November 1997
DESCRIPTION
"This table lists and describes locally known scripts."
::= { smScript 2 }
smScriptEntry OBJECT-TYPE
SYNTAX SmScriptEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry describing a particular script. Every script that
is stored in non-volatile memory is required to appear in
this script table."
INDEX { smLanguageIndex, smScriptIndex }
::= { smScriptTable 1 }
SmScriptEntry ::= SEQUENCE {
smScriptIndex Integer32,
smScriptName DisplayString,
smScriptDescr DisplayString,
smScriptVersion VersionString,
smScriptSource UniformResourceLocator,
smScriptStatus INTEGER,
smScriptOwner OwnerString,
smScriptStorageType StorageType,
smScriptRowStatus RowStatus
}
smScriptIndex OBJECT-TYPE
SYNTAX Integer32 (1..65535)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this script entry. This value must be unique for all
rows in the smScriptTable."
::= { smScriptEntry 1 }
smScriptName OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The administrative name of the script. This name may be
used by the agent to load or save the script into
non-volatile storage. The administrative name may be used
to derive the name (e.g. a file name) which is used by the
agent to access the script in non-volatile storage. The
Expires May 1998 [Page 16]
Internet-Draft Script MIB November 1997
details of this mapping are implementation specific.
However, the mapping needs to ensure that scripts created
by different managers with the same administrative name do
not map to the same name in non-volatile storage.
Setting the value of a smScriptName object changes the
administrative name. The agent has to update the name
(e.g. a file name) which is used to access the script in
non-volatile storage if the script controlled by this row
is stored in non-volatile storage."
::= { smScriptEntry 2 }
smScriptDescr OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"A description of the purpose of the script."
::= { smScriptEntry 3 }
smScriptVersion OBJECT-TYPE
SYNTAX VersionString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The version number of the script."
::= { smScriptEntry 4 }
smScriptSource OBJECT-TYPE
SYNTAX UniformResourceLocator
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines how the mid-level manager loads the
script source. The mid-level manager will load the source
from the URL contained in this object if the URL is not
empty.
An empty URL indicates that the script source is loaded
from local storage. The source is read from the smCodeTable
if the value of smScriptStorageType is volatile. Otherwise,
the source is read from non-volatile storage.
The following changes to smScriptSource require special
attention:
- Empty value changes to empty value:
Expires May 1998 [Page 17]
Internet-Draft Script MIB November 1997
This has no effect.
- Empty value changes to non-empty value:
This destroys the local script (possibly deleting it
from non-volatile storage), and initiates a download
of the script source into the mid-level manager from
the specified location.
- Non-empty value changes to empty value:
If the smScriptStorageType is nonVolatile, the
currently loaded script is written to non-volatile
storage. Otherwise, no effect.
- Non-empty value changes to non-empty value:
This initiates a download of the script into the
mid-level manager from the specified location.
Set requests to change this object are only valid if the
smScriptRowStatus is notInService or notReady."
DEFVAL { ''H }
::= { smScriptEntry 5 }
smScriptStatus OBJECT-TYPE
SYNTAX INTEGER {
unknown(1),
retrieving(2),
compiling(3),
available(4),
noSuchScript(5),
accessDenied(6),
wrongLanguage(7),
wrongVersion(8),
compilationFailed(9),
noResourcesLeft(10),
unknownProtocol(11),
noResponse(12),
genericError(13)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The status of the script described by this row. The script
status reflects the current status of this script in the
runtime system. The value of this object is only meaningful
when the value of the smScriptRowStatus object is active.
The first three status values indicate a transient state.
The value available(4) indicates that a script is loaded
into the runtime system and can be activated. The remaining
status values describe error conditions."
Expires May 1998 [Page 18]
Internet-Draft Script MIB November 1997
DEFVAL { unknown }
::= { smScriptEntry 6 }
smScriptOwner OBJECT-TYPE
SYNTAX OwnerString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The manager who created this row in the smScriptTable."
::= { smScriptEntry 7 }
smScriptStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines whether this row and the script
controlled by this row are kept in volatile storage and
lost upon reboot or if this row is backed up by
non-volatile or permanent storage.
Setting this object to nonVolatile stores the script
controlled by this row into non-volatile storage. Setting
this object to volatile removes a script from non-volatile
storage if the script has been in non-volatile storage
before. Attempts to set this object to permanent will
always fail.
The agent has to make sure that scripts controlled by a
row where smScriptStorageType is nonVolatile or permanent
are loaded at agent startup time.
The value of smScriptStorageType is only meaningful if the
value of the corresponding RowStatus object is active.
If smScriptStorageType has the value permanent(4), then all
objects whose MAX-ACCESS value is read-create must be
writable, with the exception of the smScriptStorageType and
smScriptRowStatus objects, which should be only be
readable."
DEFVAL { volatile }
::= { smScriptEntry 8 }
smScriptRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
Expires May 1998 [Page 19]
Internet-Draft Script MIB November 1997
DESCRIPTION
"The status of this smScriptEntry. A control that allows
entries to be added and removed from this table. It also
controls whether a script is known by the script runtime
system. Only scripts where the smScriptRowStatus is active
are known by the runtime system.
Changing the smScriptRowStatus from active to notInService
will remove the associated script from the runtime system.
The value of smScriptStatus should be reset to unknown.
Deleting conceptual rows from this table includes the
deletion of all resources associated with this row.
This implies that a script is removed from non-volatile
storage if the value of smScriptStorageType is non-volatile.
An entry may not exist in the active state unless all
required objects in the entry have appropriate values. The
script code is loaded into the runtime system whenever the
value of this object is changed to active. Rows that are
not complete or not in service are not known by the script
runtime system.
An entry may not leave the active state as long as the
script is executing. Attempts to do so will result in a
wrongValue error (see RFC 1903). In addition, the value of
smScriptAccess must be notAccessible or readOnly.
Attempts to destroy a row or to set a row notInService
where the value of the smScriptStorageType object is
permanent or readOnly will result in an inconsistentValue
error."
::= { smScriptEntry 9 }
smCodeTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmCodeEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This table contains the script code for scripts that are
retrieved via SNMP."
::= { smScript 3 }
smCodeEntry OBJECT-TYPE
SYNTAX SmCodeEntry
MAX-ACCESS not-accessible
Expires May 1998 [Page 20]
Internet-Draft Script MIB November 1997
STATUS current
DESCRIPTION
"An entry describing a particular fragment of a script."
INDEX { smLanguageIndex, smScriptIndex, smCodeIndex }
::= { smCodeTable 1 }
SmCodeEntry ::= SEQUENCE {
smCodeIndex Integer32,
smCodeText OCTET STRING,
smCodeRowStatus RowStatus
}
smCodeIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The index value associated with this code fragment. Index
values start at 1 and have consecutive values."
::= { smCodeEntry 1 }
smCodeText OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..255))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The code that makes up this fragment of the script."
::= { smCodeEntry 2 }
smCodeRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this smCodeEntry. A control that allows
entries to be added and removed from this table."
::= { smCodeEntry 3 }
--
-- Script execution.
--
-- This group defines tables which provide a mechanism for
-- execution of a script to be initiated, suspended, resumed,
-- and terminated. It also provides a mechanism for keeping a
-- history of script executions and their results.
--
Expires May 1998 [Page 21]
Internet-Draft Script MIB November 1997
smLaunchNext OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"This variable is used for creating rows in the smLaunchTable.
When retrieved, the value of this variable should be a
value for smLaunchIndex which does not currently exist in the
smLaunchTable. If no new rows can be created, this object
will have a value of 0."
::= { smExec 1 }
smLaunchTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmLaunchEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This table lists and describes scripts that are ready
to be executed together with their parameters."
::= { smExec 2 }
smLaunchEntry OBJECT-TYPE
SYNTAX SmLaunchEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry describing a particular executable script."
INDEX { smLanguageIndex, smScriptIndex, smLaunchIndex }
::= { smLaunchTable 1 }
SmLaunchEntry ::= SEQUENCE {
smLaunchIndex Integer32,
smLaunchArgument OCTET STRING,
smLaunchMaxRunning Integer32,
smLaunchMaxCompleted Integer32,
smLaunchLifeTime TimeInterval,
smLaunchExpireTime TimeInterval,
smLaunchStart Integer32,
smLaunchControl INTEGER,
smLaunchOwner OwnerString,
smLaunchStorageType StorageType,
smLaunchRowStatus RowStatus
}
smLaunchIndex OBJECT-TYPE
SYNTAX Integer32 (1..65535)
MAX-ACCESS not-accessible
Expires May 1998 [Page 22]
Internet-Draft Script MIB November 1997
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this executable script. This value must be unique
for all rows in the smLaunchTable."
::= { smLaunchEntry 1 }
smLaunchArgument OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..2048))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The argument supplied to the script. When a script is
invoked, the value of this object is used to initialize
the smRunArgument object."
DEFVAL { ''H }
::= { smLaunchEntry 2 }
smLaunchMaxRunning OBJECT-TYPE
SYNTAX Integer32 (1..1024)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The maximum number of concurrently running scripts that may
be invoked from this entry in the smLaunchTable."
DEFVAL { 1 }
::= { smLaunchEntry 3 }
smLaunchMaxCompleted OBJECT-TYPE
SYNTAX Integer32 (1..1024)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The maximum number of entries in the smRunTable for
completed scripts which were invoked from this entry in the
smLaunchTable. Whenever a script halts, the value of this
object is checked. If the number of rows in the smRunTable
for completed scripts is greater than this value, then
entries in the smRunTable are deleted until the number of
completed scripts is smaller than the value of this object.
Scripts whose smRunEndTime value indicates the oldest
completion time are deleted first."
DEFVAL { 1 }
::= { smLaunchEntry 4 }
smLaunchLifeTime OBJECT-TYPE
SYNTAX TimeInterval
Expires May 1998 [Page 23]
Internet-Draft Script MIB November 1997
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The default maximum amount of time that a script launched
from this entry may run. The value of this object is used
to initialize the smRunLifeTime object when a script is
launched. Changing the value of an smLaunchLifeTime
instance does not affect scripts previously launched from
this entry."
DEFVAL { 360000 }
::= { smLaunchEntry 5 }
smLaunchExpireTime OBJECT-TYPE
SYNTAX TimeInterval
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The default maximum amount of time that information about a
script launched from this entry is kept in the smRunTable
after the script has completed execution. The value of
this object is used to initialize the smRunExpireTime
object when a script is launched. Changing the value of an
smLaunchExpireTime instance does not affect scripts
previously launched from this entry."
DEFVAL { 360000 }
::= { smLaunchEntry 6 }
smLaunchStart OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object is used to start the execution of scripts. When
retrieved, the value will be the value of smRunIndex for
the last script that started execution controlled by this
row. The value will be zero if no script started execution
yet.
A script is started by setting this object to an unused
smRunIndex value. A new row in the smRunTable will be
created which is indexed by the value supplied by the
set-request. An unused value can be obtained by reading
the smRunNext object.
Setting this object to a value which is already used to index
a row in the smRunTable will result in an inconsistentValue
error."
Expires May 1998 [Page 24]
Internet-Draft Script MIB November 1997
DEFVAL { 0 }
::= { smLaunchEntry 7 }
smLaunchControl OBJECT-TYPE
SYNTAX INTEGER {
abort(1),
suspend(2),
continue(3),
nop(4)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object is used to request a state change for all
running scripts in the smRunTable that were started from
the current row in the smLaunchTable.
Setting this object to abort(1), suspend(2) or continue(3)
will set the smRunAdminStatus object of all applicable rows
in the smRunTable to abort(1), suspend(2) or continue(3)
respectively. The phrase `applicable rows' means the set of
rows which were created from this entry in the smLaunchTable
and whose value of smRunOperStatus allows the corresponding
state change as described in the definition of the
smRunAdminStatus object. Setting this object to nop(4) will
always succeed and has no effect."
DEFVAL { nop }
::= { smLaunchEntry 8 }
smLaunchOwner OBJECT-TYPE
SYNTAX OwnerString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The manager who owns this row in the smLaunchTable and the
entries in the smRunTable that are related to this row."
::= { smLaunchEntry 9 }
smLaunchStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines if this row is kept in volatile storage
and lost upon reboot or if this row is backed up by stable
storage.
Expires May 1998 [Page 25]
Internet-Draft Script MIB November 1997
The value of smLaunchStorageType is only meaningful if the
value of the corresponding RowStatus object is active.
If smLaunchStorageType has the value permanent(4), then all
objects whose MAX-ACCESS value is read-create must be
writable, with the exception of the smLaunchStorageType and
smLaunchRowStatus objects, which should be only be readable."
DEFVAL { volatile }
::= { smLaunchEntry 10 }
smLaunchRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this smLaunchEntry. A control that allows
entries to be added and removed from this table."
::= { smLaunchEntry 11 }
smRunNext OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"This variable is used for creating rows in the smRunTable.
When retrieved, the value of this variable should be a
value for smRunIndex which does not currently exist in the
smRunTable. If no new rows can be created, this object will
have a value of 0."
::= { smExec 3 }
smRunTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmRunEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This table lists and describes scripts that are currently
running or have been running in the past."
::= { smExec 4 }
smRunEntry OBJECT-TYPE
SYNTAX SmRunEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry describing a particular running or finished
Expires May 1998 [Page 26]
Internet-Draft Script MIB November 1997
script."
INDEX { smLanguageIndex, smScriptIndex, smLaunchIndex, smRunIndex }
::= { smRunTable 1 }
SmRunEntry ::= SEQUENCE {
smRunIndex Integer32,
smRunArgument OCTET STRING,
smRunStartTime TimeStamp,
smRunEndTime TimeStamp,
smRunLifeTime TimeInterval,
smRunExpireTime TimeInterval,
smRunExitCode INTEGER,
smRunResult OCTET STRING,
smRunOperStatus INTEGER,
smRunAdminStatus INTEGER
}
smRunIndex OBJECT-TYPE
SYNTAX Integer32 (1..65535)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this running or finished script. This value must be
unique for all rows in the smRunTable."
::= { smRunEntry 1 }
smRunArgument OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..2048))
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The argument supplied to the script when it started."
DEFVAL { ''H }
::= { smRunEntry 2 }
smRunStartTime OBJECT-TYPE
SYNTAX TimeStamp
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of sysUpTime when this script started running.
This object will have the value 0 if this script has not
started yet."
DEFVAL { 0 }
::= { smRunEntry 3 }
Expires May 1998 [Page 27]
Internet-Draft Script MIB November 1997
smRunEndTime OBJECT-TYPE
SYNTAX TimeStamp
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of sysUpTime when this script finished execution.
This object will have the value 0 if the script has not yet
finished execution."
DEFVAL { 0 }
::= { smRunEntry 4 }
smRunLifeTime OBJECT-TYPE
SYNTAX TimeInterval
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"This value specifies how long the script execution defined
by the row can run. The value when this object is read
specifies the remaining time that the script may run. When
this time limit is exceeded, the script is immediately
halted.
The value of this object may be set in order to extend or
limit the remaining time that the script may run. Setting
this value to 0 will halt script execution immediately,
and, if the value of smRunExpireTime is also 0, will remove
this entry from the smRunTable.
The value of smRunLifeTime reflects the real-time execution
time as seen by the outside world. The value of this object
will always be 0 for a script that finished execution."
::= { smRunEntry 5 }
smRunExpireTime OBJECT-TYPE
SYNTAX TimeInterval
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"This value specifies how long this row can exist in the
smRunTable after the script has completed running. The
value when this object is read specifies the remaining
time that the row may exist. The value will begin
'counting down' the remaining time when the script
finishes running. When the time limit is exceeded,
the row is immediately destroyed.
The value of this object may be set in order to extend or
Expires May 1998 [Page 28]
Internet-Draft Script MIB November 1997
limit the remaining time that the row may exist. Setting
the value to 0 will remove this entry from the smRunTable
if the script has completed running or the smRunLifeTime
object is also set to 0."
::= { smRunEntry 6 }
smRunExitCode OBJECT-TYPE
SYNTAX INTEGER {
noError(1),
halted(2),
lifeTimeExceeded(3),
noResourcesLeft(4),
languageError(5),
runtimeError(6),
invalidArgument(7),
securityViolation(8),
genericError(9)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of this object indicates the reason why a script
finished execution. If the script has not yet begun
running, or is currently running, the value will be
noError. Otherwise, the value will be one of the following:
- noError
The script completed successfully with no errors.
- halted
The script was halted by a Set request from an
authorized manager.
- lifeTimeExceeded
The script exited because the smRunLifeTime time
limit was exceeded.
- noResourcesLeft
The script exited because it ran out of resources.
For example, the script may have run out of memory.
- languageError
The script exited because of a language error. For
example, a syntax error in a interpreted language.
- runtimeError
The script exited due to a runtime error. For
Expires May 1998 [Page 29]
Internet-Draft Script MIB November 1997
example, a division by zero was attempted.
- invalidArgument
The script could not be run because the arguments
were invalid.
- securityViolation
The script exited due to a security violation.
- genericError
The script exited for an unspecified reason."
DEFVAL { noError }
::= { smRunEntry 7 }
smRunResult OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..2048))
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The result value produced by the running script. The value
of this object will be an empty string if the script has
not yet finished execution.
This object may contain an error message if the script
finished in an abnormal way. In particular, if the
script exits with a genericError, the implementation
should attempt to put a more descriptive message in
this object."
DEFVAL { ''H }
::= { smRunEntry 8 }
smRunOperStatus OBJECT-TYPE
SYNTAX INTEGER {
initializing(1),
executing(2),
completed(3),
aborted(4),
suspended(5)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of this object indicates the status of the script
execution defined by this row. If the script has been
invoked but has not yet begun execution, the value will be
initializing(1). If the script is currently running, the value
will be executing(2). If the script has completed running
Expires May 1998 [Page 30]
Internet-Draft Script MIB November 1997
normally, the value will be completed(3). If the script
stopped execution abnormally, the value will be aborted(4).
If a running script is suspended temporarily, the value will
be suspended(5)."
::= { smRunEntry 9 }
smRunAdminStatus OBJECT-TYPE
SYNTAX INTEGER {
abort(1),
suspend(2),
continue(3)
}
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"The value of this object indicates the desired status of the
script execution defined by this row.
Setting this object to abort(1) will abort execution if the
value of smRunOperStatus is initializing(1), executing(2)
or suspended(5). Setting this object to abort(1) when the
value of smRunOperStatus is completed(3) or aborted(4) will
result in an inconsistentValue error response.
Setting this object to suspend(2) will suspend execution
if the value of smRunOperStatus is executing(2). Setting this
object to suspend(2) will cause an inconsistentValue error
if the value of smRunOperStatus is not execution(2).
Setting this object to continue(3) will resume execution
if the value of smRunOperStatus is suspended(5). Setting this
object to continue(3) will cause an inconsistentValue error
if the value of smRunOperStatus is not suspended(2)."
::= { smRunEntry 10 }
-- conformance information
smCompliances OBJECT IDENTIFIER ::= { smConformance 1 }
smGroups OBJECT IDENTIFIER ::= { smConformance 2 }
-- compliance statements
smFullCompliance MODULE-COMPLIANCE
STATUS current
DESCRIPTION
"The compliance statement for SNMP entities which implement
the full script MIB."
Expires May 1998 [Page 31]
Internet-Draft Script MIB November 1997
MODULE -- this module
MANDATORY-GROUPS {
smLanguageGroup,
smScriptGroup,
smCodeGroup,
smLaunchGroup,
smRunGroup
}
::= { smCompliances 1 }
smLanguageGroup OBJECT-GROUP
OBJECTS {
smLanguageVersion,
smLanguageID,
smLanguageDescr,
smExtensionID,
smExtensionVersion,
smExtensionDescr
}
STATUS current
DESCRIPTION
"A collection of objects providing information about the
capabilities of the scripting engine."
::= { smGroups 1 }
smScriptGroup OBJECT-GROUP
OBJECTS {
smScriptNext,
smScriptName,
smScriptDescr,
smScriptVersion,
smScriptSource,
smScriptStatus,
smScriptOwner,
smScriptStorageType,
smScriptRowStatus
}
STATUS current
DESCRIPTION
"A collection of objects providing information about
installed scripts."
::= { smGroups 2 }
smCodeGroup OBJECT-GROUP
OBJECTS {
smCodeText,
smCodeRowStatus
Expires May 1998 [Page 32]
Internet-Draft Script MIB November 1997
}
STATUS current
DESCRIPTION
"A collection of objects used to download or modify scripts
by using SNMP set requests."
::= { smGroups 3 }
smLaunchGroup OBJECT-GROUP
OBJECTS {
smLaunchNext,
smLaunchArgument,
smLaunchMaxRunning,
smLaunchMaxCompleted,
smLaunchLifeTime,
smLaunchExpireTime,
smLaunchStart,
smLaunchControl,
smLaunchOwner,
smLaunchStorageType,
smLaunchRowStatus
}
STATUS current
DESCRIPTION
"A collection of objects providing information about scripts
that can be launched."
::= { smGroups 4 }
smRunGroup OBJECT-GROUP
OBJECTS {
smRunNext,
smRunArgument,
smRunStartTime,
smRunEndTime,
smRunLifeTime,
smRunExpireTime,
smRunExitCode,
smRunResult,
smRunOperStatus,
smRunAdminStatus
}
STATUS current
DESCRIPTION
"A collection of objects providing information about running
scripts."
::= { smGroups 5 }
END
Expires May 1998 [Page 33]
Internet-Draft Script MIB November 1997
7. Security Considerations
This MIB provides the ability to distribute applications written in
an arbitrary language to remote systems in a network. The security
features of the languages available in a particular implementation
should be taken into consideration when deploying an implementation
of this MIB.
8. Full Copyright Statement
Copyright (C) The Internet Society (1997). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
9. Acknowledgments
This document was produced by the IETF Distributed Management
(DISMAN) working group.
Expires May 1998 [Page 34]
Internet-Draft Script MIB November 1997
10. Editor's Address
David B. Levi Email: levi@snmp.com
SNMP Research, Inc. Tel: +1 423 573 1434
3001 Kimberlin Heights Road
Knoxville, TN 37920-9716
U.S.A.
Juergen Schoenwaelder Email: schoenw@ibr.cs.tu-bs.de
TU Braunschweig Tel: +49 531 391-3683
Bueltenweg 74/75
38106 Braunschweig
Germany
11. References
[1] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Structure of Management Information for Version 2 of
the Simple Network Management Protocol (SNMPv2)", RFC1902, SNMP
Research,Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc.,
International Network Services, January 1996.
[2] McCloghrie, K., and M. Rose, Editors, "Management Information Base
for Network Management of TCP/IP-based internets: MIB-II", STD 17,
RFC 1213, Hughes LAN Systems, Performance Systems International,
March 1991.
[3] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network
Management Protocol", RFC 1157, SNMP Research, Performance Systems
International, Performance Systems International, MIT Laboratory
for Computer Science, May 1990.
[4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Protocol Operations for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC1905, SNMP Research,Inc.,
Cisco Systems, Inc., Dover Beach Consulting, Inc., International
Network Services, January 1996.
[5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Textual Conventions for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC1903, SNMP Research,Inc.,
Cisco Systems, Inc., Dover Beach Consulting, Inc., International
Network Services, January 1996.
Expires May 1998 [Page 35]
Internet-Draft Script MIB November 1997
[6] T. Berners-Lee, L. Masinter, and M. McCahill, Editors, "Uniform
Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation,
University of Minnesota, December 1994.
[7] J. Postel, and J. Reynolds, "File Transfer Protocol", STD 9, RFC
959, ISI, October 1985.
[8] T. Berners-Lee, R. Fielding, and H. Nielsen, "Hypertext Transfer
Protocol -- HTTP/1.0", RFC 1945, MIT/LCS, UC Irvine, MIT/LCS, May
1996.
Expires May 1998 [Page 36]
Internet-Draft Script MIB November 1997
12. Usage Examples
This section presents some examples that explain how a higher-level
manager might use the MIB defined in this memo. The purpose of these
examples is to explain the steps that are normally used to delegate
management scripts.
12.1. Loading a script via SNMP (push model)
The following example explains the steps performed by a higher-level
manager to load a script into the mid-level manager by using the push
model.
0. The higher-level manager checks the smLanguageTable and the
smExtensionTable in order to select the script or language
appropriate for this mid-level manager.
1. Retrieve an index for an unused row in the smScriptTable by
sending a get-request to retrieve smScriptNext.0.
2. Create a row in the smScriptTable by issuing a set-request using
the index retrieved in step 1. The smScriptRowStatus object is
set to createAndWait and the smScriptSource object is set to an
empty string. The smScriptStorageType object is set to volatile
to indicate that the script will be loaded via the smCodeTable.
The smScriptOwner should be set to a string which identifies the
higher-level manager.
3. Push the script to the mid-level manager by issuing a couple of
set-requests to the smCodeTable.
4. The higher-level manager sends a set-request to set the
smScriptRowStatus object to active. The agent will pass the row
to the runtime system which starts to load the code from the
smCodeTable.
5. The higher-level manager polls the smScriptStatus object until
the value is either available or one of the error status codes.
The script can only be used if the value of smScriptStatus is
available.
6. If the higher-level manager wants to store the script in local
non-volatile storage, it should send a set-request which
includes the value of smScriptName (if not set yet) and the
value nonVolatile for the smScriptRowStatus object.
Expires May 1998 [Page 37]
Internet-Draft Script MIB November 1997
12.2. Loading a script via a URL (pull model)
This example explains the steps performed by higher-level manager to
load a script into the mid-level manager by using the pull model.
0. The higher-level manager checks the smLanguageTable and the
smExtensionTable in order to select the script or language
appropriate for this mid-level manager.
1. Retrieve an index for an unused row in the smScriptTable by
sending a get-request to retrieve smScriptNext.0.
2. Create a row in the smScriptTable by issuing a set-request using
the index retrieved in step 1. The smScriptRowStatus object is
set to createAndWait and the smScriptSource object is set to the
URL that points to the script. The smScriptOwner should be set
to a string which identifies the higher-level manager.
3. The higher-level manager sends a set-request to set the
smScriptRowStatus object to active. The agent will pass the row
to the runtime system which starts to download the code from the
location given by the smScriptSource object.
4. The higher-level manager polls the smScriptStatus object until
the value is either available or one of the error status codes.
The script can only be used if the value of smScriptStatus is
available.
5. If the higher-level manager wants to store the script in local
non-volatile storage, it should send a set-request which
includes the value of smScriptName (if not set yet) and the
value nonVolatile for the smScriptRowStatus object.
12.3. Updating and removing an existing script
This section explains how a higher-level manager updates or removes a
script from the mid-level manager.
0. The script is de-activated by setting the smScriptRowStatus to
notInService. This step will only succeed if this script is not
in use. Setting the smScriptRowStatus to notInService will also
remove the script from the runtime system.
1. The higher-level manager sets smScriptSource to an empty string.
Expires May 1998 [Page 38]
Internet-Draft Script MIB November 1997
2. The higher-level manager sends set-requests to modify the script
in the smCodeTable.
3. The higher-level manager sends a set-request to set the
smScriptRowStatus object to active. The agent will pass the row
to the runtime system which starts to load the code from the
smCodeTable.
4. The higher-level manager polls the smScriptStatus object until
the value is either available or one of the error status codes.
The script can only be used if the value of smScriptStatus is
available.
A script is removed from the runtime system be setting the
smScriptRowStatus object to notInService or destroy. Setting the
smScriptRowStatus object to destroy will also remove the row from the
smScriptTable and the code from the smCodeTable.
12.4. Starting a script using SNMP
This section explains how a higher-level manager starts scripts by
sending SNMP set-requests to a mid-level manager. This is in general
a two phase operation: The first step is to create a row in the
smLaunchTable which defines all the parameters. The second step is to
"instantiate" a running script from the row in the smLaunchTable.
0. Retrieve an index for an unused row in the smLaunchTable by
sending a get-request to retrieve smLaunchNext.0.
1. Create a row in the smLaunchTable by sending a set-request using
the index retrieved in step 0. Activate the new entry in the
smLaunchTable by setting the smLaunchRowStatus to active once
the row is complete.
2. Retrieving an unused index into the smRunTable by reading the
smRunNext object.
3. Start script execution by setting the smLaunchStart object to
the index value retrieved in the previous step.
Expires May 1998 [Page 39]
Internet-Draft Script MIB November 1997
13. Open Issues
This section documents some open issues. This section will be removed
when this Internet Draft is revised.
o Can we use the Meta-Variables defined in the disman MIB to make
script results accessible via SNMP?
o This draft should adopt the terminology defined in the DISMAN
framework.
o The error states should be explained. It might be useful to join
the error definitions into a textual convention for this
purpose.
o Does it make sense to define compliance statements that allow an
implementor to skip the smCodeTable?
o Should the script MIB support/require the concept of suspending
and resuming script execution?
o Should the smCodeIndex be of type OBJECT IDENTIFIER instead of
INTEGER to allow arbitrary insertions without renumbering?
o Setting smLauchStart to 0 will start the script with a self
generated PID value?
o Should the language index be replaced by a pointer to the
language, which can be 0? This would allow to use the MIB to
start/stop hard-wired build-in management functions and it will
simplify the indexing scheme.
o Replace the OwnerString attribute with an index suitable for
SNMPv3 view-based access control.
o Add text to explain how to configure MIB views properly to the
security considerations section.
o Include David's tables that explains when a script is available
in the smCodeTable and when it is read/written from/to NV
storage.
Expires May 1998 [Page 40]
Internet-Draft Script MIB November 1997
14. Closed Issues
This section documents some closed issues. This section will be
removed when this Internet Draft is revised.
o Do we need additional instrumentation to monitor and control the
runtime system, e.g. an indication about the resources (CPU,
memory, ...) used by running scripts? Yes if possible in a
language independent form. (San Jose)
o Does it make sense to define a set of notifications that are
emitted when the execution status of a script changes?
Notifications should be generated if a script finishes execution
with an error exit code. It is the responsibility of the script
to create a notification if it terminates correctly. (San Jose)
o Do we need additional scheduling mechanisms that allow to start
scripts e.g. in a crontab like fashion? Yes, but this should be
covered by the DISMAN MIB. (San Jose)
Expires May 1998 [Page 41]
Internet-Draft Script MIB November 1997
15. Changes from <draft-ietf-disman-script-mib-00.txt>
This section documents changes from the previous draft. This section
will be removed when this Internet Draft will be published as an RFC.
o Removed smLanguageVersion from the INDEX clause of
smLanguageEntry.
o Changed the order of smLanguageVersion and smLanguageID to make
it consistent with the smExtensionTable.
o Changed the definition of OwnerString so that it is compatible
with the RMON definition. (The OwnerString definition should be
defined in the DISMAN MIB.)
o Clarified the definition of UniformResourceLocator to use the
character set and encodings as defined by RFC 1738.
o Changed the definition of VersionString to use a DisplayString
as a base type. Changes the maximum length to 31 octets so that
it easily fits into a 32 byte null-terminated string.
o Restricted the values of smLanguageIndex to positive numbers.
o Allowed to change smScriptSource if smRowStatus is notReady.
o Changed the type of smExecInterval to Unsigned32.
o Changed the order of the first two operations in example 11.3.
o Added a default value to smExecLastError, smExecInterval and
smExecLastFinished.
o Changed the wording of requirement 1 to avoid the term "concrete
language".
o Clarified the requirement to handle multiple version of the same
script as well as scripts with the same administrative name
owned by different managers in section 4.2.
o Added text to the smScriptRowStatus description which requires
to reset the smScriptStatus to unknown if the smScriptRowStatus
is set to notInService. Also clarified that the value of
smScriptAccess must be notAccessible or readOnly when setting
smScriptRowStatus to active.
Expires May 1998 [Page 42]
Internet-Draft Script MIB November 1997
o Added some more DEFVALs for RowStorage and some other objects.
o Changes the range of smScriptNext and smExecNext to more
reasonable values. Allow the value 0 so that the agent can give
a hint if we have reached a resource limit (Perkins).
o Moved the smCodeTable into the smScript group and removed the
smCode group.
o Changed the maximum size of smExecArgument and smExecLastResult
to 2048.
o Minor modifications to the MIB so that it passes the smicng
compiler contained in Dave Perkins and Evan McGinnis book.
o Rewrote the smExec group. The scheduling mechanism has been
removed and the smExecTable has been split into the smExecTable
and the smRunTable.
o Changed the smScriptStatus state 'loading' into 'retrieving' to
avoid confusion with runtime systems that have a loading phase.
o Rewrote some paragraphs in the text to document the smExecTable
and the smRunTable.
o More changes in the smExecTable and the smRunTable.
o Replaced the RowStorage TC with RFC 1903 StorageType since there
are code bases that already support this TC.
Expires May 1998 [Page 43]
Internet-Draft Script MIB November 1997
16. Changes from <draft-ietf-disman-script-mib-01.txt>
This section documents changes from the previous draft. This section
will be removed when this Internet Draft will be published as an RFC.
o Split the OBJECT-GROUP definition into smaller pieces. Changed
the compliance definition to full compliance. This allows to add
other compliance statements for agents that for example do not
allow to download or modify scripts.
o Changed the name of the smExecTable to smLaunchTable to avoid
confusing.
o Changed the names of the following objects as follows:
smRunLifeTime -> smRunLifeTime
smRunCompletedLifeTime -> smRunExpireTime
smLaunchRunningLifeTime -> smLaunchLifeTime
smLaunchCompletedLifeTime -> smLaunchExpireTime
o Fixed the registration of smLanguageID, smLanguageVersion,
smRunNext and smRunTable to close some gaps.
o Clarified that smRunLifeTime is always 0 when a script has
finished execution.
o Removed the smScriptAccess. The SNMP access control model should
be used to control whether script source is readable/writable or
invisible.
o Changed smScriptRowStorage and smLaunchRowStorage to
smScriptStorageType and smLaunchStorageType which is more
consistent with other MIBs.
o Changed smScriptRowOwner and smLaunchRowOwner to smScriptOwner
and smLaunchOwner.
o Split the section about open and closed issues into two separate
sections.
Expires May 1998 [Page 44]
Internet-Draft Script MIB November 1997
Table of Contents
1 Abstract ..................................................... 2
2 The SNMPv2 Network Management Framework ...................... 2
2.1 Object Definitions ......................................... 2
3 Overview ..................................................... 3
3.1 Terms ...................................................... 3
4 Requirements and Design Issues ............................... 4
4.1 Script Languages ........................................... 4
4.2 Script Transfer ............................................ 5
4.3 Script Execution ........................................... 6
5 The Structure of the MIB ..................................... 6
5.1 The smLanguage Group ....................................... 6
5.2 The smScript Group ......................................... 7
5.3 The smExec Group ........................................... 8
6 Definitions .................................................. 9
7 Security Considerations ...................................... 34
8 Full Copyright Statement ..................................... 34
9 Acknowledgments .............................................. 34
10 Editor's Address ............................................ 35
11 References .................................................. 35
12 Usage Examples .............................................. 37
12.1 Loading a script via SNMP (push model) .................... 37
12.2 Loading a script via a URL (pull model) ................... 38
12.3 Updating and removing an existing script .................. 38
12.4 Starting a script using SNMP .............................. 39
13 Open Issues ................................................. 40
14 Closed Issues ............................................... 41
15 Changes from <draft-ietf-disman-script-mib-00.txt> .......... 42
16 Changes from <draft-ietf-disman-script-mib-01.txt> .......... 44
Expires May 1998 [Page 45]
