YANGsters Links:

YANG Guidelines:

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?
  • Referencing inside YANG modules
    • In the reference statement in YANG do we use the date version of the standard being referenced or just the base name and clause number? For example instead of 802.1Q-2018 clause a.b.c, use 802.1Q clause a.b.c. When newer versions of the standard come out, the YANG reference statements will not be out of date.
  • 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 – IEEE YANG Pretty Printer

  • There are still open issues regarding options used for pretty printing
    • Currently the only formatting option used is –W 76 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.


YANG Examples