RFC 3179

Script MIB Extensibility Protocol Version 1.1 🎀

Okay bestie, this is RFC 3179 💖 It's an Experimental doc (so not a full Internet standard, just a "let's try this and tell us what you think" vibe) from October 2001. It was written by J. Schoenwaelder from TU Braunschweig and J. Quittek from NEC Europe Ltd. 👑 It obsoletes RFC 2593, and the header doesn't list any RFCs it updates. Now let's get into it 🦋

---

Status of This Memo 📜

ngl this part is just the legal-ish stuff, but here's the tea: this memo defines an Experimental Protocol for the Internet community. It is NOT an Internet standard of any kind 🙈 They're literally asking for discussion and suggestions for improvement, so if you have thoughts, speak up! Distribution of this memo is unlimited 💅

Copyright Notice 🌈

Copyright (C) The Internet Society (2001). All Rights Reserved. ✨

Abstract 🧚

So the Script MIB extensibility protocol (SMX) is the thing that separates language-specific runtime systems from language-independent Script MIB implementations 🔥 The IETF Script MIB gives you an interface for handing off management functions based on the Internet management framework. And a management script is just a set of instructions that a language-specific runtime system runs. It's giving clean separation, honestly 😭

Table of Contents 🗂️

   1 Introduction .................................................    2
   2 Process Model and Communication Model ........................    3
   3 Security Profiles ............................................    4
   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 ....................................................    7
   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
   6.2 SMX Message Processing on the SNMP Agent ...................   13
   6.2.1 Creating a Runtime System ................................   14
   6.2.2 Generating the `hello' Command ...........................   14
   6.2.3 Generating the `start' Command ...........................   15
   6.2.4 Generating the `suspend' Command .........................   16
   6.2.5 Generating the `resume' Command ..........................   16
   6.2.6 Generating the `abort' Command ...........................   17
   6.2.7 Generating the `status' Command ..........................   18
   6.2.8 Processing Asynchronous Notifications ....................   19
   7 Example SMX Message Flow .....................................   20
   8 Transport Mappings ...........................................   20
   8.1 SMX over Bi-directional Pipes ..............................   21
   8.2 SMX over TCP ...............................................   21
   9 Security Considerations ......................................   21
   10 Changes from RFC 2593 .......................................   22
   11 Acknowledgments .............................................   23
   12 References ..................................................   23
   13 Authors' Addresses ..........................................   24
   14 Full Copyright Statement ....................................   25

---

1. Introduction ✨

The Script MIB [1] is a standard interface for handing off management functions based on the Internet management framework 💖 It gives you these 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 doesn't pick one language for you. Instead, it lets you control scripts written in different languages that are running at the same time 🌸

The Script MIB Extensibility protocol (SMX) in this memo is what lets you separate language-specific runtime systems from the runtime-system-independent Script MIB implementations 🦋 The lightweight SMX protocol means you can support different runtime systems without changing the language-neutral part of a Script MIB implementation. Lowkey genius 🧠

Languages and runtime systems they considered while designing SMX include the Java virtual machine [2] and the Tool Command Language (Tcl) [3]. Other languages with comparable features should be easy to integrate as well ✨

2. Process Model and Communication Model 🧚

Figure 1 shows the process and communication model underneath SMX. The language- and runtime-system-independent SNMP agent that implements the Script MIB talks to one or more runtime systems over the SMX protocol. A runtime system may be able to run one or multiple scripts simultaneously (multi-threading). SMX supports multi-threading, but it does not require multi-threaded runtime systems 💅

SMX uses a local storage device (usually built on top of the local file system) to move scripts from the SNMP agent over to the runtime systems. The SNMP agent has read and write access to that script storage device, while the runtime systems only need read access 👑 SMX passes the location of a script in the local storage device to the runtime engines, and then it's the runtime engines' job to load the script from that location. The vibes are very much "you do your part, I do mine" 🫶

                                                   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 helps to split them into two different classes 💜

• The operating system security profile specifies the set of operating system services that can be used by the operating system level process that runs a script. Under UNIX, this maps to the effective user and group identity for the running process. On top of that, many UNIX versions let you set other resource limits, like the number of open files or the maximum stack sizes. Another UNIX mechanism is the chroot() system call, which changes the file system root for a process. The chroot() mechanism can be used to stop runtime systems from accessing any system files. It is suggested to make use of all applicable operating system security mechanisms in order to protect the operating system from malicious scripts or runtime systems 🛡️
• Secure runtime systems give you fine-grained control over the set of services a running script can use at a particular point during script execution. A runtime security profile that specifies fine-grained access control depends on the runtime system. 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] 🌈

