rfc3179.txt

RFC 的详细文档！

      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
   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.1.
   They are defined only for future SMX extensions.




Schoenwaelder & Quittek       Experimental                      [Page 7]

RFC 3179                    SMX Protocol 1.1                October 2001


   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 *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





Schoenwaelder & Quittek       Experimental                      [Page 8]

RFC 3179                    SMX Protocol 1.1                October 2001


      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 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
   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.






Schoenwaelder & Quittek       Experimental                      [Page 9]

RFC 3179                    SMX Protocol 1.1                October 2001


   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 explicitly
   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 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

   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.

   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.



Schoenwaelder & Quittek       Experimental                     [Page 10]

RFC 3179                    SMX Protocol 1.1                October 2001


      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 `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 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 3179                    SMX Protocol 1.1                October 2001


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 3179                    SMX Protocol 1.1                October 2001


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.
      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.  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 will be terminated and a