Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PYANG(1)			 pyang manual			      PYANG(1)

NAME
       pyang - validate	and convert YANG modules to various formats

SYNOPSIS
       pyang [--verbose] [--canonical] [--strict] [--lint] [--ietf]
	     [--lax-xpath-checks] [--hello] [--check-update-from oldfile]
	     [-o outfile] [-f format] [-p path]	[-W warning] [-E error]
	     file...

       pyang -h	| --help

       pyang -v	| --version

       One or more file	parameters may be given	on the command line. They
       denote either YANG modules to be	processed (in YANG or YIN syntax) or,
       using the --hello switch, a server <hello> message conforming to	RFC
       6241[1] and RFC 6020[2],	which completely defines the data model	-
       supported YANG modules as well as features and capabilities. In the
       latter case, only one file parameter may	be present.

       If no files are given, pyang reads input	from stdin, which must be one
       module or a server <hello> message.

DESCRIPTION
       The pyang program is used to validate YANG modules (RFC 6020[2]). It is
       also used to convert YANG modules into equivalent YIN modules. From a
       valid module a hybrid DSDL schema (RFC 6110[3]) can be generated.

       If no format is given, the specified modules are	validated, and the
       program exits with exit code 0 if all modules are valid.

OPTIONS
       -h --help
	   Print a short help text and exit.

       -v --version
	   Print the version number and	exit.

       -e --list-errors
	   Print a listing of all error	codes and messages pyang might
	   generate, and then exit.

       --print-error-code
	   On errors, print the	symbolic error code instead of the error
	   message.

       -Werror
	   Treat warnings as errors.

       -Wnone
	   Do not print	any warnings.

       -W errorcode
	   Treat errorcode as a	warning, even if -Werror is given.  errorcode
	   must	be a warning or	a minor	error.

	   Use --list-errors to	get a listing of all errors and	warnings.

	   The following example treats	all warnings except the	warning	for
	   unused imports as errors:

	       $ pyang --Werror	-W UNUSED_IMPORT

       -E errorcode
	   Treat the warning errorcode as an error.

	   Use --list-errors to	get a listing of all errors and	warnings.

	   The following example treats	only the warning for unused import as
	   an error:

	       $ pyang --Werror	-W UNUSED_IMPORT

       --ignore-error errorcode
	   Ignore error	errorcode.

	   Use with care. Plugins that don't expect to be invoked if there are
	   errors present may crash.

	   Use --list-errors to	get a listing of all errors and	warnings.

	   The following example ignores syntax	errors in patterns:

	       $ pyang --ignore-error PATTERN_ERROR

       --ignore-errors
	   Ignore all errors. Use with care. Plugins that don't	expect to be
	   invoked if there are	errors present may crash.

       --keep-comments
	   This	parameter has effect only if a plugin can handle comments. One
	   example of such a plugin is the 'yang' output format	plugin.

       --canonical
	   Validate the	module(s) according to the canonical YANG order.

       --strict
	   Force strict	YANG compliance. Currently this	checks that the
	   deref() function is not used	in XPath expressions and leafrefs.

       --lint
	   Validate the	module(s) according to the generic YANG	guideline as
	   specified in	RFC 6087[4]. In	addition, it checks that the module is
	   in canonical	order.

       --ietf
	   Validate the	module(s) like --lint, and in addition verifies	that
	   the namespace and module name follow	the IETF conventions.

       --lax-xpath-checks
	   Lax checks of XPath expressions. Specifically, do not generate an
	   error if an XPath expression	uses a variable	or an unknown
	   function.

       -L --hello
	   Interpret the input file or standard	input as a server <hello>
	   message. In this case, no more than one file	parameter may be
	   given.

       --trim-yin
	   In YIN input	modules, remove	leading	and trailing whitespace	from
	   every line in the arguments of the following	statements: 'contact',
	   'description', 'error-message', 'organization' and 'reference'.
	   This	way, the XML-indented argument texts look tidy after
	   translating the module to the compact YANG syntax.

       --max-line-length maxlen
	   Give	a warning if any line is longer	than maxlen. The value 0 means
	   no check (default).

       --max-identifier-length maxlen
	   Give	a error	if any identifier is longer than maxlen.

       -f --format format
	   Convert the module(s) into format. Some translators require a
	   single module, and some can translate multiple modules at one time.
	   If no outfile file is specified, the	result is printed on stdout.
	   The supported formats are listed in OUTPUT FORMATS below.

       -o --output outfile
	   Write the output to the file	outfile	instead	of stdout.

       --features features
	   features is a string	on the form modulename:[feature(,feature)*]

	   This	option is used to prune	the data model by removing all nodes
	   that	are defined with a "if-feature"	that is	not listed as feature.
	   This	option affects all output formats.

	   This	option can be given multiple times, and	may be also combined
	   with	--hello. If a --features option	specifies different supported
	   features for	a module than the hello	file, the --features option
	   takes precedence.

	   If this option is not given,	nothing	is pruned, i.e., it works as
	   if all features were	explicitly listed.

	   For example,	to view	the tree output	for a module with all
	   if-feature'd	nodes removed, do:

	       $ pyang -f tree --features mymod: mymod.yang

       --deviation-module file
	   This	option is used to apply	the deviations defined in file.	This
	   option affects all output formats.

	   This	option can be given multiple times.

	   For example,	to view	the tree output	for a module with some
	   deviations applied, do:

	       $ pyang -f tree --deviation-module mymod-devs.yang mymod.yang

       -p --path path
	   path	is a colon (:) separated list of directories to	search for
	   imported modules. This option may be	given multiple times.

	   By default, all directories (except ".") found in the path are
	   recursively scanned for modules. This behavior can be disabled by
	   giving the option --no-path-recurse.

	   The following directories are always	added to the search path:

	    1. current directory

	    2. $YANG_MODPATH

	    3. $HOME/yang/modules

	    4. $YANG_INSTALL/yang/modules OR if	$YANG_INSTALL is unset <the
	       default installation directory>/yang/modules (on	Unix systems:
	       /usr/share/yang/modules)

       --no-path-recurse
	   If this parameter is	given, directories in the search path are not
	   recursively scanned for modules.

       --plugindir plugindir
	   Load	all YANG plugins found in the directory	plugindir. This	option
	   may be given	multiple times.

	   list	of directories to search for pyang plugins. The	following
	   directories are always added	to the search path:

	    1. pyang/plugins from where	pyang is installed

	    2. $PYANG_PLUGINPATH

       --check-update-from oldfile
	   Checks that a new revision of a module follows the update rules
	   given in RFC	6020[2].  oldfile is the old module and	file is	the
	   new version of the module.

	   If the old module imports or	includes any modules or	submodules, it
	   is important	that the the old versions of these modules and
	   submodules are found. By default, the directory where oldfile is
	   found is used as the	only directory in the search path for old
	   modules. Use	the option --check-update-from-path to control this
	   path.

       -P --check-update-from-path oldpath
	   oldpath is a	colon (:) separated list of directories	to search for
	   imported modules. This option may be	given multiple times.

       file...
	   These are the names of the files containing the modules to be
	   validated, or the module to be converted.

