Internet-Draft Script MIB March 1997
Definitions of Managed Objects for the
Delegation of Management Scripts
March 12, 1997
<draft-ietf-disman-script-mib-01.txt>
David B. Levi
SNMP Research, Inc.
levi@snmp.com
Juergen Schoenwaelder
University of Twente
schoenw@cs.utwente.nl
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).
Expires September 1997 [Page 1]
Internet-Draft Script MIB March 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 September 1997 [Page 2]
Internet-Draft Script MIB March 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 September 1997 [Page 3]
Internet-Draft Script MIB March 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 September 1997 [Page 4]
Internet-Draft Script MIB March 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 September 1997 [Page 5]
Internet-Draft Script MIB March 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 September 1997 [Page 6]
Internet-Draft Script MIB March 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 smScriptRowStorage
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 September 1997 [Page 7]
Internet-Draft Script MIB March 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 smScriptAccess object in the smScriptTable controls whether the
code of a script appears in the smCodeTable and if it is read-only or
read-write.
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. Only
scripts where the smScriptAccess object is set to readWrite and the
smScriptRowStatus is set to 'notInService' can be modified. 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 smExecTable describes pre-
configured scripts that are waiting for an event which triggers the
invocation of pre-configured scripts. An entry in the smExecTable
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
smRunCompletedLifeTime 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 September 1997 [Page 8]
Internet-Draft Script MIB March 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 "9702241234Z"
ORGANIZATION "IETF DISMAN Working Group"
CONTACT-INFO
"David B. Levi
SNMP Research, Inc.
3001 Kimberlin Heights Road
Knoxville, TN 37920-9716
Tel: +1 423 573 1434
E-mail: levi@snmp.com
Juergen Schoenwaelder
University of Twente
P.O. Box 217
7500 AE Enschede
The Netherlands
Tel: +31-53-489-3678
E-mail: schoenw@cs.utwente.nl"
DESCRIPTION
"This MIB module defines a MIB which provides mechanisms to
download, execute and control management scripts on remote
agents."
REVISION "9703121234Z"
Expires September 1997 [Page 9]
Internet-Draft Script MIB March 1997
DESCRIPTION
"The initial revision."
::= { experimental 5678 } -- TBD
--
-- 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 4 }
--
-- 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
information will help users to share the resources more
effectively."
SYNTAX DisplayString (SIZE (0..127))
Expires September 1997 [Page 10]
Internet-Draft Script MIB March 1997
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 }
smLanguageTcl OBJECT-IDENTITY
STATUS current
DESCRIPTION
"The Tool Command Language (Tcl)."
Expires September 1997 [Page 11]
Internet-Draft Script MIB March 1997
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
"A smLanguageTable entry."
INDEX { smLanguageIndex }
::= { smLanguageTable 1 }
Expires September 1997 [Page 12]
Internet-Draft Script MIB March 1997
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 3 }
smLanguageVersion OBJECT-TYPE
SYNTAX VersionString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The version of the scripting language."
::= { smLanguageEntry 2 }
smLanguageDescr OBJECT-TYPE
SYNTAX DisplayString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"A textual description of the scripting language."
::= { smLanguageEntry 4 }
smExtensionTable OBJECT-TYPE
Expires September 1997 [Page 13]
Internet-Draft Script MIB March 1997
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."
::= { smExtensionEntry 2 }
smExtensionVersion OBJECT-TYPE
SYNTAX VersionString
Expires September 1997 [Page 14]
Internet-Draft Script MIB March 1997
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
variable 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
DESCRIPTION
"This table lists and describes locally known scripts."
::= { smScript 2 }
Expires September 1997 [Page 15]
Internet-Draft Script MIB March 1997
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,
smScriptAccess INTEGER,
smScriptStatus INTEGER,
smScriptRowOwner OwnerString,
smScriptRowStorage 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 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
Expires September 1997 [Page 16]
Internet-Draft Script MIB March 1997
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 smScriptRowStorage 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:
This has no effect.
- Empty value changes to non-empty value:
This destroys the local script (possibly deleting it
Expires September 1997 [Page 17]
Internet-Draft Script MIB March 1997
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 smScriptRowStorage 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 }
smScriptAccess OBJECT-TYPE
SYNTAX INTEGER {
notAccessible(1),
readOnly(2),
readWrite(3)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines if the script controlled by this row is
accessible via the smCodeTable. The value notAccessible
indicates that the code does not appear in the smCodeTable.
The value readOnly indicates that the code is readable but
all attempts to change the code in the smCodeTable will
result in an inconsistentValue error. The value readWrite
allows a manager to make changes in the smCodeTable as long
as the smScriptRowStatus is notInService.
Attempts to set this object to readWrite for a script which
has a smScriptRowStorage value of permanent or readOnly will
result in an inconsistentValue error."
DEFVAL { notAccessible }
::= { smScriptEntry 6 }
smScriptStatus OBJECT-TYPE
SYNTAX INTEGER {
unknown(1),
retrieving(2),
compiling(3),
available(4),
noSuchScript(5),
Expires September 1997 [Page 18]
Internet-Draft Script MIB March 1997
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."
DEFVAL { unknown }
::= { smScriptEntry 7 }
smScriptRowOwner OBJECT-TYPE
SYNTAX OwnerString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The manager who created this row in the smScriptTable."
::= { smScriptEntry 8 }
smScriptRowStorage 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
Expires September 1997 [Page 19]
Internet-Draft Script MIB March 1997
fail.
The agent has to make sure that scripts controlled by a
row where smScriptRowStorage is nonVolatile or permanent
are loaded at agent startup time.
The value of smScriptRowStorage is only meaningful if the
value of the corresponding RowStatus object is active.
If smScriptRowStorage has the value permanent(4), then all
objects whose MAX-ACCESS value is read-create must be
writable, with the exception of the smScriptRowStorage and
smScriptRowStatus objects, which should be only be readable."
DEFVAL { volatile }
::= { smScriptEntry 9 }
smScriptRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
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 smScriptRowStorage 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 an wrongValue error (see RFC 1903). In addition, the
value of smScriptAccess must be notAccessible or readOnly.
Expires September 1997 [Page 20]
Internet-Draft Script MIB March 1997
Attempts to destroy a row or to set a row notInService where
the value of the smScriptRowStorage object is permanent or
readOnly will result in an inconsistentValue error."
::= { smScriptEntry 10 }
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
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 }
Expires September 1997 [Page 21]
Internet-Draft Script MIB March 1997
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.
--
smExecNext OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"This variable is used for creating rows in the
smExecTable. When retrieved, the value of this
variable should be a value for smExecIndex which
does not currently exist in the smExecTable. If
no new rows can be created, this object will have
a value of 0."
::= { smExec 1 }
smExecTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmExecEntry
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 }
smExecEntry OBJECT-TYPE
SYNTAX SmExecEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry describing a particular executable script."
Expires September 1997 [Page 22]
Internet-Draft Script MIB March 1997
INDEX { smLanguageIndex, smScriptIndex, smExecIndex }
::= { smExecTable 1 }
SmExecEntry ::= SEQUENCE {
smExecIndex Integer32,
smExecArgument OCTET STRING,
smExecMaxRunning Integer32,
smExecMaxCompleted Integer32,
smExecRunningLifeTime TimeInterval,
smExecCompletedLifeTime TimeInterval,
smExecStart Integer32,
smExecControl INTEGER,
smExecRowOwner OwnerString,
smExecRowStorage StorageType,
smExecRowStatus RowStatus
}
smExecIndex OBJECT-TYPE
SYNTAX Integer32 (1..65535)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this executable script. This value must be unique
for all rows in the smExecTable."
::= { smExecEntry 1 }
smExecArgument 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 }
::= { smExecEntry 2 }
smExecMaxRunning 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 smExecTable."
DEFVAL { 1 }
::= { smExecEntry 3 }
Expires September 1997 [Page 23]
Internet-Draft Script MIB March 1997
smExecMaxCompleted 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 smExecTable.
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 }
::= { smExecEntry 4 }
smExecRunningLifeTime OBJECT-TYPE
SYNTAX TimeInterval
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The default maximum amount of time that a script invoked
from this entry in the smExecTable may run. When a script
is invoked, the value of this object is used to initialize
the smRunLifeTime object."
DEFVAL { 360000 }
::= { smExecEntry 5 }
smExecCompletedLifeTime OBJECT-TYPE
SYNTAX TimeInterval
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The default maximum amount of time that a row in the smRunTable
invoked from this entry in the smExecTable may exist after the
script has completed execution. When a script is invoked, the
value of this object is used to initialize the
smCompletedLifeTime object."
DEFVAL { 360000 }
::= { smExecEntry 6 }
smExecStart OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
Expires September 1997 [Page 24]
Internet-Draft Script MIB March 1997
"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."
DEFVAL { 0 }
::= { smExecEntry 7 }
smExecControl 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 smExecTable.
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 smExecTable
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 }
::= { smExecEntry 8 }
smExecRowOwner OBJECT-TYPE
SYNTAX OwnerString
MAX-ACCESS read-create
Expires September 1997 [Page 25]
Internet-Draft Script MIB March 1997
STATUS current
DESCRIPTION
"The manager who owns this row in the smExecTable and the
entries in the smRunTable that are related to this row."
::= { smExecEntry 9 }
smExecRowStorage 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.
The value of smExecRowStorage is only meaningful if the
value of the corresponding RowStatus object is active.
If smExecRowStorage has the value permanent(4), then all
objects whose MAX-ACCESS value is read-create must be
writable, with the exception of the smExecRowStorage and
smExecRowStatus objects, which should be only be readable."
DEFVAL { volatile }
::= { smExecEntry 10 }
smExecRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this smExecEntry. A control that allows
entries to be added and removed from this table."
::= { smExecEntry 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 4 }
Expires September 1997 [Page 26]
Internet-Draft Script MIB March 1997
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 5 }
smRunEntry OBJECT-TYPE
SYNTAX SmRunEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry describing a particular running or finished script."
INDEX { smLanguageIndex, smScriptIndex, smExecIndex, smRunIndex }
::= { smRunTable 1 }
SmRunEntry ::= SEQUENCE {
smRunIndex Integer32,
smRunArgument OCTET STRING,
smRunStartTime TimeStamp,
smRunEndTime TimeStamp,
smRunLifeTime TimeInterval,
smRunCompletedLifeTime 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."
Expires September 1997 [Page 27]
Internet-Draft Script MIB March 1997
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 }
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 smRunCompletedLifeTime 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."
::= { smRunEntry 5 }
smRunCompletedLifeTime OBJECT-TYPE
Expires September 1997 [Page 28]
Internet-Draft Script MIB March 1997
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
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
Expires September 1997 [Page 29]
Internet-Draft Script MIB March 1997
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 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),
Expires September 1997 [Page 30]
Internet-Draft Script MIB March 1997
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
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 }
Expires September 1997 [Page 31]
Internet-Draft Script MIB March 1997
-- conformance information
smCompliances OBJECT IDENTIFIER ::= { smConformance 1 }
smGroups OBJECT IDENTIFIER ::= { smConformance 2 }
-- compliance statements
smCompliance MODULE-COMPLIANCE
STATUS current
DESCRIPTION
"The compliance statement for SNMP entities which implement
the script MIB."
MODULE -- this module
MANDATORY-GROUPS { smGroup }
::= { smCompliances 1 }
smGroup OBJECT-GROUP
OBJECTS {
smLanguageVersion,
smLanguageID,
smLanguageDescr,
smExtensionID,
smExtensionVersion,
smExtensionDescr,
smScriptNext,
smScriptName,
smScriptDescr,
smScriptVersion,
smScriptSource,
smScriptAccess,
smScriptStatus,
smScriptRowOwner,
smScriptRowStorage,
smScriptRowStatus,
smCodeText,
smCodeRowStatus,
smExecNext,
smExecArgument,
smExecMaxRunning,
smExecMaxCompleted,
smExecRunningLifeTime,
smExecCompletedLifeTime,
smExecStart,
smExecControl,
smExecRowOwner,
smExecRowStorage,
smExecRowStatus,
Expires September 1997 [Page 32]
Internet-Draft Script MIB March 1997
smRunNext,
smRunArgument,
smRunStartTime,
smRunEndTime,
smRunLifeTime,
smRunCompletedLifeTime,
smRunExitCode,
smRunResult,
smRunOperStatus,
smRunAdminStatus
}
STATUS current
DESCRIPTION
"A collection of objects providing a generic
scripting capability."
::= { smGroups 1 }
END
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. Acknowledgments
This document was produced by the IETF Distributed Management
(DISMAN) working group.
9. 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.
Expires September 1997 [Page 33]
Internet-Draft Script MIB March 1997
[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.
[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.
10. Author's Address
David B. Levi Juergen Schoenwaelder
SNMP Research, Inc. University of Twente
3001 Kimberlin Heights Road P.O. Box 217
Knoxville, TN 37920-9716 7500 AE Enschede
U.S.A. The Netherlands
Phone: +1 423 573 1434 Phone: +31-53-489-3678
EMail: levi@snmp.com EMail: schoenw@cs.utwente.nl
Expires September 1997 [Page 34]
Internet-Draft Script MIB March 1997
11. 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.
11.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 smScriptRowStorage object is set to volatile
to indicate that the script will be loaded via the smCodeTable.
The smScriptAccess object should be set to readWrite so that the
script can be modified in the smCodeTable. The smScriptRowOwner
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
Expires September 1997 [Page 35]
Internet-Draft Script MIB March 1997
includes the value of smScriptName (if not set yet) and the
value nonVolatile for the smScriptRowStatus object.
11.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 smScriptRowOwner 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.
11.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
Expires September 1997 [Page 36]
Internet-Draft Script MIB March 1997
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
and smScriptAccess to read-write (if not done yet).
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.
11.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
smExecTable which defines all the parameters. The second step is to
"instantiate" a running script from the row in the smExecTable.
0. Retrieve an index for an unused row in the smExecTable by
sending a get-request to retrieve smExecNext.0.
1. Create a row in the smExecTable by sending a set-request using
the index retrieved in step 0. Activate the new entry in the
smExecTable by setting the smExecRowStatus 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 smExecStart object to the
index value retrieved in the previous step.
Expires September 1997 [Page 37]
Internet-Draft Script MIB March 1997
12. Open and Closed 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 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)
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 the concept of suspending and
resuming script execution?
Expires September 1997 [Page 38]
Internet-Draft Script MIB March 1997
13. 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 is revised.
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 September 1997 [Page 39]
Internet-Draft Script MIB March 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 September 1997 [Page 40]
Internet-Draft Script MIB March 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 ...................................... 33
8 Acknowledgments .............................................. 33
9 References ................................................... 33
10 Author's Address ............................................ 34
11 Usage Examples .............................................. 35
11.1 Loading a script via SNMP (push model) .................... 35
11.2 Loading a script via a URL (pull model) ................... 36
11.3 Updating and removing an existing script .................. 36
11.4 Starting a script using SNMP .............................. 37
12 Open and Closed Issues ...................................... 38
13 Changes from <draft-ietf-disman-script-mib-00.txt> .......... 39
Expires September 1997 [Page 41]
