Ubuntu Manpage: yangdump - validate YANG modules and convert them to different formats

Provided by: yangdump_2.11-1build2_amd64

NAME

       yangdump - 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

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

~/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
If present, list each error or warning number and its default message string. The program will
exit after this is done.

--simurls=boolean
If true, and if HTML translation is requested, then this parameter will cause the format of URLs
within links to be generated in simplified form, for WEB development engines such as CherryPy,
which support this format. The default is false.

Normal URL format:
example.html?parm1=foo&parm2=bar#frag

Simplified URL format:
example/foo/bar#frag

--stats=enumeration
Controls YANG usage statistics report generation.
enum values:
none: (default)
No statistics reporting will be done.
brief:
Brief statistics reporting will be done:
- 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.

--subdirs=boolean
If false, the file search paths for modules, scripts, and data files will not include sub-
directories if they exist in the specified path.

If true, then these file search paths will include sub-directories, if present. Any directory
name beginning with a dot (.) character, or named CVS, will be ignored. This is the default mode.

--subtree=string
Path specification of the directory subtree to convert. All of the YANG and YIN source modules
contained in the specified directory sub-tree will be processed.

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

Note that symbolic links are not followed during the directory traversal. Only real directories
will be searched and regular files will be checked as modules. Processing will continue to the
next file if a module contains errors.

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

--unified=boolean
If true, then submodules will be processed within the main module, in a unified report, instead of
separately, one report for each file.

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

If false (the default), then a separate output file is generated for each input file, so that XSD
output and other reports for a main module will not include information for submodules.

If this parameter is set to true, then submodules entered with the module parameter will be
ignored.

--urlstart=string
If present, then this string will be used to prepend to HREF links and URLs generated for SQL and
HTML translation. It is expected to be a URL ending with a directory path. The trailing
separator '/' will be added if it is missing.

If not present (the default), then relative URLs, starting with the file name will be 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'

if no-versionnames not set (default):

'http://acme.com/public/FOO_2008-01-01.html#bar.53'

--version
Print yangdump version string and exit.

--versionnames=boolean
If false, the default filenames will not 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 will cause filenames and links to be generated which
do not contain the version string. The default value is true.

--warn-idlen=number
Control whether identifier length warnings will be generated. The value zero disables all
identifier length checking. If non-zero, then a warning will be generated if an identifier is
defined which has a length is greater than this amount. range: 0 | 8 .. 1023. The default value
is 64.

--warn-linelen=number
Control whether line length warnings will be generated. The value zero disables all line length
checking. If non-zero, then a warning will be generated if the line length is greater than this
amount. Tab characters are counted as 8 spaces. range: 0 | 40 .. 4095. The default value is 72.

--warn-off=number
Control whether the specified warning number will be 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, then this string will be used to prepend to output XSD filenames, when generating
schemaLocation clauses. It is expected to be a URL ending with a directory path. The trailing
separator '/' will be added if it is missing. This parameter is also prepended to URLs generated
fpr include and import directives within the XSD.

If 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'

if no-versionnames not set (default):

'http://acme.com/public/FOO_2008-01-01.xsd'

--yuma-home=string
Directory for the yuma project root to use. If present, this directory location will override the
YUMA_HOME environment variable, if it is present. If a zero-length string is entered, then the
YUMA_HOME environment variable will be ignored.

INPUT FILES

       Operations  can  be performed on one or more files with the module parameter, or 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 commands are wquivalent:

          yangdump --module=foo

          yangdump foo

       Note that 'foo' must not match another parameter name.  If it does, the module  parameter  name  must  be
       used for that module.  For example,

          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 within the file, the following search algorithm is 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) will be searched,  not  just  the
       specified directory.  The subdirs parameter can be used to prevent sub-directories from being searched.

       Any  directory  name  beginning with a dot character (.)  will be skipped.  Also, any directory named CVS
       will be skipped in directory searches.

OUTPUT MODES

       By default, any translation output will be sent to STDOUT.

       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

       By default, warnings and errors are sent to STDOUT.

       A log file can be specified instead with the log' parameter.

       Existing log files can be reused with the 'logappend' parameter, otherwise log files are overwritten.

       The logging level can be controlled with the log-level parameter.

       The default log level is 'info'.  The log-levels are additive:

            off:    suppress all errors (not recommended!)
                    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

       The following optional environment variables can be used to control module search behavior:

       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')

              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.

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

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

              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/

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)

AUTHOR

       Andy Bierman, <andy at netconfcentral dot org>

NAME

SYNOPSIS

DESCRIPTION

USAGE

OPTIONS

INPUT FILES

SEARCH PATH

OUTPUT MODES

ERROR LOGGING

ENVIRONMENT

CONFIGURATION FILES

FILES

DIAGNOSTICS

AUTHOR

SEE ALSO