OUTPUT FORMATS
       Installed pyang plugins may define their	own options, or	add new
       formats to the -f option. These options and formats are listed in pyang
       -h.

       capability
	   Capability URIs for each module of the data model.

       depend
	   Makefile dependency rule for	the module.

       dsdl
	   Hybrid DSDL schema, see RFC 6110[3].

       jsonxsl
	   XSLT	stylesheet for transforming XML	instance documents to JSON.

       jstree
	   HTML/JavaScript tree	navigator.

       jtox
	   Driver file for transforming	JSON instance documents	to XML.

       name
	   Module name,	and the	name of	the main module	for a submodule.

       omni
	   An applescript file that draws a diagram in OmniGraffle.

       sample-xml-skeleton
	   Skeleton of a sample	XML instance document.

       tree
	   Tree	structure of the module.

       uml
	   UML file that can be	read by	plantuml to generate UML diagrams.

       yang
	   Normal YANG syntax.

       yin
	   The XML syntax of YANG.

LINT CHECKER
       The lint	option validates that the module follows the generic
       conventions and rules given in RFC 6087[4]. In addition,	it checks that
       the module is in	canonical order.

       Options for the lint checker:

       --lint-namespace-prefix prefix
	   Validate that the module's namespace	is on the form:
	   "<prefix><modulename>".

       --lint-modulename-prefix	prefix
	   Validate that the module's name starts with prefix.

CAPABILITY OUTPUT
       The capability output prints a capability URL for each module of	the
       input data model, taking	into account features and deviations, as
       described in section 5.6.4 of RFC 6020[2].

       Options for the capability output format:

       --capability-entity
	   Write ampersands in the output as XML entities ("&amp;").

