Internet-Draft Script MIB November 1996 Definitions of Managed Objects for the Delegation of Management Scripts November 25, 1996 David B. Levi SNMP Research, Inc. levi@snmp.com Juergen Schoenwaelder University of Twente schoenw@cs.utwente.nl Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Expires May 1997 [Page 1] Internet-Draft Script MIB November 1996 1. Abstract This memo defines an experimental portion of the Management Information Base (MIB) for use with network management protocols in the Internet community. In particular, it describes a set of managed objects that allows the delegation of management scripts to mid-level managers. This memo does not specify a standard for the Internet community. 2. The SNMPv2 Network Management Framework The SNMP Network Management Framework presently consists of three major components. They are: o the SMI, described in RFC 1902 [1] - the mechanisms used for describing and naming objects for the purpose of management. o the MIB-II, STD 17, RFC 1213 [2] - the core set of managed objects for the Internet suite of protocols. o the protocol, RFC 1157 [3] and/or RFC 1905 [4], - the protocol for accessing managed objects. The Framework permits new objects to be defined for the purpose of experimentation and evaluation. 2.1. Object Definitions Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the subset of Abstract Syntax Notation One (ASN.1) defined in the SMI[1]. In particular, each object type is named by an OBJECT IDENTIFIER, an administratively assigned name. The object type together with an object instance serves to uniquely identify a specific instantiation of the object. For human convenience, we often use a textual string, termed the object descriptor, to refer to the object type. Expires May 1997 [Page 2] Internet-Draft Script MIB November 1996 3. Overview The Script MIB module defined in this memo can be used to delegate management functions to mid-level managers. Management functions are defined as management scripts written in a management scripting language. This MIB makes no assumptions about the language itself and even allows distribution of compiled native code, if the mid-level manager is able to execute native code under the control of this MIB. The Script MIB defines a standard interface for the delegation of management functions based on the Internet management framework. In particular, it provides the following capabilities: 1. Capabilities to transfer management scripts to a mid-level manager. 2. Capabilities for initiating, suspending, resuming and terminating management scripts. 3. Capabilities to transfer arguments for management scripts. 4. Capabilities to monitor and control running management scripts. 5. Capabilities to transfer the results produced by running management scripts. This memo does not address any additional topics like the generation of notifications or how to address remote agents from a mid-level manager. 3.1. Terms This section defines the terms used throughout this memo. o A mid-level manager is a processing entity which is capable of performing network management functions. For the scope of this memo, a mid-level manager is assumed to implement the Script MIB. o A higher-level manager is a processing entity or human who initiates and controls the operations performed by the mid-level manager. o A management script is a set of instructions written in an executable language which implements a management function. Expires May 1997 [Page 3] Internet-Draft Script MIB November 1996 o A management scripting language is a language used to write management scripts. Note, that the term scripting language does not imply that the language must have the characteristics of script languages. o A mid-level manager can be decomposed into an agent entity which implements the Script MIB defined in this memo and the runtime system that executes scripts. The Script MIB sees the runtime system as the managed resource which is controlled by this MIB. 4. Requirements and Design Issues This section discusses some general requirements that have influenced the design of the Script MIB. o The Script MIB must be independent of concrete languages. o The Script MIB must provide mechanisms that help to avoid new management problems (e.g. script versioning problems). o The Script MIB must provide SNMP interfaces to all functions required to delegate management scripts. However, other protocols might be used in addition if they provide a significant improvement in terms of convenience for implementation or performance. The following sections discuss some design issues in more detail. 4.1. Script Languages The Script MIB defined in this memo makes no assumption about the script language. This MIB can therefore be used in combination with different languages (such as Tcl or Java) and/or different versions of the same language. No assumptions are made about the format in which management scripts are transfered. The Script MIB makes information about the languages supported by a mid-level manager available so that a higher-level manager can learn about the capabilities provided by a Script MIB mid-level manager. A version number is attached to a language so that a higher-level manager can either select the language version required to execute a particular script or select a script that fits the language supported by the mid-level manager. Expires May 1997 [Page 4] Internet-Draft Script MIB November 1996 An additional table lists language extensions that provide features not covered in the core language. Language extensions are usually required to turn a general purpose language into a management language. In many cases, language extensions will come in the form of libraries that provide capabilities like sending SNMP requests to remote SNMP agents or accessing the local MIB instrumentation. Every extension is associated with a language and carries its own version number. 4.2. Script Transfer There are two different ways to transfer management scripts to the mid-level manager. The first approach requires that the higher-level manager pushes the script to the mid-level manager. This is therefore called the 'push model'. The second approach is a 'pull model' where the higher-level manager tells the mid-level manager where the script is located and the mid-level manager retrieves the script itself. The MIB defined in this memo supports both models. The 'push model' is realized by a table which allows a manager to write scripts by using a sequence of SNMP set requests. The script can be split into several fragments in order to deal with SNMP packet size limitations. The 'pull model' is realized by the use of Uniform Resource Locators (URLs) [6] that point to the script source. The higher-level manager writes the URL pointing to the script source to the mid-level manager by sending a SNMP set request. The agent is then responsible for downloading the document using the protocol specified in the URL. This allows the use of protocols like FTP [7] or HTTP [8] to transfer large management scripts efficiently. Scripts can be stored in non-volatile storage provided by the mid- level manager. This allows a mid-level manager to restart scripts if it is forced to reset itself (off-line restart) without requiring a higher-level manager to push scripts back into the mid-level manager after it resets itself. Scripts have an attached version number so that it is possible to differentiate between different versions of the same management script. Every management script has an administrative name which can be used to refer to a particular script. This administrative name may be used to derive the name which is used to access the script in non-volatile memory. This mapping is implementation specific. However, the mapping Expires May 1997 [Page 5] Internet-Draft Script MIB November 1996 should make use of the script version number and the script owner to allow either multiple versions of the same script or different scripts with the same administrative name defined by independent higher-level managers. 4.3. Script Execution The Script MIB permits execution of several instances of the same or different management scripts. Script arguments are passed as an OCTET STRING value and scripts return a single result value which is also an OCTET STRING value. The semantic interpretation of these values is left to the higher-level manager and the management script. A runtime error stops the active script. An error code is left and error specific information is stored as the result value. Executing scripts have a status object attached which allows them to be disabled and enabled. Script execution can be repeated multiple times in regular time intervals. This provides invocation of management scripts off-line. A manager must specify the number of repeated invocations and the time interval between two invocations. 5. The Structure of the MIB This section presents the structure of the MIB. The objects are arranged into the following groups: o language group (smLanguage) o script group (smScript) o script code group (smCode) o executing script group (smExec) 5.1. The smLanguage Group The smLanguage group is used to provide information about the languages and the language extensions supported by the mid-level manager. This group includes two tables and a directory of well known Expires May 1997 [Page 6] Internet-Draft Script MIB November 1996 management scripting languages. The smLanguageTable lists all languages supported by a mid-level manager and the smExtensionTable lists the extensions that are available for a given script language. Well known scripting languages are listed in the smLanguageDir subtree. 5.2. The smScript Group The smScript group consists of a single table called smScriptTable. It is used to control all the scripts known to a mid-level manager. This table defines objects that support the following operations: o download scripts via SNMP (push model) o download scripts from a URL (pull model) o read scripts from local non-volatile storage o store scripts in local non-volatile storage o delete scripts from local non-volatile storage o permanent scripts (that can't be changed or removed) o control whether a script is readable or writable via SNMP A status object smScriptStatus provides access to the current status of a script. This status object is also used to provide error information to a higher-level manager if an attempt to invoke one of the operations listed above fails. Scripts are automatically loaded into the run-time system by the mid-level manager once the row status object is set to active. Loading a script includes retrieving the script (probably from a remote location), compiling the script for languages that require a compilation step, and making the code available if the script is readable via SNMP. The smScriptStatus object is used to indicate the status of the loading process. For a compiled language, this object will start in the state 'loading', switch to the state 'compiling' and finally reach the state 'available'. The 'compiling' state is skipped for languages that do not require a compilation step. Errors during the loading or compilation phase will result in an error state such as compilationFailed. The source of a script is defined by the smScriptSource object. This Expires May 1997 [Page 7] Internet-Draft Script MIB November 1996 object may contain a URL pointing to a remote location which provides access to the management script. The script source is read from the smCodeTable described below or from non-volatile storage is the smScriptSource object contains an empty URL. The smScriptRowStorage object is used to distinguish between scripts read from stable storage and scripts read from the smCodeTable. The smScriptAccess object in the smScriptTable controls whether the code of a script appears in the smCodeTable and if it is read-only or read-write. 5.3. The smCode Group The smCode group contains a single table which is used to access and modify the source code of a script via SNMP. Only scripts where the smScriptAccess object is set to readWrite and the smScriptRowStatus is set to 'notInService' can be modified. The mid-level manager loads the modified code into the runtime system once the smScriptRowStatus is set to 'active' again. 5.4. The smExec Group Expires May 1997 [Page 8] Internet-Draft Script MIB November 1996 6. Definitions SCRIPT-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, OBJECT-IDENTITY, Integer32, Gauge32, experimental FROM SNMPv2-SMI TEXTUAL-CONVENTION, DisplayString, RowStatus, TimeStamp FROM SNMPv2-TC MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF; scriptMIB MODULE-IDENTITY LAST-UPDATED "9611250000Z" ORGANIZATION "IETF DISMAN Working Group" CONTACT-INFO "David B. Levi SNMP Research, Inc. 3001 Kimberlin Heights Road Knoxville, TN 37920-9716 Tel: +1 423 573 1434 E-mail: levi@snmp.com Juergen Schoenwaelder University of Twente P.O. Box 217 7500 AE Enschede The Netherlands Tel: +31-53-489-3678 E-mail: schoenw@cs.utwente.nl" DESCRIPTION "This MIB module defines a MIB which provides mechanisms to download, execute and control management scripts on remote agents." ::= { experimental 5678 } -- -- The various groups defined within this MIB definition: -- smObjects OBJECT IDENTIFIER ::= { scriptMIB 1 } smConformance OBJECT IDENTIFIER ::= { scriptMIB 2 } smLanguage OBJECT IDENTIFIER ::= { smObjects 1 } smScript OBJECT IDENTIFIER ::= { smObjects 2 } smCode OBJECT IDENTIFIER ::= { smObjects 3 } smExec OBJECT IDENTIFIER ::= { smObjects 4 } Expires May 1997 [Page 9] Internet-Draft Script MIB November 1996 smState OBJECT IDENTIFIER ::= { smObjects 5 } -- -- Textual Conventions: -- RowStorage ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "A RowStorage object defines how a conceptul row which is controlled by a RowStatus object is stored. A row which is volatile(1) is lost upon reboot. A row which is nonVolatile(2) or permanent(3) is backed up by stable storage. A row which is permanent(3) cannot be changed nor deleted. The value of a RowStorage object is only meaningful if the value of the corresponding RowStatus object is active." SYNTAX INTEGER { volatile(1), -- e.g. in RAM nonVolatile(2), -- e.g. in NVRAM permanent(3) -- e.g. in ROM } OwnerString ::= TEXTUAL-CONVENTION DISPLAY-HINT "255a" STATUS current DESCRIPTION "An owner string identifies the initiator or owner of a row in a table. This label is set by the initiator to provide for the following possibilities: o A management station may recognize resources it owns and no longer needs. o A network operator can find the management station that owns the resource and negotiate for it to be freed. o A network operator may decide to unilaterally free resources another network operator has reserved. o Upon initialization, a management station may recognize resources it had reserved in the past. With this information it may free the resources if it no longer needs them. Management stations and probes should support any format of the owner string dictated by the local policy of the organization. It is suggested that this name contain one or more of the following: IP address, management station name, Expires May 1997 [Page 10] Internet-Draft Script MIB November 1996 network manager's name, location, or phone number. This information will help users to share the resources more effectively." SYNTAX OCTET STRING (SIZE (0..255)) UniformResourceLocator ::= TEXTUAL-CONVENTION DISPLAY-HINT "1024a" STATUS current DESCRIPTION "This TC describes an object which holds a reference to a (remote) resource by using the Uniform Resource Locator notation as defined in RFC 1738." SYNTAX OCTET STRING (SIZE (0..1024)) VersionString ::= TEXTUAL-CONVENTION DISPLAY-HINT "40a" STATUS current DESCRIPTION "This TC describes version strings that are used to distinguish between different versions of a language, a language extension or a script. It is suggested that the version strings consist of one or more decimal numbers separated by dots, where the first number is called the major version number." SYNTAX OCTET STRING (SIZE (0..40)) -- -- Script language and language extensions. -- -- This group defines tables which list the languages and the -- language extensions supported by the mid-level manager. -- Languages are uniquely identified by object identifier values. -- smLanguageDir OBJECT IDENTIFIER ::= { smLanguage 1 } smLanguageJavaVM OBJECT-IDENTITY STATUS current DESCRIPTION "The Java virtual machine." REFERENCE "The Java Virtual Machine Specification. ISBN 0-201-63452-X" ::= { smLanguageDir 1 } smLanguageTcl OBJECT-IDENTITY Expires May 1997 [Page 11] Internet-Draft Script MIB November 1996 STATUS current DESCRIPTION "The Tool Command Language (Tcl)." REFERENCE "Tcl and the Tk Toolkit. ISBN 0-201-63337-X" ::= { smLanguageDir 2 } smLanguagePerl OBJECT-IDENTITY STATUS current DESCRIPTION "The Perl Language." REFERENCE "Programming Perl. ISBN 1-56592-149-6" ::= { smLanguageDir 3 } smLanguageScheme OBJECT-IDENTITY STATUS current DESCRIPTION "The Scheme Language." REFERENCE "The Revised^4 Report on the Algorithmic Language Scheme. MIT Press" ::= { smLanguageDir 4 } smLanguageSNMPScriptLanguage OBJECT-IDENTITY STATUS current DESCRIPTION "The SNMP Script Language defined by SNMP Research." ::= { smLanguageDir 5 } smLanguageTable OBJECT-TYPE SYNTAX SEQUENCE OF SmLanguageEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists supported script languages." ::= { smLanguage 2 } smLanguageEntry OBJECT-TYPE SYNTAX SmLanguageEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A smLanguageTable entry." Expires May 1997 [Page 12] Internet-Draft Script MIB November 1996 INDEX { smLanguageIndex, smLanguageVersion } ::= { smLanguageTable 1 } SmLanguageEntry ::= SEQUENCE { smLanguageIndex Integer32, smLanguageVersion VersionString, smLanguageID OBJECT IDENTIFIER, smLanguageDescr DisplayString } smLanguageIndex OBJECT-TYPE SYNTAX Integer32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this script language entry. The value is expected to remain constant at least from one re-initialization of the entity's network management system to the next re-initialization." ::= { smLanguageEntry 1 } smLanguageVersion OBJECT-TYPE SYNTAX VersionString MAX-ACCESS read-only STATUS current DESCRIPTION "The version of the scripting language." ::= { smLanguageEntry 2 } smLanguageID OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-only STATUS current DESCRIPTION "The globally unique identification of the scripting language." ::= { smLanguageEntry 3 } smLanguageDescr OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "A textual description of the scripting language." ::= { smLanguageEntry 4 } Expires May 1997 [Page 13] Internet-Draft Script MIB November 1996 smExtensionTable OBJECT-TYPE SYNTAX SEQUENCE OF SmExtensionEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists supported script language extensions." ::= { smLanguage 3 } smExtensionEntry OBJECT-TYPE SYNTAX SmExtensionEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A smExtensionTable entry." INDEX { smLanguageIndex, smExtensionIndex } ::= { smExtensionTable 1 } SmExtensionEntry ::= SEQUENCE { smExtensionIndex Integer32, smExtensionID OBJECT IDENTIFIER, smExtensionVersion VersionString, smExtensionDescr DisplayString } smExtensionIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this script language extension entry. The value is expected to remain constant at least from one re-initialization of the entity's network management system to the next re-initialization." ::= { smExtensionEntry 1} smExtensionID OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-only STATUS current DESCRIPTION "The globally unique identification of an extension for a scripting language." ::= { smExtensionEntry 2 } smExtensionVersion OBJECT-TYPE Expires May 1997 [Page 14] Internet-Draft Script MIB November 1996 SYNTAX VersionString MAX-ACCESS read-only STATUS current DESCRIPTION "The version number of the extension of a scripting language." ::= { smExtensionEntry 3 } smExtensionDescr OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "A textual description of the extension of the scripting language." ::= { smExtensionEntry 4 } -- -- Scripts known by the mid-level manager. -- -- This group defines a table which lists every script known to the -- mid-level manager. Scripts may be loaded and removed through -- manipulation of the smScriptTable. -- smScriptNext OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS read-only STATUS current DESCRIPTION "This variable is used for creating rows in the smScriptTable. When retrieved, the value of this variable should be a value for smScriptIndex which does not currently exist in the smScriptTable." ::= { smScript 1 } smScriptTable OBJECT-TYPE SYNTAX SEQUENCE OF SmScriptEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists and describes locally known scripts." ::= { smScript 2 } smScriptEntry OBJECT-TYPE SYNTAX SmScriptEntry Expires May 1997 [Page 15] Internet-Draft Script MIB November 1996 MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular script. Every script that is stored in non-volatile memory is required to appear in this script table." INDEX { smLanguageIndex, smScriptIndex } ::= { smScriptTable 1 } SmScriptEntry ::= SEQUENCE { smScriptIndex Integer32, smScriptName DisplayString, smScriptDescr DisplayString, smScriptVersion VersionString, smScriptSource UniformResourceLocator, smScriptAccess INTEGER, smScriptStatus INTEGER, smScriptRowOwner OwnerString, smScriptRowStorage RowStorage, smScriptRowStatus RowStatus } smScriptIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this script entry. This value must be unique for all rows in the smScriptTable." ::= { smScriptEntry 1 } smScriptName OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-create STATUS current DESCRIPTION "The administrative name of the script. This name may be used by the agent to load or save the script into non-volatile storage. The administrative name may be used to derive the name (e.g. a file name) which is used by the agent to access the script in non-volatile storage. The details of this mapping are implementation specific. However, the mapping needs to ensure that scripts created by different managers with the same administrative name do not map to the same name in non-volatile storage. Expires May 1997 [Page 16] Internet-Draft Script MIB November 1996 Setting the value of a smScriptName object changes the administrative name. The agent has to update the name (e.g. a file name) which is used to access the script in non-volatile storage if the script controlled by this row is stored in non-volatile storage." ::= { smScriptEntry 2 } smScriptDescr OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-create STATUS current DESCRIPTION "A description of the purpose of the script." ::= { smScriptEntry 3 } smScriptVersion OBJECT-TYPE SYNTAX VersionString MAX-ACCESS read-create STATUS current DESCRIPTION "The version number of the script." ::= { smScriptEntry 4 } smScriptSource OBJECT-TYPE SYNTAX UniformResourceLocator MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines how the mid-level manager loads the script source. The mid-level manager will load the source from the URL contained in this object if the URL is not empty. An empty URL indicates that the script source is loaded from local storage. The source is read from the smCodeTable if the value of smScriptRowStorage is volatile. Otherwise, the source is read from non-volatile storage. The following changes to smScriptSource require special attention: - Empty value changes to empty value: This has no effect. - Empty value changes to non-empty value: This destroys the local script (possibly deleting it from non-volatile storage), and initiates a download of the script source into the mid-level manager from Expires May 1997 [Page 17] Internet-Draft Script MIB November 1996 the specified location. - Non-empty value changes to empty value: If the smScriptRowStorage is nonVolatile, the currently loaded script is written to non-volatile storage. Otherwise, no effect. - Non-empty value changes to non-empty value: This initiates a download of the script into the mid-level manager from the specified location. Set requests to change this object are only valid if the smScriptRowStatus is set to notInService." ::= { smScriptEntry 5 } smScriptAccess OBJECT-TYPE SYNTAX INTEGER { notAccessible(1), readOnly(2), readWrite(3) } MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines if the script controlled by this row is accessible via the smCodeTable. The value notAccessible indicates that the code does not appear in the smCodeTable. The value readOnly indicates that the code is readable but all attempts to change the code in the smCodeTable will result in an inconsistentValue error. The value readWrite allows a manager to make changes in the smCodeTable as long as the smScriptRowStatus is notInService. Attempts to set this object to readWrite for a script which has a smScriptRowStorage value of permanent will result in an inconsistenValue error." ::= { smScriptEntry 6 } smScriptStatus OBJECT-TYPE SYNTAX INTEGER { unknown(1), loading(2), compiling(3), available(4), noSuchScript(5), accessDenied(6), wrongLanguage(7), wrongVersion(8), compilationFailed(9), Expires May 1997 [Page 18] Internet-Draft Script MIB November 1996 noResourcesLeft(10), unknownProtocol(11), noResponse(12), genericError(13) } MAX-ACCESS read-only STATUS current DESCRIPTION "The status of the script described by this row. The script status reflects the current status of this script in the runtime system. The value of this object is only meaningful when the value of the smScriptRowStatus object is active. The first three status values indicate a transient state. The value available(4) indicates that a script is loaded into the runtime system and can be activated. The remaining status values describe error conditions." ::= { smScriptEntry 7 } smScriptRowOwner OBJECT-TYPE SYNTAX OwnerString MAX-ACCESS read-create STATUS current DESCRIPTION "The manager who created this row in the smScriptTable." ::= { smScriptEntry 8 } smScriptRowStorage OBJECT-TYPE SYNTAX RowStorage MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines whether this row and the script controlled by this row is kept in volatile storage and lost upon reboot or if this row is backed up by non-volatile or permanent storage. Setting this object to nonVolatile stores the script controlled by this row into non-volatile storage using a name derived from the smScriptName object. Setting this object to volatile removes a script from non-volatile storage if the script has been in non-volatile storage before. Attempts to set this object to permanent will always fail. The agent has to make sure that scripts controlled by a row where smScriptRowStorage is nonVolatile or permanent are loaded at agent startup time." Expires May 1997 [Page 19] Internet-Draft Script MIB November 1996 ::= { smScriptEntry 9 } smScriptRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this smScriptEntry. A control that allows entries to be added and removed from this table. It also controls whether a script is known by the script runtime system. Only scripts where the smScriptRowStatus is active are known by the runtime system. Changing the smScriptRowStatus from active to notInService will remove the associated script from the runtime system. This includes the removal of all resources associated with the script. This implies that a script is removed from non-volatile storage if the value of smScriptRowStorage is non-volatile. Deleting conceptual rows from this table includes the deletion of all resources associated with this row. An entry may not exist in the active state unless all objects in the entry have appropriate values. The script code is loaded into the runtime system whenever the value of this object is changed to active. Rows that are not complete or not in service are not known by the script runtime system. An entry may not leave the active state as long as the script is executing. Attempts to do so will result in an wrongValue error (see RFC 1903). Attempts to destroy a row or to set a row notInService where the value of the smScriptRowStorage object is permanent will result in an inconsistentValue error." ::= { smScriptEntry 10 } -- -- Script source code. -- -- This group defines a table which provides a mechanism for a script -- to be loaded into a mid-level manager using a sequence of SNMP set -- operations. -- Expires May 1997 [Page 20] Internet-Draft Script MIB November 1996 smCodeTable OBJECT-TYPE SYNTAX SEQUENCE OF SmCodeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table contains the script code for scripts that are retrieved via SNMP." ::= { smCode 1 } smCodeEntry OBJECT-TYPE SYNTAX SmCodeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular fragment of a script." INDEX { smLanguageIndex, smScriptIndex, smCodeIndex } ::= { smCodeTable 1 } SmCodeEntry ::= SEQUENCE { smCodeIndex Integer32, smCodeText OCTET STRING, smCodeRowStatus RowStatus } smCodeIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The index value associated with this code fragment. Index values start at 1 and have consecutive values." ::= { smCodeEntry 1 } smCodeText OBJECT-TYPE SYNTAX OCTET STRING (SIZE (0..255)) MAX-ACCESS read-create STATUS current DESCRIPTION "The code that makes up this fragment of the script." ::= { smCodeEntry 2 } smCodeRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this smCodeEntry. A control that allows Expires May 1997 [Page 21] Internet-Draft Script MIB November 1996 entries to be added and removed from this table." ::= { smCodeEntry 3 } -- -- Script execution. -- -- This group defines a table which provides a mechanism for -- execution of a script to be initiated, suspended, resumed, -- terminated. It also provides a mechanism for a script -- to be executed periodically. -- smExecNext OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS read-only STATUS current DESCRIPTION "This variable is used for creating rows in the smExecTable. When retrieved, the value of this variable should be a value for smExecIndex which does not currently exist in the smExecTable." ::= { smExec 1 } smExecTable OBJECT-TYPE SYNTAX SEQUENCE OF SmExecEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table lists and describes executing scripts." ::= { smExec 2 } smExecEntry OBJECT-TYPE SYNTAX SmExecEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular script execution." INDEX { smLanguageIndex, smScriptIndex, smExecIndex } ::= { smExecTable 1 } SmExecEntry ::= SEQUENCE { smExecIndex Integer32, smExecInterval Integer32, smExecRemaining Gauge32, smExecAdminStatus INTEGER, smExecOperStatus INTEGER, Expires May 1997 [Page 22] Internet-Draft Script MIB November 1996 smExecErrorBehaviour INTEGER, smExecArgument OCTET STRING, smExecLastFinish TimeStamp, smExecLastError INTEGER, smExecLastResult OCTET STRING, smExecRowOwner OwnerString, smExecRowStorage RowStorage, smExecRowStatus RowStatus } smExecIndex OBJECT-TYPE SYNTAX Integer32 (1..2147483647) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally arbitrary, but unique identifier associated with this script execution. This value must be unique for all rows in the smExecTable." ::= { smExecEntry 1 } smExecInterval OBJECT-TYPE SYNTAX Integer32 UNITS "seconds" MAX-ACCESS read-create STATUS current DESCRIPTION "The desired interval between two executions of this script." ::= { smExecEntry 2 } smExecRemaining OBJECT-TYPE SYNTAX Gauge32 MAX-ACCESS read-create STATUS current DESCRIPTION "The number of script executions until this entry 'auto-disables'. This constitutes a 'dead-man switch' which will keep the script from executing forever. The top-level manager should periodically refresh this number in order to keep the management script running." DEFVAL { 1 } ::= { smExecEntry 3 } smExecAdminStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2), execute(3) Expires May 1997 [Page 23] Internet-Draft Script MIB November 1996 } MAX-ACCESS read-create STATUS current DESCRIPTION "The desired status of the script." ::= { smExecEntry 4 } smExecOperStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2), executing(3) } MAX-ACCESS read-only STATUS current DESCRIPTION "The actual status of the script." ::= { smExecEntry 5 } smExecErrorBehaviour OBJECT-TYPE SYNTAX INTEGER { retryNextInterval(1), disable(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "The behaviour if script execution fails because of an error." DEFVAL { retryNextInterval } ::= { smExecEntry 6 } smExecArgument OBJECT-TYPE SYNTAX OCTET STRING (SIZE (0..65535)) MAX-ACCESS read-create STATUS current DESCRIPTION "The argument supplied to the script." ::= { smExecEntry 7 } smExecLastFinish OBJECT-TYPE SYNTAX TimeStamp MAX-ACCESS read-only STATUS current DESCRIPTION "The value of sysUpTime when this script last finished execution. If this operation never executed, this object will have the value 0." Expires May 1997 [Page 24] Internet-Draft Script MIB November 1996 ::= { smExecEntry 8 } smExecLastError OBJECT-TYPE SYNTAX INTEGER { noError(1), noResourcesLeft(2), languageError(3), runtimeError(4), invalidArgument(5), securityViolation(6), genericError(7) } MAX-ACCESS read-only STATUS current DESCRIPTION "The error code of the last finished script execution." ::= { smExecEntry 9 } smExecLastResult OBJECT-TYPE SYNTAX OCTET STRING (SIZE (0..65535)) MAX-ACCESS read-only STATUS current DESCRIPTION "The result value of the last finished script execution. This object contains an error message if the script finished in an abnormal way." ::= { smExecEntry 10 } smExecRowOwner OBJECT-TYPE SYNTAX OwnerString MAX-ACCESS read-create STATUS current DESCRIPTION "The manager who created this row in the smExecTable." ::= { smExecEntry 11 } smExecRowStorage OBJECT-TYPE SYNTAX RowStorage MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines if this row is kept in volatile storage and lost upon reboot or if this row is backed up by stable storage." ::= { smExecEntry 12 } smExecRowStatus OBJECT-TYPE Expires May 1997 [Page 25] Internet-Draft Script MIB November 1996 SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this smExecEntry. A control that allows entries to be added and removed from this table." ::= { smExecEntry 13 } -- conformance information smCompliances OBJECT IDENTIFIER ::= { smConformance 1 } smGroups OBJECT IDENTIFIER ::= { smConformance 2 } -- compliance statements smCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for SNMP entities which represent generic testing capabilities." MODULE -- this module MANDATORY-GROUPS { smGroup } ::= { smCompliances 1 } smGroup OBJECT-GROUP OBJECTS { smLanguageVersion, smLanguageID, smLanguageDescr, smExtensionID, smExtensionVersion, smExtensionDescr, smScriptNext, smScriptName, smScriptDescr, smScriptVersion, smScriptSource, smScriptAccess, smScriptStatus, smScriptRowOwner, smScriptRowStorage, smScriptRowStatus, smCodeText, smCodeRowStatus, smExecNext, smExecInterval, smExecRemaining, Expires May 1997 [Page 26] Internet-Draft Script MIB November 1996 smExecAdminStatus, smExecOperStatus, smExecErrorBehaviour, smExecArgument, smExecLastFinish, smExecLastError, smExecLastResult, smExecRowOwner, smExecRowStorage, smExecRowStatus } STATUS current DESCRIPTION "A collection of objects providing a generic scripting capability." ::= { smGroups 1 } END 7. Security Considerations Security issues are not discussed in this memo. 8. Acknowledgments This document was produced by the IETF Distributed Management (DISMAN) working group. 9. References [1] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC1902, SNMP Research,Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. [2] McCloghrie, K., and M. Rose, Editors, "Management Information Base for Network Management of TCP/IP-based internets: MIB-II", STD 17, RFC 1213, Hughes LAN Systems, Performance Systems International, March 1991. Expires May 1997 [Page 27] Internet-Draft Script MIB November 1996 [3] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol", RFC 1157, SNMP Research, Performance Systems International, Performance Systems International, MIT Laboratory for Computer Science, May 1990. [4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC1905, SNMP Research,Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. [5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC1903, SNMP Research,Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. [6] T. Berners-Lee, L. Masinter, and M. McCahill, Editors, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994. [7] J. Postel, and J. Reynolds, "File Transfer Protocol", STD 9, RFC 959, ISI, October 1985. [8] T. Berners-Lee, R. Fielding, and H. Nielsen, "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, MIT/LCS, UC Irvine, MIT/LCS, May 1996. 10. Author's Address David B. Levi Juergen Schoenwaelder SNMP Research, Inc. University of Twente 3001 Kimberlin Heights Road P.O. Box 217 Knoxville, TN 37920-9716 7500 AE Enschede U.S.A. The Netherlands Phone: +1 423 573 1434 Phone: +31-53-489-3678 EMail: levi@snmp.com EMail: schoenw@cs.utwente.nl Expires May 1997 [Page 28] Internet-Draft Script MIB November 1996 11. Usage Examples This section presents some examples that explain how a higher-level manager might use the MIB defined in this memo. The purpose of these examples is to explain the steps that are normally used to delegate management scripts. 11.1. Loading a script via SNMP (push model) The following example explains the steps performed by a higher-level manager to load a script into the mid-level manager by using the push model. 0. The higher-level manager checks the smLanguageTable and the smExtensionTable in order to select the script or language appropriate for this mid-level manager. 1. Retrieve an index for an unused row in the smScriptTable by sending a get-request to retrieve smScriptNext.0. 2. Create a row in the smScriptTable by issuing a set-request using the index retrieved in step 1. The smScriptRowStatus object is set to createAndWait and the smScriptSource object is set to an empty string. The smScriptRowStorage object is set to volatile to indicate that the script will be loaded via the smCodeTable. The smScriptAccess object should be set to readWrite so that the script can be modified in the smCodeTable. The smScriptRowOwner should be set to a string which identifies the higher-level manager. 3. Push the script to the mid-level manager by issuing a couple of set-requests to the smCodeTable. 4. The higher-level manager sends a set-request to set the smScriptRowStatus object to active. The agent will pass the row to the runtime system which starts to load the code from the smCodeTable. 5. The higher-level manager polls the smScriptStatus object until the value is either available or one of the error status codes. The script can only be used if the value of smScriptStatus is available. 6. If the higher-level manager wants to store the script in local non-volatile storage, it should send a set-request which Expires May 1997 [Page 29] Internet-Draft Script MIB November 1996 includes the value of smScriptName (if not set yet) and the value nonVolatile for the smScriptRowStatus object. 11.2. Loading a script via a URL (pull model) This example explains the steps performed by higher-level manager to load a script into the mid-level manager by using the pull model. 0. The higher-level manager checks the smLanguageTable and the smExtensionTable in order to select the script or language appropriate for this mid-level manager. 1. Retrieve an index for an unused row in the smScriptTable by sending a get-request to retrieve smScriptNext.0. 2. Create a row in the smScriptTable by issuing a set-request using the index retrieved in step 1. The smScriptRowStatus object is set to createAndWait and the smScriptSource object is set to the URL that points to the script. The smScriptRowOwner should be set to a string which identifies the higher-level manager. 3. The higher-level manager sends a set-request to set the smScriptRowStatus object to active. The agent will pass the row to the runtime system which starts to download the code from the location given by the smScriptSource object. 4. The higher-level manager polls the smScriptStatus object until the value is either available or one of the error status codes. The script can only be used if the value of smScriptStatus is available. 5. If the higher-level manager wants to store the script in local non-volatile storage, it should send a set-request which includes the value of smScriptName (if not set yet) and the value nonVolatile for the smScriptRowStatus object. 11.3. Updating and removing an existing script This section explains how a higher-level manager updates or removes a script from the mid-level manager. 0. The higher-level manager sets smScriptSource to an empty string and smScriptAccess to read-write (if not done yet). Expires May 1997 [Page 30] Internet-Draft Script MIB November 1996 1. The row is de-activated by setting the smScriptRowStatus to notInService. This step will only succeed if this script is not in use. Setting the smScriptRowStatus to notInService will also remove the script from the runtime system. 2. The higher-level manager sends set-requests to modify the script in the smCodeTable. 3. The higher-level manager sends a set-request to set the smScriptRowStatus object to active. The agent will pass the row to the runtime system which starts to load the code from the smCodeTable. 4. The higher-level manager polls the smScriptStatus object until the value is either available or one of the error status codes. The script can only be used if the value of smScriptStatus is available. A script is removed from the runtime system be setting the smScriptRowStatus object to notInService or destroy. Setting the smScriptRowStatus object to destroy will also remove the row from the smScriptTable and the code from the smCodeTable. Expires May 1997 [Page 31] Internet-Draft Script MIB November 1996 12. Open Issues This section documents some open issues. This section will be removed when this Internet Draft is revised. o Should the MIB provide a mechanism to make results available via a URL? Should the higher-level manager pull the results or does the mid-level manager push the results (via traps/informs)? o Can we use the Meta-Variables defined in the disman MIB to make script results accessible via SNMP? o Do we need additional instrumentation to monitor and control the runtime system, e.g. an indication about the resources (CPU, memory, ...) used by running scripts? o Does it make sense to define a set of notifications that are emitted when the execution status of a script changes? o Do we need a mechanism to clone scripts? o Do we need additional scheduling mechanisms that allow to start scripts e.g. in a crontab like fashion? Expires May 1997 [Page 32] Internet-Draft Script MIB November 1996 Table of Contents 1 Abstract ..................................................... 2 2 The SNMPv2 Network Management Framework ...................... 2 2.1 Object Definitions ......................................... 2 3 Overview ..................................................... 3 3.1 Terms ...................................................... 3 4 Requirements and Design Issues ............................... 4 4.1 Script Languages ........................................... 4 4.2 Script Transfer ............................................ 5 4.3 Script Execution ........................................... 6 5 The Structure of the MIB ..................................... 6 5.1 The smLanguage Group ....................................... 6 5.2 The smScript Group ......................................... 7 5.3 The smCode Group ........................................... 8 5.4 The smExec Group ........................................... 8 6 Definitions .................................................. 9 7 Security Considerations ...................................... 27 8 Acknowledgments .............................................. 27 9 References ................................................... 27 10 Author's Address ............................................ 28 11 Usage Examples .............................................. 29 11.1 Loading a script via SNMP (push model) .................... 29 11.2 Loading a script via a URL (pull model) ................... 30 11.3 Updating and removing an existing script .................. 30 12 Open Issues ................................................. 32 Expires May 1997 [Page 33]