YANGsters FAQ
Contents
- YANGsters Links:
- YANG Terminology:
- YANG Guidelines:
- Do’s and Don’ts:
- UML-like Diagram Description:
- YANG Prefix
- YANG Style Guidelines
- YANG Lifecycle
- Guidelines Discussion Topics
- What is YANG?
- YANG Catalog GitHub Repository
- Tool – YANG Pretty Printer
- Framemaker and YANG files
- Tool – pyang
- Tool – yanglint (libyang)
- On-line YANG Validation Tool
- On-line SNMP Validation Tool
- SMIlib Tools
- Metadata
- YANG Examples
- Revision Numbering
YANGsters Links:
- Coordination Group for IEEE 802
- Home Page: https://1.ieee802.org/yangsters/
- Mailing List Info: https://1.ieee802.org/yangsters/yangsters-mail-list-information/
- eMeetings: https://1.ieee802.org/yangsters/yangsters-call-information/
- Agendas: https://1.ieee802.org/category/yangsters-agenda/
- Issues List: https://1.ieee802.org/yangsters/yangsters-issue-list/
- IEEE 802.1 Repository for YANG: https://1.ieee802.org/yang-modules/
YANG Terminology:
- YANG:
- YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. IETF RFC 7950
- YANG Data Model
- Not explicitly defined. Data model is defined in the terminology section of IETF RFC 7950 as: “data model: A data model describes how data is represented and accessed.”
- YANG Module
- In IETF RFC 7950:
- Section 3:
- module: A YANG module defines hierarchies of schema nodes. With its definitions and the definitions it imports or includes from elsewhere, a module is self-contained and “compilable”.
- Section 4.1:
- “YANG structures data models into modules and submodules.”
- Section 4.2.1:
- “YANG data models are defined in modules. A module contains a collection of related definitions.”
- Section 5.2: “YANG modules and submodules are typically stored in files, one “module” or “submodule” statement per file.”
- Section 3:
- In IETF RFC 7950:
- IEEE YANGster Definitions
- YANG model
- One or more YANG modules used to configure and monitor the managed element or system.
- YANG module
- The description of the data model used to configure and monitor the managed element or system. A YANG module defines a hierarchy of nodes that can be used for NETCONF-based (see IETF RFC 7803) and RESTCONF-based (see IETF RFC 8040) operations.
- Schema tree
- The definition hierarchy specified within a module. [IETF RFC 7950]
- Schema
- A collection of schema trees with a common root. [IETF RFC 8528]
- YANG model
YANG Guidelines:
- IEEE 802.1 Editor’s Guidelines
- https://1.ieee802.org/editors-resources/ (password protected – 802.1 private area password)
- IETF Guidelines
- Module Naming Conventions
- IEEE URN
- YANG Contact Information
- Abbreviations or Acronyms
- References Guidelines
- YANG Copyright Text in the YANG module
- Insert “Copyright (C) IEEE (2021). All rights reserved. This version of this YANG module is part of IEEE Std 802.1<<std number>>; see the standard itself for full legal notices.” at the end of the description statement associated with the module.
- For amendments, use the base standard in the copyright statement.
- YANG Copyright text in the standard (add as footnote to module sub-clause)
- Copyright release for YANG: Users of this standard may freely reproduce the YANG modules contained in this standard so that they can be used for their intended purpose.
Do’s and Don’ts:
- Consider interaction with other models
- YANG models are rarely used alone but are meant to be mixed and matched, so consider potentially unwanted interaction! In particular, just loading another YANG model should not invalidate previously valid instance data.
- Care must be taken to ensure augmentations are done in such a way that the capabilities being added by the augmentation can be ignored. Leverage features, presence containers or rearrange the must statements to avoid the issue.
- See Microsoft PowerPoint – yangsters-smansfield-axdz-augmentation-issue-0524-v01.pptx (ieee802.org) for an example.
- Overeager must statements
- must statements in currently unused branches are often evaluated as false, e.g. “count(./gate-control-entry) <= ../supported-list-max”, implicitly forcing the existence of certain leafs far down in unused branches. Consider inverting the statement as in “not(count(./gate-control-entry) > ../supported-list-max)” to avoid that.
UML-like Diagram Description:
- https://1.ieee802.org/uml-like-diagrams/
- Text for Introduction Clause:
- A UML-like representation of the management model is provided in the following subclauses.
The purpose of an UML-like diagram is to express the model design on a single piece of paper. The structure of the UML-like representation shows the name of the object followed by a list of properties for the object. The properties indicate their type and accessibility. It should be noted that the UML-like representation is meant to express simplified semantics for the properties. It is not meant to provide the specific datatype as used to encode the object in either MIB or YANG. In the UML-like representation, a box with a white background represents information that comes from sources outside of this IEEE standard. A box with a light gray background represents objects that are defined by this IEEE standard. A box with a hatched or dark gray background represents objects that are augmented/modified by this IEEE standard.
- A UML-like representation of the management model is provided in the following subclauses.
- In IEEE Std 802.1Q-2022 light gray and dark gray were used because it was easier to see than the hatched pattern.
YANG Prefix
- https://1.ieee802.org/yangsters/yang-prefixes/
- Use of prefixes. Information from YANG Doctors (Follow RFC 8407)
- The local module prefix SHOULD be used instead of no prefix in all path expressions.
- The local module prefix MUST be used instead of no prefix in all “default” statements for an “identityref” or “instance-identifier” data type.
- The local module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module.
- Use of prefixes. Information from YANG Doctors (Follow RFC 8407)
YANG Style Guidelines
- Style follows guidelines from IETF
- https://tools.ietf.org/html/rfc8407
- kebab-case
- Canonical order: enforced by pretty printer and checked by pyang
- For datastores, NMDA is used
YANG Lifecycle
- https://www.ieee802.org/1/files/public/docs2020/yangsters-smansfield-yang-revision-guidelines-0820-v01.pdf
- YANG files are integral parts of a IEEE Standards document
- The YANG file that is in-line in the Standard is the YANG of record
- The use of a repository is for convenience, the YANG file in the published standard is the final word
- During development use the YANG Catalog’s github repository
- Create a directory for your project if needed
- Copy in any published modules from the published directories that will be modified by your project
- Keep in mind that others may be modifying the same files, so keep the YANGsters notified, so that rebasing can occur when YANG files are updated
- If your project uses other draft projects use the check_pyang_extra_flags file to make the checking script aware of the directory where the other YANG files are located
- Update the check.sh script in the …/yang/standard/ieee directory to add your project if needed
- This is the script that is run automatically when new versions of YANG files are loaded into the git repository (uses pyang), so checking your files before uploading is a must
- Use the Pretty Printer
- Use yanglint for testing
- Once the Standard has been approved (at least at the level of SA Editing)
- Update the Revision statement and date (append revision date to YANG filename)
- Once the Standard is published
- Remove the draft YANG files from the repository
- Put all the published YANG in the proper published directory (…/yang/standard/ieee/802.1/ for example)
Guidelines Discussion Topics
- Use of “types” modules
- Are typedefs and groupings put in a separate “types” module or kept in-line
- Current practice is to only separate into a “types” files if it is known that the types or groupings will be used by other modules
- Xpath and when statements
- How much checking/validation should be used in our modules?
- Should constraints just be documented in description statements?
- Use of uses
- If a grouping is only used in one place, do not use a grouping but put in-line
- Semantics of read-write in YANG
- MAC Address Differences
- The IETF and the IEEE have a different format for MAC Addresses
- Discussion of Issue
What is YANG?
- NETCONF and YANG provide a powerful toolset for network, service, and device management
- NETCONF is the Network Configuration Protocol that provides the tools for configuration and monitoring of network devices (or really anything that supports a NETCONF server)
- YANG is a data modeling language that models the configuration and state data that is used by NETCONF.
- So, analogy… SNMP is to NETCONF, like SMI is to YANG
- Sure you can read https://tools.ietf.org/html/rfc7950
- But to get more of an introduction:
- https://rule11.tech/history-of-yang-with-phil-shafer/
- (a bit old) https://datatracker.ietf.org/doc/slides-edu-network-configuration-with-yang/
- (not a sales pitch, but it is awesome) https://www.claise.be/category/yang/
YANG Catalog GitHub Repository
- The YANG Catalog provides a set of tools and repository for storage of YANG modules
- https://yangcatalog.org/
- The YANG Catalog’s github repository is used by IEEE for published and draft modules
- YANGsters guidelines for repository usage
- For Git introduction and examples on interacting with the YANG Catalog’s github repository
- When your git is X commits ahead try this…
- https://1.ieee802.org/yangsters/tools-for-yang/git-issue-x-commits-ahead/
Tool – YANG Pretty Printer
- This is a tool that is currently under development, the preferred tool is currently pyang (see Tool – pyang) below.
- https://www.ieee802.org/1/files/public/docs2020/new-specht-yang-pretty-printing-0620-v05.pdf
- https://www.ieee802.org/1/files/public/docs2020/new-specht-yang-pretty-printer-live-1120-v01.pdf
- There are still open issues regarding options used for pretty printing
- Currently the only formatting option used is –W 73 to set the max width of the line
- The MIF and Diffmark MIF options can be used to make Framemaker inclusion easier
- Open Technical Issues
- Blank line handling
- Adding of double quotes
- Spacing (indentation options)
- Line Length options
- Line ending CRLF issues between Unix and Windows
Framemaker and YANG files
- YANG file handling in framemaker:
- Click in the frame where you want file to be inserted
- File->Import->File
- Import Text Flow by Reference dialog pops up
- Change “Formatting of Imported Flow:” to “Retain Source’s Formatting”
- Click Import
- The module is inserted and will be kept up to date if the file changes.
- Closing the Document and reopening it, or closing the Book and opening it again will refresh the imported file.
Tool – pyang
- An open source tool that is essential to the YANG development lifecycle
- The tool can be downloaded and installed on Windows/Linux
- Tutorial
- pyang source
- Options used for checking
- –verbose: more warning and error information provided
- –canonical: Validate usual YANG order as defined by RFC 7950
- –ieee: Validates with ieee options, there is an issue with the checking for module name in the tool. pyang complains that all ieee modules should start with ieee and not ieee802. This should be fixed at some point.
- –max-identifier-length: set a value for how long the longest yang identifier can be
- –path: search path for modules (multiple –path parameters are allowed)
- -f tree –tree-print-groupings: using those two options will produce a tree and also print out the groupings in tree format. If you don’t want the groupings leave that option off.
- Example way to use pyang
- A way to use the tool is to create a directory on your system and copy in all YANG modules that are used (including all imports) locally. Then run pyang over the files in that directory. There will be no issues with understanding where the modules are coming from.
- If you are doing your work in a clone of the YANG Catalog GitHub repository, the check.sh script does minimal checking, so a separate validation with more strict pyang options is suggested. Also running against yanglint is suggested (see below).
- Important to check using –ieee or –ietf so that RFC 8407 errors/warnings can be resolved.
- Current preferred pretty printing settings:
- pyang -o <pretty-file> -f yang –yang-canonical –yang-remove-unused-imports –yang-remove-comments –yang-line-length=68 <original-file>
Tool – yanglint (libyang)
- A YANG parser and toolkit
- Important tool that is suggested to be used to validate the YANG structure and testing for Xpaths and constraints
- Creating a directory with all the necessary YANG files is suggested.
- Example XML: https://1.ieee802.org/wp-content/uploads/2020/11/psfs-xml.txt
- Example run: https://1.ieee802.org/wp-content/uploads/2020/11/psfs-out.txt
- Collection of Examples: https://1.ieee802.org/yangsters/yang-instance-examples/
On-line YANG Validation Tool
The YANG Validator provides a useful set of tools to validate YANG files.
- The on-line tools currently have an issue with revision handling, so if there are a set of files that include newer versions of imported files, there may be strange errors related to missing definitions. So, best to use the tools natively as described above.
- The on-line tools have stricter checking, which checks for compliance against RFC 8407. There are RFC 8407 errors in some IETF imported files, those can be ignored, but any RFC 8407 issues found in IEEE files should be addressed.
On-line SNMP Validation Tool
If SNMP/MIBs are being modified, checking with the SimpleWeb On-line tool is recommended.
SimpleWeb MIB Validation provides the ability to load a file and all of the necessary import files that are not include in the default search path (for example the standard IETF MIBs do not need to be included).
Usage notes:
- Create a directory with all the MIB files you want to upload.
- Make sure the file names do not include the “date” and make sure the extension is “.mib”.
- Choose a file then click submit, the system will then tell you what imports you are missing. Continue to add the files and clicking submit until all the imports have been resolved. Important… use the back button on the browser to navigate back to page to add more files.
- You can change the severity level, the default is “3”.
SMIlib Tools
A set of client-based tools for validating MIBs is available at https://www.ibr.cs.tu-bs.de/projects/libsmi/index.html
There are several tools that are useful, but the one that provides the functionality like the on-line version described above is smilint.
On my Windows 10 machine running WSL2/Ubuntu is is possible to install version 0.4.8 of smilib using apt get. If you want the latest 0.5.0, download the source from here (direct link to file) https://www.ibr.cs.tu-bs.de/projects/libsmi/download/libsmi-0.5.0.tar.gz or search the directory for what you want at https://www.ibr.cs.tu-bs.de/projects/libsmi/download/. I followed the build instructions in the README file found in the gzipped tar file and everything compiled and ran. It even created directories in /usr/local/share/mibs with the iana and ietf MIB files.
In order to use smilint with a config file, first you need to create one. Here is an example: https://1.ieee802.org/yangsters/tools-for-yang/mib-smilint-config-file-example/
To run the tool, copy all the MIB files you want check and then:
smilint –config=./smi.config -l3 *-BRIDGE*
Example, if you want to test the IEEE8021-BRIDGE-MIB file. I extracted all the IEEE mibs from IEEE802.1Q-2018. My example also uses “medium” severity for checking (-l3). The smi.config file has the path to the IETF and IANA MIBs so those do not need to be copied to the local directory.
Metadata
- IEEE Metadata Page
- Current metadata for IEEE 802 published YANG modules. This information was retrieved using ‘curl’ of the appropriate {path, moduleName, versionDate, org} and passing the results through ‘jq’.
- Where:
- path=”https://yangcatalog.org/api/search/modules/”
- moduleName=<ieee802 yang module name>
- versionDate=<yang module date>
- org=”ieee”
- For example:
- $ curl https://yangcatalog.org/api/search/modules/ieee802-dot1q-bridge,2018-03-07,ieee | jq > ieee802-dot1q-bridge.ymd
- If you look for metadata via the yangcatalog web browser (https://yangcatalog.org/yang-search/module_details/), Keep in mind there may be multiple versions of a module. By default, the most recent versionData is displayed. For three modules (ieee802-dot1q-bridge, ieee802-dot1q-tpmr, ieee802-types), the latest date is a draft, not the published module.
- annotated-metadata-tree
YANG Examples
Revision Numbering
Guidance for revision selection on imports
[RFC7950] and [RFC6020] allow YANG module “import” statements to optionally require the imported module to have a specific revision date. In practice, importing a module with an exact revision date can be too restrictive because it requires the importing module to be updated whenever any change to the imported module occurs, and hence section Section 7.1 suggests that authors do not restrict YANG module imports to exact revision dates.¶
Instead, for conformance purposes (section 5.6 of [RFC7950]), the recommended approach for defining the relationship between specific YANG module revisions is to specify the relationships outside of the YANG modules, e.g., via YANG library [RFC8525], YANG packages [I-D.ietf-netmod-yang-packages], a filesystem directory containing a set of consistent YANG module revisions, or a revision control system commit label.¶
Therefore, current practice is to import without specific revision number for imported modules and to continue the discussion when the IETF’s work on YANG packages and Module Versioning completes.