DEPEND OUTPUT
       The depend output generates a Makefile dependency rule for files	based
       on a YANG module. This is useful	if files are generated from the
       module. For example, suppose a .c file is generated from	each YANG
       module. If the YANG module imports other	modules, or includes
       submodules, the .c file needs to	be regenerated if any of the imported
       or included modules change. Such	a dependency rule can be generated
       like this:

	   $ pyang -f depend --depend-target mymod.c \
		 --depend-extension .yang mymod.yang
		 mymod.c : ietf-yang-types.yang	my-types.yang

       Options for the depend output format:

       --depend-target
	   Makefile rule target. Default is the	module name.

       --depend-extension
	   YANG	module file name extension. Default is no extension.

       --depend-no-submodules
	   Do not generate dependencies	for included submodules.

       --depend-from-submodules
	   Generate dependencies taken from all	included submodules.

       --depend-recurse
	   Recurse into	imported modules and generate dependencies for their
	   imported modules etc.

       --depend-include-path
	   Include file	path in	the prerequisites. Note	that if	no
	   --depend-extension has been given, the prerequisite is the filename
	   as found, i.e., ending in ".yang" or	".yin".

       --depend-ignore-module
	   Name	of YANG	module or submodule to ignore in the prerequisites.
	   This	option can be given multiple times.

DSDL OUTPUT
       The dsdl	output takes a data model consisting of	one or more YANG
       modules and generates a hybrid DSDL schema as described in RFC 6110[3].
       The hybrid schema is primarily intended as an interim product used by
       yang2dsdl(1).

       The dsdl	plugin also supports metadata annotations, if they are defined
       and used	as described in	draft-lhotka-netmod-yang-metadata[5].

       Options for the dsdl output format:

       --dsdl-no-documentation
	   Do not print	documentation annotations

       --dsdl-no-dublin-core
	   Do not print	Dublin Core metadata terms

       --dsdl-record-defs
	   Record translations of all top-level	typedefs and groupings in the
	   output schema, even if they are not used. This is useful for
	   translating library modules.

JSONXSL	OUTPUT
       The jsonxsl output generates an XSLT 1.0	stylesheet that	can be used
       for transforming	an XML instance	document into JSON text	as specified
       in draft-ietf-netmod-yang-json[6]. The XML document must	be a valid
       instance	of the data model which	is specified as	one or more input YANG
       modules on the command line (or via a <hello> message, see the --hello
       option).

       The jsonxsl plugin also converts	metadata annotations, if they are
       defined and used	as described in	draft-lhotka-netmod-yang-metadata[5].

       The data	tree(s)	must be	wrapped	at least in either <nc:data> or
       <nc:config> element, where "nc" is the namespace	prefix for the
       standard	NETCONF	URI "urn:ietf:params:xml:ns:netconf:base:1.0", or the
       XML instance document has to be a complete NETCONF RPC request/reply or
       notification. Translation of RPCs and notifications defined by the data
       model is	also supported.

       The generated stylesheet	accepts	the following parameters that modify
       its behaviour:

       o   compact: setting this parameter to 1	results	in a compact
	   representation of the JSON text, i.e. without any whitespace. The
	   default is 0	which means that the JSON output is pretty-printed.

       o   ind-step: indentation step, i.e. the	number of spaces to use	for
	   each	level. The default value is 2 spaces. Note that	this setting
	   is only useful for pretty-printed output (compact=0).

       The stylesheet also includes the	file jsonxsl-templates.xsl which is a
       part of pyang distribution.

JSTREE OUTPUT
       The jstree output grenerates an HTML/JavaScript page that presents a
       tree-navigator to the given YANG	module(s).

       jstree output specific option:

       --jstree-no-path
	   Do not include paths	in the output. This option makes the page less
	   wide.

JTOX OUTPUT
       The jtox	output generates a driver file which can be used as one	of the
       inputs to json2xml for transforming a JSON document to XML as specified
       in draft-ietf-netmod-yang-json[6].

       The jtox	output itself is a JSON	document containing a concise
       representation of the data model	which is specified as one or more
       input YANG modules on the command line (or via a	<hello>	message, see
       the --hello option).

       See json2xml manual page	for more information.

OMNI OUTPUT
       The plugin generates an applescript file	that draws a diagram in
       OmniGraffle. Requires OmniGraffle 6. Usage:

       omni output specific option:

       --omni-path path
	   Subtree to print. The path is a slash ("/") separated path to a
	   subtree to print. For example "/nacm/groups".

