Note recent fixes
[freeradius.git] / doc / rfc / rfc1227.txt
1
2
3
4
5
6
7 Network Working Group                                            M. Rose
8 Request for Comments: 1227       Performance Systems International, Inc.
9                                                                 May 1991
10
11
12                        SNMP MUX Protocol and MIB
13
14 Status of this Memo
15
16    This memo suggests a mechanism by which a user process may associate
17    itself with the local SNMP agent on a host, in order to implement
18    portions of the MIB.  This mechanism would be local to the host.
19
20    This is an Experimental Protocol for the Internet community.
21    Discussion and suggestions for improvement are requested.  Please
22    refer to the current edition of the "IAB Official Protocol Standards"
23    for the standardization state and status of this protocol.
24    Distribution of this memo is unlimited.
25
26 Table of Contents
27
28    1. Introduction ..........................................    1
29    2. Architecture ..........................................    2
30    3. Protocol ..............................................    3
31    3.1 Tricky Things ........................................    3
32    3.1.1 Registration .......................................    4
33    3.1.2 Removing Registration ..............................    4
34    3.1.3 Atomic Sets ........................................    4
35    3.1.4 Variables in Requests ..............................    5
36    3.1.5 Request-ID .........................................    5
37    3.1.6 The powerful get-next operator .....................    5
38    3.2 Protocol Data Units ..................................    6
39    3.3 Mappings on Transport Service ........................    8
40    3.3.1 Mapping onto the TCP ...............................    8
41    4. MIB for the SMUX ......................................    9
42    5. Acknowledgements ......................................   12
43    6. References ............................................   12
44    7. Security Considerations................................   13
45    8. Author's Address.......................................   13
46
47 1.  Introduction
48
49    On typical kernel/user systems, an agent speaking the SNMP [1] is
50    often implemented as a user-process, that reads kernel variables in
51    order to realize the Internet-standard MIB [2].  This approach works
52    fine as long as all of the information needed by the SNMP agent
53    resides in either the kernel or in stable storage (i.e., files).
54    However, when other user-processes are employed to implement other
55
56
57
58 Rose                                                            [Page 1]
59 \f
60 RFC 1227                          SMUX                          May 1991
61
62
63    network services, such as routing protocols, communication between
64    the SNMP agent and other processes is problematic.
65
66    In order to solve this problem, a new protocol, the SNMP multiplexing
67    (SMUX) protocol is introduced.  When a user-process, termed a SMUX
68    peer, wishes to export a MIB module, it initiates a SMUX association
69    to the local SNMP agent, registers itself, and (later) fields
70    management operations for objects in the MIB module.
71
72    Carrying this approach to its fullest, it is possible to generalize
73    the SNMP agent so that it knows about only the SNMP group of the
74    Internet-standard MIB.  All other portions of the Internet-standard
75    MIB can be implemented by another process.  This is quite useful, for
76    example, when a computer manufacturer wishes to provide SNMP access
77    for its operating system in binary form.
78
79    In addition to defining the SMUX protocol, this document defines a
80    MIB for the SMUX.  Obviously, this MIB module must also be
81    implemented in the local SNMP agent.
82
83 2.  Architecture
84
85    There are two approaches that can be taken when trying to integrate
86    arbitrary MIB modules with the SNMP agent: request-response and
87    cache-ahead.
88
89    The request-response model simply propagates the SNMP requests
90    received by the SNMP agent to the user process which exported the MIB
91    module.  The SMUX peer then performs the operation and returns a
92    response.  In turn, the SNMP agent propagates this response back to
93    the network management station.  The request-response model is said
94    to be agent-driven since, after registration, the SNMP agent
95    initiates all transactions.
96
97    The cache-ahead model requires that the SMUX peer, after
98    registration, periodically updates the SNMP agent with the subtree
99    for the MIB module which has been registered.  The SNMP agent, upon
100    receiving an SNMP request for information retrieval, locally performs
101    the operation, and returns a response to the network management
102    station.  (SNMP set requests are given immediately to the SMUX peer.)
103    The cache-ahead model is said to be peer-driven since, after
104    registration, the SMUX peer initiates all transactions.
105
106    There are advantages and disadvantages to both approaches.  As such,
107    the architecture envisioned supports both models in the following
108    fashion: the protocol between the SNMP agent and the SMUX peer is
109    based on the request-response model.  However, the SMUX peer, may
110    itself be a user-process which employs the cache-ahead model with
111
112
113
114 Rose                                                            [Page 2]
115 \f
116 RFC 1227                          SMUX                          May 1991
117
118
119    other user-processes.
120
121    Obviously, the SMUX peer which employs the cache-ahead model acts as
122    a "firewall" for those user-processes which actually implement the
123    managed objects in the given MIB module.
124
125    Note that this document describes only the SMUX protocol, for the
126    request-response model.  Each SMUX peer is free to define a cache-
127    ahead protocol specific for the application at hand.
128
129 3.  Protocol
130
131    The SMUX protocol is simple: the SNMP agent listens for incoming
132    connections.  Upon establishing a connection, the SMUX peer issues an
133    OpenPDU to initialize the SMUX association.  If the SNMP agent
134    declines the association, it issues a closePDU and closes the
135    connection.  If the SNMP agent accepts the association, no response
136    is issued by the SNMP agent.
137
138    For each subtree defined in a MIB module that the SMUX peer wishes to
139    register (or unregister), the SMUX peer issues a RReqPDU.  When the
140    SNMP agent receives such a PDU, it issues a corresponding RRspPDU.
141    The SNMP agent returns RRspPDUs in the same order as the RReqPDUs
142    were received.
143
144    When the SMUX peer wishes to issue a trap, it issues an SNMP Trap-
145    PDU.  When the SNMP agent receives such a PDU, it propagates this to
146    the network management stations that it is configured to send traps
147    to.
148
149    When the SNMP agent receives an SNMP GetRequest-PDU, GetNextRequest-
150    PDU, or SetRequest-PDU which includes one or more variable-bindings
151    within a subtree registered by a SMUX peer, the SNMP agent sends an
152    equivalent SNMP PDU containing only those variables within the
153    subtree registered by that SMUX peer.  When the SMUX peer receives
154    such a PDU, it applies the indicated operation and issues a
155    corresponding SNMP GetResponse-PDU.  The SNMP agent then correlates
156    this result and propagates the resulting GetResponse-PDU to the
157    network management station.
158
159    When either the SNMP agent or the SMUX peer wishes to release the
160    SMUX association, the ClosePDU is issued, the connection is closed,
161    and all subtree registrations for that association are released.
162
163 3.1.  Tricky Things
164
165    Although straight-forward, there are a few nuances.
166
167
168
169
170 Rose                                                            [Page 3]
171 \f
172 RFC 1227                          SMUX                          May 1991
173
174
175 3.1.1.  Registration
176
177    Associated with each registration is an integer priority, from 0 to
178    (2^31)-1.  The lower the value, the higher the priority.
179
180    Multiple SMUX peers may register the same subtree.  However, they
181    must do so at different priorities (i.e., a subtree and a priority
182    uniquely identifies a SMUX peer).  As such, if a SMUX peer wishes to
183    register a subtree at a priority which is already taken, the SNMP
184    agent repeatedly increments the integer value until an unused
185    priority is found.
186
187    When registering a subtree, the special priority -1 may be used,
188    which selects the highest available priority.
189
190    Of course, the SNMP agent may select an arbitrarily worse priority
191    for a SMUX peer, based on local (configuration) information.
192
193    Note that when a subtree is registered, the SMUX peer with the
194    highest registration priority is exclusively consulted for all
195    operations on that subtree.  Further note that SNMP agents must
196    enforce the "subtree mounting effect", which hides the registrations
197    by other SMUX peers of objects within the subtree.  For example, if a
198    SMUX peer registered "sysDescr", and later another SMUX peer
199    registered "system" (which scopes "sysDescr"), then all requests for
200    "sysDescr" would be given to the latter SMUX peer.
201
202    An SNMP agent should disallow any attempt to register above, at, or
203    below, the SNMP and SMUX subtrees of the MIB.  Other subtrees may be
204    disallowed as an implementation-specific option.
205
206 3.1.2.  Removing Registration
207
208    A SMUX peer may remove registrations for only those subtrees which it
209    has registered.  If the priority given in the RReqPDU is -1, then the
210    registration of highest priority is selected for deletion.
211    Otherwise, only that registration with the precise priority is
212    selected.
213
214 3.1.3.  Atomic Sets
215
216    A simple two-phase commit protocol is used between the SNMP agent and
217    the SMUX peers.  When an SNMP SetRequest-PDU is received, the SNMP
218    agent determines which SMUX peers will participate in the
219    transaction.  For each of these peers, at least one SNMP SetRequest-
220    PDU is sent, with only those variables of interest to that peer.
221
222    Each SMUX peer must either accept or refuse the set operation,
223
224
225
226 Rose                                                            [Page 4]
227 \f
228 RFC 1227                          SMUX                          May 1991
229
230
231    without actually performing the operation.  If the peer opts to
232    accept, it sends back an SNMP GetResponse-PDU with an error-status of
233    noError(0); otherwise, if the peer refuses to perform the operation,
234    then an SNMP GetResponse-PDU is returned with a non-zero error-
235    status.
236
237    The SNMP agent examines all of the responses.  If at least one SMUX
238    peer refused the operation, then a SMUX SOutPDU is sent to each SMUX
239    peer, with value rollback, telling the SMUX peer to discard any
240    knowledge of the requested operation.
241
242    Otherwise if all SMUX peers accepted the operation, then a SMUX
243    SOutPDU is sent to each SMUX peer, with value commit, telling the
244    SMUX peer to perform the operation.
245
246    In either case, the SMUX peer does not generate a response to the
247    SMUX SOutPDU.
248
249 3.1.4.  Variables in Requests
250
251    When constructing an SNMP GetRequest-PDU or GetNextRequest-PDU for a
252    SMUX peer, the SNMP agent may send one, or more than one variable in
253    a single request.  In all cases, the SNMP agent should process each
254    variable sequentially, and block accordingly when a SMUX peer is
255    contacted.
256
257 3.1.5.  Request-ID
258
259    When the SNMP agent constructs an SNMP GetRequest-PDU,
260    GetNextRequest-PDU, or SetRequest-PDU, for a SMUX peer, the
261    request_id field of the SNMP takes a special meaning: if an SNMP
262    agent generates multiple PDUs for a SMUX peer, upon receipt of a
263    single PDU from the network management station, then the request_id
264    field of the PDUs sent to the SMUX peer must take the same value
265    (which need bear no relationship to the value of the request_id field
266    of the PDU originally received by the SNMP agent.)
267
268 3.1.6.  The powerful get-next operator
269
270    Each SMUX peer acts as though it contains the entire MIB when
271    processing a SNMP GetNext-PDU from the SNMP agent.  This means that
272    the SNMP agent must check each variable returned in the SNMP
273    GetResponse-PDU generated by the SMUX peer to ensure that each
274    variable is still within the same registered subtree as caused the
275    SNMP GetNext-PDU to be sent to that peer.  For each variable which is
276    not, the SNMP agent must include it in a SNMP GetNext-PDU to the peer
277    for the succeeding registered subtree, until responses are available
278    for all variables within their expected registered subtree.
279
280
281
282 Rose                                                            [Page 5]
283 \f
284 RFC 1227                          SMUX                          May 1991
285
286
287 3.2.  Protocol Data Units
288
289    The SMUX protocol data units are defined using Abstract Syntax
290    Notation One (ASN.1) [3]:
291
292    SMUX DEFINITIONS ::= BEGIN
293
294    IMPORTS
295            DisplayString, ObjectName
296                    FROM RFC1155-SMI
297
298            PDUs
299                    FROM RFC1157-SNMP;
300
301
302    -- tags for SMUX-specific PDUs are application-wide to
303    -- avoid conflict with tags for current (and future)
304    -- SNMP-generic PDUs
305
306    SMUX-PDUs ::=
307        CHOICE {
308            open            -- SMUX peer uses
309                OpenPDU,    -- immediately after TCP open
310
311            close           -- either uses immediately before TCP close
312                ClosePDU,
313
314            registerRequest -- SMUX peer uses
315                RReqPDU,
316
317            registerResponse -- SNMP agent uses
318                RRspPDU,
319
320                PDUs,       -- note that roles are reversed:
321                            --   SNMP agent does get/get-next/set
322                            --   SMUX peer does get-response/trap
323
324            commitOrRollback -- SNMP agent uses
325                SOutPDU
326       }
327
328
329    -- open PDU
330    -- currently only simple authentication
331
332    OpenPDU ::=
333        CHOICE {
334           simple
335
336
337
338 Rose                                                            [Page 6]
339 \f
340 RFC 1227                          SMUX                          May 1991
341
342
343               SimpleOpen
344        }
345
346    SimpleOpen ::=
347        [APPLICATION 0] IMPLICIT
348            SEQUENCE {
349                version     -- of SMUX protocol
350                    INTEGER {
351                        version-1(0)
352                    },
353
354                identity    -- of SMUX peer, authoritative
355                    OBJECT IDENTIFIER,
356
357                description -- of SMUX peer, implementation-specific
358                    DisplayString,
359
360                password    -- zero length indicates no authentication
361                    OCTET STRING
362            }
363
364
365    -- close PDU
366
367    ClosePDU ::=
368        [APPLICATION 1] IMPLICIT
369            INTEGER {
370                goingDown(0),
371                unsupportedVersion(1),
372                packetFormat(2),
373                protocolError(3),
374                internalError(4),
375                authenticationFailure(5)
376            }
377
378
379    -- insert PDU
380
381    RReqPDU ::=
382        [APPLICATION 2] IMPLICIT
383            SEQUENCE {
384                subtree
385                    ObjectName,
386
387                priority    -- the lower the better, "-1" means default
388                    INTEGER (-1..2147483647),
389
390                operation
391
392
393
394 Rose                                                            [Page 7]
395 \f
396 RFC 1227                          SMUX                          May 1991
397
398
399                    INTEGER {
400                        delete(0),    -- remove registration
401                        readOnly(1),  -- add registration, objects are RO
402                        readWrite(2)  --   .., objects are RW
403                    }
404            }
405
406    RRspPDU ::=
407        [APPLICATION 3] IMPLICIT
408            INTEGER {
409                failure(-1)
410
411               -- on success the non-negative priority is returned
412            }
413
414    SOutPDU ::=
415        [APPLICATION 4] IMPLICIT
416            INTEGER {
417                commit(0),
418                rollback(1)
419            }
420
421    END
422
423
424 3.3.  Mappings on Transport Service
425
426    The SMUX protocol may be mapped onto any CO-mode transport service.
427    At present, only one such mapping is defined.
428
429 3.3.1.  Mapping onto the TCP
430
431    When using the TCP to provide the transport-backing for the SMUX
432    protocol, the SNMP agent listens on TCP port 199.
433
434    Each SMUX PDU is serialized using the Basic Encoding Rules [4] and
435    sent on the TCP.  As ASN.1 objects are self-delimiting when encoding
436    using the BER, no packetization protocol is required.
437
438
439
440
441
442
443
444
445
446
447
448
449
450 Rose                                                            [Page 8]
451 \f
452 RFC 1227                          SMUX                          May 1991
453
454
455 4.  MIB for the SMUX
456
457    The MIB objects for the SMUX are implemented by the local SNMP agent:
458
459           SMUX-MIB DEFINITIONS ::= BEGIN
460
461           IMPORTS
462                   enterprises
463                           FROM RFC1155-SMI
464                   OBJECT-TYPE
465                           FROM RFC1212;
466
467           unix    OBJECT IDENTIFIER ::= { enterprises 4 }
468
469           smux    OBJECT IDENTIFIER ::= { unix 4 }
470
471           smuxPeerTable   OBJECT-TYPE
472                   SYNTAX  SEQUENCE OF SmuxPeerEntry
473                   ACCESS  not-accessible
474                   STATUS  mandatory
475                   DESCRIPTION
476                       "The SMUX peer table."
477                   ::= { smux 1 }
478
479           smuxPeerEntry   OBJECT-TYPE
480                   SYNTAX  SmuxPeerEntry
481                   ACCESS  not-accessible
482                   STATUS  mandatory
483                   DESCRIPTION
484                       "An entry in the SMUX peer table."
485                   INDEX   { smuxPindex }
486                   ::= { smuxPeerTable 1}
487
488           SmuxPeerEntry ::=
489               SEQUENCE {
490                   smuxPindex
491                       INTEGER,
492                   smuxPidentity
493                       OBJECT IDENTIFIER,
494                   smuxPdescription
495                       DisplayString,
496                   smuxPstatus
497                       INTEGER
498               }
499
500           smuxPindex      OBJECT-TYPE
501                   SYNTAX  INTEGER
502                   ACCESS  read-only
503
504
505
506 Rose                                                            [Page 9]
507 \f
508 RFC 1227                          SMUX                          May 1991
509
510
511                   STATUS  mandatory
512                   DESCRIPTION
513                       "An index which uniquely identifies a SMUX peer."
514                   ::= { smuxPeerEntry 1 }
515
516           smuxPidentity   OBJECT-TYPE
517                   SYNTAX  OBJECT IDENTIFIER
518                   ACCESS  read-only
519                   STATUS  mandatory
520                   DESCRIPTION
521                       "The authoritative designation for a SMUX peer."
522                   ::= { smuxPeerEntry 2 }
523
524           smuxPdescription OBJECT-TYPE
525                   SYNTAX  DisplayString (SIZE (0..255))
526                   ACCESS  read-only
527                   STATUS  mandatory
528                   DESCRIPTION
529                       "A human-readable description of a SMUX peer."
530                   ::= { smuxPeerEntry 3 }
531
532           smuxPstatus     OBJECT-TYPE
533                   SYNTAX  INTEGER { valid(1), invalid(2), connecting(3) }
534                   ACCESS  read-write
535                   STATUS  mandatory
536                   DESCRIPTION
537                       "The type of SMUX peer.
538
539                       Setting this object to the value invalid(2) has
540                       the effect of invaliding the corresponding entry
541                       in the smuxPeerTable.  It is an implementation-
542                       specific matter as to whether the agent removes an
543                       invalidated entry from the table.  Accordingly,
544                       management stations must be prepared to receive
545                       tabular information from agents that correspond to
546                       entries not currently in use.  Proper
547                       interpretation of such entries requires
548                       examination of the relative smuxPstatus object."
549                   ::= { smuxPeerEntry 4 }
550
551           smuxTreeTable   OBJECT-TYPE
552                   SYNTAX  SEQUENCE OF SmuxTreeEntry
553                   ACCESS  not-accessible
554                   STATUS  mandatory
555                   DESCRIPTION
556                       "The SMUX tree table."
557                   ::= { smux 2 }
558
559
560
561
562 Rose                                                           [Page 10]
563 \f
564 RFC 1227                          SMUX                          May 1991
565
566
567           smuxTreeEntry   OBJECT-TYPE
568                   SYNTAX  SmuxTreeEntry
569                   ACCESS  not-accessible
570                   STATUS  mandatory
571                   DESCRIPTION
572                       "An entry in the SMUX tree table."
573                   INDEX   { smuxTsubtree, smuxTpriority }
574                   ::= { smuxTreeTable 1}
575
576           SmuxTreeEntry ::=
577               SEQUENCE {
578                   smuxTsubtree
579                       OBJECT IDENTIFIER,
580                   smuxTpriority
581                       INTEGER,
582                   smuxTindex
583                       INTEGER,
584                   smuxTstatus
585                       INTEGER
586               }
587
588           smuxTsubtree    OBJECT-TYPE
589                   SYNTAX  OBJECT IDENTIFIER
590                   ACCESS  read-only
591                   STATUS  mandatory
592                   DESCRIPTION
593                       "The MIB subtree being exported by a SMUX peer."
594                   ::= { smuxTreeEntry 1 }
595
596           smuxTpriority OBJECT-TYPE
597                   SYNTAX  INTEGER (0..'07fffffff'h)
598                   ACCESS  read-only
599                   STATUS  mandatory
600                   DESCRIPTION
601                       "The SMUX peer's priority when exporting the MIB
602                       subtree."
603                   ::= { smuxTreeEntry 2 }
604
605           smuxTindex OBJECT-TYPE
606                   SYNTAX  INTEGER
607                   ACCESS  read-only
608                   STATUS  mandatory
609                   DESCRIPTION
610                       "The SMUX peer's identity."
611                   ::= { smuxTreeEntry 3 }
612
613           smuxTstatus     OBJECT-TYPE
614                   SYNTAX  INTEGER { valid(1), invalid(2) }
615
616
617
618 Rose                                                           [Page 11]
619 \f
620 RFC 1227                          SMUX                          May 1991
621
622
623                   ACCESS  read-write
624                   STATUS  mandatory
625                   DESCRIPTION
626                       "The type of SMUX tree.
627
628                       Setting this object to the value invalid(2) has
629                       the effect of invaliding the corresponding entry
630                       in the smuxTreeTable.  It is an implementation-
631                       specific matter as to whether the agent removes an
632                       invalidated entry from the table.  Accordingly,
633                       management stations must be prepared to receive
634                       tabular information from agents that correspond to
635                       entries not currently in use.  Proper
636                       interpretation of such entries requires
637                       examination of the relative smuxTstatus object."
638                   ::= { smuxTreeEntry 4 }
639
640           END
641
642 5.  Acknowledgements
643
644    SMUX was designed one afternoon by these people:
645
646                Jeffrey S. Case, UTK-CS
647                James R. Davin, MIT-LCS
648                Mark S. Fedor, PSI
649                Jeffrey C. Honig, Cornell
650                Louie A. Mamakos, UMD
651                Michael G. Petry, UMD
652                Yakov Rekhter, IBM
653                Marshall T. Rose, PSI
654
655 6.  References
656
657    [1] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
658        Network Management Protocol", RFC 1157, SNMP Research,
659        Performance Systems International, Performance Systems
660        International, MIT Laboratory for Computer Science, May 1990.
661
662    [2] McCloghrie K., and M. Rose, "Management Information Base for
663        Network Management of TCP/IP-based Internets", RFC 1156,
664        Performance Systems International and Hughes LAN Systems, May
665        1990.
666
667    [3] Information processing systems - Open Systems Interconnection -
668        Specification of Abstract Syntax Notation One (ASN.1),
669        International Organization for Standardization, International
670        Standard 8824, December 1987.
671
672
673
674 Rose                                                           [Page 12]
675 \f
676 RFC 1227                          SMUX                          May 1991
677
678
679    [4] Information processing systems - Open Systems Interconnection -
680        Specification of Basic Encoding Rules for Abstract Notation One
681        (ASN.1), International Organization for Standardization,
682        International Standard 8825, December 1987.
683
684    [5] Rose, M., and K. McCloghrie, "Structure and Identification of
685        Management Information for TCP/IP-based Internets", RFC 1155,
686        Performance Systems International and Hughes LAN Systems, May
687        1990.
688
689 7. Security Considerations
690
691    Security issues are not discussed in this memo.
692
693 8. Author's Address
694
695    Marshall T. Rose
696    Performance Systems International, Inc.
697    5201 Great America Parkway
698    Suite 3106
699    Santa Clara, CA  95054
700
701    Phone: +1 408 562 6222
702
703    EMail: mrose@psi.com
704    X.500:  rose, psi, us
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 Rose                                                           [Page 13]
731 \f