doc: Add RFC documents

1 files changed, 675 insertions, 0 deletions

diff --git a/doc/rfc/rfc1303.txt b/doc/rfc/rfc1303.txt
new file mode 100644
index 0000000..02402c9
--- /dev/null
+++ b/doc/rfc/rfc1303.txt
@@ -0,0 +1,675 @@
+
+
+
+
+
+
+Network Working Group                                      K. McCloghrie
+Request For Comments: 1303                            Hughes LAN Systems
+                                                                 M. Rose
+                                                  Dover Beach Consulting
+                                                           February 1992
+
+
+             A Convention for Describing SNMP-based Agents
+
+Status of This Memo
+
+   This memo provides information for the Internet community.  It does
+   not specify an Internet standard.  Distribution of this memo is
+   unlimited.
+
+Abstract
+
+   This memo suggests a straight-forward approach towards describing
+   SNMP-based agents.
+
+Table of Contents
+
+   1. The Network Management Framework ............................    2
+   2. Objects .....................................................    2
+   3. Describing Agents ...........................................    3
+   3.1 Definitions ................................................    4
+   3.2 Mapping of the MODULE-CONFORMANCE macro ....................    5
+   3.2.1 Mapping of the LAST-UPDATED clause .......................    6
+   3.2.2 Mapping of the PRODUCT-RELEASE clause ....................    6
+   3.2.3 Mapping of the DESCRIPTION clause ........................    6
+   3.2.4 Mapping of the SUPPORTS clause ...........................    6
+   3.2.4.1 Mapping of the INCLUDES clause .........................    6
+   3.2.4.2 Mapping of the VARIATION clause ........................    6
+   3.2.4.2.1 Mapping of the SYNTAX clause .........................    6
+   3.2.4.2.2 Mapping of the WRITE-SYNTAX clause ...................    7
+   3.2.4.2.3 Mapping of the ACCESS clause .........................    7
+   3.2.4.2.4 Mapping of the CREATION-REQUIRES clause ..............    7
+   3.2.4.2.5 Mapping of the DEFVAL clause .........................    7
+   3.2.4.2.6 Mapping of the DESCRIPTION clause ....................    7
+   3.3 Refined Syntax .............................................    7
+   3.4 Usage Example ..............................................    8
+   4. Acknowledgements ............................................   11
+   5. References ..................................................   11
+   6. Security Considerations......................................   12
+   7. Authors' Addresses...........................................   12
+
+
+
+
+
+
+McCloghrie & Rose                                               [Page 1]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+1.  The Network Management Framework
+
+   The Internet-standard Network Management Framework consists of
+   three components.  They are:
+
+   RFC 1155 [1] which defines the SMI, the mechanisms used for
+   describing and naming objects for the purpose of management.
+   RFC 1212 [2] defines a more concise description mechanism,
+   which is wholly consistent with the SMI.
+
+   RFC 1213 [3] which defines MIB-II, the core set of managed
+   objects for the Internet suite of protocols.
+
+   RFC 1157 [4] which defines the SNMP, the protocol used for
+   network access to managed objects.
+
+   The Framework permits new objects to be defined for the
+   purpose of experimentation and evaluation.
+
+2.  Objects
+
+   Managed objects are accessed via a virtual information store,
+   termed the Management Information Base or MIB.  Within a given
+   MIB module, objects are defined using RFC 1212's OBJECT-TYPE
+   macro.  At a minimum, each object has a name, a syntax, an
+   access-level, and an implementation-status.
+
+   The name is an object identifier, an administratively assigned
+   name, which specifies an object type.  The object type
+   together with an object instance serves to uniquely identify a
+   specific instantiation of the object.  For human convenience,
+   we often use a textual string, termed the OBJECT DESCRIPTOR,
+   to also refer to the object type.
+
+   The syntax of an object type defines the abstract data
+   structure corresponding to that object type.  The ASN.1[5]
+   language is used for this purpose.  However, RFC 1155
+   purposely restricts the ASN.1 constructs which may be used.
+   These restrictions are explicitly made for simplicity.
+
+   The access-level of an object type defines whether it makes
+   "protocol sense" to read and/or write the value of an instance
+   of the object type.  (This access-level is independent of any
+   administrative authorization policy.)
+
+   The implementation-status of an object type indicates whether
+   the object is mandatory, optional, obsolete, or deprecated.
+
+
+
+
+McCloghrie & Rose                                               [Page 2]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+3.  Describing Agents
+
+   When a MIB module is written, it is divided into units of
+   conformance termed groups.  If an agent claims conformance to
+   a group, then it must implement each and every object within
+   that group.  Of course, for whatever reason, an agent may
+   implement only a subset of the groups within a MIB module.  In
+   addition, the definition of some MIB objects leave some
+   aspects of the definition to the discretion of an implementor.
+
+   Practical experience has demonstrated a need for concisely
+   describing the capabilities of an agent with regards to the
+   MIB groups that it implements.  This memo defines a new macro,
+   MODULE-CONFORMANCE, which allows an agent implementor to
+   describe the precise level of support which an agent claims in
+   regards to a MIB group, and to bind that description to the
+   sysObjectID associated with the agent.  In particular, some
+   objects may have restricted or augmented syntax or access-
+   levels.
+
+   If the MODULE-CONFORMANCE invocation is given to a
+   management-station implementor, then that implementor can
+   build management applications which optimize themselves when
+   communicating with a particular agent.  For example, the
+   management-station can maintain a database of these
+   invocations.  When a management-station interacts with an
+   agent, it retrieves the agent's sysObjectID.  Based on this,
+   it consults the database.  If an entry is found, then the
+   management application can optimize its behavior accordingly.
+
+   This binding to sysObjectId may not always suffice to define
+   all MIB objects to which an agent can provide access. In
+   particular, this situation occurs where the agent dynamically
+   learns of the objects it supports, for example, an agent
+   supporting SMUX peers via the SMUX protocol [6]. In these
+   situations, additional MIB objects beyond sysObjectID must be
+   used to name other invocations of the MODULE-CONFORMANCE macro
+   to augment the description of MIB support provided by the
+   agent. For example, if an agent's sysObjectID indicates that
+   it supports the SMUX MIB, then each instance of smuxPidentity
+   will indicate another MODULE-CONFORMANCE invocation which is
+   dynamically being supported by the agent.
+
+
+
+
+
+
+
+
+
+McCloghrie & Rose                                               [Page 3]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+3.1.  Definitions
+
+   RFC-1303 DEFINITIONS ::= BEGIN
+
+       IMPORTS
+           ObjectName, ObjectSyntax
+               FROM RFC1155-SMI
+           DisplayString
+               FROM RFC1213-MIB;
+
+       MODULE-CONFORMANCE MACRO ::=
+       BEGIN
+           TYPE NOTATION ::=
+                             "LAST-UPDATED"
+                                 value(update      UTCTime)
+                             "PRODUCT-RELEASE"
+                                 value(release     DisplayString)
+                             "DESCRIPTION"
+                                 value(description DisplayString)
+                             ModulePart
+
+           VALUE NOTATION ::=      -- agent's sysObjectID --
+                             value(VALUE ObjectName)
+
+           ModulePart ::=    Modules
+                           | empty
+
+           Modules ::=       Module
+                           | Modules Module
+
+           Module ::=                   -- name of module --
+                             "SUPPORTS" ModuleName
+                             "INCLUDES" "{" Groups "}"
+                             VariationPart
+
+           ModuleName ::=    identifier ModuleIdentifier
+
+           ModuleIdentifier ::=
+                             value (moduleID OBJECT IDENTIFIER)
+                           | empty
+
+           Groups ::=        Group
+                           | Groups "," Group
+
+           Group ::=         value(group OBJECT IDENTIFIER)
+
+           VariationPart ::= Variations
+                           | empty
+
+
+
+McCloghrie & Rose                                               [Page 4]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+           Variations ::=    Variation
+                           | Variations Variation
+
+           Variation ::=     "VARIATION" value(object ObjectName)
+                             Syntax WriteSyntax Access
+                             Creation DefaultValue
+                             "DESCRIPTION"
+                                 value(limitext DisplayString)
+
+           -- must be a refinement for object's SYNTAX
+           Syntax ::=        "SYNTAX" type(SYNTAX)
+                           | empty
+
+           -- must be a refinement for object's SYNTAX
+           WriteSyntax ::=   "WRITE-SYNTAX" type(WriteSYNTAX)
+                           | empty
+
+           Access ::=        "ACCESS" AccessValue
+                           | empty
+
+           AccessValue ::=   "read-only"
+                           | "read-write"
+                           | "write-only"
+                           | "not-accessible"
+
+           Creation ::=      "CREATION-REQUIRES" "{" Cells "}"
+
+           Cells ::=         Cell
+                           | Cells "," Cell
+
+           Cell ::=          value(cell ObjectName)
+
+           DefaultValue ::=  "DEFVAL"
+                             "{" value (defval ObjectSyntax) "}"
+                           | empty
+
+       END
+
+   END
+
+3.2.  Mapping of the MODULE-CONFORMANCE macro
+
+   It should be noted that the expansion of the MODULE-CONFORMANCE macro
+   is something which conceptually happens during implementation and not
+   during run-time.
+
+
+
+
+
+
+McCloghrie & Rose                                               [Page 5]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+3.2.1.  Mapping of the LAST-UPDATED clause
+
+   The LAST-UPDATED clause, which must be present, contains the date and
+   time that this definition was last edited.
+
+3.2.2.  Mapping of the PRODUCT-RELEASE clause
+
+   The PRODUCT-RELEASE clause, which must be present, contains a textual
+   description of the product release which includes this agent.
+
+3.2.3.  Mapping of the DESCRIPTION clause
+
+   The DESCRIPTION clause, which must be present, contains a textual
+   description of this agent.
+
+3.2.4.  Mapping of the SUPPORTS clause
+
+   The SUPPORTS clause, which need not be present, is repeatedly used to
+   name each MIB module for which the agent claims a complete or partial
+   implementation.  Each MIB module is named by its module name, and
+   optionally, by its associated OBJECT IDENTIFIER as well.  (Note that
+   only a few MIB modules have had OBJECT IDENTIFIERs assigned to them.)
+
+3.2.4.1.  Mapping of the INCLUDES clause
+
+   The INCLUDES clause, which must be present for each use of the
+   SUPPORTS clause, is used to name each MIB group associated with the
+   SUPPORT clause, which the agent claims to implement.
+
+3.2.4.2.  Mapping of the VARIATION clause
+
+   The VARIATION clause, which need not be present, is repeatedly used
+   to name each MIB object which the agent implements in some variant or
+   refined fashion.
+
+3.2.4.2.1.  Mapping of the SYNTAX clause
+
+   The SYNTAX clause, which need not be present, is used to provide a
+   refined SYNTAX for the object named in the correspondent VARIATION
+   clause.  Note that if this clause and a WRITE-SYNTAX clause are both
+   present, then this clause only applies when instances of the object
+   named in the correspondent VARIATION clause are read.
+
+   Consult Section 3.3 for more information on refined syntax.
+
+
+
+
+
+
+
+McCloghrie & Rose                                               [Page 6]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+3.2.4.2.2.  Mapping of the WRITE-SYNTAX clause
+
+   The WRITE-SYNTAX clause, which need not be present, is used to
+   provide a refined SYNTAX for the object named in the correspondent
+   VARIATION clause when instances of that object are written.
+
+   Consult Section 3.3 for more information on refined syntax.
+
+3.2.4.2.3.  Mapping of the ACCESS clause
+
+   The ACCESS clause, which need not be present, is used to provide a
+   refined ACCESS for the object named in the correspondent VARIATION
+   clause.
+
+3.2.4.2.4.  Mapping of the CREATION-REQUIRES clause
+
+   The CREATION-REQUIRES clause, which need not be present, is used to
+   name the columnar objects of a conceptual row to which values must be
+   explicitly assigned, by a SNMP Set operation, before the agent will
+   create new instances of objects in that row.  This clause must not be
+   present unless the object named in the correspondent VARIATION clause
+   is a conceptual row, i.e., has a syntax which resolves to a SEQUENCE
+   containing columnar objects.  The objects named in the value of this
+   clause usually will refer to columnar objects in that row.  However,
+   objects unrelated to the conceptual row may also be specified.
+
+   The absence of this clause for a particular conceptual row indicates
+   that the agent does not support the creation, via SNMP operations, of
+   new object instances in that row.
+
+3.2.4.2.5.  Mapping of the DEFVAL clause
+
+   The DEFVAL clause, which need not be present, is used to provide a
+   refined DEFVAL value for the object named in the correspondent
+   VARIATION clause.  The semantics of this value are identical to those
+   of the OBJECT-TYPE macro's DEFVAL clause [2].
+
+3.2.4.2.6.  Mapping of the DESCRIPTION clause
+
+   The DESCRIPTION clause, which must be present for each use of the
+   VARIATION clause, contains a textual description of the variant or
+   refined implementation.
+
+3.3.  Refined Syntax
+
+   The SYNTAX and WRITE-SYNTAX clauses allow an object's Syntax to be
+   refined.  However, not all refinements of syntax are appropriate.  In
+   particular,
+
+
+
+McCloghrie & Rose                                               [Page 7]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+   (1)  the object's primitive or application type (as defined in
+        the SMI [1]) must not be changed;
+
+   (2)  an object defined with an SMI type of OBJECT IDENTIFIER,
+        IpAddress, Counter, or TimeTicks cannot be refined; and,
+
+   (3)  an object defined to have a specific set of values (e.g.,
+        an INTEGER with named values) cannot have additional
+        values defined for it.
+
+3.4.  Usage Example
+
+   Consider how one might document the 4BSD/ISODE "Secure" SNMP
+   agent:
+
+   FourBSD-ISODE   DEFINITIONS ::= BEGIN
+
+   IMPORTS
+       MODULE-CONFORMANCE
+           FROM RFC-1303
+       -- everything --
+           FROM RFCxxxx-MIB
+       -- everything --
+           FROM RFC1213-MIB
+       -- everything --
+           FROM UNIX-MIB
+       -- everything --
+           FROM EVAL-MIB;
+
+   fourBSD-isode-support MODULE-CONFORMANCE
+       LAST-UPDATED        "9201252354Z"
+       PRODUCT-RELEASE     "ISODE 7.0 + 'Secure' SNMP
+                            upgrade for SunOS 4.1"
+       DESCRIPTION         "4BSD/ISODE 'Secure' SNMP"
+
+       SUPPORTS            RFCxxxx-MIB -- SNMP Party MIB --
+           INCLUDES        { partyPublic, partyPrivate }
+
+       SUPPORTS            RFC1213-MIB
+           INCLUDES        { system, interfaces, at, ip, icmp,
+                             tcp, udp, snmp }
+
+           VARIATION       atEntry
+               CREATION-REQUIRES { atPhysAddress }
+               DESCRIPTION "Address mappings on 4BSD require
+                            both protocol and media addresses"
+
+           VARIATION       ifAdminStatus
+
+
+
+McCloghrie & Rose                                               [Page 8]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+               SYNTAX      INTEGER { up(1), down(2) }
+               DESCRIPTION "Unable to set test mode on 4BSD"
+
+           VARIATION       ifOperStatus
+               SYNTAX      INTEGER { up(1), down(2) }
+               DESCRIPTION "Information limited on 4BSD"
+
+           VARIATION       ipDefaultTTL
+               SYNTAX      INTEGER { maxttl(255) }
+               DESCRIPTION "Hard-wired on 4BSD"
+
+           VARIATION       ipInAddrErrors
+               ACCESS      not-accessible
+               DESCRIPTION "Information not available on 4BSD"
+
+           VARIATION       ipInDiscards
+               ACCESS      not-accessible
+               DESCRIPTION "Information not available on 4BSD"
+
+           VARIATION       ipRouteEntry
+               CREATION-REQUIRES { ipRouteNextHop }
+               DESCRIPTION "Routes on 4BSD require both
+                            destination and next-hop"
+
+           VARIATION       ipRouteType
+               SYNTAX       INTEGER { direct(3), indirect(4) }
+               WRITE-SYNTAX INTEGER { invalid(2), direct(3),
+                                      indirect(4) }
+               DESCRIPTION "Information limited on 4BSD"
+
+           VARIATION       ipRouteProto
+               SYNTAX      INTEGER { other(1), icmp (4) }
+               DESCRIPTION "Information limited on 4BSD"
+
+           VARIATION       ipRouteAge
+               ACCESS      not-accessible
+               DESCRIPTION "Information not available on 4BSD"
+
+           VARIATION       ipNetToMediaEntry
+               CREATION-REQUIRES { ipNetToMediaPhysAddress }
+               DESCRIPTION "Address mappings on 4BSD require
+                            both protocol and media addresses"
+
+           VARIATION       ipNetToMediaType
+               SYNTAX       INTEGER { dynamic(3), static(4) }
+               WRITE-SYNTAX INTEGER { invalid(2), dynamic(3),
+                                      static(4) }
+               DESCRIPTION "Information limited on 4BSD"
+
+
+
+McCloghrie & Rose                                               [Page 9]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+           VARIATION       tcpConnState
+               ACCESS      read-only
+               DESCRIPTION "Unable to set this on 4BSD"
+
+           VARIATION       tcpInErrs
+               ACCESS      not-accessible
+               DESCRIPTION "Information not available on 4BSD"
+
+           VARIATION       tcpOutRsts
+               ACCESS      not-accessible
+               DESCRIPTION "Information not available on 4BSD"
+
+       SUPPORTS            UNIX-MIB
+           INCLUDES        { agents, mbuf, netstat }
+
+       SUPPORTS            EVAL-MIB
+           INCLUDES        { functions, expressions }
+
+       ::= { fourBSD-isode 6 6 }
+
+   END
+
+   According to this invocation, an agent with a sysObjectID of
+
+        { fourBSD-isode 6 6 }
+
+   supports four MIB modules.
+
+   From the SNMP Party MIB, all the objects contained in the partyPublic
+   and partyPrivate groups are supported, without variation.
+
+   From MIB-II, all groups except the egp group are supported.  However,
+   the objects
+
+        ipInAddrErrors
+        ipInDiscards
+        ipRouteAge
+        tcpInErrs
+        tcpOutRsts
+
+   are not available, whilst the objects
+
+        ifAdminStatus
+        ifOperStatus
+        ipDefaultTTL
+        ipRouteType
+        ipRouteProto
+        ipNetToMediaType
+
+
+
+McCloghrie & Rose                                              [Page 10]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+   have a restricted syntax, and the object
+
+        tcpConnState
+
+   is available only for reading.  Note that in the case of the objects
+
+        ipRouteType
+        ipNetToMediaType
+
+   the set of values which may be read is different than the set of
+   values which may be written.  Finally, when creating a new row in the
+   atTable, the set-request must create an instance of atPhysAddress.
+   Similarly, when creating a new row in the ipRouteTable, the set-
+   request must create an instance of ipRouteNextHop.  Similarly, when
+   creating a new row in the ipNetToMediaTable, the set-request must
+   create an instance of ipNetToMediaPhysAddress.
+
+   From the UNIX-MIB, all the objects contained in the agents, mbuf, and
+   netstat groups are supported, without variation.
+
+   From the EVAL-MIB, all the objects contained in the functions and
+   expressions groups are supported, without variation.
+
+4.  Acknowledgements
+
+   The authors gratefully acknowledge the comments of Mark van der Pol
+   of Hughes LAN Systems, and David T. Perkins of SynOptics
+   Communications.
+
+5.  References
+
+   [1]  Rose M., and K. McCloghrie, "Structure and Identification of
+        Management Information for TCP/IP-based internets", RFC 1155,
+        Performance Systems International, Hughes LAN Systems, May 1990.
+
+   [2]  Rose, M., and K. McCloghrie, Editors, "Concise MIB Definitions",
+        RFC 1212, Performance Systems International, Hughes LAN Systems,
+        March 1991.
+
+   [3]  McCloghrie K., and M. Rose, Editors, "Management Information
+        Base forNetwork Management of TCP/IP-based internets", RFC 1213,
+        Performance Systems International, March 1991.
+
+   [4]  Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
+        Network Management Protocol (SNMP), RFC 1157, SNMP Research,
+        Performance Systems International, Performance Systems
+        International, MIT Laboratory for Computer Science, May 1990.
+
+
+
+
+McCloghrie & Rose                                              [Page 11]
+
+RFC 1303         Convention for Describing SNMP Agents     February 1992
+
+
+   [5]  Information processing systems - Open Systems Interconnection -
+        Specification of Abstract Syntax Notation One (ASN.1),
+        International Organization for Standardization, International
+        Standard 8824, December 1987.
+
+   [6]  Rose, M., "SNMP MUX Protocol and MIB", RFC 1227, Performance
+        Systems International, May 1991.
+
+6.  Security Considerations
+
+   Security issues are not discussed in this memo.
+
+7.  Authors' Addresses
+
+   Keith McCloghrie
+   Hughes LAN Systems
+   1225 Charleston Road
+   Mountain View, CA 94043
+
+   Phone: (415) 966-7934
+   EMail: kzm@hls.com
+
+
+   Marshall T. Rose
+   Dover Beach Consulting, Inc.
+   420 Whisman Court
+   Mountain View, CA  94043-2112
+
+   Phone: (415) 968-1052
+   EMail: mrose@dbc.mtview.ca.us
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+McCloghrie & Rose                                              [Page 12]
+
\ No newline at end of file