SMX lets you run scripts under different operating system profiles and runtime system profiles. Multiple operating system security profiles are realized by using multiple runtime systems that run 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 doesn't define how operating system or runtime system security profiles get 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 each runtime system (multi-threaded or single-threaded) and on the operating system security profiles. Starting a new runtime system means creating a process environment that matches the operating system security profile 💖

To keep SMX communication away from untrusted peers, the SNMP agent has to choose a secure SMX transport. This memo defines two transports in Section 8: (a) a bi-directional pipe using standard input/output streams on the runtime engine side, and (b) a TCP connection where the SNMP agent acts as a listening server that accepts only connections from local runtime engines that authenticate themselves with a secret shared between the agent and the runtime engine 🔒

5. SMX Messages 💌

The message formats below are defined using the Augmented BNF (ABNF) from 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 aren't repeated here, so go check that appendix if you need them 🫶

5.1. Common Definitions ✨

okay bestie, this is the shared vocab section 🎀 every SMX message gets built out of these little pieces, so they're basically the foundation 💅

Zero          = %x30          ; the ASCII character '0'

ProfileChars  = DIGIT / ALPHA / %x2D-2F / %x3A / %x5F
                              ; digits, alphas, and the characters
                              ; '-', '.', '/', ':', '_'

QuotedString  = DQUOTE *(VCHAR / WSP) DQUOTE

HexString     = 1*(HEXDIG HEXDIG)

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*ProfileChars ; 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'

Authenticator = HexString     ; authentication cookie

Version       = "SMX/1.1"     ; current version of the SMX protocol

Argument      = HexString / QuotedString      ; see smRunArgument

Result        = HexString / QuotedString      ; see smRunResult

ErrorMsg      = HexString / QuotedString      ; see smRunError

The QuotedString definition needs a little extra explaining 🙈 A quoted string can contain special character sequences, and every one of them starts with a backslash (%x5C). Here's how they get read:

            `\\'   backslash character       (`%x5C')
            `\t'   tab character             (`HTAB')
            `\n'   newline character         (`LF')
            `\r'   carriage-return character (`CR')
            `\"'   quote character           (`DQUOTE')

Any backslash followed by something not on that list just gets dropped, and the next character is treated as a regular character 🌸

Argument and Result can each be either a QuotedString or a HexString. The Script MIB defines script arguments and results as arbitrary octet strings. SMX supports both a binary and a human-readable form, since printable strings are probably going to get used a lot 💜 Still, an implementation must be able to handle both formats to be compliant with the Script MIB 🫶

The Authenticator is a HexString with no meaning beyond being a random sequence of bytes, so it doesn't need a human-readable version 🔐

---

5.2. Commands 💌

These ABNF definitions list the SMX commands that the SNMP agent can send 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

hello is always the first command on an SMX connection. It's how the runtime system gets identified and authenticated 🪪 start kicks off a script's execution, suspend, resume and abort let you change the status of a running script, and status gets you the status info for a running script ✨

No compile command here, bestie 🙅‍♀️ If a script needs compiling, the SNMP agent has to take care of that before using start. There's also no SMX command to shut down a runtime system. Instead, closing the connection must be treated as a request to terminate every running script in that runtime system and shut the runtime system down 💀

---

5.3. Replies 🦋

Every reply message starts with a three-digit reply code and ends with CRLF. Those three digits are doing a lot of work 👑 The first digit tells you the class of the reply:

   1yz   transient positive response
   2yz   permanent positive response
   3yz   transient negative response
   4yz   permanent negative response
   5yz   asynchronous notification

Classes 1yz and 3yz aren't used by SMX version 1.1 yet. They're only defined for future SMX extensions 🔮

The second digit gets more specific about the category:

   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

And the third digit gives a finer level of detail inside each of those categories. Here's the full ABNF for all the reply messages and codes 🌈

   Reply =  "211" WSP Id WSP Version *1(WSP Authenticator) 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

   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
                                 ; triggers an event report

   Reply =/ "534" WSP Zero WSP RunId WSP Result CRLF
                                 ; normal script termination,
                                 ; deprecated

   Reply =/ "535" WSP Zero WSP RunId WSP ExitCode WSP ErrorMsg CRLF
                                 ; abnormal script termination,
                                 ; deprecated

   Reply =/ "536" WSP Zero WSP RunId WSP RunState WSP ErrorMsg CRLF
                                 ; script error

   Reply =/ "537" WSP Zero WSP RunId WSP RunState WSP ErrorMsg CRLF
                                 ; script error that
                                 ; triggers an event report

   Reply =/ "538" WSP Zero WSP RunId WSP ExitCode CRLF
                                 ; script termination

