7. Usage Examples
This section presents some examples that explain how a manager can use the Script MIB defined in this memo. The purpose of these examples is to explain the steps that are normally used to delegate management scripts.7.1. Pushing a Script via SNMP
This example explains the steps performed by a manager to push a script into a distributed manager. 1. The manager first checks the smLangTable and the smExtsnTable in order to select the appropriate script or language. 2. The manager creates a row in the smScriptTable by issuing an SNMP set-request. The smScriptRowStatus object is set to `createAndWait' and the smScriptSource object is set to an empty string. The smScriptLanguage object is set to the language in which the script was written. The smScriptStorageType object is set to `volatile' to indicate that the script will be loaded via the smCodeTable. The smScriptOwner is set to a string which identifies the principal who owns the new row. The smScriptName defines the administratively assigned unique name for the script. 3. The manager sets the smScriptRowStatus object to `active' and the smScriptAdminStatus object to `editing'. 4. The manager pushes the script to the distributed manager by issuing a couple of SNMP set-requests to fill the smCodeTable. 5. Once the whole script has been transferred, the manager sends a set-request to set the smScriptAdminStatus object to `enabled'. The Script MIB implementation now makes the script accessible to the runtime system. This might include the compilation of the script if the language requires a compilation step. 6. The manager polls the smScriptOperStatus object until the value is either `enabled' or one of the error status codes. The script can only be used if the value of smScriptOperStatus is `enabled'. 7. If the manager wants to store the script in local non-volatile storage, it should send a set-request which changes the smScriptStorageType object to `nonVolatile'.
7.2. Pulling a Script from a URL
This example explains the steps performed by a manager to cause a distributed manager to pull a script from a URL. 1. The manager first checks the smLangTable and the smExtsnTable in order to select the appropriate script or language. 2. The manager creates a row in the smScriptTable by issuing an SNMP set-request. The smScriptRowStatus object is set to `createAndWait' and the smScriptSource object is set to the URL which points to the script source. The smScriptLanguage object is set to the language in which the script was written. The smScriptOwner is set to a string which identifies the principal who owns the new row. The smScriptName defines the administratively assigned unique name for the script. 3. The manager sets the smScriptRowStatus object to `active'. 4. The manager sends a set-request to set the smScriptAdminStatus object to `enabled'. The Script MIB implementation now makes the script accessible to the runtime system. This causes a retrieval operation to pull the script from the URL stored in smScriptSource. This retrieval operation might be followed by a compile operation if the language requires a compilation step. 5. The manager polls the smScriptOperStatus object until the value is either `enabled' or one of the error status codes. The script can only be used if the value of smScriptOperStatus is `enabled'. 6. If the manager wants to store the script in local non-volatile storage, it should send a set-request which changes the smScriptStorageType object to `nonVolatile'.7.3. Modifying an Existing Script
This section explains how a manager can modify a script by sending SNMP set-requests. 1. First, the script is de-activated by setting the smScriptAdminStatus to `disabled'. 2. The manager polls the smScriptOperStatus object until the value is `disabled'. 3. The manager sets smScriptSource to an empty string and smScriptAdminStatus to `editing'. This makes the script source available in the smCodeTable.
4. The manager polls the smScriptOperStatus object until the value is `editing'. 5. The manager sends SNMP set-requests to modify the script in the smCodeTable. 6. The manager sends a set-request to set the smScriptAdminStatus object to `enabled'. The Script MIB implementation now makes the script accessible to the runtime system. This might include the compilation of the script if the language requires a compilation step. 7. The manager polls the smScriptOperStatus object until the value is either `enabled' or one of the error status codes. The script can only be used if the value of smScriptOperStatus is `enabled'.7.4. Removing an Existing Script
This section explains how a manager can remove a script from a distributed manager. 1. First, the manager sets the smScriptAdminStatus to `disabled'. This will ensure that no new scripts can be started while running scripts finish their execution. 2. The manager polls the smScriptOperStatus object until the value is `disabled'. 3. The manager sends an SNMP set-request to change the smScriptRowStatus object to `destroy'. This will remove the row and all associated resources from the Script MIB implementation.7.5. Creating a Launch Button
This section explains how a manager can create a launch button for starting a script. 1. The manager, who is identified by an smLaunchOwner value, first chooses a name for the new row in the smLaunchTable. The manager sends an SNMP set-request to set the smLaunchRowStatus object for this smLaunchOwner and smLaunchName to `createAndWait'. 2. The manager fills the new smLaunchTable row with all required parameters. The smLaunchScriptOwner and smLaunchScriptName values point to the script that should be started from this launch button. 3. The manager sets the smLaunchRowStatus object to `active'.
4. The manager sends a set-request to change smLaunchAdminStatus to `enabled' once the new smLaunchTable row is complete. 5. The manager polls the smLaunchOperStatus object until the value is `enabled'.7.6. Launching a Script
This section explains the suggested way to launch a script from a given launch button. 1. The manager first retrieves the value of smLaunchRunIndexNext from the launch button selected to start the script. 2. The manager sends an SNMP set-request to set the smLaunchStart object to the value obtained in step 1. This will launch the script if all necessary pre-conditions are satisfied (see the definition of smLaunchStart for more details). The manager can also provide the smLaunchArgument in the same set-request that is used to start the script. Upon successful start, a new row will be created in the smRunTable indexed by smLaunchOwner, smLaunchName and the value written to smLaunchStart. 3. The manager polls the smRunState object until the value is either `executing' (the default case), `suspended' or `terminated'. The first step is not required. A manager can also try to guess an unused value for smRunIndex if the manager wants to start the script in a single transaction. A manager can also use the special value 0 if it does not care about the smRunIndex.7.7. Suspending a Running Script
This section explains how a manager can suspend a running script. 1. The manager sets the smRunControl object of the running script or the smLaunchControl object of the launch button used to start the running script to `suspend'. Setting smLaunchControl will suspend all running scripts started from the launch button while smRunControl will only suspend the running script associated with the smRunControl instance. 2. The manager polls the smRunState object until the value is either `suspended', `executing', or `terminated'. If the value is `suspended', then the suspend operation was successful. If the value is `executing', then the attempt to suspend the script
failed. The value `terminated' can be received in cases where the suspend operation failed and the running script terminated between the polls. Note that the set operation in the first step can lead to an inconsistentValue error which indicates that the suspend operation failed (e.g., because the runtime system does not support suspend/resume). There is no need to poll smRunState in this case.7.8. Resuming a Suspended Script
This section explains how a manager can resume a suspended script. 1. The manager sets the smRunControl object of the running script or the smLaunchControl object of the launch button used to start the running script to `resume'. Setting smLaunchControl will resume all running scripts started from the launch button while smRunControl will only resume the running script associated with the smRunControl instance. 2. The manager polls the smRunState object until the value is either `suspended', `executing', or `terminated'. If the value is `executing', then the resume operation was successful. If the value is `suspended', then the attempt to resume the script failed. The value `terminated' can be received in cases where the resume operation was successful and the running script terminated between the polls. Note that the set operation in the first step can lead to an inconsistentValue error which indicates that the resume operation failed (e.g., because the runtime system does not support suspend/resume). There is no need to poll smRunState in this case.7.9. Terminating a Running Script
This section explains two ways to terminate a running script. The first approach is as follows: 1. The manager sets the smRunControl object of the running script or the smLaunchControl object of the launch button used to start the running script to `abort'. Setting smLaunchControl will abort all running scripts started from the launch button while smRunControl will only abort the running script associated with the smRunControl instance. 2. The manager polls the smRunState object until the value is `terminated'.
The second way to terminate a script is to set the smRunLifeTime to zero which causes the runtime system to terminate the script with a `lifeTimeExceeded' exit code: 1. The manager changes the value of smRunLifeTime to 0. This causes the Script MIB implementation to abort the script because the remaining life time has expired. 2. The manager polls the smRunState object until the value is `terminated'. Note that changing the smRunLifeTime value can also be used to increase the permitted lifetime of a running script. For example, a manager can choose to set smRunLifeTime to a small fixed time interval and increase the value periodically. This strategy has the nice effect that scripts terminate automatically if the manager loses contact with the Script MIB engine.7.10. Removing a Terminated Script
This section explains how a manager can remove a terminated script. 1. The manager changes the smRunExpireTime to 0. This causes the Script MIB implementation to destroy the smRunTable entry of the terminated script.7.11. Removing a Launch Button
This section explains how a manager can remove a launch button from a distributed manager. 1. First, the manager sets the smLaunchAdminStatus to `disabled'. This will ensure that no new scripts can be started from this launch button while running scripts finish their execution. 2. The manager polls the smLaunchOperStatus object until the value is `disabled'. 3. The manager sends an SNMP set-request to change the smLaunchRowStatus object to `destroy'. This will remove the row and all associated resources from the Script MIB implementation.8. VACM Configuration Examples
This section shows how the view-based access control model defined in RFC 2575 [RFC2575] can be configured to control access to the Script MIB.
8.1. Sandbox for Guests
The first example demonstrates how to configure VACM to give the members of the VACM group "guest" limited access to the Script MIB. The MIB views defined below give the members of the "guest" group a sandbox where they can install and start their own scripts, but not access any other scripts maintained by the Script MIB implementation. vacmAccessReadView."guest"."".usm.authNoPriv = "guestReadView" vacmAccessWriteView."guest"."".usm.authNoPriv = "guestWriteView" The guestReadView grants read access to the smLangTable, the smExtsnTable and to all the table entries owned by "guest": guestReadView: smLangTable (included) smExtsnTable (included) smScriptObjects.*.*.*."guest" (included) smRunObjects.*.*.*."guest" (included) The guestWriteView grants write access to all the table entries owned by "guest": guestWriteView: smScriptObjects.*.*.*."guest" (included) smRunObjects.*.*.*."guest" (included)8.2. Sharing Scripts
This example demonstrates how VACM can be used to share a repository of scripts between the members of the "senior" and the members of the "junior" VACM group: vacmAccessReadView."junior"."".usm.authNoPriv = "juniorReadView" vacmAccessWriteView."junior"."".usm.authNoPriv = "juniorWriteView" juniorReadView: smLangTable (included) smExtsnTable (included) smScriptObjects.*.*.*."junior" (included) smRunObjects.*.*.*."junior" (included) smScriptObjects.*.*.*."utils" (included) juniorWriteView: smScriptObjects.*.*.*."junior" (included) smRunObjects.*.*.*."junior" (included)
The definitions above allow the members of the "junior" VACM group to start the scripts owned by "utils" in addition to the script the members of the "junior" VACM group installed themselves. This is accomplished by giving the members of "junior" read access to scripts in "utils". This allows members of "junior" to create entries in the smLaunchTable which refer to scripts in "utils", and to launch those scripts using these entries in the smLaunchTable. vacmAccessReadView."senior"."".usm.authNoPriv = "seniorReadView" vacmAccessWriteView."senior"."".usm.authNoPriv = "seniorWriteView" seniorReadView: smLangTable (included) smExtsnTable (included) smScriptObjects.*.*.*."senior" (included) smRunObjects.*.*.*."senior" (included) smScriptObjects.*.*.*."utils" (included) seniorWriteView: smScriptObjects.*.*.*."senior" (included) smRunObjects.*.*.*."senior" (included) smScriptObjects.*.*.*."utils" (included) The definitions for the members of the "senior" VACM group allow to start the scripts owned by "utils" in addition to the script the members of the "senior" VACM group installed themself. The third write access rule in the seniorWriteView also grants the permission to install scripts owned by "utils". The members of the "senior" VACM group therefore have the permissions to install and modify scripts that can be called by the members of the "junior" VACM group.8.3. Emergency Scripts
This example demonstrates how VACM can be used to allow the members of the "junior" VACM group to launch scripts that are executed with the permissions associated with the "emergency" owner. This works by adding the following rules to the juniorReadView and the juniorWriteView: juniorReadView: smScriptObjects.*.*.*."emergency" (included) smRunObjects.*.*.*."emergency" (included) juniorWriteView smLaunchStart."emergency" (included) smLaunchArgument."emergency" (included)
The rules added to the juniorReadView grant read access to the scripts, the launch buttons and the results owned by "emergency". The rules added to the juniorWriteView grant write permissions to the smLaunchStart and smLaunchArgument variables owned by "emergency". Members of the "junior" VACM group can therefore start scripts that will execute under the owner "emergency". seniorReadView: smScriptObjects.*.*.*."emergency" (included) smRunObjects.*.*.*."emergency" (included) seniorWriteView: smScriptObjects.*.*.*."emergency" (included) smRunObjects.*.*.*."emergency" (included) The rules added to the seniorReadView and the seniorWriteView will give the members of the "senior" VACM group the rights to install emergency scripts and to configure appropriate launch buttons.9. IANA Considerations
The Internet Assigned Numbers Authority (IANA) is responsible for maintaining a MIB module (IANA-LANGUAGE-MIB) which provides OID registrations for well-known languages. The IANA language registry is intended to reduce interoperability problems by providing a single list of well-known languages. However, it is of course still possible to register languages in private OID spaces. Registering languages in private OID spaces is especially attractive if a language is used for experimentation or if a language is only used in environments where the distribution of MIB modules with the language registration does not cause any maintenance problems. Any additions or changes to the list of languages registered via IANA require Designated Expert Review as defined in the IANA guidelines [RFC2434]. The Designated Expert will be selected by the IESG Area Director for the IETF Operations and Management Area.10. Security Considerations
There are a number of management objects defined in this MIB that have a MAX-ACCESS clause of read-write and/or read-create. Such objects may be considered sensitive or vulnerable in some network environments. The support for SET operations in a non-secure environment without proper protection can have a negative effect on network operations.
SNMPv1 by itself is not a secure environment. Even if the network itself is secure (for example by using IPSec), even then, there is no control as to who on the secure network is allowed to access and GET/SET (read/change/create/delete) the objects in this MIB. It is recommended that the implementers consider the security features as provided by the SNMPv3 framework. Specifically, the use of the User-based Security Model RFC 2574 [RFC2574] and the View- based Access Control Model RFC 2575 [RFC2575] is recommended. It is then a customer/user responsibility to ensure that the SNMP entity giving access to an instance of this MIB, is properly configured to give access to the objects only to those principals (users) that have legitimate rights to indeed GET or SET (change/create/delete) them. 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. To facilitate the provisioning of access control by a security administrator using the View-Based Access Control Model (VACM) defined in RFC 2575 [RFC2575] for tables in which multiple users may need to independently create or modify entries, the initial index is used as an "owner index". Such an initial index has a syntax of SnmpAdminString, and can thus be trivially mapped to a securityName or groupName as defined in VACM, in accordance with a security policy. All entries in related tables belonging to a particular user will have the same value for this initial index. For a given user's entries in a particular table, the object identifiers for the information in these entries will have the same subidentifiers (except for the "column" subidentifier) up to the end of the encoded owner index. To configure VACM to permit access to this portion of the table, one would create vacmViewTreeFamilyTable entries with the value of vacmViewTreeFamilySubtree including the owner index portion, and vacmViewTreeFamilyMask "wildcarding" the column subidentifier. More elaborate configurations are possible. The VACM access control mechanism described above provides control over SNMP access to Script MIB objects. There are a number of other access control issues that are outside of the scope of this MIB. For example, access control on URLs, especially those that use the file scheme, must be realized by the underlying operating system. A mapping of the owner index value to a local operating system security
user identity should be used by an implementation of this MIB to control access to operating system resources when resolving URLs or executing scripts.11. Intellectual Property
The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director.12. Changes from RFC 2592
The following list documents major changes from the previous version of this document, published as RFC 2592: - Updated the boilerplate and the references. - Added revision clauses to the module identity macro. - Various typos have been fixed. - Added SIZE restriction to smScriptName which is consistent with smLaunchScriptName. Added DEFVAL and some clarifying text on the usage of a zero-length string to smLaunchScriptName. - Clarified under which conditions changes to smScriptLanguage are invalid. - Added new smScriptError and smLaunchError objects. - Setting smRunLifeTime to its maximum value now disables the timer so that scripts can run forever.
- Added the `autostart' value to the smLaunchAdminStatus object which allows to launch scripts during the disable->enabled transition of smLaunchOperStatus. - Added an additional step to the "creating a launch button" procedure which sets the smLaunchRowStatus to active. - Added a final polling step in the procedure to launch a script. - Added a final polling step in the procedure to terminate a running script. - Removed the requirement that smRunError is a zero-length string while the smRunExitCode has the value `noError'. - Added new smScriptLastChange, smLaunchLastChange, smRunResultTime, and smRunErrorTime objects. - Added some additional boilerplate text to the security considerations section. - Added a new smLaunchRowExpireTime object and a new `expired' state to the smLaunchOperStatus object. - Clarified that the smRunState object reports the actual state if attempts to suspend or resume scripts fail. - Clarified the conditions under which set operations to smLaunchControl and smRunControl can lead to inconsistentValue errors. - Added procedures for suspending/resuming/removing running scripts to section 7. - Added text to the smScriptStorageType description to better highlight the difference between the storage type of the script row entry and the script itself. - Updated the smCompliances statement to not require write access to the smCodeText object after row creation. - Deprecated smCompliance, smScriptGroup, smLaunchGroup, smRunGroup, smNotificationsGroup and created smCompliance2, smScriptGroup2, smLaunchGroup2, smRunGroup2 and smNotificationsGroup2 that take care of the new objects and notifications.
13. Acknowledgments
This document was produced by the IETF Distributed Management (DISMAN) working group.14. References
[RFC2571] Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture for Describing SNMP Management Frameworks", RFC 2571, April 1999. [RFC1155] Rose, M. and K. McCloghrie, "Structure and Identification of Management Information for TCP/IP-based Internets", STD 16, RFC 1155, May 1990. [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 16, RFC 1212, March 1991. [RFC1215] Rose, M., "A Convention for Defining Traps for use with the SNMP", RFC 1215, March 1991. [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999. [RFC1157] Case, J., Fedor, M., Schoffstall, M. and J. Davin, "Simple Network Management Protocol", STD 15, RFC 1157, May 1990. [RFC1901] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901, January 1996. [RFC1906] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1906, January 1996. [RFC2572] Case, J., Harrington D., Presuhn R. and B. Wijnen, "Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)", RFC 2572, April 1999.
[RFC2574] Blumenthal, U. and B. Wijnen, "User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)", RFC 2574, April 1999. [RFC1905] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1996. [RFC2573] Levi, D., Meyer, P. and B. Stewart, "SNMPv3 Applications", RFC 2573, April 1999. [RFC2575] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", RFC 2575, April 1999. [RFC2570] Case, J., Mundy, R., Partain, D. and B. Stewart, "Introduction to Version 3 of the Internet-standard Network Management Framework", RFC 2570, April 1999. [RFC2028] Hovey, R. and S. Bradner, "The Organizations Involved in the IETF Standards Process", BCP 11, RFC 2028, October 1996. [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, " Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [RFC959] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC 959, October 1985. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
15. Editors' Addresses
David B. Levi Nortel Networks 4401 Great America Parkway Santa Clara, CA 95052-8185 USA Phone: +1 423 686 0432 EMail: dlevi@nortelnetworks.com Juergen Schoenwaelder TU Braunschweig Bueltenweg 74/75 38106 Braunschweig Germany Phone: +49 531 391-3283 EMail: schoenw@ibr.cs.tu-bs.de
16. Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.