File: rfc2593.txt

package info (click to toggle)
doc-rfc 20181229-2
  • links: PTS, VCS
  • area: non-free
  • in suites: buster
  • size: 570,944 kB
  • sloc: xml: 285,646; sh: 107; python: 90; perl: 42; makefile: 14
file content (1235 lines) | stat: -rw-r--r-- 49,625 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
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]