---

6. Elements of Procedure ✨

This section breaks down the processing steps that the SNMP agent and the runtime system each take for the SMX protocol 🛠️

6.1. SMX Message Processing on the Runtime Systems 🖥️

This part covers how a runtime engine processes SMX command messages, and when it generates asynchronous notifications 🔔

When the runtime system gets a message, it first tries to pick out a command made of the command string and the transaction identifier. If it can't extract both, the message gets discarded. An asynchronous 511 reply may be generated in that case 🙃 Otherwise, the command string gets checked for validity, meaning it has to be one of hello, start, suspend, resume, abort, or status. If it isn't, a 402 reply gets sent and processing of that message stops 🛑 If a valid command is detected, the rest of the processing depends on the command, as described below 💖

The command-specific processing describes several possible syntax errors that get their own reply messages. If the runtime engine finds any syntax error that isn't explicitly mentioned, or that can't be identified uniquely, it sends a generic 401 reply saying the command can't be executed 🙈

6.1.1. Processing the hello Command 👋

When the runtime system receives a hello command, here's what happens:

1. The runtime system sends a 211 reply. If the runtime system has access to a shared secret, then the reply must contain the optional Authenticator, which is a function of the shared secret.

6.1.2. Processing the `start' Command 🚀

okay bestie, here's the vibe when the runtime system gets a `start' command 💅 It runs through these steps in order:

1. First it checks the syntax of the arguments to the `start' command. The following four checks must be made:
   • (a) It checks the syntax of the RunId' parameter and sends a 431' reply if there's any syntax error ❌
   • (b) It checks the syntax of the Script' parameter and sends a 421' reply if there's any syntax error 🙈
   • (c) It checks the syntax of the Profile' parameter and sends a 432' reply if there's any syntax error 🫠
   • (d) If syntax of the Argument' parameter is checked and a 433' reply is sent if any syntax error is detected.
2. It checks whether the new RunId' is already in use. If yes, a 431' reply is sent and processing stops 🛑
3. It 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 📂
4. It checks whether the security profile is known. If not, it sends a `432' reply and stops processing 🔐
5. The runtime engine starts the script given by the script name ✨ Once the script has started, a `231' reply is sent including the current run state.

Processing of the start' command stops once 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 also stops if an error occurs before the state running' is reached. In that case the run is aborted and a 538' reply is generated. An optional 536' reply can be send before the 538' reply to report an error message 🥲

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 gets a `suspend' command, it goes like this:

1. If there's a syntax error in the running script identifier, or there's no running script matching the identifier, a `431' reply is sent and processing of the command stops 🙅‍♀️
2. If the running script is already in the state suspended', a 231' reply is sent and processing stops 💜
3. If the running script is in the state running', it gets suspended and a 231' reply is sent after suspending. If suspending fails, a `434' reply is sent and processing stops 😭
4. If the running script hasn't reached the state running' yet (the start' command is still being processed), it may reach the state suspended' without ever having been in the state running'. After it reaches suspended', a 231' reply is sent 🌸
5. If the running script is in any other state, a `434' reply is sent.

---

6.1.4. Processing the `resume' Command ▶️

when the runtime system gets a `resume' command:

1. If there's a syntax error in the running script identifier, or there's no running script matching the identifier, a `431' reply is sent and processing stops 🙃
2. If the running script is already in the state running', a 231' reply is sent and processing stops 🦋
3. If the running script is in the state suspended', it gets resumed and a 231' reply is sent after resuming. If resuming fails, a `434' reply is sent and processing stops 🥀
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 gets an `abort' command:

1. If there's a syntax error in the running script identifier, or there's no running script matching the identifier, a `431' reply is sent and processing stops 🚫
2. If the running script is already aborted, a `232' reply is sent and processing stops 🫥
3. The running script gets 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 gets a `status' command:

1. If there's a syntax error in the running script identifier, or there's no running script matching the identifier, a `431' reply is sent and processing of the command stops 🙋‍♀️
2. The status of the script is obtained and a `231' reply is sent 📊

---

6.1.7. Generation of Asynchronous Notifications 🔔

the runtime system generates, or may generate, the following notifications (it's giving main character energy, ngl) 🌈

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. This reply is deprecated 🙅‍♀️ You can emulate this reply with a combination of a 532' reply and a `538' reply.
3. A 535' reply is sent if a running script terminates abnormally. This reply is deprecated too 😩 You can emulate this reply with a combination of a 536' reply and a `538' reply.
4. A `532' reply is sent if a script generates an intermediate result.
5. A 533' reply is sent if a script generates an intermediate result which causes the generation of a smScriptResult' notification ✨
6. A `536' reply is sent if a running script produces an error. If the error is fatal, the script execution gets terminated and a 538 reply follows. Otherwise, if the error is non-fatal, the script keeps executing 🫶
7. A 537' reply is sent if a running script produces an error which should cause the generation of a smScriptException' notification. If the error is fatal, the script execution gets terminated and a 538 reply follows. Otherwise, if the error is non-fatal, the script keeps executing 😳
8. A 538' reply is sent if a running script terminates. The ExitCode is used to tell apart normal termination (noError') from abnormal termination 🏁
9. Besides the notifications above, the runtime system may generate arbitrary `511' replies, which get logged or displayed by the SNMP agent 🍓

---

6.2. SMX Message Processing on the SNMP Agent 🧠

this section is about when an SNMP agent implementing the Script MIB generates SMX commands 💖 It also covers how the SNMP agent handles replies to those SMX commands.

6.2.1. Creating a Runtime System 🏗️

new runtime systems get started by the SNMP agent while it's processing set requests for a smLaunchStart' variable 🚀 First the SNMP agent looks for an already running runtime system that matches the security profiles associated with the smLaunchStart' variable. If no suitable runtime system is available, a new one gets started in either of these ways:

• (a) It starts the executable for the runtime system in a new process that conforms to the operating system security profile, and sets up a bi-directional pipe to the runtime system's standard input/output streams, to be used for SMX transport 🔌 or
• (b) It prepares the environment for the new runtime system and starts the executable for the runtime system in a new process that conforms to the operating system security profile. The SNMP agent gets ready to accept a connection from the new runtime system 🤝

The smRunState' of all scripts that should be executed in the new runtime system is set to initializing' 🌱

---

6.2.2. Generating the `hello' Command 👋

the hello' command gets generated once an SMX connection is established 💬 The SNMP agent sends the hello' command as defined in section 5.2. Then it waits for a reply from the runtime system within a reasonable timeout interval ⏳

1. If the timeout expires before the SNMP agent receives a reply, 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 doesn't have the required format, 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 to see whether it matches the Id' used in the hello' command. If the Id' matches, the Version' is checked. If the Version' matches a supported SMX protocol version, then, if present, the Authenticator' is checked. If any of the tests fails, or if the SNMP agent requires an authenticator and it didn't receive a matching Authenticator' with the 211' reply, 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 🗑️

That's the end of this part, bestie 🌈 Keep scrolling for the next chunk 💅✨

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 MUST send 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 MUST send an abort command to abort the running script and MUST set the RunState 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 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 MUST send an abort command to abort the running script and MUST set 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. 🌸

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 MUST send an abort command to abort the running script and MUST set 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 MUST set 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 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 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 terminated and smExitCode and smRunError are updated. 🙈
7. If the received message is a 536 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 smRunError are updated. 🍓
8. If the received message is a 537 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 smRunError are updated and the smScriptException notification is generated. 💅
9. If the received message is a 538 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 is set to terminated and the smExitCode is updated. 🫶

7. Example SMX Message Flow ✨

okay so this part is the example, and it's SO good for seeing how the messages bounce back and forth 💖 messages from the SNMP agent are marked with > and the replies from the runtime system are marked with <. the line terminators (CRLF) are left out so it's easier to read 🎀

   > hello 1
   < 211 1 SMX/1.1 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.1 0AF0BAED6F877FBC
   > suspend 581 42
   < 231 581 4
   < 532 0 44 7 "test completed"
   < 538 0 44 1
   > abort 611 42
   < 232 611

---

8. Transport Mappings 🦋

okay this part is about how the SNMP agent keeps SMX communication away from untrusted peers 🔒 the agent has to pick a secure SMX transport, and this memo defines two of them in Section 8: (a) a bi-directional pipe that uses standard input/output streams on the runtime engine side, and (b) a TCP connection where the agent acts as a listening server and only accepts connections from local runtime engines that prove themselves with a secret shared between the agent and the runtime engine 🫶

for simplicity and security reasons, the bi-directional pipe transport is the preferred one 💅

other transports (like UNIX domain sockets) are possible but aren't defined yet 🌸 pipes and TCP were picked because most potential runtime systems support those IPC mechanisms, while other transports aren't available everywhere 🧚

8.1. SMX over Bi-directional Pipes

the SNMP agent creates a bi-directional pipe first, and then it creates the runtime system process with its standard input and standard output streams hooked up to that pipe 🎀 no further authentication mechanisms are required here.

8.2. SMX over TCP

this is the one with a bit more drama 😭 the SNMP agent first creates a listening TCP socket that accepts connections from runtime systems, and then it creates the runtime system process. after the runtime system has been started, it's the runtime system's job to connect to the agent's TCP socket. the agent must make sure that only authorized runtime systems connect to that listening socket, and it uses these rules to do it:

• the TCP connection must originate from the local host.
• the agent must check the Authenticator in the 211 reply if authentication is required, and it must close the TCP connection if no valid response arrives within a given time interval.

---

9. Security Considerations 🔐

okay this section is SERIOUS but also iconic 👑 pay attention bestie

SMX as specified in this memo runs over a bi-directional pipe or over a local TCP connection between the agent and the runtime system. protocol messages never leave the local system, so attacking the message exchanges isn't possible as long as the operating system protects those pipes and local TCP connections from other users on the same machine 🛡️

for the pipe transport, the pipe gets created and hooked up to the runtime engine's standard input/output by the agent before the runtime engine starts. that means an unauthorized process can't exchange SMX messages over the pipe 🙅‍♀️

for TCP, the only critical moment is the connection establishment phase 😳 the rules in Section 8 make sure only local connections are accepted, and a runtime system has to authenticate itself with an authenticator if the agent requires authentication. it is strongly suggested that agents require authentication, especially on multiuser systems 🚨

the SMX 1.0 spec in RFC 2593 suggested passing the authenticator to the runtime engines as part of the process environment 💀 that scheme relies on the operating system protecting process environments from unauthorized access, but some operating systems let users read the process environment of arbitrary processes. so the RFC 2593 scheme is considered unsecure on those operating systems 🙈 this memo doesn't dictate how the runtime obtains the shared secret. it's up to implementers or administrators to pick a mechanism that's secure on their target platforms.

the SMX protocol assumes a local script storage area that passes script code from the SNMP agent to the runtime systems, and it passes file names from the agent to the runtime engines too. the script files in that storage area need to be properly protected so that only the SNMP agent has write access. if write access isn't protected properly, attackers could execute arbitrary code in runtime systems that might have special privileges 😱

finally, SMX lets scripts run under different operating system and runtime system security profiles. the memo suggests mapping the smLaunchOwner value to an operating system and a runtime system security profile. the OS profile gets enforced by the operating system when it sets up a proper process environment, and the runtime profile gets enforced by a secure runtime system (for example, the Java virtual machine or a safe Tcl interpreter) [7] 🌈

---

10. Changes from RFC 2593 🍓

these are the non-editorial changes from RFC 2593, so you can see what's new ✨

1. added the 536 and 537 replies, which runtime engines may generate asynchronously to report error conditions.
2. added the 538 reply, which can signal the (normal or abnormal) termination of a running script. this new reply replaces the 534 and 535 replies, which are now deprecated.
3. relaxed the rules for ProfileChars so they also include : and _, which show up a lot in namespaces and identifiers 🧚
4. changed the SMX protocol version number from 1.0 to 1.1.
5. added a second (and preferred) transport over a bi-directional pipe, because passing a shared secret through an operating system's environment variable carries security risks.
6. made the Authenticator in the 211 reply optional.

---

11. Acknowledgments 🫶

the protocol in this memo came out of a joint project between the Technical University of Braunschweig and C&C Research Laboratories of NEC Europe Ltd. in Heidelberg 🌸 the authors would like to thank Matthias Bolz, Cornelia Kappler, Andreas Kind, Sven Mertens, Jan Nicklisch, and Frank Strauss for their contributions to the design and implementation of the protocol. they also want to thank David Wallis for pointing out a security risk in SMX 1.0 with passing a cookie via an operating system environment variable 👑

---

12. References 📚

[1]  Levi, D. and J. Schoenwaelder, "Definitions of Managed Objects
     for the Delegation of Management Scripts", RFC 3165, September
     2001.

[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, November 1997.

[7]  Schoenwaelder, J., and J. Quittek, "Secure Internet Management
     by Delegation", Computer Networks 35(1), January 2001.

---

13. 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
Adenauerplatz 6
69115 Heidelberg
Germany

Phone: +49 6221 90511-15
EMail: quittek@ccrle.nec.de

---

14. Full Copyright Statement ⚖️

the legal bits, kept word for word so nothing gets lost 💅

Copyright (C) The Internet Society (2001).  All Rights Reserved.

This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works.  However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.

The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement 🌷

funding for the RFC Editor function is currently provided by the Internet Society ✨