yangdump(1)

📦 version 2.14, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, welcome to yangdump(1) from yangdump 2.2. This icon is here to validate YANG modules and convert them to different formats. 💖✨

🦋 SYNOPSIS 🦋

yangdump (module=value | subtree=value)+ [parameter=value...]

yangdump  --help [brief | normal | full]

yangdump  --version

yangdump  --show-errors

💅 DESCRIPTION 💅

okay so yangdump provides validation and translation of YANG data models. Information about a module or submodule can be generated as well. This version of yangdump supports the YANG data modeling language defined in RFC 6020. ✨

The format parameter is used to select a translation output mode. If it is missing, then no translation will be done. 💀

This parameter can be used with the module reports parameters, but the translation output should be directed to a file instead of STDOUT to keep them separated. 🫶

For XSD 1.0 translation, use the format=xsd parameter.

For XHTML 1.0 translation, use the format=html parameter.

For a 1 line output of the module name and version, use the modversion parameter.

For a listing of all the symbols that the file exports to other files, use the exports parameter.

For a listing of all the files that the file depends on, to compile, use the dependencies parameter.

For a listing of all the accessible object identifiers that the file contains, use the identifiers parameter.

For a listing of all the accessible object identifiers that the file contains, in tree format, use the tree-identifiers parameter. 🌸

🌸 USAGE 🌸

Parameters can be entered in any order, and have the form:

[start] name [separator [value]]

where:

  • start == 0, 1, or 2 dashes (foo, -foo, --foo)
  • name == parameter name
    • Parameter name completion will be attempted if a partial name is entered.
  • separator == whitespace or equals sign (foo=bar, foo bar)
  • value == string value for the parameter.
    • Strings with whitespace need to be double quoted (--foo="some string")

Some examples of valid command line parameters:

foo=3
-foo=3
--foo=3
foo 3
foo=fred
--foo "fred flintstone"

Partial parameter names can be entered if they are unique. ✨

🎀 OPTIONS 🎀

  • --config=filespec — The name of the configuration file to use. Any parameter except this one can be set in the config file. The default config file /etc/yuma/yangdump.conf will not be checked if this parameter is present.
  • --defnames=boolean — If true, output to a file with the default name for the format, in the current directory. The default value is 'false'.
    • If the output parameter is present and represents an existing directory, then the default filename will be created in that directory, instead of the current directory.
  • --dependencies — Validate the file, write the module name, version and module source for each file that this [sub]module imports and includes, then exit.
    • Each dependency type, name, version, and source is listed once.
    • If the dependency version and source are missing, then that import or include file was not found.
  • --deviation=string — This parameter identifies a YANG module that should only be checked for deviation statements for external modules. These will be collected and applied to the real module(s) being processed.
    • Deviations are applied as patches to the target module. Since they are not identified in the target module at all (ala imports), they have to be specified explicitly, so they will be correctly processed. Zero or more instances of this parameter are allowed.
  • --exports — Validate the file, write information for the symbols that this [sub]module exports, then exit. Report includes the following info for the specific file, not the entire module, if submodules are used:
    • [sub]module name
    • version
    • source filespec
    • namespace (module only)
    • prefix (module only)
    • belongs-to (submodule only)
    • typedefs
    • groupings
    • objects, rpcs, notifications
    • extensions.
  • --feature-code-default=enum — If 'dynamic' (the default), then dynamic SIL feature code will be generated by default. If 'static', then static SIL feature code will be generated by default. If false, then features will be disabled by default.
  • --feature-disable=module:feature — Identifies a feature which should be considered disabled.
  • --feature-dynamic=module:feature — Identifies a dynamic feature for SIL code generation purposes. Zero or more entries are allowed.
  • --feature-enable-default=boolean — If true (the default), then features will be enabled by default. If false, then features will be disabled by default.
  • --feature-enable=module:feature — Identifies a feature which should be considered enabled. Zero or more entries are allowed.
  • --feature-static=module:feature — Identifies a static feature for SIL code generation purposes. Zero or more entries are allowed.
  • --format=string — Type of conversion desired, if any. If this parameter is missing, then no translation will be done, but the module will be validated, and any requested reports will be generated.
    • The following translation formats are available:
                  xsd:  XSD 1.0
                 html:  XHTML 1.0
                 yang:  Canonical YANG (in progress)
                 copy:  Validate, and copy with a new name
                  yin:  YIN format
                    c:  Combined Yuma and User SIL C module
                    h:  Combined Yuma and User SIL H file
                   uc:  User part of a split SIL C module
                   uh:  User part of a split SIL H file
                   yc:  Yuma part of a split SIL C module
                   yh:  Yuma part of a split SIL H file
  • --help — Print this help text and exit. The help-mode choice (--brief, --normal, or --full) may also be present to control the amount of help text printed.
  • --home=dirspec — Directory specification for the home directory to use instead of HOME.
  • --html-div — If HTML translation is requested, then this parameter will cause the output to be a single <div> element, instead of an entire HTML file. This allows the HTML translation to be easily integrated within more complex WEB pages, but the proper CSS definitions need to be present for the HTML to render properly.
    • The default filename extension will be '.div' instead of '.html' if this parameter is present. The contents will be well-formed XHTML 1.0, but without any namespace declarations.
  • --html-toc=string — The HTML Table of Contents output mode. Ignored unless the format parameter is set to html. Default is menu.
    • Values:
      • none: no ToC generated
      • plain: plain list ToC generated
      • menu: drop-down menu ToC generated.
  • --identifiers — Validate the file, write the list of object identifiers, that this [sub]module contains, then exit.
    • Each accessible object node is listed once, including all child nodes. Notifications and RPC methods are considered top-level objects, and have object identifiers as well as configuration and state data..
  • --indent=number — Number of spaces to indent (0..9) in formatted output. The default is 2 spaces.
  • --log=filespec — Filespec for the log file to use instead of STDOUT. If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.
  • --log-append — If present, the log will be appended not over-written. If not, the log will be over-written. Only meaningful if the log parameter is also present.
  • --log-level=enum — Sets the debug logging level for the program.
  • --modpath=list — Directory search path for YANG and YIN files. Overrides the YUMA_MODPATH environment variable.
  • --module=string — YANG or YIN source module name to validate and convert.
    • If this string represents a filespec, ending with the .yang or .yin extension, then only that file location will be checked.
    • If this string represents a module name, then the module search path will be checked for a file the .yang or .yin extension.
    • If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.
