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