    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]