Internet-Draft Script MIB February 1998 Definitions of Managed Objects for the Delegation of Management Scripts March 3, 1998 David B. Levi SNMP Research, Inc. levi@snmp.com Juergen Schoenwaelder TU Braunschweig schoenw@ibr.cs.tu-bs.de Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Expires September 1998 [Page 1] Internet-Draft Script MIB February 1998 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 allow the delegation of management scripts to mid-level managers. This memo does not specify a standard for the Internet community. 2. The SNMP Network Management Framework The SNMP Network Management Framework presently consists of three major components. They are: o the SMI, described in RFC 1902 [1], RFC 1903 [2] - the mechanisms used for describing and naming objects for the purpose of management. o the MIB-II, STD 17, RFC 1213 [3] - the core set of managed objects for the Internet suite of protocols. o the protocol, RFC 1157 [4] and/or RFC 1905 [5], RFC 1906 [6] and/or RFC 2272 [7], RFC 2274 [8] - 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 1998 [Page 2] Internet-Draft Script MIB February 1998 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 1998 [Page 3] Internet-Draft Script MIB February 1998 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 scripting languages. o A mid-level manager can be decomposed into an SNMP 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 or runtime systems. 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. o The Script MIB must be organized so that access can be controlled effectively by using view-based access control [9]. 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 Expires September 1998 [Page 4] Internet-Draft Script MIB February 1998 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. 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) [10] 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 [11] or HTTP [12] 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. Expires September 1998 [Page 5] Internet-Draft Script MIB February 1998 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 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 or other management script. Runtime errors terminate active scripts. An exit code is left in the MIB and error specific information is stored as the result value. A notification is generated when a script terminates with an error exit code. Executing scripts have a status object attached which allows script execution to be suspended, resumed, or aborted. The precise semantics of the suspend and resume operations are language and runtime system dependent. Some runtime systems may not implement the suspend/resume operations. 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) Expires September 1998 [Page 6] Internet-Draft Script MIB February 1998 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 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. Additional languages may be registered in other branches of the global registration tree. 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 not be changed or removed) o control the script status A status object called smScriptOperStatus allows a manager to read the current status of a script. It is also used to provide error information to a higher-level manager if an attempt to invoke one of the operations listed above fails. The source of a script is defined by the smScriptSource object. This object may contain a URL pointing to a remote location which provides access to the management script. The script source is read from the smCodeTable described below or from non-volatile storage if the smScriptSource object contains an empty URL. The smScriptStorageType object is used to distinguish between scripts read from stable storage and scripts read from the smCodeTable. Expires September 1998 [Page 7] Internet-Draft Script MIB February 1998 Scripts are automatically loaded into the run-time system by the mid-level manager once the smScriptAdminStatus object is set to `enabled'. 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 system. The smScriptOperStatus 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 `enabled'. Errors during the retrieval or compilation phase will result in an error state such as `compilationFailed'. The smCodeTable is used to access and modify the source code of a script via SNMP. A script can be fragmented over multiple rows of the smCodeTable in order to handle SNMP message size limitations. The mid-level manager loads the modified code into the runtime system once the smScriptAdminStatus is set to `enabled' again. 5.3. The smExec Group The smExec group contains two tables. The smLaunchTable describes pre-configured scripts that are waiting for an event which triggers the invocation of pre-configured scripts. An entry in the smLaunchTable attaches an argument to a script and control variables which for example define the maximum number of times that this pre- configured script may be running concurrently. The smRunTable lists all scripts that are currently running or have finished recently. Every row contains the argument, result and exit code as well as information about the current status and the start and end time-stamps. There are three writable objects in the smRunTable. The smRunLifeTime object defines the maximum time a running script may run before it is terminated. The smRunExpireTime object defines the time that a completed script can stay in the smRunTable before it is removed automatically. The smRunAdminStatus object can be used to suspend, resume, or abort a running script. 6. The Indexing Structure XXX TBD Expires September 1998 [Page 8] Internet-Draft Script MIB February 1998 7. Definitions SCRIPT-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, OBJECT-IDENTITY, NOTIFICATION-TYPE, Integer32, experimental FROM SNMPv2-SMI TEXTUAL-CONVENTION, RowStatus, TimeStamp, TimeInterval, StorageType FROM SNMPv2-TC MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP FROM SNMPv2-CONF SnmpAdminString FROM SNMP-FRAMEWORK-MIB; scriptMIB MODULE-IDENTITY LAST-UPDATED "9803030000Z" ORGANIZATION "IETF DISMAN Working Group" CONTACT-INFO "David B. Levi SNMP Research, Inc. 3001 Kimberlin Heights Road Knoxville, TN 37920-9716 U.S.A. Tel: +1 423 573 1434 E-mail: levi@snmp.com Juergen Schoenwaelder TU Braunschweig Bueltenweg 74/75 38106 Braunschweig Germany Tel: +49-531-391-3283 E-mail: schoenw@ibr.cs.tu-bs.de" DESCRIPTION "This MIB module defines a MIB which provides mechanisms to download, execute and control management scripts on remote mid-level managers." -- Get real registration number from IANA. -- ::= { mib-2 XXXX } ::= { experimental 5678 } -- -- The groups defined within this MIB module: Expires September 1998 [Page 9] Internet-Draft Script MIB February 1998 -- smObjects OBJECT IDENTIFIER ::= { scriptMIB 1 } smNotifications OBJECT IDENTIFIER ::= { scriptMIB 2 } smConformance OBJECT IDENTIFIER ::= { scriptMIB 3 } smLanguage OBJECT IDENTIFIER ::= { smObjects 1 } smScript OBJECT IDENTIFIER ::= { smObjects 2 } smExec OBJECT IDENTIFIER ::= { smObjects 3 } -- -- Textual Conventions: -- 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 (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..1024)) VersionString ::= TEXTUAL-CONVENTION DISPLAY-HINT "32a" 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 a version string consist of one or more decimal numbers separated by dots, where the first number is called the major version number." SYNTAX SnmpAdminString (SIZE (0..32)) ExitCode ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "The ExitCode textual convention descibes the exit code from a running script. The exit code may have one of the following values: - `noError', which indicates that the script completed successfully without errors; Expires September 1998 [Page 10] Internet-Draft Script MIB February 1998 - `halted', which indicates that the script was halted by a request from an authorized manager; - `lifeTimeExceeded', which indicates that the script exited because a time limit was exceeded; - `noResourcesLeft', which indicates that the script exited because it ran out of resources (e.g. memory); - `languageError', which indicates that the script exited because of a language error (e.g. a syntax error in an interpreted language); - `runtimeError', which indicates that the script exited due to a runtime error (e.g. a division by zero); - `invalidArgument', which indicates that the script could not be run because of invalid script arguments; - `securityViolation', which indicates that the script exited due to a security violation; - `genericError', which indicates that the script exited for an unspecified reason." SYNTAX INTEGER { noError(1), halted(2), lifeTimeExceeded(3), noResourcesLeft(4), languageError(5), runtimeError(6), invalidArgument(7), securityViolation(8), genericError(9) } -- -- 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 Expires September 1998 [Page 11] Internet-Draft Script MIB February 1998 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)." 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 } smLanguagePSL OBJECT-IDENTITY STATUS current DESCRIPTION "The PSL language defined by BCM." ::= { smLanguageDir 6 } Expires September 1998 [Page 12] Internet-Draft Script MIB February 1998 smLanguageSMSL OBJECT-IDENTITY STATUS current DESCRIPTION "The Systems Management Scripting Language." REFERENCE "ISO/ITU Command Sequencer. ISO 10164-21 or ITU X.753" ::= { smLanguageDir 7 } 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 "An entry describing a particular language." INDEX { smLanguageIndex } ::= { smLanguageTable 1 } SmLanguageEntry ::= SEQUENCE { smLanguageIndex Integer32, smLanguageID OBJECT IDENTIFIER, smLanguageVersion VersionString, smLanguageDescr SnmpAdminString } smLanguageIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this 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 } Expires September 1998 [Page 13] Internet-Draft Script MIB February 1998 smLanguageID OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-only STATUS current DESCRIPTION "The globally unique identification of the language." ::= { smLanguageEntry 2 } smLanguageVersion OBJECT-TYPE SYNTAX VersionString MAX-ACCESS read-only STATUS current DESCRIPTION "The version number of the language." ::= { smLanguageEntry 3 } smLanguageDescr OBJECT-TYPE SYNTAX SnmpAdminString MAX-ACCESS read-only STATUS current DESCRIPTION "A textual description of the language." ::= { smLanguageEntry 4 } smExtensionTable OBJECT-TYPE SYNTAX SEQUENCE OF SmExtensionEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists supported language extensions." ::= { smLanguage 3 } smExtensionEntry OBJECT-TYPE SYNTAX SmExtensionEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular language extension." INDEX { smLanguageIndex, smExtensionIndex } ::= { smExtensionTable 1 } SmExtensionEntry ::= SEQUENCE { smExtensionIndex Integer32, smExtensionID OBJECT IDENTIFIER, smExtensionVersion VersionString, smExtensionDescr SnmpAdminString Expires September 1998 [Page 14] Internet-Draft Script MIB February 1998 } smExtensionIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this 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 the language extension." ::= { smExtensionEntry 2 } smExtensionVersion OBJECT-TYPE SYNTAX VersionString MAX-ACCESS read-only STATUS current DESCRIPTION "The version number of the language extension." ::= { smExtensionEntry 3 } smExtensionDescr OBJECT-TYPE SYNTAX SnmpAdminString MAX-ACCESS read-only STATUS current DESCRIPTION "A textual description of the language extension." ::= { 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 can be added and removed through -- manipulation of the smScriptTable. The source of the script Expires September 1998 [Page 15] Internet-Draft Script MIB February 1998 -- can be written to or read from the mid-level manager by means -- of the smCodeTable. -- smScriptNext OBJECT-TYPE SYNTAX Integer32 (0..2147483647) MAX-ACCESS read-only STATUS current DESCRIPTION "This variable is used for creating rows in the smScriptTable. When retrieved, the value of this scalar should be a value for smScriptIndex which does not currently exist in the smScriptTable. If no new rows can be created, this object will have a value of 0." ::= { smScript 1 } smScriptTable OBJECT-TYPE SYNTAX SEQUENCE OF SmScriptEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists and describes locally known scripts." ::= { smScript 2 } smScriptEntry OBJECT-TYPE SYNTAX SmScriptEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular script. Every script that is stored in non-volatile memory is required to appear in this script table." INDEX { smScriptOwner, smScriptIndex } ::= { smScriptTable 1 } SmScriptEntry ::= SEQUENCE { smScriptOwner SnmpAdminString, smScriptIndex Integer32, smScriptName SnmpAdminString, smScriptDescr SnmpAdminString, smScriptVersion VersionString, smScriptLanguage Integer32, smScriptSource UniformResourceLocator, smScriptAdminStatus INTEGER, smScriptOperStatus INTEGER, smScriptStorageType StorageType, smScriptRowStatus RowStatus Expires September 1998 [Page 16] Internet-Draft Script MIB February 1998 } smScriptOwner OBJECT-TYPE SYNTAX SnmpAdminString (SIZE (0..32)) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The manager who owns this row in the smScriptTable." ::= { smScriptEntry 1 } 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 2 } smScriptName OBJECT-TYPE SYNTAX SnmpAdminString 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. 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 3 } smScriptDescr OBJECT-TYPE SYNTAX SnmpAdminString MAX-ACCESS read-create STATUS current DESCRIPTION Expires September 1998 [Page 17] Internet-Draft Script MIB February 1998 "A description of the purpose of the script." ::= { smScriptEntry 4 } smScriptVersion OBJECT-TYPE SYNTAX VersionString MAX-ACCESS read-create STATUS current DESCRIPTION "The version number of the script." ::= { smScriptEntry 5 } smScriptLanguage OBJECT-TYPE SYNTAX Integer32 (0..2147483647) MAX-ACCESS read-create STATUS current DESCRIPTION "The value of this object type identifies an entry in the smLanguageTable which is used to execute this script. The special value 0 may be used by hard-wired scripts that can not be modified and that are executed by internal functions." ::= { smScriptEntry 6 } smScriptSource OBJECT-TYPE SYNTAX UniformResourceLocator MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines how the mid-level manager loads the script source. The mid-level manager will load the source from the URL contained in this object if the URL is not empty. An empty URL indicates that the script source is loaded from local storage. The source is read from the smCodeTable if the value of smScriptStorageType is volatile. Otherwise, the source is read from non-volatile storage. The following changes to smScriptSource require special attention: - Empty value changes to empty value: 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 September 1998 [Page 18] Internet-Draft Script MIB February 1998 the specified location. - Non-empty value changes to empty value: If the smScriptStorageType is nonVolatile, the currently loaded script is written to non-volatile storage. Otherwise, no effect. - Non-empty value changes to non-empty value: This initiates a download of the script into the mid-level manager from the specified location. Set requests to change this object are only valid if the value of smScriptOperStatus is `disabled'." DEFVAL { ''H } ::= { smScriptEntry 7 } smScriptAdminStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2), editing(3) } MAX-ACCESS read-create STATUS current DESCRIPTION "The value of this object indicates the desired status of the script." DEFVAL { disabled } ::= { smScriptEntry 8 } smScriptOperStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2), editing(3), retrieving(4), compiling(5), noSuchScript(6), accessDenied(7), wrongLanguage(8), wrongVersion(9), compilationFailed(10), noResourcesLeft(11), unknownProtocol(12), noResponse(13), genericError(14) } MAX-ACCESS read-only STATUS current Expires September 1998 [Page 19] Internet-Draft Script MIB February 1998 DESCRIPTION "The actual status of the script in the runtime system. The value of this object is only meaningful when the value of the smScriptRowStatus object is `active'. The smScriptOperStatus object may have the following values: - `enabled' indicates that the script is loaded into the runtime system and can be started by a launch table entry. - `disabled' indicates that the script can not be used. - `editing' indicates that the script can be modified in the smCodeTable. - `retrieving' indicates that the script is currently being loaded from non-volatile storage or a remote system. - `compiling' indicates that the script is currently being compiled by the runtime system. - `noSuchScript' indicates that the script does not exist at the smScriptSource. - `accessDenied' indicates that the script can not be loaded from the smScriptSource due to a lack of permissions. - `wrongLanguage' indicates that the script can not be loaded from the smScriptSource because of a language mismatch. - `wrongVersion' indicates that the script can not be loaded from the smScriptSource because of a language version mismatch. - `compilationFailed' indicates that the compilation failed. - `noResourcesLeft' indicates that the runtime system does not have enough resources to load the script. - `unknownProtocol' indicates that the script could not be loaded from the smScriptSource because the requested protocol is not supported. - `protocolFailure' indicates that the script could not be loaded from the smScriptSource because of a protocol failure. Expires September 1998 [Page 20] Internet-Draft Script MIB February 1998 - `genericError' indicates that the script could not be loaded due to an error condition not listed above. The `retrieving' and `compiling' states are transient states which will either lead to one of the error states or the `enabled' state. The `diabled' and `editing' states are administrative state which are only reached by explicit management operations. The implementation has to ensure that all launch table entries which refer to this script entry have a smLaunchOperStatus value of `disabled' when the value of this object is not `enabled'." DEFVAL { disabled } ::= { smScriptEntry 9 } smScriptStorageType OBJECT-TYPE SYNTAX StorageType MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines whether this row and the script controlled by this row are kept in volatile storage and lost upon reboot or if this row is backed up by non-volatile or permanent storage. Setting this object to nonVolatile stores the script controlled by this row into non-volatile storage. Setting this object to volatile removes a script from non-volatile storage if the script has been in non-volatile storage before. Attempts to set this object to permanent will always fail with an inconsistentValue error. The agent has to make sure that scripts controlled by a row where smScriptStorageType is nonVolatile or permanent are loaded at agent startup time. The value of smScriptStorageType is only meaningful if the value of the corresponding RowStatus object is active. If smScriptStorageType has the value permanent(4), then all objects whose MAX-ACCESS value is read-create must be writable, with the exception of the smScriptStorageType and smScriptRowStatus objects, which should be only be readable." DEFVAL { volatile } ::= { smScriptEntry 10 } Expires September 1998 [Page 21] Internet-Draft Script MIB February 1998 smScriptRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "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 smScriptOperStatus will be reset to `disabled'. Deleting conceptual rows from this table includes the deletion of all resources associated with this row. This implies that a script is removed from non-volatile storage if the value of smScriptStorageType is non-volatile. An entry may not exist in the `active' state unless all required objects in the entry have appropriate values. The script code is loaded into the runtime system whenever the value of this object is changed to `active'. Rows that are not complete or not in service are not known by the script runtime system. An entry may not leave the active state as long as the script is executing. Attempts to do so will result in a wrongValue error (see RFC 1903). Attempts to `destroy' a row or to set a row `notInService' where the value of the smScriptStorageType object is `permanent' or `readOnly' will result in an inconsistentValue error." ::= { smScriptEntry 11 } 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 or written via SNMP." ::= { smScript 3 } Expires September 1998 [Page 22] Internet-Draft Script MIB February 1998 smCodeEntry OBJECT-TYPE SYNTAX SmCodeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular fragment of a script." INDEX { smScriptOwner, 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 identifying this code fragment." ::= { smCodeEntry 1 } smCodeText OBJECT-TYPE SYNTAX OCTET STRING (SIZE (0..1024)) MAX-ACCESS read-create STATUS current DESCRIPTION "The code that makes up a fragment of the script." ::= { smCodeEntry 2 } smCodeRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "A control that allows entries to be added and removed from this table." ::= { smCodeEntry 3 } -- -- Script execution. -- -- This group defines tables which allow script execution to be -- initiated, suspended, resumed, and terminated. It also provides -- a mechanism for keeping a history of recent script executions -- and their results. Expires September 1998 [Page 23] Internet-Draft Script MIB February 1998 -- smLaunchNext OBJECT-TYPE SYNTAX Integer32 (0..2147483647) MAX-ACCESS read-only STATUS current DESCRIPTION "This variable is used for creating rows in the smLaunchTable. When retrieved, the value of this variable should be a value for smLaunchIndex which does not currently exist in the smLaunchTable. If no new rows can be created, this object will have a value of 0." ::= { smExec 1 } smLaunchTable OBJECT-TYPE SYNTAX SEQUENCE OF SmLaunchEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists and describes scripts that are ready to be executed together with their parameters." ::= { smExec 2 } smLaunchEntry OBJECT-TYPE SYNTAX SmLaunchEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular executable script." INDEX { smLaunchOwner, smLaunchIndex } ::= { smLaunchTable 1 } SmLaunchEntry ::= SEQUENCE { smLaunchOwner SnmpAdminString, smLaunchIndex Integer32, smLaunchScriptIndex Integer32, smLaunchArgument OCTET STRING, smLaunchMaxRunning Integer32, smLaunchMaxCompleted Integer32, smLaunchLifeTime TimeInterval, smLaunchExpireTime TimeInterval, smLaunchStart Integer32, smLaunchControl INTEGER, smLaunchAdminStatus INTEGER, smLaunchOperStatus INTEGER, smLaunchStorageType StorageType, Expires September 1998 [Page 24] Internet-Draft Script MIB February 1998 smLaunchRowStatus RowStatus } smLaunchOwner OBJECT-TYPE SYNTAX SnmpAdminString (SIZE (0..32)) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The manager who owns this row in the smLaunchTable." ::= { smLaunchEntry 1 } smLaunchIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) 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 smLaunchTable." ::= { smLaunchEntry 2 } smLaunchScriptIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS read-create STATUS current DESCRIPTION "XXX TBD" ::= { smLaunchEntry 3 } smLaunchArgument OBJECT-TYPE SYNTAX OCTET STRING (SIZE (0..2048)) MAX-ACCESS read-create STATUS current DESCRIPTION "The argument supplied to the script. When a script is invoked, the value of this object is used to initialize the smRunArgument object." DEFVAL { ''H } ::= { smLaunchEntry 4 } smLaunchMaxRunning OBJECT-TYPE SYNTAX Integer32 (1..1024) MAX-ACCESS read-create STATUS current DESCRIPTION "The maximum number of concurrently running scripts that may be invoked from this entry in the smLaunchTable." Expires September 1998 [Page 25] Internet-Draft Script MIB February 1998 DEFVAL { 1 } ::= { smLaunchEntry 5 } smLaunchMaxCompleted OBJECT-TYPE SYNTAX Integer32 (1..1024) MAX-ACCESS read-create STATUS current DESCRIPTION "The maximum number of finished scripts kept in the smRunTable that were invoked from this entry in the smLaunchTable. The value of this object is checked whenever a script terminates. Entries in the smRunTable are deleted until the number of completed scripts is smaller than the value of this object. Scripts whose smRunEndTime value indicates the oldest completion time are deleted first." DEFVAL { 1 } ::= { smLaunchEntry 6 } smLaunchLifeTime OBJECT-TYPE SYNTAX TimeInterval MAX-ACCESS read-create STATUS current DESCRIPTION "The default maximum amount of time a script launched from this entry may run. The value of this object is used to initialize the smRunLifeTime object when a script is launched. Changing the value of an smLaunchLifeTime instance does not affect scripts previously launched from this entry." DEFVAL { 360000 } ::= { smLaunchEntry 7 } smLaunchExpireTime OBJECT-TYPE SYNTAX TimeInterval MAX-ACCESS read-create STATUS current DESCRIPTION "The default maximum amount of time information about a script launched from this entry is kept in the smRunTable after the script has completed execution. The value of this object is used to initialize the smRunExpireTime object when a script is launched. Changing the value of an smLaunchExpireTime instance does not affect scripts previously launched from this entry." DEFVAL { 360000 } ::= { smLaunchEntry 8 } Expires September 1998 [Page 26] Internet-Draft Script MIB February 1998 smLaunchStart OBJECT-TYPE SYNTAX Integer32 (0..2147483647) MAX-ACCESS read-create STATUS current DESCRIPTION "This object is used to start the execution of scripts. When retrieved, the value will be the value of smRunIndex for the last script that started execution controlled by this row. The value will be zero if no script started execution yet. A script is started by setting this object to an unused smRunIndex value. A new row in the smRunTable will be created which is indexed by the value supplied by the set-request. An unused value can be obtained by reading the smRunNext object. Setting this object to the special value 0 will start a a script with a self-generated smRunIndex value. The consequence is that the script invoker has no reliable way to determine the smRunIndex value for this script invocation and that the invoker has therefore no way to obain the results from this script invocation. The special value 0 is however useful for scheduled script invocations. Any attempts to write this objects will fail with an inconsistentValue error if the value of smLaunchOperStatus value of this row is not `enabled'. Setting this object to a value which is already used to identify a row in the smRunTable will also result in an inconsistentValue error." DEFVAL { 0 } ::= { smLaunchEntry 9 } smLaunchControl OBJECT-TYPE SYNTAX INTEGER { abort(1), suspend(2), resume(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 Expires September 1998 [Page 27] Internet-Draft Script MIB February 1998 this row in the smLaunchTable. Setting this object to abort(1), suspend(2) or resume(3) will set the smRunAdminStatus object of all applicable rows in the smRunTable to abort(1), suspend(2) or resume(3) respectively. The phrase `applicable rows' means the set of rows which were created from this entry in the smLaunchTable and whose value of smRunOperStatus allows the corresponding state change as described in the definition of the smRunAdminStatus object. Setting this object to nop(4) will always succeed and has no effect." DEFVAL { nop } ::= { smLaunchEntry 10 } smLaunchAdminStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "The value of this object indicates the desired status of this launch table entry." DEFVAL { disabled } ::= { smLaunchEntry 11 } smLaunchOperStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2) } MAX-ACCESS read-only STATUS current DESCRIPTION "The value of this object indicates the actual status of this launch table entry. An `enabled' launch table entry can be used to start scripts while a `disabled' launch table entry will refuse any attempts to start scripts. The value `enabled' requires that the corresponding smScriptOperStatus object has the value `enabled' and that the smLaunchRowStatus object is active." DEFVAL { disabled } ::= { smLaunchEntry 12 } smLaunchStorageType OBJECT-TYPE Expires September 1998 [Page 28] Internet-Draft Script MIB February 1998 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 smLaunchStorageType is only meaningful if the value of the corresponding RowStatus object is active. If smLaunchStorageType has the value permanent(4), then all objects whose MAX-ACCESS value is read-create must be writable, with the exception of the smLaunchStorageType and smLaunchRowStatus objects, which should be only be readable." DEFVAL { volatile } ::= { smLaunchEntry 13 } smLaunchRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "A control that allows entries to be added and removed from this table." ::= { smLaunchEntry 14 } smRunNext OBJECT-TYPE SYNTAX Integer32 (0..2147483647) MAX-ACCESS read-only STATUS current DESCRIPTION "This variable is used for creating rows in the smRunTable. When retrieved, the value of this variable should be a value for smRunIndex which does not currently exist in the smRunTable. If no new rows can be created, this object will have a value of 0." ::= { smExec 3 } smRunTable OBJECT-TYPE SYNTAX SEQUENCE OF SmRunEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists and describes scripts that are currently running or have been running in the past." Expires September 1998 [Page 29] Internet-Draft Script MIB February 1998 ::= { smExec 4 } smRunEntry OBJECT-TYPE SYNTAX SmRunEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular running or finished script." INDEX { smLaunchOwner, smLaunchIndex, smRunIndex } ::= { smRunTable 1 } SmRunEntry ::= SEQUENCE { smRunIndex Integer32, smRunArgument OCTET STRING, smRunStartTime TimeStamp, smRunEndTime TimeStamp, smRunLifeTime TimeInterval, smRunExpireTime TimeInterval, smRunExitCode ExitCode, smRunResult OCTET STRING, smRunAdminStatus INTEGER, smRunOperStatus INTEGER } smRunIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this running or finished script. This value must be unique for all rows in the smRunTable." ::= { smRunEntry 1 } smRunArgument OBJECT-TYPE SYNTAX OCTET STRING (SIZE (0..2048)) MAX-ACCESS read-only STATUS current DESCRIPTION "The argument supplied to the script when it started." DEFVAL { ''H } ::= { smRunEntry 2 } smRunStartTime OBJECT-TYPE SYNTAX TimeStamp MAX-ACCESS read-only Expires September 1998 [Page 30] Internet-Draft Script MIB February 1998 STATUS current DESCRIPTION "The value of sysUpTime when this script started execution. This object will have the value 0 if this script has not started yet or if sysUpTime has been reset during script execution." 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 or if sysUpTime has been reset after script termination." DEFVAL { 0 } ::= { smRunEntry 4 } smRunLifeTime OBJECT-TYPE SYNTAX TimeInterval MAX-ACCESS read-write STATUS current DESCRIPTION "This value specifies how long the script can execute. This object returns the remaining time that the script may run. The script is immediately halted when this time limit if exceeded. The value of this object may be set in order to extend or limit the remaining time that the script may run. Setting this value to 0 will halt script execution immediately, and, if the value of smRunExpireTime is also 0, will remove this entry from the smRunTable. The value of smRunLifeTime reflects the real-time execution time as seen by the outside world. The value of this object will always be 0 for a script that finished execution." ::= { smRunEntry 5 } smRunExpireTime OBJECT-TYPE SYNTAX TimeInterval MAX-ACCESS read-write STATUS current DESCRIPTION Expires September 1998 [Page 31] Internet-Draft Script MIB February 1998 "This value specifies how long this row can exist in the smRunTable after the script has terminated. This object returns the remaining time that the row may exist. The value will start 'counting down' the remaining time when the script terminates. The entry in the smRunTable is immediately destroyed when the time limit is exceeded. 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 ExitCode 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'." 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 as long as 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 } smRunAdminStatus OBJECT-TYPE SYNTAX INTEGER { abort(1), suspend(2), Expires September 1998 [Page 32] Internet-Draft Script MIB February 1998 resume(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' will abort execution if the value of smRunOperStatus is `initializing', `executing', `suspending', `suspended' or `resuming'. Setting this object to `abort' when the value of smRunOperStatus is `completed', `aborting' or `terminated' will result in an inconsistentValue error. Setting this object to `suspend' will suspend execution if the value of smRunOperStatus is `executing'. Setting this object to `suspend' will cause an inconsistentValue error if the value of smRunOperStatus is not `executing'. Setting this object to `resume' will resume execution if the value of smRunOperStatus is `suspending' or `suspended'. Setting this object to `resume' will cause an inconsistentValue error if the value of smRunOperStatus is not `suspending' or `suspended'." ::= { smRunEntry 9 } smRunOperStatus OBJECT-TYPE SYNTAX INTEGER { initializing(1), executing(2), suspending(3), suspended(4), resuming(5), aborting(6), terminated(7) } MAX-ACCESS read-only STATUS current DESCRIPTION "The value of this object indicates the script's execution status. If the script has been invoked but has not yet begun execution, the value will be `initializing'. If the script is running, the value will be `executing'. A script which received a request to suspend execution but which did not actually suspend execution will be `suspending'. A script which has suspended execution will be `suspended'. Expires September 1998 [Page 33] Internet-Draft Script MIB February 1998 A script which received a request to resume execution but which is not yet running is `resuming'. The resuming state will finally lead to the `executing' state. A script which received a request to abort execution but which is still running is `aborting'. A script which stopped execution is `terminated'." ::= { smRunEntry 10 } -- -- Notifications -- -- The smNotificationPrefix makes sure that the notification -- registration is reversible, which is needed for SNMPv1 to SNMPv2 -- or SNMPv3 proxies. smNotificationPrefix OBJECT IDENTIFIER ::= { smNotifications 0 } smScriptAbort NOTIFICATION-TYPE OBJECTS { smRunExitCode } STATUS current DESCRIPTION "This notification is generated whenever a running script terminates with an smRunExitCode unequal to noError." ::= { smNotificationPrefix 1 } -- 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 { smLanguageGroup, smScriptGroup, smLaunchGroup, smRunGroup } GROUP smCodeGroup DESCRIPTION "The smCodeGroup is mandatory only for those implementations that support the downloading of scripts via SNMP." OBJECT smScriptSource Expires September 1998 [Page 34] Internet-Draft Script MIB February 1998 MIN-ACCESS read-only DESCRIPTION "The smScriptSource object is read-only for implementations that are not able to download script code from a URL." ::= { smCompliances 1 } smLanguageGroup OBJECT-GROUP OBJECTS { smLanguageVersion, smLanguageID, smLanguageDescr, smExtensionID, smExtensionVersion, smExtensionDescr } STATUS current DESCRIPTION "A collection of objects providing information about the capabilities of the scripting engine." ::= { smGroups 1 } smScriptGroup OBJECT-GROUP OBJECTS { smScriptNext, smScriptName, smScriptDescr, smScriptVersion, smScriptLanguage, smScriptSource, smScriptAdminStatus, smScriptOperStatus, smScriptStorageType, smScriptRowStatus } STATUS current DESCRIPTION "A collection of objects providing information about installed scripts." ::= { smGroups 2 } smCodeGroup OBJECT-GROUP OBJECTS { smCodeText, smCodeRowStatus } STATUS current DESCRIPTION Expires September 1998 [Page 35] Internet-Draft Script MIB February 1998 "A collection of objects used to download or modify scripts by using SNMP set requests." ::= { smGroups 3 } smLaunchGroup OBJECT-GROUP OBJECTS { smLaunchNext, smLaunchScriptIndex, smLaunchArgument, smLaunchMaxRunning, smLaunchMaxCompleted, smLaunchLifeTime, smLaunchExpireTime, smLaunchStart, smLaunchControl, smLaunchAdminStatus, smLaunchOperStatus, smLaunchStorageType, smLaunchRowStatus } STATUS current DESCRIPTION "A collection of objects providing information about scripts that can be launched." ::= { smGroups 4 } smRunGroup OBJECT-GROUP OBJECTS { smRunNext, smRunArgument, smRunStartTime, smRunEndTime, smRunLifeTime, smRunExpireTime, smRunExitCode, smRunResult, smRunOperStatus, smRunAdminStatus } STATUS current DESCRIPTION "A collection of objects providing information about running scripts." ::= { smGroups 5 } smNotificationsGroup NOTIFICATION-GROUP NOTIFICATIONS { Expires September 1998 [Page 36] Internet-Draft Script MIB February 1998 smScriptAbort } STATUS current DESCRIPTION "The notifications emitted by the script MIB." ::= { smGroups 6 } END Expires September 1998 [Page 37] Internet-Draft Script MIB February 1998 8. 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. 8.1. Loading a script via SNMP (push model) The following example explains the steps performed by a higher-level manager to load a script into the mid-level manager by using the push model. 0. The higher-level manager checks the smLanguageTable and the smExtensionTable in order to select the script or language appropriate for this mid-level manager. 1. Retrieve an index for an unused row in the smScriptTable by sending a get-request to retrieve smScriptNext.0. 2. Create a row in the smScriptTable by issuing a set-request using the index retrieved in step 1. The smScriptRowStatus object is set to `createAndWait' and the smScriptSource object is set to an empty string. The smScriptStorageType object is set to `volatile' to indicate that the script will be loaded via the smCodeTable. The smScriptOwner should be set to a string which identifies the higher-level manager. 3. Set the smScriptRowStatus object to `active' and the smScriptAdminStatus object to `editing'. 4. Push the script to the mid-level manager by issuing a couple of set-requests to the smCodeTable. 5. The higher-level manager sends a set-request to set the smScriptAdminStatus object to `enabled'. The agent will pass the row to the runtime system which starts to load the code from the smCodeTable. 6. The higher-level manager polls the smScriptOperStatus object until the value is either `enabled' or one of the error status codes. The script can only be used if the value of smScriptOperStatus is `enabled'. Expires September 1998 [Page 38] Internet-Draft Script MIB February 1998 7. 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 smScriptStorageType object. 8.2. Loading a script via a URL (pull model) This example explains the steps performed by higher-level manager to load a script into the mid-level manager by using the pull model. 0. The higher-level manager checks the smLanguageTable and the smExtensionTable in order to select the script or language appropriate for this mid-level manager. 1. Retrieve an index for an unused row in the smScriptTable by sending a get-request to retrieve smScriptNext.0. 2. Create a row in the smScriptTable by issuing a set-request using the index retrieved in step 1. The smScriptRowStatus object is set to `createAndWait' and the smScriptSource object is set to the URL that points to the script. The smScriptOwner should be set to a string which identifies the higher-level manager. 3. The higher-level manager sends a set-request to set the smScriptRowStatus object to `active'. 4. The higher-level manager sends a set-request to set the smScriptAdminStatus object to `enabled'. The agent will pass the row to the runtime system which starts to download the code from the location given by the smScriptSource object. 5. The higher-level manager polls the smScriptOperStatus object until the value is either `enabled' or one of the error status codes. The script can only be used if the value of smScriptOperStatus is `enabled'. 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 smScriptStorageType object. Expires September 1998 [Page 39] Internet-Draft Script MIB February 1998 8.3. Modifying 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 smScriptAdminStatus to `disabled'. 1. The higher-level manager polls the smScriptOperStatus object until the value is `disabled'. 2. The higher-level manager sets smScriptSource to an empty string and smScriptAdminStatus to `editing'. 3. The higher-level manager polls the smScriptOperStatus object until the value is `editing'. 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 smScriptAdminStatus object to `enabled'. 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 smScriptOperStatus object until the value is either `enabled' or one of the error status codes. The script can only be used if the value of smScriptOperStatus is `enabled'. 8.4. Removing an existing script A script is removed from the runtime system be setting the smScriptRowStatus object to `notInService' or `destroy'. Setting the smScriptRowStatus object to `destroy' will remove the row from the smScriptTable and the code from the smCodeTable. 8.5. Starting a script using SNMP This section explains how a higher-level manager starts scripts by sending SNMP set-requests to a mid-level manager. This is in general a two phase operation: The first step is to create a row in the smLaunchTable which defines all the parameters. The second step is to "instantiate" a running script from the row in the smLaunchTable. Expires September 1998 [Page 40] Internet-Draft Script MIB February 1998 0. Retrieve an index for an unused row in the smLaunchTable by sending a get-request to retrieve smLaunchNext.0. 1. Create a row in the smLaunchTable by sending a set-request using the index retrieved in step 0. Activate the new entry in the smLaunchTable by setting the smLaunchRowStatus to active once the row is complete. 2. Retrieving an unused index into the smRunTable by reading the smRunNext object. 3. Start script execution by setting the smLaunchStart object to the index value retrieved in the previous step. 9. 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. XXX TBD 10. Intellectual Property The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice Expires September 1998 [Page 41] Internet-Draft Script MIB February 1998 this standard. Please address the information to the IETF Executive Director. 11. Acknowledgments This document was produced by the IETF Distributed Management (DISMAN) working group. 12. 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] 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. [3] 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. [4] 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. [5] 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. [6] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC1906, SNMP Research, Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. Expires September 1998 [Page 42] Internet-Draft Script MIB February 1998 [7] Case J., Harrington D., Presuhn R., and B. Wijnen, "Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)", RFC2272, SNMP Research, Inc., Cabletron Systems, Inc., BMC Software, Inc., IBM T. J. Watson Research, January 1998. [8] Blumenthal U., and B. Wijnen, "User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)", RFC2274, IBM T. J. Watson Research, January 1998. [9] Wijnen B., Presuhn R., and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", IBM T. J. Watson Research, BMC Software, Inc., Cisco Systems, Inc., January 1998 [10] Berners-Lee T., Masinter L., and M. McCahill, Editors, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994. [11] Postel J., and J. Reynolds, "File Transfer Protocol", STD 9, RFC 959, ISI, October 1985. [12] Fielding R., Gettys J., Mogul J., Frystyk H., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, UC Irvine, DEC, MIT/LCS, January 1997. 13. Editor's Address David B. Levi Email: levi@snmp.com SNMP Research, Inc. Tel: +1 423 573 1434 3001 Kimberlin Heights Road Knoxville, TN 37920-9716 U.S.A. Juergen Schoenwaelder Email: schoenw@ibr.cs.tu-bs.de TU Braunschweig Tel: +49 531 391-3683 Bueltenweg 74/75 38106 Braunschweig Germany Expires September 1998 [Page 43] Internet-Draft Script MIB February 1998 14. Changes from This section documents changes from the previous draft. This section will be removed when this Internet Draft will be published as an RFC. o Removed smLanguageVersion from the INDEX clause of smLanguageEntry. o Changed the order of smLanguageVersion and smLanguageID to make it consistent with the smExtensionTable. o Changed the definition of OwnerString so that it is compatible with the RMON definition. (The OwnerString definition should be defined in the DISMAN MIB.) o Clarified the definition of UniformResourceLocator to use the character set and encodings as defined by RFC 1738. o Changed the definition of VersionString to use a DisplayString as a base type. Changes the maximum length to 31 octets so that it easily fits into a 32 byte null-terminated string. o Restricted the values of smLanguageIndex to positive numbers. o Changed to allow modification of 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 smScriptOperStatus 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 1998 [Page 44] Internet-Draft Script MIB February 1998 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 smScriptOperStatus 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 1998 [Page 45] Internet-Draft Script MIB February 1998 15. Changes from This section documents changes from the previous draft. This section will be removed when this Internet Draft will be published as an RFC. o Split the OBJECT-GROUP definition into smaller pieces. Changed the the compliance definition to full compliance. This permits the creation of additional compliance statements for agents with different capabilities (for example, agents which do not permit downloading or modifying scripts). o Changed the name of the smExecTable to smLaunchTable to avoid confusing. o Changed the names of the following objects as follows: smRunLifeTime -> smRunLifeTime smRunCompletedLifeTime -> smRunExpireTime smLaunchRunningLifeTime -> smLaunchLifeTime smLaunchCompletedLifeTime -> smLaunchExpireTime o Fixed the registration of smLanguageID, smLanguageVersion, smRunNext and smRunTable to close some gaps. o Clarified that smRunLifeTime is always 0 when a script has finished execution. o Removed the smScriptAccess. The SNMP access control model should be used to control whether script source is readable/writable or invisible. o Changed smScriptRowStorage and smLaunchRowStorage to smScriptStorageType and smLaunchStorageType which is more consistent with other MIBs. o Changed smScriptRowOwner and smLaunchRowOwner to smScriptOwner and smLaunchOwner. o Split the section about open and closed issues into two separate sections. Expires September 1998 [Page 46] Internet-Draft Script MIB February 1998 16. Changes from o Added PSL and SMSL to the language directory. o Added the IPR section required by RFC 2026. o Clearified that languages may be registered in other branches of the OID registration tree. o Replaced "continue" with "resume". o Removed the consecutive value constaint for smCodeIndex. o Relaxed the index ranges from 1..65535 to 1..2147483647. o Turned the script exit codes into a textual convention. o The compliance macro allows implementations that do not support the push nor the pull model to download script code. o Changed the definition of smRunOperStatus to a) allow transient states between reception of a `signal' and the actual state change b) to use only one state to represent a terminated script. The smRunExitCode object contains the information necessary to distinguish between an aborted script and a script which terminates normally. o Added a smScriptAbort notification as discussed in San Jose. o Removed the index component smLanguageIndex from the smScriptTable, the smCodeTable, the smLaunchTable and the smRunTable. Added a new smScriptLanguage column which identifies the language. o Replaced DisplayStrings with SnmpAdminStrings to facilitate internationalization. o Removed the sections on open and closed issues. o Added smLauchAdminStatus and smLauchOperStatus. Added a note that writing smLauchStart will result in an inconsistentValue error if the value of smLauchOperStatus is disabled. o Updated the section about the SNMP management framework and added references to SNMPv3. Expires September 1998 [Page 47] Internet-Draft Script MIB February 1998 o Added the smScriptAdminStatus object and renamed the smScriptStatus object to smScriptOperStatus. Renamed some of the states of the smScriptOperStatus object and added a short explanation for each possible state. o Changed the indexing scheme to use owner string as the first component. o Clarified the value of smRunStartTime and smRunEndTime after discontinuities. o Updated the usage examples to reflect the recent changes. 17. Full Copyright Statement Copyright (C) The Internet Society (1998). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Expires September 1998 [Page 48] Internet-Draft Script MIB February 1998 Table of Contents 1 Abstract ..................................................... 2 2 The SNMP 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 ....................................... 7 5.2 The smScript Group ......................................... 7 5.3 The smExec Group ........................................... 8 6 The Indexing Structure ....................................... 8 7 Definitions .................................................. 9 8 Usage Examples ............................................... 38 8.1 Loading a script via SNMP (push model) ..................... 38 8.2 Loading a script via a URL (pull model) .................... 39 8.3 Modifying an existing script ............................... 40 8.4 Removing an existing script ................................ 40 8.5 Starting a script using SNMP ............................... 40 9 Security Considerations ...................................... 41 10 Intellectual Property ....................................... 41 11 Acknowledgments ............................................. 42 12 References .................................................. 42 13 Editor's Address ............................................ 43 14 Changes from .......... 44 15 Changes from .......... 46 16 Changes from .......... 47 17 Full Copyright Statement .................................... 48 Expires September 1998 [Page 49]