RFC 7407
A YANG Data Model for SNMP Configuration
Internet Engineering Task Force (IETF) M. Bjorklund Request for Comments: 7407 Tail-f Systems Category: Standards Track J. Schoenwaelder ISSN: 2070-1721 Jacobs University December 2014 A YANG Data Model for SNMP ConfigurationAbstract
This document defines a collection of YANG definitions for configuring SNMP engines. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7407. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................3 2. Data Model ......................................................3 2.1. Tree Diagrams ..............................................4 2.2. General Considerations .....................................4 2.3. Common Definitions .........................................4 2.4. Engine Configuration .......................................5 2.5. Target Configuration .......................................6 2.6. Notification Configuration .................................7 2.7. Proxy Configuration ........................................8 2.8. Community Configuration ....................................8 2.9. View-Based Access Control Model Configuration ..............9 2.10. User-Based Security Model Configuration ..................10 2.11. Transport Security Model Configuration ...................11 2.12. Transport Layer Security Transport Model Configuration ...12 2.13. Secure Shell Transport Model Configuration ...............13 3. Implementation Guidelines ......................................14 3.1. Supporting read-only SNMP Access ..........................15 3.2. Supporting read-write SNMP Access .........................15 4. Definitions ....................................................16 4.1. Module 'ietf-x509-cert-to-name' ...........................16 4.2. Module 'ietf-snmp' ........................................22 4.3. Submodule 'ietf-snmp-common' ..............................24 4.4. Submodule 'ietf-snmp-engine' ..............................28 4.5. Submodule 'ietf-snmp-target' ..............................32 4.6. Submodule 'ietf-snmp-notification' ........................36 4.7. Submodule 'ietf-snmp-proxy' ...............................41 4.8. Submodule 'ietf-snmp-community' ...........................44 4.9. Submodule 'ietf-snmp-vacm' ................................49 4.10. Submodule 'ietf-snmp-usm' ................................55 4.11. Submodule 'ietf-snmp-tsm' ................................60 4.12. Submodule 'ietf-snmp-tls' ................................63 4.13. Submodule 'ietf-snmp-ssh' ................................68 5. IANA Considerations ............................................71 6. Security Considerations ........................................72 7. References .....................................................75 7.1. Normative References ......................................75 7.2. Informative References ....................................75 Appendix A. Example Configurations ...............................78 A.1. Engine Configuration Example ..............................78 A.2. Community Configuration Example ...........................78 A.3. User-Based Security Model Configuration Example ...........79 A.4. Target and Notification Configuration Example .............81 A.5. Proxy Configuration Example ...............................82
A.6. View-Based Access Control Model Configuration Example .....85
A.7. Transport Layer Security Transport Model Configuration
Example ...................................................87
Acknowledgments ...................................................88
Authors' Addresses ................................................88
1. Introduction
This document defines a YANG [RFC6020] data model for the
configuration of SNMP engines. The configuration model is consistent
with the MIB modules defined in [RFC3411], [RFC3412], [RFC3413],
[RFC3414], [RFC3415], [RFC3417], [RFC3418], [RFC3419], [RFC3584],
[RFC3826], [RFC5591], [RFC5592], and [RFC6353] but takes advantage of
YANG's ability to define hierarchical configuration data models.
The configuration data model in particular has been designed for SNMP
deployments where SNMP runs in read-only mode and the Network
Configuration Protocol (NETCONF) is used to configure the SNMP agent.
Nevertheless, the data model allows implementations that support
write access both via SNMP and NETCONF in order to interwork with
SNMP management applications manipulating SNMP agent configuration
using SNMP. Further details can be found in Section 3.
The YANG data model focuses on configuration. Operational state
objects are not explicitly modeled. The operational state of an SNMP
agent can be accessed either directly via SNMP or, alternatively, via
NETCONF using the read-only translation of the relevant SNMP MIB
modules into YANG modules [RFC6643].
This document also defines a YANG data model for mapping an X.509
certificate to a name.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119].
2. Data Model
In order to preserve the modularity of SNMP, the YANG configuration
data model is organized in a set of YANG submodules, all sharing the
same module namespace. This allows adding configuration support for
additional SNMP features while keeping the number of namespaces that
have to be dealt with down to a minimum.
2.1. Tree Diagrams
A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration (read-write), and "ro" means state data (read-only). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown.2.2. General Considerations
Most YANG nodes are mapped 1-1 to the corresponding MIB object. The "reference" statement is used to indicate which corresponding MIB object the YANG node is mapped to. When there is not a simple 1-1 mapping, the "description" statement explains the mapping. The persistency models in SNMP and NETCONF are quite different. In NETCONF, the persistency is defined by the datastore, whereas in SNMP, it is defined either explicitly in the data model or on a row- by-row basis using the Textual Convention "StorageType". Thus, in the YANG model defined here, the "StorageType" columns are not present. For implementation guidelines, see Section 3. In SNMP, row creation and deletion are controlled using the Textual Convention "RowStatus". In NETCONF, creation and deletion are handled by the protocol, not in the data model. Thus, in the YANG model defined here, the "RowStatus" columns are not present.2.3. Common Definitions
The submodule "ietf-snmp-common" defines a set of common typedefs and the top-level container "snmp". All configuration parameters defined in the other submodules are organized under this top-level container.
2.4. Engine Configuration
The submodule "ietf-snmp-engine", which defines configuration parameters that are specific to SNMP engines, has the following structure: +--rw snmp +--rw engine +--rw enabled? boolean +--rw listen* [name] | +--rw name snmp:identifier | +--rw (transport) | +--:(udp) | +--rw udp | +--rw ip inet:ip-address | +--rw port? inet:port-number +--rw version | +--rw v1? empty | +--rw v2c? empty | +--rw v3? empty +--rw engine-id? snmp:engine-id +--rw enable-authen-traps? boolean The leaf "/snmp/engine/enabled" can be used to enable/disable an SNMP engine. The list "/snmp/engine/listen" provides configuration of the transport endpoints the engine is listening to. In this submodule, SNMP over UDP is defined. The Secure Shell (SSH) Protocol, Transport Layer Security (TLS), and Datagram Transport Layer Security (DTLS) are also supported, defined in "ietf-snmp-ssh" (Section 2.13) and "ietf-snmp-tls" (Section 2.12), respectively. The "transport" choice is expected to be augmented for other transports. The "/snmp/engine/version" container can be used to enable/disable the different message processing models [RFC3411].
2.5. Target Configuration
The submodule "ietf-snmp-target", which defines configuration parameters that correspond to the objects in SNMP-TARGET-MIB, has the following structure: +--rw snmp +--rw target* [name] | +--rw name snmp:identifier | +--rw (transport) | | +--:(udp) | | +--rw udp | | +--rw ip inet:ip-address | | +--rw port? inet:port-number | | +--rw prefix-length? uint8 | +--rw tag* snmp:identifier | +--rw timeout? uint32 | +--rw retries? uint8 | +--rw target-params snmp:identifier +--rw target-params* [name] +--rw name snmp:identifier +--rw (params)? An entry in the list "/snmp/target" corresponds to an "snmpTargetAddrEntry". The "snmpTargetAddrTDomain" and "snmpTargetAddrTAddress" objects are mapped to transport-specific YANG nodes. Each transport is configured as a separate case in the "transport" choice. In this submodule, SNMP over UDP is defined. TLS and DTLS are also supported, defined in "ietf-snmp-tls" (Section 2.12). The "transport" choice is expected to be augmented for other transports. An entry in the list "/snmp/target-params" corresponds to an "snmpTargetParamsEntry". This list contains a choice "params", which is augmented by submodules specific to the security model, currently, "ietf-snmp-community" (Section 2.8), "ietf-snmp-usm" (Section 2.10), and "ietf-snmp-tls" (Section 2.12).
2.6. Notification Configuration
The submodule "ietf-snmp-notification", which defines configuration parameters that correspond to the objects in SNMP-NOTIFICATION-MIB, has the following structure: +--rw snmp +--rw notify* [name] | +--rw name snmp:identifier | +--rw tag snmp:identifier | +--rw type? enumeration +--rw notify-filter-profile* [name] +--rw name snmp:identifier +--rw include* snmp:wildcard-object-identifier +--rw exclude* snmp:wildcard-object-identifier This submodule also augments the "target-params" list defined in the "ietf-snmp-target" submodule (Section 2.5) with one leaf: +--rw snmp +--rw target-params* [name] ... +--rw notify-filter-profile? leafref An entry in the list "/snmp/notify" corresponds to an "snmpNotifyEntry". An entry in the list "/snmp/notify-filter-profile" corresponds to an "snmpNotifyFilterProfileEntry". In the MIB, there is a sparse relationship between "snmpTargetParamsTable" and "snmpNotifyFilterProfileTable". In the YANG model, this sparse relationship is represented with a leafref leaf "notify-filter-profile" in the "/snmp/target-params" list, which refers to an entry in the "/snmp/notify-filter-profile" list. The "snmpNotifyFilterTable" is represented as a list "filter" within the "/snmp/notify-filter-profile" list. This submodule defines the feature "notification-filter". A server implements this feature if it supports SNMP notification filtering [RFC3413].
2.7. Proxy Configuration
The submodule "ietf-snmp-proxy", which defines configuration parameters that correspond to the objects in SNMP-PROXY-MIB, has the following structure: +--rw snmp +--rw proxy* [name] +--rw name snmp:identifier +--rw type enumeration +--rw context-engine-id snmp:engine-id +--rw context-name? snmp:context-name +--rw target-params-in? snmp:identifier +--rw single-target-out? snmp:identifier +--rw multiple-target-out? snmp:identifier An entry in the list "/snmp/proxy" corresponds to an "snmpProxyEntry". This submodule defines the feature "proxy". A server implements this feature if it can act as an SNMP proxy [RFC3413].2.8. Community Configuration
The submodule "ietf-snmp-community", which defines configuration parameters that correspond to the objects in SNMP-COMMUNITY-MIB, has the following structure: +--rw snmp +--rw community* [index] +--rw index snmp:identifier +--rw (name)? | +--:(text-name) | | +--rw text-name? string | +--:(binary-name) | +--rw binary-name? binary +--rw security-name snmp:security-name +--rw engine-id? snmp:engine-id +--rw context? snmp:context-name +--rw target-tag? snmp:identifier This submodule also augments the "/snmp/target-params/params" choice with nodes for the Community-based Security Model used by SNMPv1 and SNMPv2c:
+--rw snmp
+--rw target-params* [name]
| ...
| +--rw (params)?
| +--:(v1)
| | +--rw v1
| | +--rw security-name snmp:security-name
| +--:(v2c)
| +--rw v2c
| +--rw security-name snmp:security-name
+--rw target* [name]
+--rw mms? union
An entry in the list "/snmp/community" corresponds to an
"snmpCommunityEntry".
When a case "v1" or "v2c" is chosen, it implies an
snmpTargetParamsMPModel 0 (SNMPv1) or 1 (SNMPv2), and an
snmpTargetParamsSecurityModel 1 (SNMPv1) or 2 (SNMPv2), respectively.
Both cases imply an snmpTargetParamsSecurityLevel of noAuthNoPriv.
2.9. View-Based Access Control Model Configuration
The submodule "ietf-snmp-vacm", which defines configuration
parameters that correspond to the objects in SNMP-VIEW-BASED-ACM-MIB,
has the following structure:
+--rw snmp
+--rw vacm
+--rw group* [name]
| +--rw name group-name
| +--rw member* [security-name]
| | +--rw security-name snmp:security-name
| | +--rw security-model* snmp:security-model
| +--rw access* [context security-model security-level]
| +--rw context snmp:context-name
| +--rw context-match? enumeration
| +--rw security-model snmp:security-model-or-any
| +--rw security-level snmp:security-level
| +--rw read-view? view-name
| +--rw write-view? view-name
| +--rw notify-view? view-name
+--rw view* [name]
+--rw name view-name
+--rw include* snmp:wildcard-object-identifier
+--rw exclude* snmp:wildcard-object-identifier
The "vacmSecurityToGroupTable" and "vacmAccessTable" are mapped to a structure of nested lists in the YANG model. Groups are defined in the list "/snmp/vacm/group", and for each group, there is a sublist "member" that maps to "vacmSecurityToGroupTable" and a sublist "access" that maps to "vacmAccessTable". MIB views are defined in the list "/snmp/vacm/view", and for each MIB view, there is a leaf-list of included subtree families and a leaf- list of excluded subtree families. This is more compact and thus a more readable representation of the "vacmViewTreeFamilyTable".2.10. User-Based Security Model Configuration
The submodule "ietf-snmp-usm", which defines configuration parameters that correspond to the objects in SNMP-USER-BASED-SM-MIB, has the following structure: +--rw snmp +--rw usm +--rw local | +--rw user* [name] | +-- {common user params} +--rw remote* [engine-id] +--rw engine-id snmp:engine-id +--rw user* [name] +-- {common user params} The "{common user params}" are: +--rw name snmp:identifier +--rw auth! | +--rw (protocol) | +--:(md5) | | +--rw md5 | | +-- rw key yang:hex-string | +--:(sha) | +--rw sha | +-- rw key yang:hex-string +--rw priv! +--rw (protocol) +--:(des) | +--rw des | +-- rw key yang:hex-string +--:(aes) +--rw aes +-- rw key yang:hex-string
This submodule also augments the "/snmp/target-params/params" choice
with nodes for the SNMP User-based Security Model.
+--rw snmp
+--rw target-params* [name]
...
+--rw (params)?
+--:(usm)
+--rw usm
+--rw user-name snmp:security-name
+--rw security-level security-level
In the MIB, there is a single table with local and remote users,
indexed by the engine ID and user name. In the YANG model, there is
one list of local users and a nested list of remote users.
In the MIB, there are several objects related to changing the
authentication and privacy keys. These objects are not present in
the YANG model. However, the localized key can be changed. This
implies that if the engine ID is changed, all users keys need to be
changed as well.
2.11. Transport Security Model Configuration
The submodule "ietf-snmp-tsm", which defines configuration parameters
that correspond to the objects in SNMP-TSM-MIB, has the following
structure:
+--rw snmp
+--rw tsm
+--rw use-prefix? boolean
This submodule also augments the "/snmp/target-params/params" choice
with nodes for the SNMP Transport Security Model.
+--rw snmp
+--rw target-params* [name]
...
+--rw (params)?
+--:(tsm)
+--rw tsm
+--rw security-name snmp:security-name
+--rw security-level security-level
This submodule defines the feature "tsm". A server implements this
feature if it supports the Transport Security Model (TSM) [RFC5591].
2.12. Transport Layer Security Transport Model Configuration
The submodule "ietf-snmp-tls", which defines configuration parameters that correspond to the objects in SNMP-TLS-TM-MIB, has the following structure: +--rw snmp ... +--rw target* [name] | ... | +--rw (transport) | ... | +--:(tls) | | +--rw tls | | +-- {common (d)tls transport params} | +--:(dtls) | +--rw dtls | +-- {common (d)tls transport params} +--rw tlstm +--rw cert-to-name* [id] +--rw id uint32 +--rw fingerprint x509c2n:tls-fingerprint +--rw map-type identityref +--rw name string The "{common (d)tls transport params}" are: +--rw ip? inet:host +--rw port? inet:port-number +--rw client-fingerprint? x509c2n:tls-fingerprint +--rw server-fingerprint? x509c2n:tls-fingerprint +--rw server-identity? snmp:admin-string
This submodule also augments the "/snmp/engine/listen/transport"
choice with objects for the D(TLS) transport endpoints:
+--rw snmp
+--rw engine
...
+--rw listen* [name]
...
+--rw (transport)
...
+--:(tls)
| +--rw tls
| +--rw ip inet:ip-address
| +--rw port? inet:port-number
+--:(dtls)
+--rw dtls
+--rw ip inet:ip-address
+--rw port? inet:port-number
This submodule defines the feature "tlstm". A server implements this
feature if it supports the Transport Layer Security (TLS) Transport
Model (TLSTM) [RFC6353].
2.13. Secure Shell Transport Model Configuration
The submodule "ietf-snmp-ssh", which defines configuration parameters
that correspond to the objects in SNMP-SSH-TM-MIB, has the following
structure:
+--rw snmp
...
+--rw target* [name]
...
+--rw (transport)
...
+--:(ssh)
+--rw ssh
+--rw ip inet:host
+--rw port? inet:port-number
+--rw username? string
It also augments the "/snmp/engine/listen/transport" choice with
objects for the SSH transport endpoints:
+--rw snmp
+--rw engine
...
+--rw listen* [name]
...
+--rw (transport)
...
+--:(ssh)
+--rw ssh
+--rw ip inet:host
+--rw port? inet:port-number
+--rw username? string
This submodule defines the feature "sshtm". A server implements this
feature if it supports the Secure Shell Transport Model (SSHTM)
[RFC5592].
3. Implementation Guidelines
This section describes some challenges for implementations that
support both the YANG models defined in this document and either
read-write or read-only SNMP access to the same data, using the
standard MIB modules.
As described in Section 2.2, the persistency models in NETCONF and
SNMP are quite different. This poses a challenge for an
implementation to support both NETCONF and SNMP access to the same
data, in particular if the data is writable over both protocols.
Specifically, the configuration data may exist in some combination of
the three NETCONF configuration datastores, and this data must be
mapped to rows in the SNMP tables, in some SNMP contexts, with proper
values for the StorageType columns.
This problem is not new; it has been handled in many implementations
that support configuration of the SNMP engine over a command line
interface (CLI), which normally have a persistency model similar to
NETCONF.
Since there is not one solution that works for all cases, this
document does not provide a recommended solution. Instead, some of
the challenges involved are described below.
3.1. Supporting read-only SNMP Access
If a device implements only :writable-running, it is trivial to map the contents of "running" to data in the SNMP tables, where all instances of the StorageType columns have the value "nonVolatile". If a device implements :candidate but not :startup, the implementation may choose to not expose the contents of the "candidate" datastore over SNMP and map the contents of "running" as described above. As an option, the contents of "candidate" might be accessible in a separate SNMP context. If a device implements :startup, the handling of StorageType becomes more difficult. Since the contents of "running" and "startup" might differ, data in "running" cannot automatically be mapped to instances with StorageType "nonVolatile". If a particular entry exists in "running" but not in "startup", its StorageType should be "volatile". If a particular entry exists in "startup" but not "running", it should not be mapped to an SNMP instance, at least not in the default SNMP context.3.2. Supporting read-write SNMP Access
If the implementation supports read-write access to data over SNMP, and specifically creation of table rows, special attention has to be given to the handling of the RowStatus and StorageType columns. The problem is to determine which table rows to store in the configuration datastores and which configuration datastore is appropriate for each row. The SNMP tables contain a mix of configured data and operational state, and only rows with an "active" RowStatus column should be stored in a configuration datastore. If a device implements only :writable-running, "active" rows with a "nonVolatile" StorageType column can be stored in "running". Rows with a "volatile" StorageType column are operational state. If a device implements :candidate but not :writable-running, all configuration changes typically go through the "candidate", even if they are done over SNMP. An implementation might have to perform some automatic commit of the "candidate" when data is written over SNMP, since there is no explicit "commit" operation in SNMP. If a device implements :startup, "nonVolatile" rows cannot just be written to "running"; they must also be copied into "startup". "volatile" rows may be treated as operational state and not copied to any datastore, or they may be copied into "running".
Cooperating SNMP management applications may use spin lock objects (snmpTargetSpinLock [RFC3413], usmUserSpinLock [RFC3414], vacmViewSpinLock [RFC3415]) to coordinate concurrent write requests. Implementations supporting modifications of MIB objects protected by a spin lock via NETCONF should ensure that the spin lock objects are properly incremented whenever objects are changed via NETCONF. This allows cooperating SNMP management applications to discover that concurrent modifications are taking place.
(page 16 continued on part 2)