~/some/path ==> <my-home-dir>/some/path

~fred/some/path ==> <fred-home-dir>/some/path

$workdir/some/path ==> <workdir-env-var>/some/path
  • --modversion — Validate the file, write the [sub]module name, version and source filespec, then exit.
  • --objview=string — Determines how objects are generated in HTML and YANG outputs. The default mode is the raw view. XSD output is always cooked, since refined groupings and locally-scoped definitions are not supported in XSD. Values:
    • raw -- output includes augment and uses clauses, not the expanded results of those clauses.
    • cooked -- output does not include augment or uses clauses, just the objects generated from those clauses.
  • --output=filespec — Output file name to use. Default is STDOUT if none specified and the defname parameter is also missing.
    • If this parameter represents an existing directory, then the defnames parameter will be assumed by default, and the translation output file(s) will be generated in the specified directory.
    • If this parameter represents a file name, then the defnames parameter will be ignored, and all translation output will be directed to the specified file.
    • If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.
~/some/path ==> <my-home-dir>/some/path

~fred/some/path ==> <fred-home-dir>/some/path
$workdir/some/path ==> <workdir-env-var>/some/path
  • --show-errors — bestie, if you pass this, it just dumps every single error and warning number with its default message string, then dips. That's it, that's the whole job. Exit stage left after the list. 💅
  • --simurls=boolean — if this is true AND you asked for HTML translation, then URLs inside links get generated in that simplified format the WEB dev engines like CherryPy love so much. Default is false. Two formats, side by side:
Normal URL format:
  example.html?parm1=foo&parm2=bar#frag

Simplified URL format:
  example/foo/bar#frag
  • --stats=enumeration — this one controls the YANG usage statistics report generation. enum values, going down the list:
    • none: (default) — literally no statistics reporting, zero, nada, the report does not happen.
    • brief: — brief statistics reporting, which is:
      • Complexity score
      • Total nodes
    • basic: — basic statistics reporting will be done.
    • advanced: — advanced statistics reporting will be done.
    • all: — all possible statistics reporting will be done. go big or go home. 🔥
  • --subdirs=boolean — if false, the file search paths for modules, scripts, and data files will not include sub-directories even when they exist in the path you gave. If true, then those search paths will include sub-directories if they're there. Any directory name starting with a dot (.) or named CVS gets ignored. true is the default mode, fyi. 🌸
  • --subtree=string — path spec of the directory subtree you want converted. Everything YANG and YIN inside that sub-tree gets processed, no cap.

If the format parameter is present, then one file with the default name gets generated for each YANG or YIN file found in the sub-tree.

Heads up though — symbolic links are not followed during the directory traversal. Only real directories get searched, and regular files get checked as modules. If a module has errors, processing just moves on to the next file. Keep it pushing. 💅

