draft-ietf-netmod-yang-usage-09.txt   draft-ietf-netmod-yang-usage-10.txt 
Internet Engineering Task Force A. Bierman Internet Engineering Task Force A. Bierman
Internet-Draft InterWorking Labs Internet-Draft Brocade
Intended status: Informational July 12, 2010 Intended status: Informational August 11, 2010
Expires: January 13, 2011 Expires: February 12, 2011
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-yang-usage-09 draft-ietf-netmod-yang-usage-10
Abstract Abstract
This memo provides guidelines for authors and reviewers of standards This memo provides guidelines for authors and reviewers of standards
track specifications containing YANG data model modules. Applicable track specifications containing YANG data model modules. Applicable
portions may be used as a basis for reviews of other YANG data model portions may be used as a basis for reviews of other YANG data model
documents. Recommendations and procedures are defined, which are documents. Recommendations and procedures are defined, which are
intended to increase interoperability and usability of Network intended to increase interoperability and usability of Network
Configuration Protocol (NETCONF) implementations which utilize YANG Configuration Protocol (NETCONF) implementations which utilize YANG
data model modules. data model modules.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 13, 2011. This Internet-Draft will expire on February 12, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 38 skipping to change at page 2, line 38
4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 12 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 12
4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 12 4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 12
4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 13 4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 13
4.7. Module Header, Meta, and Revision Statements . . . . . . . 14 4.7. Module Header, Meta, and Revision Statements . . . . . . . 14
4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 15 4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 15
4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 16 4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 16
4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 16 4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 16
4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 17 4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 17
4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 17 4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 17
4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 18 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 19
4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 6.1. Security Considerations Section Template . . . . . . . . . 21
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
8.1. Normative References . . . . . . . . . . . . . . . . . . . 23 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.2. Informative References . . . . . . . . . . . . . . . . . . 23 8.1. Normative References . . . . . . . . . . . . . . . . . . . 25
Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 25 8.2. Informative References . . . . . . . . . . . . . . . . . . 25
Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 27 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 27
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 30 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 29
C.1. Changes from 08 to 09 . . . . . . . . . . . . . . . . . . 30 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 32
C.2. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 30 C.1. Changes from 09 to 10 . . . . . . . . . . . . . . . . . . 32
C.3. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 30 C.2. Changes from 08 to 09 . . . . . . . . . . . . . . . . . . 32
C.4. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 30 C.3. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 32
C.5. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 30 C.4. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 32
C.6. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 31 C.5. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 32
C.7. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 32 C.6. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 32
C.8. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 32 C.7. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 33
C.9. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 32 C.8. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 34
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 33 C.9. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 34
C.10. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 34
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36
1. Introduction 1. Introduction
The standardization of network configuration interfaces for use with The standardization of network configuration interfaces for use with
the Network Configuration Protocol (NETCONF) [RFC4741] requires a the Network Configuration Protocol (NETCONF) [RFC4741] requires a
modular set of data models, which can be reused and extended over modular set of data models, which can be reused and extended over
time. time.
This document defines a set of usage guidelines for standards track This document defines a set of usage guidelines for standards track
documents containing YANG [I-D.ietf-netmod-yang] data models. YANG documents containing YANG [I-D.ietf-netmod-yang] data models. YANG
skipping to change at page 12, line 36 skipping to change at page 12, line 36
'if-feature' and/or 'when' statements. 'if-feature' and/or 'when' statements.
Data model designers need to carefully consider all modularity Data model designers need to carefully consider all modularity
aspects, including the use of YANG conditional statements. aspects, including the use of YANG conditional statements.
If a data definition is optional, depending on server support for a If a data definition is optional, depending on server support for a
NETCONF protocol capability, then a YANG 'feature' statement SHOULD NETCONF protocol capability, then a YANG 'feature' statement SHOULD
be defined to indicate that the NETCONF capability is supported be defined to indicate that the NETCONF capability is supported
within the data model. within the data model.
If any notification data, or any data definition, for a non-
configuration data node is not mandatory, then the server may or may
not be required to return an instance of this data node. If any
conditional requirements exist for returning the data node in a
notification payload or retrieval request, they MUST be documented
somewhere. For example, a 'when' or 'if-feature' statement could
apply to the data node, or the conditional requirements could be
explained in a 'description' statement within the data node or one of
its ancestors (if any).
4.5. XPath Usage 4.5. XPath Usage
This section describes guidelines for using the XML Path Language This section describes guidelines for using the XML Path Language
[W3C.REC-xpath-19991116] (XPath) within YANG modules. [W3C.REC-xpath-19991116] (XPath) within YANG modules.
The 'attribute' and 'namespace' axes are not supported in YANG, and The 'attribute' and 'namespace' axes are not supported in YANG, and
MAY be empty in a NETCONF server implementation. MAY be empty in a NETCONF server implementation.
The 'position' and 'last' functions MAY be used with caution. A The 'position' and 'last' functions MAY be used with caution. A
server is not required to maintain any particular XML document order server is not required to maintain any particular XML document order
skipping to change at page 14, line 45 skipping to change at page 15, line 6
A revision statement MUST be present for each published version of A revision statement MUST be present for each published version of
the module. The revision statement MUST have a reference the module. The revision statement MUST have a reference
substatement. It MUST identify the published document which contains substatement. It MUST identify the published document which contains
the module. Modules are often extracted from their original the module. Modules are often extracted from their original
documents and it is useful for developers and operators to know how documents and it is useful for developers and operators to know how
to find the original source document in a consistent manner. The to find the original source document in a consistent manner. The
revision statement MAY have a description substatement. revision statement MAY have a description substatement.
Each new revision MUST include a revision date which is higher than Each new revision MUST include a revision date which is higher than
any other revision date in the module. any other revision date in the module. The revision date does not
need to be updated if the module contents do not change in the new
document revision.
It is acceptable to reuse the same revision statement within It is acceptable to reuse the same revision statement within
unpublished versions (i.e., Internet-Drafts), but the revision date unpublished versions (i.e., Internet-Drafts), but the revision date
MUST be updated to a higher value each time the Internet-Draft is re- MUST be updated to a higher value each time the Internet-Draft is re-
published. published.
4.8. Namespace Assignments 4.8. Namespace Assignments
It is RECOMMENDED that only valid YANG modules are included in It is RECOMMENDED that only valid YANG modules are included in
documents, whether they are published yet or not. This allows: documents, whether they are published yet or not. This allows:
skipping to change at page 22, line 5 skipping to change at page 21, line 17
This document defines documentation guidelines for NETCONF content This document defines documentation guidelines for NETCONF content
defined with the YANG data modeling language. The guidelines for how defined with the YANG data modeling language. The guidelines for how
to write a Security Considerations section for a YANG module are to write a Security Considerations section for a YANG module are
defined in the online document defined in the online document
http://www.ops.ietf.org/netconf/yang-security-considerations.txt http://www.ops.ietf.org/netconf/yang-security-considerations.txt
This document does not introduce any new or increased security risks This document does not introduce any new or increased security risks
into the management system. into the management system.
The following section contains the security considerations template
dated 2010-06-16. Be sure to check the WEB page at the URL listed
above in case there is a more recent version available.
Each specification that defines one or more YANG modules MUST contain
a section that discusses security considerations relevant to those
modules. This section MUST be patterned after the latest approved
template (available at [ed: URL TBD]).
In particular, writable data nodes that could be especially
disruptive if abused MUST be explicitly listed by name and the
associated security risks MUST be spelled out.
Similarly, readable data nodes that contain especially sensitive
information or that raise significant privacy concerns MUST be
explicitly listed by name and the reasons for the sensitivity/privacy
concerns MUST be explained.
Further, if new RPC operations have been defined, then the security
considerations of each new RPC operation MUST be explained.
6.1. Security Considerations Section Template
X. Security Considerations
The YANG module defined in this memo is designed to be accessed
via the NETCONF protocol [RFC4741]. The lowest NETCONF layer is
the secure transport layer and the mandatory to implement secure
transport is SSH [RFC4742].
-- if you have any writeable data nodes (those are all the
-- "config true" nodes, and remember, that is the default)
-- describe their specific sensitivity or vulnerability.
There are a number of data nodes defined in this YANG module
which are writable/creatable/deletable (i.e. config true, which
is the default). These data nodes may be considered sensitive
or vulnerable in some network environments. Write operations
(e.g. edit-config) to these data nodes without proper protection
can have a negative effect on network operations. These are
the subtrees and data nodes and their sensitivity/vulnerability:
<list subtrees and data nodes and state why they are sensitive>
-- for all YANG modules you must evaluate whether any readable data
-- nodes (those are all the "config false" nodes, but also all other
-- nodes, because they can also be read via operations like get or
-- get-config) are sensitive or vulnerable (for instance, if they
-- might reveal customer information or violate personal privacy
-- laws such as those of the European Union if exposed to
-- unauthorized parties)
Some of the readable data nodes in this YANG module may be
considered sensitive or vulnerable in some network environments.
It is thus important to control read access (e.g. via get,
get-config or notification) to these data nodes. These are the
subtrees and data nodes and their sensitivity/vulnerability:
<list subtrees and data nodes and state why they are sensitive>
-- if your YANG module has defined any rpc operations
-- describe their specific sensitivity or vulnerability.
Some of the RPC operations in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control access to these operations. These are the
operations and their sensitivity/vulnerability:
<list RPC operations and state why they are sensitive>
Figure 2
7. Acknowledgments 7. Acknowledgments
The structure and contents of this document are adapted from The structure and contents of this document are adapted from
Guidelines for MIB Documents [RFC4181], by C. M. Heard. Guidelines for MIB Documents [RFC4181], by C. M. Heard.
The working group thanks Martin Bjorklund and Juergen Schoenwaelder The working group thanks Martin Bjorklund and Juergen Schoenwaelder
for their extensive reviews and contributions to this document. for their extensive reviews and contributions to this document.
8. References 8. References
skipping to change at page 23, line 32 skipping to change at page 25, line 32
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006. December 2006.
[RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide
to the IETF Trust", BCP 78, RFC 5378, November 2008. to the IETF Trust", BCP 78, RFC 5378, November 2008.
[RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers,
and Boilerplates", RFC 5741, December 2009. and Boilerplates", RFC 5741, December 2009.
[W3C.REC-xpath-19991116] [W3C.REC-xpath-19991116]
DeRose, S. and J. Clark, "XML Path Language (XPath) Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[I-D.ietf-netmod-yang] [I-D.ietf-netmod-yang]
Bjorklund, M., "YANG - A data modeling language for the Bjorklund, M., "YANG - A data modeling language for the
Network Configuration Protocol (NETCONF)", Network Configuration Protocol (NETCONF)",
draft-ietf-netmod-yang-13 (work in progress), June 2010. draft-ietf-netmod-yang-13 (work in progress), June 2010.
[I-D.ietf-netmod-yang-types] [I-D.ietf-netmod-yang-types]
skipping to change at page 29, line 4 skipping to change at page 31, line 4
// rpc statements // rpc statements
// notification statements // notification statements
// DO NOT put deviation statements in a published module // DO NOT put deviation statements in a published module
} }
<CODE ENDS> <CODE ENDS>
Figure 2 Figure 3
Appendix C. Change Log Appendix C. Change Log
C.1. Changes from 08 to 09 C.1. Changes from 09 to 10
o Added security considerations section template.
o Added guideline for documenting conditional requirements for non-
mandatory non-configuration data nodes.
o Clarified that revision date update applies to the module
contents.
C.2. Changes from 08 to 09
o Clarifications and corrections to address Gen-ART review comments. o Clarifications and corrections to address Gen-ART review comments.
C.2. Changes from 07 to 08 C.3. Changes from 07 to 08
o Corrected YANG security considerations URL. o Corrected YANG security considerations URL.
o Expanded 'CODE BEGINS' example. o Expanded 'CODE BEGINS' example.
o Added RPC operations to the security considerations guidelines o Added RPC operations to the security considerations guidelines
section. section.
o Removed guideline about leading and trailing whitespace. o Removed guideline about leading and trailing whitespace.
C.3. Changes from 06 to 07 C.4. Changes from 06 to 07
o Corrected title change bug; supposed to be page header instead. o Corrected title change bug; supposed to be page header instead.
o Fixed typos added to last revision. o Fixed typos added to last revision.
o Added sentence to checklist to make sure text outside module o Added sentence to checklist to make sure text outside module
contains citations for imports. contains citations for imports.
C.4. Changes from 05 to 06 C.5. Changes from 05 to 06
o Several clarifications and corrections, based on the AD review by o Several clarifications and corrections, based on the AD review by
Dan Romascanu. Dan Romascanu.
C.5. Changes from 04 to 05 C.6. Changes from 04 to 05
o Changed 'object' terminology to 'data definition'. o Changed 'object' terminology to 'data definition'.
o Put XPath guidelines in separate section. o Put XPath guidelines in separate section.
o Clarified XPath usage for XML document order dependencies. o Clarified XPath usage for XML document order dependencies.
o Updated <CODE BEGINS> guidelines to current conventions. o Updated <CODE BEGINS> guidelines to current conventions.
o Added informative reference for IANA considerations guidelines and o Added informative reference for IANA considerations guidelines and
XML registry. XML registry.
o Updated IANA Considerations section to reserve the ietf-template o Updated IANA Considerations section to reserve the ietf-template
module in the YANG Module Name Registry so it cannot be reused module in the YANG Module Name Registry so it cannot be reused
accidently. accidently.
o Many other clarifications and fixed typos found in WGLC reviews. o Many other clarifications and fixed typos found in WGLC reviews.
C.6. Changes from 03 to 04 C.7. Changes from 03 to 04
o Removed figure 1 to reduce duplication, just refer to 4741bis o Removed figure 1 to reduce duplication, just refer to 4741bis
draft. draft.
o Fixed bugs and typos found in WGLC reviews. o Fixed bugs and typos found in WGLC reviews.
o Removed some guidelines and referring to YANG draft instead of o Removed some guidelines and referring to YANG draft instead of
duplicating YANG rules here. duplicating YANG rules here.
o Changed security guidelines so they refer to the IETF Trust TLP o Changed security guidelines so they refer to the IETF Trust TLP
skipping to change at page 32, line 5 skipping to change at page 34, line 12
o Added guideline that strings should not rely on preservation of o Added guideline that strings should not rely on preservation of
leading and trailing whitespace characters. leading and trailing whitespace characters.
o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST
NOT to MAY use with caution. NOT to MAY use with caution.
o Updated the TLP text within the example module again. o Updated the TLP text within the example module again.
o Reversed order of change log so most recent entries are first. o Reversed order of change log so most recent entries are first.
C.7. Changes from 02 to 03 C.8. Changes from 02 to 03
o Updated figure 1 to align with 4741bis draft. o Updated figure 1 to align with 4741bis draft.
o Updated guidelines for import-by-revision and include-by-revision. o Updated guidelines for import-by-revision and include-by-revision.
o Added file name to code begins convention in ietf-template module. o Added file name to code begins convention in ietf-template module.
C.8. Changes from 01 to 02 C.9. Changes from 01 to 02
o Updated figure 1 per mailing list comments. o Updated figure 1 per mailing list comments.
o Updated suggested organization to include the working group name. o Updated suggested organization to include the working group name.
o Updated ietf-template.yang to use new organization statement o Updated ietf-template.yang to use new organization statement
value. value.
o Updated Code Component requirements as per new TLP. o Updated Code Component requirements as per new TLP.
o Updated ietf-template.yang to use new Code Component begin and end o Updated ietf-template.yang to use new Code Component begin and end
markers. markers.
o Updated references to the TLP in a couple sections. o Updated references to the TLP in a couple sections.
o Change manager/agent terminology to client/server. o Change manager/agent terminology to client/server.
C.9. Changes from 00 to 01 C.10. Changes from 00 to 01
o Added transport 'TLS' to figure 1. o Added transport 'TLS' to figure 1.
o Added note about RFC 2119 terminology. o Added note about RFC 2119 terminology.
o Corrected URL for instructions to authors. o Corrected URL for instructions to authors.
o Updated namespace procedures section. o Updated namespace procedures section.
o Updated guidelines on module contact, reference, and organization o Updated guidelines on module contact, reference, and organization
skipping to change at page 33, line 8 skipping to change at page 36, line 8
o Added section on temporary namespace statement values. o Added section on temporary namespace statement values.
o Added section on top level database objects. o Added section on top level database objects.
o Added ietf-template.yang appendix. o Added ietf-template.yang appendix.
Author's Address Author's Address
Andy Bierman Andy Bierman
InterWorking Labs Brocade
Email: andyb@iwl.com Email: andy.bierman@brocade.com
 End of changes. 21 change blocks. 
36 lines changed or deleted 130 lines changed or added

This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/