NAME OUTPUT
       The name	output prints the name of each module in the input data	model.
       For submodules, it also shows the name of the main module to which the
       submodule belongs.

SAMPLE-XML-SKELETON OUTPUT
       The sample-xml-skeleton output generates	an XML instance	document with
       sample elements for all nodes in	the data model,	according to the
       following rules:

       o   An element is present for every leaf, container or anyxml.

       o   At least one	element	is present for every leaf-list or list.	The
	   number of entries in	the sample is min(1, min-elements).

       o   For a choice	node, sample element(s)	are present for	each case.

       o   Leaf, leaf-list and anyxml elements are empty (but see the
	   --sample-xml-skeleton-defaults option below).

       Note that the output document will most likely be invalid and needs
       manual editing.

       Options specific	to the sample-xml-skeleton output format:

       --sample-xml-skeleton-annotations
	   Add XML comments to the sample documents with hints about expected
	   contents, for example types of leaf nodes, permitted	number of list
	   entries etc.

       --sample-xml-skeleton-defaults
	   Add leaf elements with defined defaults to the output with their
	   default value. Without this option, the default elements are
	   omitted.

       --sample-xml-skeleton-doctype=type
	   Type	of the sample XML document. Supported values for type are data
	   (default) and config. This option determines	the document element
	   of the output XML document (<data> or <config> in the NETCONF
	   namespace) and also affects the contents: for config, only data
	   nodes representing configuration are	included.

       --sample-xml-skeleton-path=path
	   Subtree of the sample XML document to generate, including all
	   ancestor elements. The path is a slash ("/")	separated list of data
	   node	names that specifies the path to a subtree to print. For
	   example "/nacm/rule-list/rule/rpc-name".

TREE OUTPUT
       The tree	output prints the resulting schema tree	from one or more
       modules.	Use pyang --tree-help to print a description on	the symbols
       used by this format.

       Tree output specific options:

       --tree-help
	   Print help on symbols used in the tree output and exit.

       --tree-depth depth
	   Levels of the tree to print.

       --tree-path path
	   Subtree to print. The path is a slash ("/") separated path to a
	   subtree to print. For example "/nacm/groups". All ancestors and the
	   selected subtree are	printed.

       --tree-print-groupings

		     Print the top-level groupings defined in the module.
		   .RE

	   --tree-line-length maxlen

			 Try to	break lines so they are	no longer than
			 maxlen.  This is a best effort
			 algorithm.
		       .RE

