summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc2593.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc2593.txt')
-rw-r--r--doc/rfc/rfc2593.txt1235
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]
+