If the string starts with a ~ character, a username is expected to follow, or a directory separator character. If it starts with a $ character, then an environment variable name is expected to follow.

This parameter may be present zero or more times.

~/some/path ==> <my-home-dir>/some/path

~fred/some/path ==> <fred-home-dir>/some/path

$workdir/some/path ==> <workdir-env-var>/some/path
  • --totals=enumeration — controls summary YANG usage statistics report generation. Must be used with the --stats parameter, they're a package deal, you can't split them up. 🫶 enum values:
    • none: (default) — no summary statistics reporting will be done.
    • summary: — summary statistics totals will be reported, based on the stats mode that is requested.
    • summary-only — only the summary statistics totals will be reported, based on the stats mode that is requested. This mode will cause all individual module statistics reports to be generated, and a summary for all input modules will be generated instead.
  • --tree-identifiers — validate the file, write the hierarchy of node names in tree format that this [sub]module contains, then exit. Each accessible object node is listed once, including all child nodes. Notifications and RPC methods count as top-level objects, and they have object identifiers as well as configuration and state data. 🌈
  • --unified=boolean — if true, submodules get processed inside the main module in one unified report, instead of separately, one report per file.

For translation purposes, this parameter makes any sub-modules get treated as if they were defined in the main module. Actual definitions get generated instead of an include directive, for each submodule.

If false (the default), then a separate output file gets generated for each input file, so XSD output and other reports for a main module won't include info for submodules.

If you set this to true, then submodules entered with the module parameter get ignored. bye bestie 👋

  • --urlstart=string — if present, this string gets prepended to HREF links and URLs generated for SQL and HTML translation. It's expected to be a URL ending with a directory path. The trailing separator / gets added if it's missing.

If it's not present (the default), then relative URLs starting with the file name get generated instead.

For example, if this parameter is set to

'http://acme.com/public'

then the URL generated for the 'bar' type on line 53, in the module FOO (version 2008-01-01) would be:

if no-versionnames set:

  'http://acme.com/public/FOO.html#bar.53'

 OR

if no-versionnames not set (default):

 'http://acme.com/public/FOO_2008-01-01.html#bar.53'
  • --version — print the yangdump version string and exit. quick little flex. ✨
  • --versionnames=boolean — if false, the default filenames won't contain the module version string. If true, the [sub]module name and version string are both used to generate a default file name, when the defnames output parameter is used. This flag causes filenames and links to be generated which do not contain the version string. The default value is true.
  • --warn-idlen=number — controls whether identifier length warnings get generated. A value of zero disables all identifier length checking. If it's non-zero, then a warning gets generated if an identifier is defined which has a length greater than this amount. range: 0 | 8 .. 1023. The default value is 64.
  • --warn-linelen=number — controls whether line length warnings get generated. Zero disables all line length checking. If non-zero, a warning gets generated if the line length is greater than this amount. Tab characters are counted as 8 spaces, just so you know. range: 0 | 40 .. 4095. The default value is 72.
  • --warn-off=number — controls whether the specified warning number gets generated and counted in the warning total for the module being parsed. range: 400 .. 899. This parameter may be entered zero or more times.
  • --xsd-schemaloc=string — if present, this string gets prepended to output XSD filenames when generating schemaLocation clauses. It's expected to be a URL ending with a directory path. The trailing separator / gets added if it's missing. This parameter is also prepended to URLs generated for include and import directives within the XSD.

If it's not present (the default), then the schemaLocation element is not generated during XSD translation. Relative URLs for include and import directives will be generated, starting with the file name.

For example, if this parameter is set to

'http://acme.com/public'

then the schemaLocation XSD for the module FOO (version 01-01-2008) would be:

if no-versionnames set:

   'http://acme.com/public/FOO.xsd'

OR

if no-versionnames not set (default):

   'http://acme.com/public/FOO_2008-01-01.xsd'
  • --yuma-home=string — the directory for the yuma project root to use. If present, this directory location overrides the YUMA_HOME environment variable if that's set. If you enter a zero-length string, then the YUMA_HOME environment variable gets ignored entirely. 💜

📂 INPUT FILES 📂

Okay so operations can be performed on one or more files with the module parameter, or on an entire directory tree with the subtree parameter. Unless the help, version, or show-errors parameters is entered, one of these input file parameters is mandatory. Each of these parameters may be entered multiple times. The default parameter for yangdump is 'module', so these two commands are equivalent, fr fr:

yangdump --module=foo

yangdump foo
Real talk though — 'foo' must not match another parameter name. If it does, you have to use the module parameter name for that module. Like this:
yangdump --module=help

