Internet-Draft Script MIB November 1996
Definitions of Managed Objects for the
Delegation of Management Scripts
November 25, 1996
<draft-ietf-disman-script-mib-00.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 May 1997 [Page 1]
Internet-Draft Script MIB November 1996
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 1997 [Page 2]
Internet-Draft Script MIB November 1996
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 1997 [Page 3]
Internet-Draft Script MIB November 1996
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 be independent of concrete languages.
o The Script MIB must provide mechanisms that help to avoid new
management problems (e.g. script versioning 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 transfered.
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
by the mid-level manager.
Expires May 1997 [Page 4]
Internet-Draft Script MIB November 1996
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
downloading 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
to derive the name which is used to access the script in non-volatile
memory. This mapping is implementation specific. However, the mapping
Expires May 1997 [Page 5]
Internet-Draft Script MIB November 1996
should make use of the script version number and the script owner to
allow either multiple versions of the same script or different
scripts with the same administrative name defined by independent
higher-level managers.
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.
Script execution can be repeated multiple times in regular time
intervals. This provides invocation of management scripts off-line. A
manager must specify the number of repeated invocations and the time
interval between two invocations.
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 script code group (smCode)
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 1997 [Page 6]
Internet-Draft Script MIB November 1996
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 a single table called smScriptTable.
It is used to control 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 permanent scripts (that can't be changed or removed)
o control whether a script is readable or writable via SNMP
A status object smScriptStatus provides access to the current status
of a script. This status object is also used to provide error
information to a higher-level manager if an attempt to invoke one of
the operations listed above fails.
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 if the script is
readable via SNMP. The smScriptStatus object is used to indicate the
status of the loading process. For a compiled language, this object
will start in the state 'loading', switch to the state 'compiling'
and finally reach the state 'available'. The 'compiling' state is
skipped for languages that do not require a compilation step. Errors
during the loading or compilation phase will result in an error state
such as compilationFailed.
The source of a script is defined by the smScriptSource object. This
Expires May 1997 [Page 7]
Internet-Draft Script MIB November 1996
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 is 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.
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.
5.3. The smCode Group
The smCode group contains a single table which is used to access and
modify the source code of a script via SNMP. 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.4. The smExec Group
Expires May 1997 [Page 8]
Internet-Draft Script MIB November 1996
6. Definitions
SCRIPT-MIB DEFINITIONS ::= BEGIN
IMPORTS
MODULE-IDENTITY, OBJECT-TYPE, OBJECT-IDENTITY, Integer32, Gauge32,
experimental FROM SNMPv2-SMI
TEXTUAL-CONVENTION, DisplayString, RowStatus, TimeStamp
FROM SNMPv2-TC
MODULE-COMPLIANCE, OBJECT-GROUP
FROM SNMPv2-CONF;
scriptMIB MODULE-IDENTITY
LAST-UPDATED "9611250000Z"
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."
::= { 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 }
smCode OBJECT IDENTIFIER ::= { smObjects 3 }
smExec OBJECT IDENTIFIER ::= { smObjects 4 }
Expires May 1997 [Page 9]
Internet-Draft Script MIB November 1996
smState OBJECT IDENTIFIER ::= { smObjects 5 }
--
-- Textual Conventions:
--
RowStorage ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"A RowStorage object defines how a conceptul row which is
controlled by a RowStatus object is stored. A row which
is volatile(1) is lost upon reboot. A row which is
nonVolatile(2) or permanent(3) is backed up by stable storage.
A row which is permanent(3) cannot be changed nor deleted.
The value of a RowStorage object is only meaningful if the
value of the corresponding RowStatus object is active."
SYNTAX INTEGER {
volatile(1), -- e.g. in RAM
nonVolatile(2), -- e.g. in NVRAM
permanent(3) -- e.g. in ROM
}
OwnerString ::= TEXTUAL-CONVENTION
DISPLAY-HINT "255a"
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,
Expires May 1997 [Page 10]
Internet-Draft Script MIB November 1996
network manager's name, location, or phone number. This
information will help users to share the resources more
effectively."
SYNTAX OCTET STRING (SIZE (0..255))
UniformResourceLocator ::= TEXTUAL-CONVENTION
DISPLAY-HINT "1024a"
STATUS current
DESCRIPTION
"This TC describes an object which holds a reference to a
(remote) resource by using the Uniform Resource Locator
notation as defined in RFC 1738."
SYNTAX OCTET STRING (SIZE (0..1024))
VersionString ::= TEXTUAL-CONVENTION
DISPLAY-HINT "40a"
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 OCTET STRING (SIZE (0..40))
--
-- 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
Expires May 1997 [Page 11]
Internet-Draft Script MIB November 1996
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
"A smLanguageTable entry."
Expires May 1997 [Page 12]
Internet-Draft Script MIB November 1996
INDEX { smLanguageIndex, smLanguageVersion }
::= { smLanguageTable 1 }
SmLanguageEntry ::= SEQUENCE {
smLanguageIndex Integer32,
smLanguageVersion VersionString,
smLanguageID OBJECT IDENTIFIER,
smLanguageDescr DisplayString
}
smLanguageIndex OBJECT-TYPE
SYNTAX Integer32
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 }
smLanguageVersion OBJECT-TYPE
SYNTAX VersionString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The version of the scripting language."
::= { smLanguageEntry 2 }
smLanguageID OBJECT-TYPE
SYNTAX OBJECT IDENTIFIER
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The globally unique identification 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."
::= { smLanguageEntry 4 }
Expires May 1997 [Page 13]
Internet-Draft Script MIB November 1996
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."
::= { smExtensionEntry 2 }
smExtensionVersion OBJECT-TYPE
Expires May 1997 [Page 14]
Internet-Draft Script MIB November 1996
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.
--
smScriptNext OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
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."
::= { 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 }
smScriptEntry OBJECT-TYPE
SYNTAX SmScriptEntry
Expires May 1997 [Page 15]
Internet-Draft Script MIB November 1996
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 RowStorage,
smScriptRowStatus RowStatus
}
smScriptIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
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
name in non-volatile storage.
Expires May 1997 [Page 16]
Internet-Draft Script MIB November 1996
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
from non-volatile storage), and initiates a download
of the script source into the mid-level manager from
Expires May 1997 [Page 17]
Internet-Draft Script MIB November 1996
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 set to notInService."
::= { 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 will result in
an inconsistenValue error."
::= { smScriptEntry 6 }
smScriptStatus OBJECT-TYPE
SYNTAX INTEGER {
unknown(1),
loading(2),
compiling(3),
available(4),
noSuchScript(5),
accessDenied(6),
wrongLanguage(7),
wrongVersion(8),
compilationFailed(9),
Expires May 1997 [Page 18]
Internet-Draft Script MIB November 1996
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."
::= { 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 RowStorage
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines whether this row and the script
controlled by this row is 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 using a
name derived from the smScriptName object. 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 smScriptRowStorage is nonVolatile or permanent
are loaded at agent startup time."
Expires May 1997 [Page 19]
Internet-Draft Script MIB November 1996
::= { 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.
This includes the removal of all resources associated with
the script. This implies that a script is removed from
non-volatile storage if the value of smScriptRowStorage
is non-volatile.
Deleting conceptual rows from this table includes the
deletion of all resources associated with this row.
An entry may not exist in the active state unless all
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).
Attempts to destroy a row or to set a row notInService where
the value of the smScriptRowStorage object is permanent will
result in an inconsistentValue error."
::= { smScriptEntry 10 }
--
-- Script source code.
--
-- This group defines a table which provides a mechanism for a script
-- to be loaded into a mid-level manager using a sequence of SNMP set
-- operations.
--
Expires May 1997 [Page 20]
Internet-Draft Script MIB November 1996
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."
::= { smCode 1 }
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 }
smCodeRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this smCodeEntry. A control that allows
Expires May 1997 [Page 21]
Internet-Draft Script MIB November 1996
entries to be added and removed from this table."
::= { smCodeEntry 3 }
--
-- Script execution.
--
-- This group defines a table which provides a mechanism for
-- execution of a script to be initiated, suspended, resumed,
-- terminated. It also provides a mechanism for a script
-- to be executed periodically.
--
smExecNext OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
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."
::= { smExec 1 }
smExecTable OBJECT-TYPE
SYNTAX SEQUENCE OF SmExecEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This table lists and describes executing scripts."
::= { smExec 2 }
smExecEntry OBJECT-TYPE
SYNTAX SmExecEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry describing a particular script execution."
INDEX { smLanguageIndex, smScriptIndex, smExecIndex }
::= { smExecTable 1 }
SmExecEntry ::= SEQUENCE {
smExecIndex Integer32,
smExecInterval Integer32,
smExecRemaining Gauge32,
smExecAdminStatus INTEGER,
smExecOperStatus INTEGER,
Expires May 1997 [Page 22]
Internet-Draft Script MIB November 1996
smExecErrorBehaviour INTEGER,
smExecArgument OCTET STRING,
smExecLastFinish TimeStamp,
smExecLastError INTEGER,
smExecLastResult OCTET STRING,
smExecRowOwner OwnerString,
smExecRowStorage RowStorage,
smExecRowStatus RowStatus
}
smExecIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The locally arbitrary, but unique identifier associated
with this script execution. This value must be unique
for all rows in the smExecTable."
::= { smExecEntry 1 }
smExecInterval OBJECT-TYPE
SYNTAX Integer32
UNITS "seconds"
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The desired interval between two executions of this script."
::= { smExecEntry 2 }
smExecRemaining OBJECT-TYPE
SYNTAX Gauge32
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The number of script executions until this entry
'auto-disables'. This constitutes a 'dead-man switch'
which will keep the script from executing forever. The
top-level manager should periodically refresh this
number in order to keep the management script running."
DEFVAL { 1 }
::= { smExecEntry 3 }
smExecAdminStatus OBJECT-TYPE
SYNTAX INTEGER {
enabled(1),
disabled(2),
execute(3)
Expires May 1997 [Page 23]
Internet-Draft Script MIB November 1996
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The desired status of the script."
::= { smExecEntry 4 }
smExecOperStatus OBJECT-TYPE
SYNTAX INTEGER {
enabled(1),
disabled(2),
executing(3)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The actual status of the script."
::= { smExecEntry 5 }
smExecErrorBehaviour OBJECT-TYPE
SYNTAX INTEGER {
retryNextInterval(1),
disable(2)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The behaviour if script execution fails because of an error."
DEFVAL { retryNextInterval }
::= { smExecEntry 6 }
smExecArgument OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..65535))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The argument supplied to the script."
::= { smExecEntry 7 }
smExecLastFinish OBJECT-TYPE
SYNTAX TimeStamp
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of sysUpTime when this script last finished
execution. If this operation never executed, this object
will have the value 0."
Expires May 1997 [Page 24]
Internet-Draft Script MIB November 1996
::= { smExecEntry 8 }
smExecLastError OBJECT-TYPE
SYNTAX INTEGER {
noError(1),
noResourcesLeft(2),
languageError(3),
runtimeError(4),
invalidArgument(5),
securityViolation(6),
genericError(7)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The error code of the last finished script execution."
::= { smExecEntry 9 }
smExecLastResult OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..65535))
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The result value of the last finished script execution.
This object contains an error message if the script
finished in an abnormal way."
::= { smExecEntry 10 }
smExecRowOwner OBJECT-TYPE
SYNTAX OwnerString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The manager who created this row in the smExecTable."
::= { smExecEntry 11 }
smExecRowStorage OBJECT-TYPE
SYNTAX RowStorage
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."
::= { smExecEntry 12 }
smExecRowStatus OBJECT-TYPE
Expires May 1997 [Page 25]
Internet-Draft Script MIB November 1996
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 13 }
-- 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 represent
generic testing capabilities."
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,
smExecInterval,
smExecRemaining,
Expires May 1997 [Page 26]
Internet-Draft Script MIB November 1996
smExecAdminStatus,
smExecOperStatus,
smExecErrorBehaviour,
smExecArgument,
smExecLastFinish,
smExecLastError,
smExecLastResult,
smExecRowOwner,
smExecRowStorage,
smExecRowStatus
}
STATUS current
DESCRIPTION
"A collection of objects providing a generic
scripting capability."
::= { smGroups 1 }
END
7. Security Considerations
Security issues are not discussed in this memo.
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.
[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.
Expires May 1997 [Page 27]
Internet-Draft Script MIB November 1996
[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 May 1997 [Page 28]
Internet-Draft Script MIB November 1996
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 May 1997 [Page 29]
Internet-Draft Script MIB November 1996
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 higher-level manager sets smScriptSource to an empty string
and smScriptAccess to read-write (if not done yet).
Expires May 1997 [Page 30]
Internet-Draft Script MIB November 1996
1. The row 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.
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.
Expires May 1997 [Page 31]
Internet-Draft Script MIB November 1996
12. Open Issues
This section documents some open issues. This section will be removed
when this Internet Draft is revised.
o Should the MIB provide a mechanism to make results available via
a URL? Should the higher-level manager pull the results or does
the mid-level manager push the results (via traps/informs)?
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?
o Does it make sense to define a set of notifications that are
emitted when the execution status of a script changes?
o Do we need a mechanism to clone scripts?
o Do we need additional scheduling mechanisms that allow to start
scripts e.g. in a crontab like fashion?
Expires May 1997 [Page 32]
Internet-Draft Script MIB November 1996
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 smCode Group ........................................... 8
5.4 The smExec Group ........................................... 8
6 Definitions .................................................. 9
7 Security Considerations ...................................... 27
8 Acknowledgments .............................................. 27
9 References ................................................... 27
10 Author's Address ............................................ 28
11 Usage Examples .............................................. 29
11.1 Loading a script via SNMP (push model) .................... 29
11.2 Loading a script via a URL (pull model) ................... 30
11.3 Updating and removing an existing script .................. 30
12 Open Issues ................................................. 32
Expires May 1997 [Page 33]