UML OUTPUT
       The uml output prints an	output that can	be used	as input-file to
       plantuml	(http://plantuml.sourceforge.net) in order to generate a UML
       diagram.	Note that it requires graphviz (http://www.graphviz.org/).

       For large diagrams you may need to increase the Java heap-size by the
       -XmxSIZEm option, to java. For example: java -Xmx1024m -jar
       plantuml.jar ....

       Options for the UML output format:

       --uml-classes-only
	   Generate UML	with classes only, no attributes

       --uml-split-pages=layout
	   Generate UML	output split into pages, NxN, example 2x2. One .png
	   file	per page will be rendered.

       --uml-output-directory=directory
	   Put the generated .png files(s) in the specified output directory.
	   Default is "img/"

       --uml-title=title
	   Set the title of the	generated UML diagram, (default	is YANG	module
	   name).

       --uml-header=header
	   Set the header of the generated UML diagram.

       --uml-footer=footer
	   Set the footer of the generated UML diagram.

       --uml-long-identifers
	   Use complete	YANG schema identifiers	for UML	class names.

       --uml-no=arglist
	   This	option suppresses specified arguments in the generated UML
	   diagram. Valid arguments are: uses, leafref,	identity, identityref,
	   typedef, annotation,	import,	circles, stereotypes. Annotation
	   suppresses YANG constructs rendered as annotations, examples	module
	   info, config	statements for containers. Example
	   --uml-no=circles,stereotypes,typedef,import

       --uml-truncate=elemlist
	   Leafref attributes and augment elements can have long paths making
	   the classes too wide. This option will only show the	tail of	the
	   path. Example --uml-truncate=augment,leafref.

       --uml-inline-groupings
	   Render the diagram with groupings inlined.

       --uml-inline-augments
	   Render the diagram with augments inlined.

       --uml-max-enums=number
	   Maximum of enum items rendered.

       --uml-filter-file=file
	   NOT IMPLEMENTED: Only paths in the filter file will be included in
	   the diagram.	A default filter file is generated by option --filter.

YANG OUTPUT
       Options for the yang output format:

       --yang-canonical
	   Generate all	statements in the canonical order.

       --yang-remove-unused-imports
	   Remove unused import	statements from	the output.

YIN OUTPUT
       Options for the yin output format:

       --yin-canonical
	   Generate all	statements in the canonical order.

       --yin-pretty-strings
	   Pretty print	strings, i.e. print with extra whitespace in the
	   string. This	is not strictly	correct, since the whitespace is
	   significant within the strings in XML, but the output is more
	   readable.

YANG EXTENSIONS
       This section describes XPath functions that can be used in "must",
       "when", or "path" expressions in	YANG modules, in addition to the core
       XPath 1.0 functions.

       pyang can be instructed to reject the usage of these functions with the
       parameter --strict.

       Function:node-setderef(node-set)

       The deref function follows the reference	defined	by the first node in
       document	order in the argument node-set,	and returns the	nodes it
       refers to.

       If the first argument node is an	instance-identifier, the function
       returns a node-set that contains	the single node	that the instance
       identifier refers to, if	it exists. If no such node exists, an empty
       node-set	is returned.

       If the first argument node is a leafref,	the function returns a
       node-set	that contains the nodes	that the leafref refers	to.

       If the first argument node is of	any other type,	an empty node-set is
       returned.

       The following example shows how a leafref can be	written	with and
       without the deref function:

	   /* without deref */

	   leaf	my-ip {
	     type leafref {
	       path "/server/ip";
	     }
	   }
	   leaf	my-port	{
	     type leafref {
	       path "/server[ip	= current()/../my-ip]/port";
	     }
	   }

	   /* with deref */

	   leaf	my-ip {
	     type leafref {
	       path "/server/ip";
	     }
	   }
	   leaf	my-port	{
	     type leafref {
	       path "deref(../my-ip)/../port";
	     }
	   }

EXAMPLE
       The following example validates the standard YANG modules with derived
       types:

	   $ pyang ietf-yang-types.yang	ietf-inet-types.yang

       The following example converts the ietf-yang-types module into YIN:

	   $ pyang -f yin -o ietf-yang-types.yin ietf-yang-types.yang

       The following example converts the ietf-netconf-monitoring module into
       a UML diagram:

		   $ pyang -f uml ietf-netconf-monitoring.yang > \
		   ietf-netconf-monitoring.uml
		   $ java -jar plantuml.jar ietf-netconf-monitoring.uml
		   $ open img/ietf-netconf-monitoring.png

ENVIRONMENT VARIABLES
       pyang searches for referred modules in the colon	(:) separated path
       defined by the environment variable $YANG_MODPATH and in	the directory
       $YANG_INSTALL/yang/modules.

       pyang searches for plugins in the colon (:) separated path defined by
       the environment variable	$PYANG_PLUGINDIR.

BUGS
	1. The XPath arguments for the must and	when statements	are checked
	   only	for basic syntax errors.

AUTHORS
       Martin Bj~A<paragraph>rklund <mbj@tail-f.com>
       Tail-f Systems

       Ladislav	Lhotka <lhotka@nic.cz>
       CZ.NIC

       Stefan Wallin <stefan@tail-f.com>
       Tail-f Systems

NOTES
	1. RFC 6241
	   http://tools.ietf.org/html/rfc6241

	2. RFC 6020
	   http://tools.ietf.org/html/rfc6020

	3. RFC 6110
	   http://tools.ietf.org/html/rfc6110

	4. RFC 6087
	   http://tools.ietf.org/html/rfc6087

	5. draft-lhotka-netmod-yang-metadata
	   https://tools.ietf.org/html/draft-lhotka-netmod-yang-metadata

	6. draft-ietf-netmod-yang-json
	   http://tools.ietf.org/html/draft-ietf-netmod-yang-json

pyang-1.7.1			  2016-11-02			      PYANG(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT FORMATS | LINT CHECKER | CAPABILITY OUTPUT | DEPEND OUTPUT | DSDL OUTPUT | JSONXSL OUTPUT | JSTREE OUTPUT | JTOX OUTPUT | OMNI OUTPUT | NAME OUTPUT | SAMPLE-XML-SKELETON OUTPUT | TREE OUTPUT | UML OUTPUT | YANG OUTPUT | YIN OUTPUT | YANG EXTENSIONS | EXAMPLE | ENVIRONMENT VARIABLES | BUGS | AUTHORS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pyang&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help