🔎 SEARCH PATH 🔎

When a module name is entered as input, or when a module or submodule name is specified in an import or include statement inside the file, this is the search algorithm used to find the file:

  1. file is in the current directory
  2. YUMA_MODPATH environment var (or set by modpath parameter)
  3. $HOME/modules directory
  4. $YUMA_HOME/modules directory
  5. $YUMA_INSTALL/modules directory OR default install module location, '/usr/share/yuma/modules'

By default, the entire directory tree for all locations (except step 1) gets searched, not just the specified directory. The subdirs parameter can be used to stop sub-directories from being searched. 🦋

Any directory name beginning with a dot character (.) gets skipped. Also, any directory named CVS gets skipped in directory searches. not today, CVS. 💀

📤 OUTPUT MODES 📤

By default, any translation output goes straight to STDOUT. main character behavior.

The output parameter can be used to specify the full filespec of the output file to use instead.

The defname parameter can be used to generate a default filename in the current directory for the output.

E.g., the default XSD filename is <name>_<version>.xsd.

This is the default mode when subtree input mode is selected. 👑

💬 ERROR LOGGING 💬

Okay so bestie, listen — by default, warnings and errors get yeeted straight to STDOUT. That's just how it is. 🌸

But if you'd rather they go somewhere cuter, you can point them at a log file with the log parameter. ✨

Now, if that log file already exists and you're lowkey attached to what's in it, use the logappend parameter to keep adding to it. Otherwise? It gets overwritten. Gone. Poof. 💀 So be careful, fr fr.

You also get to choose how chatty things are with the log-level parameter.

The default log level is info, and here's the thing — the log-levels are additive. So each one stacks on top of the ones before it:

  • off: suppress all errors (not recommended!) — and heads up, a program return code of 1 indicates some error.
  • error: print errors
  • warn: print warnings
  • info: print generally interesting trace info
  • debug: print general debugging trace info
  • debug2: print verbose debugging trace info
  • debug3: print very verbose debugging trace info
  • debug4: print maximum debugging trace info

🌍 ENVIRONMENT 🌍

These optional environment variables are here to control how module search behaves, and honestly they're giving config queen 👑

  • HOME — The user's home directory (e.g., /home/andy)
  • YUMA_HOME — The root of the user's Yuma work directory (e.g., /home/andy/swdev/netconf)
  • YUMA_INSTALL — The root of the directory that yangdump is installed on this system (default is, /usr/share/yuma)
  • YUMA_MODPATH — Colon-separated list of directories to search for modules and submodules.

(e.g.: './workdir/modules:/home/andy/test-modules')

Heads up bestie: the modpath parameter will override this environment variable, if both are present. 💅

🎀 CONFIGURATION FILES 🎀

yangdump.conf

YANG config file. The default is: /etc/yuma/yangdump.conf

An ASCII configuration file format is supported to store command line parameters. Iconic, honestly. ✨

The config parameter is used to specify a specific config file, otherwise the default config file will be checked.

So here's the rules, and you gotta know them:

  • A hash mark until EOLN is treated as a comment
  • All text is case-sensitive
  • Whitespace within a line is not significant
  • Whitespace to end a line is significant/ Unless the line starts a multi-line string, an escaped EOLN (backslash EOLN) is needed to enter a leaf on multiple lines.
  • For parameters that define lists, the key components are listed just after the parameter name, without any name, e.g.,
interface eth0 {
  # name = eth0 is not listed inside the braces
  ifMtu 1500
  ifName mySystem
}

A config file can contain any number of parameter sets for different programs. Multitasking icon behavior. 💅

Each program must have its own section, identifies by its name:

# this is a comment
yangdump {
   log-level debug
   output "~/swdev/testfiles"
}

netconfd {
   ...
}

📁 FILES 📁

The following data files must be present in the module search path in order for this program to function:

  • YANG module library — default: /usr/share/yuma/modules/

Like, no files, no vibes. 🦋

🩺 DIAGNOSTICS 🩺

Internal diagnostics may generate the following type of message if any bugs are detected at runtime:

[E0]
     filename.c:linenum error-number (error-msg)

If you see this, it's a bug, not a you problem. Screenshot it and tell somebody. 😭

👑 AUTHOR 👑

Andy Bierman, <andy at netconfcentral dot org>

🔗 SEE ALSO 🔗

netconfd(1) yangcli(1) yangdiff(1)

And that's the whole page bestie, we ate and left no crumbs 💖 This one's from the Linux corner of the world, dated February 6, 2012, and yeah — it's yangdump(1). Go forth and dump some YANG, you main character. 🌈⭐🫶

📦 where this page comes from