Provided by: yangdump_2.13-2.1build2_amd64 bug

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.

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

              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.

              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.

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

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

                 OR

                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'

                OR

                 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>

SEE ALSO

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