doc: Add RFC documents

1 files changed, 1235 insertions, 0 deletions

diff --git a/doc/rfc/rfc2593.txt b/doc/rfc/rfc2593.txt
new file mode 100644
index 0000000..7807689
--- /dev/null
+++ b/doc/rfc/rfc2593.txt
@@ -0,0 +1,1235 @@
+
+
+
+
+
+
+Network Working Group                                   J. Schoenwaelder
+Request for Comments: 2593                               TU Braunschweig
+Category: Experimental                                        J. Quittek
+                                                         NEC Europe Ltd.
+                                                                May 1999
+
+
+             Script MIB Extensibility Protocol Version 1.0
+
+Status of this Memo
+
+   This memo defines an Experimental Protocol for the Internet
+   community.  It does not specify an Internet standard of any kind.
+   Discussion and suggestions for improvement are requested.
+   Distribution of this memo is unlimited.
+
+Copyright Notice
+
+   Copyright (C) The Internet Society (1999).  All Rights Reserved.
+
+Abstract
+
+   The IETF Script MIB defines an interface for the delegation of
+   management functions based on the Internet management framework. A
+   management script is a set of instructions that are executed by a
+   language specific runtime system. The Script MIB extensibility
+   protocol (SMX) defined in this memo separates language specific
+   runtime systems from language independent Script MIB implementations.
+
+Table of Contents
+
+   1. Introduction ................................................    2
+   2. Process Model and Communication Model .......................    3
+   3. Security Profiles ...........................................    3
+   4. Start of Runtime Systems and Connection Establishment .......    4
+   5. SMX Messages ................................................    5
+   5.1 Common Definitions .........................................    5
+   5.2 Commands ...................................................    7
+   5.3 Replies ....................................................    8
+   6. Elements of Procedure .......................................    9
+   6.1 SMX Message Processing on the Runtime Systems ..............    9
+   6.1.1 Processing the `hello' Command ...........................   10
+   6.1.2 Processing the `start' Command ...........................   10
+   6.1.3 Processing the `suspend' Command .........................   11
+   6.1.4 Processing the `resume' Command ..........................   12
+   6.1.5 Processing the `abort' Command ...........................   12
+   6.1.6 Processing the `status' Command ..........................   12
+   6.1.7 Generation of Asynchronous Notifications .................   13
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 1]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   6.2 SMX Message Processing on the SNMP Agent ...................   13
+   6.2.1 Creating a Runtime System ................................   13
+   6.2.2 Generating the `hello' Command ...........................   13
+   6.2.3 Generating the `start' Command ...........................   14
+   6.2.4 Generating the `suspend' Command .........................   15
+   6.2.5 Generating the `resume' Command ..........................   16
+   6.2.6 Generating the `abort' Command ...........................   16
+   6.2.7 Generating the `status' Command ..........................   17
+   6.2.8 Processing Asynchronous Notifications ....................   18
+   7. An Example SMX Message Flow .................................   19
+   8. Security Considerations .....................................   19
+   9. Acknowledgments .............................................   20
+   10. References .................................................   20
+   11. Authors' Addresses .........................................   21
+   12. Full Copyright Statement ...................................   22
+
+1.  Introduction
+
+   The Script MIB [1] defines a standard interface for the delegation of
+   management functions based on the Internet management framework. In
+   particular, it provides the following capabilities:
+
+   1.   Transfer of management scripts to a distributed manager.
+
+   2.   Initiating, suspending, resuming and terminating management
+        scripts.
+
+   3.   Transfer of arguments for management scripts.
+
+   4.   Monitoring and control of running management scripts.
+
+   5.   Transfer of results produced by management scripts.
+
+   A management script is a set of instructions executed by a language
+   specific runtime system. The Script MIB does not prescribe a specific
+   language. Instead, it allows to control scripts written in different
+   languages that are executing concurrently.
+
+   The Script MIB Extensibility protocol (SMX) defined in this memo can
+   be used to separate language specific runtime systems from the
+   runtime system independent Script MIB implementations. The
+   lightweight SMX protocol can be used to support different runtime
+   systems without any changes to the language neutral part of a Script
+   MIB implementation.
+
+   Examples of languages and runtime systems considered during the
+   design of the SMX protocol are the Java virtual machine [2] and the
+   Tool Command Language (Tcl) [3]. Other languages with comparable
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 2]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   features should be easy to integrate as well.
+
+2.  Process Model and Communication Model
+
+   Figure 1 shows the process and communication model underlying the SMX
+   protocol. The language and runtime system independent SNMP agent
+   implementing the Script MIB communicates with one ore more runtime
+   systems via the SMX protocol. A runtime system may be able to execute
+   one or multiple scripts simultaneously (multi-threading). The SMX
+   protocol supports multi-threading, but it does not require multi-
+   threaded runtime systems.
+
+   The SMX protocol uses a local storage device (usually implemented on
+   top of the local file system) to transfer scripts from the SNMP agent
+   to the runtime systems. The SNMP agent has read and write access to
+   the script storage device while the runtime systems only need read
+   access. The SMX protocol passes the location of a script in the local
+   storage device to the runtime engines. It is then the responsibility
+   of the runtime engines to load the script from the specified
+   location.
+
+                                                    runtime 1
+                   +--------------+       SMX      +---------+
+                   |              |<-------------->| O  O  O |<-+
+           SNMP    |  Script MIB  |                +---------+  |
+       <---------->|              |                             |
+                   |  SNMP Agent  |                 runtime 2   |
+                   |              |       SMX      +---------+  |
+                   |              |<-------------->| O       |  |
+                   +--------------+                +---------+  |
+                           ^                            ^       |
+                           |       +---------+          |       |
+                           |       | script  |----------+       |
+                           +------>| storage |------------------+
+                                   +---------+
+
+           Figure 1: SMX process and communication model
+
+
+3.  Security Profiles
+
+   Security profiles control what a running script is allowed to do. It
+   is useful to distinguish two different classes of security profiles:
+
+   -    The operating system security profile specifies the set of
+        operating system services that can be used by the operating
+        system level process which executes a script. Under UNIX, this
+        maps to the effective user and group identity for the running
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 3]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+        process. In addition, many UNIX versions allow to set other
+        resource limits, such as the number of open files or the maximum
+        stack sizes. Another mechanism in UNIX is the chroot() system
+        call which changes the file system root for a process. The
+        chroot() mechanism can be used to prevent runtime systems from
+        accessing any system files. It is suggested to make use of all
+        applicable operating system security mechanism in order to
+        protect the operating system from malicious scripts or runtime
+        systems.
+
+   -    Secure runtime systems provide fine grained control over the set
+        of services that can be used by a running script at a particular
+        point during script execution. A runtime security profile
+        specifying fine grained access control is runtime system
+        dependent. For a Java virtual machine, the runtime security
+        profile is interpreted by the SecurityManager and ClassLoader
+        classes[4]. For Tcl, the runtime security profile maps to the
+        interpreter's security profile [5].
+
+   The SMX protocol allows to execute scripts under different operating
+   system profiles and runtime system profiles. Multiple operating
+   system security profiles are realized by using multiple runtime
+   systems which execute in operating system processes with different
+   security profiles.  Multiple runtime security profiles are supported
+   by passing a security profile name to a runtime system during script
+   invocation.
+
+   The Script MIB does not define how operating system or runtime system
+   security profiles are identified. This memo suggests that the
+   smLaunchOwner is mapped to an operating system security profile and a
+   runtime system security profile when a script is started.
+
+4.  Start of Runtime Systems and Connection Establishment
+
+   The SNMP agent starts runtime systems based on the static properties
+   of the runtime system (multi-threaded or single-threaded) and the
+   operating system security profiles. Starting a new runtime system
+   requires to create a process environment which matches the operating
+   system security profile.
+
+   The SNMP agent initially passes information to the runtime system by
+   means of environment variables. The information is needed to
+   establish a trusted communication channel between the SNMP agent and
+   a runtime system.
+
+   The SNMP agent first creates a listening TCP socket which accepts
+   connections from runtime systems. It is the responsibility of the
+   runtime system to establish a connection to this TCP socket once it
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 4]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   has been started. The port number of the listening TCP socket is
+   passed from the SNMP agent to the runtime system in the environment
+   variable SMX_PORT.
+
+   The SNMP agent must ensure that only authorized runtime systems
+   establish a connection to the listening TCP socket. The following
+   rules are used for this purpose:
+
+   -    The TCP connection must originate from the local host.
+
+   -    The SNMP agent queries the runtime system for a security cookie
+        and closes the TCP connection if no valid response is received
+        within a given time interval. The security cookie is a random
+        number generated by the SNMP agent and passed to the runtime
+        system as part of its environment. The cookie is found in the
+        environment variable SMX_COOKIE.
+
+   The security assumption here is that access to the process
+   environment is protected by the operating system.
+
+   Alternate transports (e.g. UNIX domain sockets) are possible but not
+   defined at this point in time. The reason to choose TCP as the
+   transport protocol for SMX was that TCP is supported by all potential
+   runtime systems, while other transports are not universally
+   available.
+
+5.  SMX Messages
+
+   The message formats described below are defined using the Augmented
+   BNF (ABNF) defined in RFC 2234 [6]. The definitions for `ALPHA',
+   `DIGIT', `HEXDIG', `WSP', `CRLF', `CR', `LF', `HTAB', `VCHAR' and
+   `DQUOTE' are imported from appendix A of RFC 2234 and not repeated
+   here.
+
+5.1.  Common Definitions
+
+   The following ABNF definitions are used in subsequent sections to
+   define the SMX protocol messages.
+
+     Zero          = %x30          ; the ASCII character '0'
+
+     AlNum         = DIGIT / ALPHA / %x2D-2F
+                                   ; digits, alphas plus '-', '.', '/'
+
+     QuotedString  = DQUOTE *(VCHAR / WSP) DQUOTE
+
+     HexString     = 1*(HEXDIG HEXDIG)
+
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 5]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+     Id            = 1*DIGIT       ; identifier for an SMX transaction
+
+     Script        = QuotedString  ; script file name
+
+     RunId         = 1*DIGIT       ; globally unique identifier for a
+                                   ; running script (note, smRunIndex
+                                   ; is only unique for a smLaunchOwner,
+                                   ; smLaunchName pair)
+
+     Profile       = 1*AlNum       ; security profile name
+
+     RunState      =  "1"          ; smRunState `initializing'
+     RunState      =/ "2"          ; smRunState `executing'
+     RunState      =/ "3"          ; smRunState `suspending'
+     RunState      =/ "4"          ; smRunState `suspended'
+     RunState      =/ "5"          ; smRunState `resuming'
+     RunState      =/ "6"          ; smRunState `aborting'
+     RunState      =/ "7"          ; smRunState `terminated'
+
+     ExitCode      =  "1"          ; smRunExitCode `noError'
+     ExitCode      =/ "2"          ; smRunExitCode `halted'
+     ExitCode      =/ "3"          ; smRunExitCode `lifeTimeExceeded'
+     ExitCode      =/ "4"          ; smRunExitCode `noResourcesLeft'
+     ExitCode      =/ "5"          ; smRunExitCode `languageError'
+     ExitCode      =/ "6"          ; smRunExitCode `runtimeError'
+     ExitCode      =/ "7"          ; smRunExitCode `invalidArgument'
+     ExitCode      =/ "8"          ; smRunExitCode `securityViolation'
+     ExitCode      =/ "9"          ; smRunExitCode `genericError'
+
+     Cookie        = HexString     ; authentication cookie
+
+     Version       = "SMX/1.0"     ; current version of the SMX protocol
+
+     Argument      = HexString / QuotedString      ; see smRunArgument
+
+     Result        = HexString / QuotedString      ; see smRunResult
+
+     ErrorMsg      = HexString / QuotedString      ; see smRunError
+
+
+   The definition of QuotedString requires further explanation. A quoted
+   string may contain special character sequences, all starting with the
+   backslash character (%x5C). The interpretation of these sequences is
+   as follows:
+
+
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 6]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+           `\\'   backslash character       (`%x5C')
+           `\t'   tab character             (`HTAB')
+           `\n'   newline character         (`LF')
+           `\r'   carriage-return character (`CR')
+           `\"'   quote character           (`DQUOTE')
+
+   In all other cases not listed above, the backslash is dropped and the
+   following character is treated as an ordinary character.  `Argument'
+   and `Result' is either a QuotedString or a HexString.  The Script MIB
+   defines script arguments and results as arbitrary octet strings. The
+   SMX protocol supports a binary and a human readable representation
+   since it is likely that printable argument and result strings will be
+   used frequently. However, an implementation must be able to handle
+   both formats in order to be compliant with the Script MIB.
+
+   The `Cookie' is a HexString which does not carry any semantics other
+   than being a random sequence of bytes. It is therefore not necessary
+   to have a human readable representation.
+
+5.2.  Commands
+
+   The following ABNF definitions define the set of SMX commands which
+   can be sent from the SNMP agent to a runtime system.
+
+     Command =  "hello"   WSP Id CRLF
+
+     Command =/ "start"   WSP Id WSP RunId WSP Script WSP Profile
+                          WSP Argument CRLF
+
+     Command =/ "suspend" WSP Id WSP RunId CRLF
+
+     Command =/ "resume"  WSP Id WSP RunId CRLF
+
+     Command =/ "abort"   WSP Id WSP RunId CRLF
+
+     Command =/ "status"  WSP Id WSP RunId CRLF
+
+   The `hello' command is always the first command sent over a SMX
+   connection. It is used to identify and authenticate the runtime
+   system. The `start' command starts the execution of a script. The
+   `suspend', `resume' and `abort' commands can be used to change the
+   status of a running script. The `status' command is used to retrieve
+   status information for a running script.
+
+   There is no compile command. It is the responsibility of the SNMP
+   agent to perform any compilation steps as needed before using the SMX
+   `start' command. There is no SMX command to shutdown a runtime
+   system. Closing the connection must be interpreted as a request to
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 7]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   terminate all running scripts in that runtime system and to shutdown
+   the runtime system.
+
+5.3.  Replies
+
+   Every reply message starts with a three digit reply code and ends
+   with `CRLF'. The three digits in a reply code have a special meaning.
+   The first digit identifies the class of a reply message. The
+   following classes exist:
+
+     1yz   transient positive response
+     2yz   permanent positive response
+     3yz   transient negative response
+     4yz   permanent negative response
+     5yz   asynchronous notification
+
+   The classes 1yz and 3yz are currently not used by SMX version 1.0.
+   They are defined only for future SMX extensions.
+
+   The second digit encodes the specific category. The following
+   categories exist:
+
+     x0z   syntax errors that don't fit any other category
+     x1z   replies for commands targeted at the whole runtime system
+     x2z   replies for commands targeted at scripts
+     x3z   replies for commands targeted at running instances of scripts
+
+   The third digit gives a finer gradation of meaning in each category
+   specified by the second digit. Below is the ABNF definition of all
+   reply messages and codes:
+
+     Reply =  "211" WSP Id WSP Version WSP Cookie CRLF
+                                   ; identification of the
+                                   ; runtime system
+
+     Reply =/ "231" WSP Id WSP RunState CRLF
+                                   ; status of a running script
+
+     Reply =/ "232" WSP Id CRLF    ; abort of a running script
+
+     Reply =/ "401" WSP Id CRLF    ; syntax error in command
+
+     Reply =/ "402" WSP Id CRLF    ; unknown command
+
+     Reply =/ "421" WSP Id CRLF    ; unknown or illegal Script
+
+     Reply =/ "431" WSP Id CRLF    ; unknown or illegal RunId
+
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 8]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+     Reply =/ "432" WSP Id CRLF    ; unknown or illegal Profile
+
+     Reply =/ "433" WSP Id CRLF    ; illegal Argument
+
+     Reply =/ "434" WSP Id CRLF    ; unable to change the status of
+                                   ; a running script
+
+     Reply =/ "511" WSP Zero WSP QuotedString CRLF
+                                   ; an arbitrary message send from
+                                   ; the runtime system
+
+     Reply =/ "531" WSP Zero WSP RunId WSP RunState CRLF
+                                   ; asynchronous running script
+                                   ; status change
+
+     Reply =/ "532" WSP Zero WSP RunId WSP RunState WSP Result CRLF
+                                   ; intermediate script result
+
+     Reply =/ "533" WSP Zero WSP RunId WSP RunState WSP Result CRLF
+                                   ; intermediate script result that
+                                   ; trigger an event report
+
+     Reply =/ "534" WSP Zero WSP RunId WSP Result CRLF
+                                   ; normal script termination
+
+     Reply =/ "535" WSP Zero WSP RunId WSP ExitCode WSP ErrorMsg CRLF
+                                   ; abnormal script termination.
+
+6.  Elements of Procedure
+
+   This section describes in detail the processing steps performed by
+   the SNMP agent and the runtime system with regard to the SMX
+   protocol.
+
+6.1.  SMX Message Processing on the Runtime Systems
+
+   This section describes the processing of SMX command messages by a
+   runtime engine and the conditions under which asynchronous
+   notifications are generated.
+
+   When the runtime system receives a message, it first tries to
+   recognize a command consisting of the command string and the
+   transaction identifier. If the runtime system is not able to extract
+   both the command string and the transaction identifier, then the
+   message is discarded. An asynchronous `511' reply may be generated in
+   this case. Otherwise, the command string is checked to be valid, i.e.
+   to be one of the strings `hello', `start', `suspend', `resume',
+   `abort', or `status'.  If the string is invalid, a `402' reply is
+
+
+
+Schoenwaelder & Quittek       Experimental                      [Page 9]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   sent and processing of the message stops.  If a valid command has
+   been detected, further processing of the message depends on the
+   command as described below.
+
+   The command specific processing describes several possible syntax
+   errors for which specific reply messages are generated. If the
+   runtime engine detects any syntax error which is not explicitely
+   mentioned or which cannot be identified uniquely, a generic `401'
+   reply is sent indicating that the command cannot be executed.
+
+6.1.1.  Processing the `hello' Command
+
+   When the runtime system receives a `hello' command, it processes it
+   as follows:
+
+   1.   The runtime system obtains the security cookie from its process
+        environment.
+
+   2.   The runtime system sends a `211' reply containing the security
+        cookie.
+
+6.1.2.  Processing the `start' Command
+
+   When the runtime system receives a `start' command, it processes it
+   as follows:
+
+   1.   The syntax of the arguments of the `start' command is checked.
+        The following four checks must be made:
+
+        (a)   The syntax of the `RunId' parameter is checked and a `431'
+              reply is sent if any syntax error is detected.
+
+        (b)   The syntax of the `Script' parameter is checked and a
+              `421' reply is sent if any syntax error is detected.
+
+        (c)   The syntax of the `Profile' parameter is checked and a
+              `432' reply is sent if any syntax error is detected.
+
+        (d)   If syntax of the `Argument' parameter is checked and a
+              `433' reply is sent if any syntax error is detected.
+
+   2.   The runtime system checks whether the new `RunId' is already in
+        use. If yes, a `431' reply is sent and processing stops.
+
+   3.   The runtime system checks whether the `Script' parameter is the
+        name of a file on the local storage device, that can be read. A
+        `421' reply is sent and processing stops if the file does not
+        exist or is not readable.
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 10]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   4.   The runtime system checks whether the security profile is known
+        and sends a `432' reply and stops processing if not.
+
+   5.   The runtime engine starts the script given by the script name.
+        When the script has been started, a `231' reply is sent
+        including the current run state.
+
+   Processing of the `start' command stops, when the script reaches the
+   state `running'. For each asynchronous state change of the running
+   script, a `531' reply is sent. Processing of the `start' command is
+   also stopped if an error occurs before the state `running' is
+   reached. In this case, the run is aborted and a `535' reply is
+   generated.
+
+   If an `abort' command or a `suspend' command for the running script
+   is received before processing of the `start' command is complete,
+   then the processing of the `start' command may be stopped before the
+   state `running' is reached. In this case, the resulting status of the
+   running script is given by the respective reply to the `abort' or
+   `suspend' command, and no reply with the transaction identifier of
+   the `start' command is generated.
+
+6.1.3.  Processing the `suspend' Command
+
+   When the runtime system receives a `suspend' command, it processes it
+   as follows:
+
+   1.   If there is a syntax error in the running script identifier or
+        if there is no running script matching the identifier, a `431'
+        reply is sent and processing of the command is stopped.
+
+   2.   If the running script is already in the state `suspended', a
+        '231' reply is sent and processing of the command is stopped.
+
+   3.   If the running script is in the state `running', it is suspended
+        and a `231' reply is sent after suspending. If suspending fails,
+        a `434' reply is sent and processing of the command is stopped.
+
+   4.   If the running script has not yet reached the state `running'
+        (the `start' command still being processed), it may reach the
+        state `suspended' without having been in the state `running'.
+        After reaching the state `suspended', a `231' reply is sent.
+
+   5.   If the running script is in any other state, a `434' reply is
+        sent.
+
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 11]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+6.1.4.  Processing the `resume' Command
+
+   When the runtime system receives a `resume' command, it processes it
+   as follows:
+
+   1.   If there is a syntax error in the running script identifier or
+        if there is no running script matching the identifier, a `431'
+        reply is sent and processing of the command is stopped.
+
+   2.   If the running script is already in the state `running', a `231'
+        reply is sent and processing of the command is stopped.
+
+   3.   If the running script is in the state `suspended', it is resumed
+        and a `231' reply is sent after resuming. If resuming fails, a
+        `434' reply is sent and processing of the command is stopped.
+
+   4.   If the `start' command is still being processed for the script,
+        a `231' reply is sent when the state `running' has been reached.
+
+   5.   If the running script is in any other state, a `434' reply is
+        sent.
+
+6.1.5.  Processing the `abort' Command
+
+   When the runtime system receives an `abort' command, it processes it
+   as follows:
+
+   1.   If there is a syntax error in the running script identifier or
+        if there is no running script matching the identifier, a `431'
+        reply is sent and processing of the command is stopped.
+
+   2.   If the running script is already aborted, a `232' reply is sent
+        and processing of the command is stopped.
+
+   3.   The running script is aborted and a `232' reply is sent after
+        aborting. If aborting fails, a `434' reply is sent and
+        processing is stopped.
+
+6.1.6.  Processing the `status' Command
+
+   When the runtime system receives a `status' command, it processes it
+   as follows:
+
+   1.   If there is a syntax error in the running script identifier or
+        if there is no running script matching the identifier, a `431'
+        reply is sent and processing of the command is stopped.
+
+   2.   The status of the script is obtained and a `231' reply is sent.
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 12]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+6.1.7.  Generation of Asynchronous Notifications
+
+   The runtime system generates or may generate the following
+   notifications:
+
+   1.   If a change of the status of a running script is observed by the
+        runtime system, a `531' reply is sent.
+
+   2.   A `534' reply is sent if a running script terminates normally.
+
+   3.   A `535' reply is sent if a running script terminates abnormally.
+
+   4.   If a script generates an intermediate result, a `532' reply is
+        sent.
+
+   5.   If a script requests the generation of a `smScriptResult'
+        notification, a `533' reply is sent.
+
+   6.   Besides the notifications mentioned above, the runtime system
+        may generate arbitrary `511' replies, which are logged or
+        displayed by the SNMP agent.
+
+6.2.  SMX Message Processing on the SNMP Agent
+
+   This section describes the conditions under which an SNMP agent
+   implementing the Script MIB generates SMX commands. It also describes
+   how the SNMP agent processes replies to SMX commands.
+
+6.2.1.  Creating a Runtime System
+
+   New runtime systems are started by the SNMP agent while processing
+   set requests for a `smLaunchStart' variable. The SNMP agent first
+   searches for an already running runtime systems which matches the
+   security profiles associated with the `smLaunchStart' variable. If no
+   suitable runtime system is available, a new runtime system is started
+   by preparing the environment for the new runtime system and starting
+   the executable for the runtime system in a new process which conforms
+   to the operating system security profile. The SNMP agent prepares to
+   accept a connection from the new runtime system. The `smRunState' of
+   all scripts that should be executed in this new runtime system is set
+   to `initializing'.
+
+6.2.2.  Generating the `hello' Command
+
+   The `hello' command is generated once a connection request from a
+   runtime system has been accepted. The SNMP agent sends the `hello'
+   command as defined in section 5.2. The SNMP agent then expects a
+   reply from the runtime system within a reasonable timeout interval.
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 13]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   1.   If the timeout expires before the SNMP agent received a reply,
+        then the connection is closed and all data associated with it is
+        deleted.  Any scripts that should be running in this runtime
+        system are aborted, the `smRunExitCode' is set to `genericError'
+        and `smRunError' is modified to describe the error situation.
+
+   2.   If the received message can not be analyzed because it does not
+        have the required format, then the connection is closed and all
+        data associated with it is deleted. Any scripts that should be
+        running in this runtime system are aborted, the `smRunExitCode'
+        is set to `genericError' and `smRunError' is modified to
+        describe the error situation.
+
+   3.   If the received message is a `211' reply, then the `Id' is
+        checked whether it matches the `Id' used in the `hello' command.
+        If the `Id' matches, then the `Version' is checked. If the
+        `Version' matches a supported SMX protocol version, then the
+        `Cookie' is checked whether it matches the cookie passed to the
+        runtime system. If any of these tests fails, then the connection
+        is closed and all data associated with this runtime system is
+        deleted. Any scripts that should be running in this runtime
+        system are aborted, the `smRunExitCode' is set to `genericError'
+        and `smRunError' is modified to describe the error situation.
+
+   4.   Received messages are discarded if none of the previous rules
+        applies.
+
+6.2.3.  Generating the `start' Command
+
+   The `start' command is generated while processing set-requests for a
+   `smLaunchStart' variable. The `start' command assumes that the SNMP
+   agent already determined a runtime system suitable to execute the
+   script associated with the `smLaunchStart' variable.  The SNMP agent
+   sends the `start' command as defined in section 5.2 to the selected
+   runtime system. The SNMP agent then expects a reply from the runtime
+   system within a reasonable timeout interval.
+
+   1.   If the timeout expires before the SNMP agent received a reply,
+        then the SNMP agent sends an `abort' command to abort the
+        running script and sets the `smRunState' of the running script
+        to `terminated', the `smRunExitCode' to `genericError' and
+        `smRunError' is modified to describe the timeout situation.
+
+   2.   If the received message can not be analyzed because it does not
+        have the required format, then the message is ignored. The SNMP
+        agent continues to wait for a valid reply message until the
+        timeout expires.
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 14]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   3.   If the received message is a `4yz' reply and the `Id' matches
+        the `Id' of the `start' command, then the SNMP agent assumes
+        that the script can not be started. The `smRunState' of the
+        running script is set to `terminated', the `smRunExitCode' to
+        `genericError' and the `smRunError' is modified to contain a
+        message describing the error situation.
+
+   4.   If the received message is a `231' reply and the `Id' matches
+        the `Id' of the `start' command, then the `smRunState' variable
+        of the running script is updated.
+
+   5.   Received messages are discarded if none of the previous rules
+        applies.
+
+6.2.4.  Generating the `suspend' Command
+
+   The `suspend' command is generated while processing set-requests for
+   the `smLaunchControl' and `smRunControl' variables which change the
+   value to `suspend'. The SNMP agent sets the `smRunState' variable to
+   `suspending' and sends the `suspend' command as defined in section
+   5.2. The SNMP agent then expects a reply from the runtime system
+   within a reasonable timeout interval.
+
+   1.   If the timeout expires before the SNMP agent received a reply,
+        then the SNMP agent sends an `abort' command to abort the
+        running script and sets the `smRunState' of the running script
+        to `terminated', the `smRunExitCode' to `genericError' and
+        `smRunError' is modified to describe the timeout situation.
+
+   2.   If the received message can not be analyzed because it does not
+        have the required format, then the message is ignored. The SNMP
+        agent continues to wait for a valid reply message until the
+        timeout expires.
+
+   3.   If the received message is a `401', `402' or a `431' reply and
+        the `Id' matches the `Id' of the `suspend' command, then the
+        runtime systems is assumed to not provide the suspend/resume
+        capability and processing of the `suspend' command stops.
+
+   4.   If the received message is a `231' reply and the `Id' matches
+        the `Id' of the `suspend' command, then the `smRunState'
+        variable of the running script is updated.
+
+   5.   Received messages are discarded if none of the previous rules
+        applies.
+
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 15]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+6.2.5.  Generating the `resume' Command
+
+   The `resume' command is generated while processing set-requests for
+   the `smLaunchControl' and `smRunControl' variables which change the
+   value to `resume'. The SNMP agent sets the `smRunState' variable to
+   `resuming' and sends the `resume' command as defined in section 5.2.
+   The SNMP agent then expects a reply from the runtime system within a
+   reasonable timeout interval.
+
+   1.   If the timeout expires before the SNMP agent received a reply,
+        then the SNMP agent sends an `abort' command to abort the
+        running script and sets the `smRunState' of the running script
+        to `terminated', the `smRunExitCode' to `genericError' and
+        `smRunError' is modified to describe the timeout situation.
+
+   2.   If the received message can not be analyzed because it does not
+        have the required format, then the message is ignored. The SNMP
+        agent continues to wait for a valid reply message until the
+        timeout expires.
+
+   3.   If the received message is a `401', `402' or a `431' reply and
+        the `Id' matches the `Id' of the `resume' command, then the
+        runtime systems is assumed to not provide the suspend/resume
+        capability and processing of the `resume' command stops.
+
+   4.   If the received message is a `231' reply and the `Id' matches
+        the `Id' of the `resume' command, then the `smRunState' variable
+        of the running script is updated.
+
+   5.   Received messages are discarded if none of the previous rules
+        applies.
+
+6.2.6.  Generating the `abort' Command
+
+   The `abort' command is generated while processing set-requests for
+   the `smLaunchControl' and `smRunControl' variables which change the
+   value to `abort'. In addition, the `abort' command is also generated
+   if the `smRunLifeTime' variable reaches the value 0. The SNMP agent
+   sends the `abort' command as defined in section 5.2. The SNMP agent
+   then expects a reply from the runtime system within a reasonable
+   timeout interval.
+
+   1.   If the timeout expires before the SNMP agent received a reply,
+        then the SNMP agent sets the `smRunState' of the running script
+        to `terminated', the `smRunExitCode' to `genericError' and
+        `smRunError' is modified to describe the timeout situation.
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 16]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   2.   If the received message can not be analyzed because it does not
+        have the required format, then the message is ignored. The SNMP
+        agent continues to wait for a valid reply message until the
+        timeout expires.
+
+   3.   If the received message is a `4yz' reply and the `Id' matches
+        the `Id' of the `abort' command, then the SNMP agent assumes
+        that the script can not be aborted. The `smRunState' of the
+        running script is set to `terminated', the `smRunExitCode' to
+        `genericError' and the `smRunResult' is modified to describe the
+        error situation.
+
+   4.   If the received message is a `232' reply and the `Id' matches
+        the `Id' of the `abort' command, then the `smRunExitCode'
+        variable of the terminated script is changed to either `halted'
+        (when processing a set-request for the `smLaunchControl' and
+        `smRunControl' variables) or `lifeTimeExceeded' (if the `abort'
+        command was generated because the `smRunLifeTime' variable
+        reached the value 0). The `smRunState' variable is changed to
+        the value `terminated'.
+
+   5.   Received messages are discarded if none of the previous rules
+        applies.
+
+6.2.7.  Generating the `status' Command
+
+   The `status' command is generated either periodically or on demand by
+   the SNMP agent in order to retrieve status information from running
+   scripts. The SNMP agent sends the `status' command as defined in 5.2.
+   The SNMP agent then expects a reply from the runtime system within a
+   reasonable timeout interval.
+
+   1.   If the timeout expires before the SNMP agent received a reply,
+        then the SNMP agent sends an `abort' command to abort the
+        running script and sets the `smRunState' of the running script
+        to `terminated', the `smRunExitCode' to `genericError' and
+        `smRunError' is modified to describe the timeout situation.
+
+   2.   If the received message can not be analyzed because it does not
+        have the required format, then the message is ignored. The SNMP
+        agent continues to wait for a valid reply message until the
+        timeout expires.
+
+   3.   If the received message is a `4yz' reply and the `Id' matches
+        the `Id' of the `status' command, then the SNMP agent assumes
+        that the script status can not be read, which is a fatal error
+        condition. The SNMP agent sends an `abort' command to abort the
+        running script. The `smRunState' of the running script is set to
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 17]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+        `terminated', the `smRunExitCode' to `genericError' and the
+        `smRunError' is modified to describe the error situation.
+
+   4.   If the received message is a `231' reply and the `Id' matches
+        the `Id' of the `status' command, then the `smRunState' variable
+        of the running script is updated.
+
+   5.   Received messages are discarded if none of the previous rules
+        applies.
+
+6.2.8.  Processing Asynchronous Notifications
+
+   The runtime system can send asynchronous status change notifications.
+   These `5yz' replies are processed as described below.
+
+   1.   If the received message is a `511' reply, then the message is
+        displayed or logged appropriately and processing stops.
+
+   2.   If the received message is a `531' reply, then the SNMP agent
+        checks whether a running script with the given `RunId' exists in
+        the runtime system. Processing of the notification stops if
+        there is no running script with the `RunId'. Otherwise, the
+        `smRunState' is updated.
+
+   3.   If the received message is a `532' reply, then the SNMP agent
+        checks whether a running script with the given `RunId' exists in
+        the runtime system. Processing of the notification stops if
+        there is no running script with the `RunId'. Otherwise,
+        `smRunState' and `smRunResult' are updated.
+
+   4.   If the received message is a `533' reply, then the SNMP agent
+        checks whether a running script with the given `RunId' exists in
+        the runtime system. Processing of the notification stops if
+        there is no running script with the `RunId'. Otherwise,
+        `smRunState' and `smRunResult' are updated and the
+        `smScriptResult' notification is generated.
+
+   5.   If the received message is a `534' reply, then the SNMP agent
+        checks whether a running script with the given `RunId' exists in
+        the runtime system. Processing stops if there is no running
+        script with the `RunId'. Otherwise, `smExitCode' is set to
+        `noError', `smRunState' is set to `terminated' and `smRunResult'
+        is updated.
+
+   6.   If the received message is a `535' reply, then the SNMP agent
+        checks whether a running script with the given `RunId' exists in
+        the runtime system. Processing stops if there is no running
+        script with the `RunId'. Otherwise, `smRunState' is set to
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 18]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+        `terminated' and `smExitCode' and `smRunError' are updated.
+
+7.  An Example SMX Message Flow
+
+   Below is an example SMX message exchange. Messages send from the SNMP
+   agent are marked with `>' while replies send from the runtime system
+   are marked with `<'. Line terminators (`CRLF') are not shown in order
+   to make the example more readable.
+
+     > hello 1
+     < 211 1 SMX/1.0 0AF0BAED6F877FBC
+     > start 2 42 "/var/snmp/scripts/foo.jar" untrusted ""
+     > start 5 44 "/var/snmp/scripts/bar.jar" trusted "www.ietf.org"
+     < 231 2 2
+     > start 12 48 "/var/snmp/scripts/foo.jar" funny ""
+     < 231 5 2
+     < 532 0 44 2 "waiting for response"
+     > status 18 42
+     > status 19 44
+     < 432 12
+     < 231 19 2
+     < 231 18 2
+     > hello 578
+     < 211 578 SMX/1.0 0AF0BAED6F877FBC
+     > suspend 581 42
+     < 231 581 4
+     < 534 0 44 "test completed"
+     > abort 611 42
+     < 232 611
+
+8.  Security Considerations
+
+   The SMX protocol runs on top of a local TCP connection. Protocol
+   messages never leave the local system. It is therefore not possible
+   to attack the message exchanges if the underlying operating system
+   protects local TCP connections from other users on the same machine.
+
+   The only critical situation is the connection establishment phase.
+   The rules defined in section 4 ensure that only local connections are
+   accepted and that a runtime system has to identify itself with a
+   security cookie generated by the SNMP agent and passed to the runtime
+   system process as part of its environment. This rule ensures that
+   scripts will only be executed on authorized runtime systems. This
+   scheme relies on the protection of process environments by the
+   operating system. Well maintained UNIX operating systems have this
+   property.
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 19]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+   The SMX protocol allows to execute script under different operating
+   system and runtime system security profiles. The memo suggests to map
+   the smLaunchOwner value to an operating system and a runtime system
+   security profile. The operating system security profile is enforced
+   by the operating system by setting up a proper process environment.
+   The runtime security profile is enforced by a secure runtime system
+   (e.g. the Java virtual machine or a safe Tcl interpreter) [7].
+
+9.  Acknowledgments
+
+   The protocol described in this memo is the result of a joint project
+   between the Technical University of Braunschweig and C&C Research
+   Laboratories of NEC Europe Ltd. in Berlin. We would like to thank the
+   following project members for their contributions to the initial
+   design and the implementation of the protocol described in this memo:
+
+           M. Bolz         (TU Braunschweig)
+           C. Kappler      (NEC Europe Ltd.)
+           A. Kind         (NEC Europe Ltd.)
+           S. Mertens      (TU Braunschweig)
+           J. Nicklisch    (NEC Europe Ltd.)
+
+10.  References
+
+   [1]  Levi, D. and J. Schoenwaelder, "Definitions of Managed Objects
+        for the Delegation of Management Scripts", RFC 2592, May 1999.
+
+   [2]  Lindholm, T., and F. Yellin, "The Java Virtual Machine
+        Specification", Addison Wesley, 1997.
+
+   [3]  J.K. Ousterhout, "Tcl and the Tk Toolkit", Addison Wesley, 1994.
+
+   [4]  Fritzinger, J.S., and M. Mueller, "Java Security", White Paper,
+        Sun Microsystems, Inc., 1996.
+
+   [5]  Levy, J.Y., Demailly, L., Ousterhout, J.K., and B. Welch, "The
+        Safe-Tcl Security Model", Proc. USENIX Annual Technical
+        Conference, June 1998.
+
+   [6]  Crocker, D., and P. Overell, "Augmented BNF for Syntax
+        Specifications: ABNF", RFC 2234, Internet Mail Consortium, Demon
+        Internet Ltd., November 1997.
+
+   [7]  Schoenwaelder, J., and J. Quittek, "Secure Management by
+        Delegation within the Internet Management", Proc. IFIP/IEEE
+        International Symposium on Integrated Network Management '99,
+        May 1999.
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 20]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+11.  Authors' Addresses
+
+   Juergen Schoenwaelder
+   TU Braunschweig
+   Bueltenweg 74/75
+   38106 Braunschweig
+   Germany
+
+   Phone: +49 531 391-3283
+   EMail: schoenw@ibr.cs.tu-bs.de
+
+
+   Juergen Quittek
+   NEC Europe Ltd.
+   C&C Research Laboratories
+   Hardenbergplatz 2
+   10623 Berlin
+   Germany
+
+   Phone: +49 30 254230-19
+   EMail: quittek@ccrle.nec.de
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 21]
+
+RFC 2593                    SMX Protocol 1.0                    May 1999
+
+
+12.  Full Copyright Statement
+
+   Copyright (C) The Internet Society (1999). 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Schoenwaelder & Quittek       Experimental                     [Page 22]
+