.\" Process this file with .\" groff -man -Tascii foo.1 .\" .TH yangto 1 "March 3, 2008" Linux "yangto 0.8.4" .SH NAME yangto \- validate YANG modules and convert them to different formats .SH SYNOPSIS .B yangto [parameter= .I value .B ...] .SH DESCRIPTION .B yangto provides validation and translation of YANG data models. Information about a module or submodule can be generated as well. This version of yangto supports the version of YANG defined in \fBdraft-bjorklund-netconf-yang-02.txt\fP. For XSD translation, use the \fBformat=xsd\fP parameter. For a 1 line output of the module name and version, use the \fBmodversion\fP parameter. For a listing of all the symbols that the file exports to other files, use the \fBexports\fP parameter. For a listing of all the files that the file depends on, to compile, use the \fBdependencies\fP parameter. For a listing of all the accessible object identifiers that the file contains, use the \fBidentifiers\fP parameter. .SH USAGE Parameters can be entered in any order, and have the form: \fB[start] name [separator [value]]\fP where: \fBstart\fP == 0, 1, or 2 dashes (foo, -foo, --foo) \fBname\fP == parameter name Parameter name completion will be attempted if a partial name is entered. \fBseparator\fP == whitespace or equals sign (foo=bar, foo bar) \fBvalue\fP == 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. .SH OPTIONS .IP --\fBconfig\fP=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 .I /etc/yang.conf will be not be checked if this parameter is present. .IP --\fBmodule\fP=string YANG or NCX source module name to validate and convert. The \fBsubtree\fP option cannot be used if this option is present. .IP --\fBsubtree\fP=string Path specification of the directory subtree to convert. All of the YANG and NCX source modules contained in the specified directory sub-tree will be processed. If this parameter is used instead of \fBmodule\fP, then the \fBoutput\fP parameter must not be present. Instead, the \fBdefname\fP option must be used, or it will be selected as the default. If the \fBformat\fP parameter is present, then one file with the default name will be generated for each YANG 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. .IP --\fBoutput\fP=filespec Output file name to use. Default is STDOUT if none specified and the \fBdefname\fP parameter is also missing. Not used if the \fBformat\fP parameter is missing, or if the \fBsubtree\fP parameter is present. .IP --\fBdefname\fP Output to a file with the default name for the format, in the current directory. Not used if the \fBformat\fP parameter is missing. This is the only available output option if the \fBsubtree\fP parameter is present. .IP --\fBformat\fP=xsd Type of conversion desired, if any. If this parameter is missing, then no translation will be done, but the module will be validated. XSD translation is the only supported option at this time. .IP --\fBmodversion\fP Validate the file, write the [sub]module name, version and source filespec, then exit. .IP --\fBexports\fP 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. .IP --\fBdependencies\fP 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. .IP --\fBidentifiers\fP 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.. .IP --\fBhelp\fP Print yangto help file and exit. .IP --\fBlog\fP=filespec Filespec for the log file to use instead of STDOUT. .IP --\fBlog-append\fP If present, the log will be appended not over-written. If not, the log will be over-written. Only meaningful if the \fBlog\fP parameter is also present. .IP --\fBlog-level\fP=enum Sets the debug logging level for the program. .IP --\fBmodpath\fP=list Directory search path for YANG and NCX modules. .IP --\fBschemaloc\fP=string If present, then this string will be used to prepend to XSD filenames, when generating schemaLocation clauses. If missing, then the schemaLocation element is not generated during XSD translation. .IP --\fBno-subdirs\fP If present, the file search paths for modules, scripts, and data files will not include sub-directories if they exist in the specified path. If missing, then these file search paths will include sub-directories, if present. Any directory name beginning with a dot (\fB.\fP) character, or named \fBCVS\fP, will be ignored. .IP \fB--with-submods\fP If present, then submodules will be processed within the main module, instead of separately. For example, a single XSD will be generated instead of using XSD 'include' directives within the main module, For identifier or dependency listings, the entire module contents will be checked, not just the main module. If this mode is selected, then submodels entered with the \fBmodule\fP parameter will be ignored. Normally, 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. .IP --\fBversion\fP Print yangto version string and exit. .SH INPUT FILES Operations can be performed on one or more files with the \fBmodule\fP parameter, or an entire directory tree with the \fBsubtree\fP parameter. Unless the \fBhelp\fP or \fBversion\fP parameters is entered, one of these input file parameters is mandatory. .SH 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) YANG_MODPATH environment var (or set by modpath parameter) 3) $HOME/modules directory 4) $YANG_HOME/modules directory 5) $YANG_INSTALL/modules directory OR default install module location, '/usr/share/yang/modules' By default, the entire directory tree for all locations (except step 1) will be searched, not just the specified directory. The \fBno-subdirs\fP parameter can be used to prevent sub-directories from being searched. Any directory name beginning with a dot character (\fB.\fP) will be skipped. Also, any directory named \fBCVS\fP will be skipped in directory searches. .SH OUTPUT MODES By default, any translation output will be sent to \fBSTDOUT\fP. The \fBoutput\fP parameter can be used to specify the full filespec of the output file to use instead. The \fBdefname\fP parameter can be used to generate a default filename in the current directory for the output. E.g., the default XSD filename is \fB_.xsd\fP. This is the default mode when \fBsubtree\fP input mode is selected. .SH ERROR LOGGING By default, warnings and errors are sent to STDOUT. A log file can be specified instead with the \fBlog\fP' parameter. Existing log files can be reused with the 'logappend' parameter, otherwise log files are overwritten. The logging level can be controlled with the \fBlog-level\fP parameter. The default log level is 'info'. The log-levels are additive: \fBoff\fP: suppress all errors (not recommended!) A program return code of '1' indicates some error. \fBerror\fP: print errors \fBwarn\fP: print warnings \fBinfo\fP: print generally interesting trace info \fBdebug\fP: print general debugging trace info \fBdebug2\fP: print verbose debugging trace info .SH ENVIRONMENT The following optional environment variables can be used to control module search behavior: .IP HOME The user's home directory (e.g., /home/andy) .IP YANG_HOME The root of the user's YANG work directory (e.g., /home/andy/swdev/netconf) .IP YANG_INSTALL The root of the directory that yangto is installed on this system (default is, /usr/share/yang) .IP YANG_MODPATH Colon-separated list of directories to search for modules and submodules. (e.g.: './workdir/modules:/home/andy/test-modules') The \fBmodpath\fP parameter will override this environment variable, if both are present. .SH CONFIGURATION FILES .IP "yang.conf" YANG config file The default is: \fB/etc/yang.conf\fP An ASCII configuration file format is supported to store command line parameters. The \fBconfig\fP 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 yangto { log-level debug output "~/swdev/testfiles" } netconfd { ... } .SH FILES The following data files must be present in the module search path in order for this program to function: * \fByangto.ncx\fP default: /usr/share/yang/modules/apps/yangto.ncx * \fBncxtypes.ncx\fP default: /usr/share/yang/modules/base/ncxtypes.ncx .SH BUGS - keyref Xpath expressions are not validated - must-stmt Xpath expressions are not validated - top-level augment from module A into module B is validated but output is not generated .SH 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) .SH AUTHOR Andy Bierman, .SH SEE ALSO .BR pyang (1)