YANGsters FAQ

YANGsters Links:

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.”
  • 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 Guidelines:

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.
  • 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.

YANG Style Guidelines

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

What is YANG?

YANG Catalog GitHub Repository

Tool – YANG Pretty Printer

  • 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:
    1. Click in the frame where you want file to be inserted
    2. File->Import->File
    3. Import Text Flow by Reference dialog pops up
    4. Change “Formatting of Imported Flow:” to “Retain Source’s Formatting”
    5. 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.

Tool – yanglint (libyang)

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

YANG Examples

Revision Numbering

https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-module-versioning#name-guidance-for-revision-selec

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.

Sidebar