Section 1

`ncs`

ncs - command to start and control the NCS daemon

Synopsis

ncs [--conf ConfFile] [--cd Dir] [--addloadpath Dir] [--nolog ] [--smp Nr] [--foreground [-v | --verbose] [--stop-on-eof]] [--with-package-reload ] [--ignore-initial-validation ] [--full-upgrade-validation ] [--disable-compaction-on-start ] [--start-phase0 ] [--epoll {true | false}]

ncs {--wait-phase0[TryTime] | --start-phase1 | --start-phase2 | --wait-started[TryTime] | --reload | --areload | --status | --check-callbacks [Namespace | Path] | --loadfile File | --rollback Nr | --debug-dump File [Options...] | --cli-j-dump File | --loadxmlfiles File | --mergexmlfiles File | --stop } [--timeout MaxTime]

ncs {--version | --cdb-debug-dump Directory [Options...] | --cdb-compact Directory}

Description

Use this command to start and control the NCS daemon.

Starting Ncs

These options are relevant when starting the NCS daemon.

-c, --conf ConfFile

ConfFile is the path to a ncs.conf file. If the -c File argument is not given to ncs, first $PWD is searched for a file called ncs.conf, if not found $NCS_DIR/etc/ncs/ncs.conf is chosen.

--cd Dir

Change working directory

--addloadpath Dir

Add Dir to the set of directories NCS uses to load fxs, clispec, NCS packages and SNMP bin files.

--nolog

Do not log initial startup messages to syslog.

--smp Nr

Number of threads to run for Symmetric Multiprocessing (SMP). The default is to enable SMP support, with as many threads as the system has logical processors, if more than one logical processor is detected. Giving a value of 1 will disable SMP support, while a value bigger than 1 will enable SMP support, where NCS will at any given time use at most as many logical processors as the number of threads.

--foreground [ -v | --verbose ] [ --stop-on-eof ]

Do not start as a daemon. Can be used to start NCS from a process manager. In combination with -v or --verbose, all log messages are printed to stdout. Useful during development. In combination with --stop-on-eof, NCS will stop if it receives EOF (ctrl-d) on standard input. Note that to stop NCS when run in foreground, send EOF (if --stop-on-eof was used) or use ncs --stop. Do not terminate with ctrl-c, since NCS in that case won't have the chance to close the database files.

--with-package-reload

When NCS starts, if the private package directory tree already exists, NCS will load the packages from this directory tree and not search the load-path for packages. If the --with-package-reload option is given when starting NCS, the load-path will be searched and the packages found there copied to the private package directory tree, replacing the previous contents, before loading. This should always be used when upgrading to a new version of NCS in an existing directory structure, to make sure that new packages are loaded together with the other parts of the new system.
When NCS is started from the /etc/init.d scripts, that get generated by the --system-install option to the NCS installer, the environment variable NCS_RELOAD_PACKAGES can be set to 'true' to attempt a package reload.

--with-package-reload-force

When reloading packages NCS will give a warning when the upgrade looks "suspicious", i.e. may break some functionality. This is not a strict upgrade validation, but only intended as a hint to NSO administrator early in the upgrade process that something might be wrong. Please refer to Loading Packages section in NSO Administration Guide for more information.
If all changes indicated by the warnings are intended, this option allows to override warnings and proceed with the upgrade. This option is equivalent to setting NCS_RELOAD_PACKAGES environment variable to 'force'.

--ignore-initial-validation

When CDB starts on an empty database, or when upgrading, it starts a transaction to load the initial configuration or perform the upgrade. This option makes NCS skip any validation callpoints when committing these initial transaction. (The preferred alternative is to use start-phases and register the validation callpoints in phase 0, see the user guide).

--full-upgrade-validation

Perform a full validation of the entire database if the data models have been upgraded. This is useful in order to trigger external validation to run even if the database content has not been modified.

--disable-compaction-on-start

Do not compact CDB files when starting the NCS daemon.

--start-phase0

Start the daemon, but only start internal subsystems and CDB. Phase 0 is used when a controlled upgrade is done.

--epoll { true | false }

Determines whether NCS should use an enhanced poll() function (e.g. Linux epoll(7)). This can improve performance when NCS has a high number of connections, but there may be issues with the implementation in some OS/kernel versions. The default is true.

Communicating With Ncs

When the NCS daemon has been started, these options are used to communicate with the running daemon.

By default these options will perform their function by connecting to a running NCS daemon over the loopback interface on the standard port. If the environment variable NCS_IPC_PORT and/or NCS_IPC_ADDR are set then the address/port in those variables will be used to communicate with the NCS daemon. (Must be used if the daemon is not listening on its standard port on localhost, see the /ncs-config/ncs-ipc-address/ip setting in the ncs.conf(5) man-page, and the section on IPC in the Admin Guide).

--wait-phase0 [ TryTime ]

This call hangs until NCS has initialized start phase0. After this call has returned, it is safe to register validation callbacks, upgrade CDB etc. This function is useful when NCS has been started with --foreground and --start-phase0. It will keep trying the initial connection to NCS for at most TryTime seconds (default 5).

--start-phase1

Do not start the subsystems that listen to the management IP address. Must be called after the daemon was started with --start-phase0.

--start-phase2

Must be called after the management interface has been brought up, if --start-phase1 has been used. Starts the subsystems that listens to the management IP address.

--wait-started [ TryTime ]

This call hangs until NCS is completely started. This function is useful when NCS has been started with --foreground. It will keep trying the initial connection to NCS for at most TryTime seconds (default 5).

--reload

Reload the NCS daemon configuration. All log files are closed and reopened, which means that ncs --reload can be used from e.g. logrotate(8), but it is more efficient to use ncs_cmd -c reopen_logs for this purpose. Note: If we update a .fxs file it is not enough to do a reload; the "packages reload" action must be invoked, or the daemon must be restarted with the --with-package-reload option.

--areload

Asynchronously reload the NCS daemon configuration. This can be used in scripts executed by the NCS daemon.

--stop

Stop the NCS daemon.

--status

Prints status information about the NCS daemon on stdout. Among the things listed are: loaded namespaces, current user sessions, callpoints (and whether they are registered or not), CDB status, and the current start-phase. Start phases are reported as "status:" and can be one of starting (which is pre-phase0), phase0, phase1, started (i.e. phase2), or stopping (which means that NCS is about to shutdown).

--debug-dump File [Options...]

Dump debug information from an already running NCS daemon into a <File>. The file only makes sense to NCS developers. It is often a good idea to include a debug dump in NCS trouble reports.
Additional options are supported as following
--collect-timeout Seconds
Extend the timeout when collecting information to build the debug dump. The default timeout is 10 seconds.
--compress
Compress the debug dump to <File.gz>

--cli-j-dump File

Dump cli structure information from the NCS daemon into a file.

--check-callbacks [Namespace | Path]

Walks through the entire data tree (config and stat), or only the Namespace or Path, and verifies that all read-callbacks are implemented for all elements, and verifies their return values.

--loadfile File

Load configuration in curly bracket format from File.

--rollback Nr

Rollback configuration to saved configuration number Nr.

--loadxmlfiles File ...

Load configuration in XML format from Files. The configuration is completely replaced by the contents in Files.

--mergexmlfiles File ...

Load configuration in XML format from Files. The configuration is merged with the contents in Files. The XML may use the 'operation' attribute, in the same way as it is used in a NETCONF <edit-config> operation.

--timeout MaxTime

Specify the maximum time to wait for the NCS daemon to complete the command, in seconds. If this option is not given, no timeout is used..

Standalone Options

--cdb-debug-dump Directory [Options...]

Print debug information about the CDB files in <Directory> to stdout. This is a completely stand-alone feature and the only thing needed is the .cdb files (no running NCS daemon or .fxs files etc).
Additional options may be provided to alter the output format and content.
file_debug
Dump raw file contents with keypaths.
file_debug_hkp
Dump raw file contents with hashed keypaths.
ns_debug
Dump fxs headers and namespace list.
schema_debug
Dump extensive schema information.
validate_utf8
Only emit paths and content with invalid UTF-8.
xml
Dump file contents as XML files, without output to stdout. The files will be named A.xml, O.xml and S.xml if data is available.
The output may also be filtered by file type using the skip_conf, skip_oper and skip_snap options to filter out configuration, operational and snapshot databases respectively.

--cdb-compact Directory

Compact CDB files in <Directory>. This is a completely stand-alone feature and the only thing needed is the .cdb files (no running NCS daemon or .fxs files etc).

--version

Reports the ncs version without interacting with the daemon.

--timeout MaxTime

See above

Environment

When NCS is started from the /etc/init.d scripts, that get generated by the --system-install option to the NCS installer, the environment variable NCS_RELOAD_PACKAGES can be set to 'true' to attempt a package reload.

Diagnostics

If NCS starts, the exit status is 0. If not it is a positive integer. The different meanings of the different exit codes are documented in the "NCS System Management" chapter in the user guide. When failing to start, the reason is stated in the NCS daemon log. The location of the daemon log is specified in the ConfFile as described in ncs.conf(5).

`ncs-backup`

ncs-backup - Command to backup and restore NCS data

Synopsis

ncs-backup [--install-dir InstallDir] [--no-compress]

ncs-backup --restore [Backup] [--install-dir InstallDir] [--non-interactive]

Description

The ncs-backup command can be used to backup and restore NCS CDB, state data, and config files for an NCS installation. It supports both "system installation", i.e. one that was done with the --system-install option to the NCS installer (see ncs-installer(1)), and "local installation" that was probably set up using the ncs-setup(1) command. Note that it is not supported to restore a backup from a "local installation" to a "system installation", and vice versa.

Unless the --restore option is used, the command creates a backup. The backup is stored in the RunDir/backups directory, named with the NCS version and current date and time. In case a "local install" backup is created, its name will also include "_local". The ncs-backup command will determine whether an NCS installation is "system" or "local" by itself based on the directory structure.

Options

--restore [ Backup ]

Restore a previously created backup. For backups of "system installations", the <Backup> argument is either the name of a file in the RunDir/backups directory or the full path to a backup file. If the argument is omitted, unless the --non-interactive option is given, the command will offer selection from available backups.
For backups of "local installations", the <Backup> argument must be a path to a backup file. Also, "local installation" restoration must target an empty directory as --install-dir.

[ --install-dir InstallDir ]

Specifies the directory for installation of NCS static files, like the --install-dir option to the installer. In the case of "system installations", if this option is omitted, /opt/ncs will be used for <InstallDir>.
In the case of "local installations", the --install-dir option should point to the directory containing an 'ncs.conf' file. If no 'ncs.conf' file is found, the default 'ncs.conf' of the NCS installation will be used.
If you are restoring a backup of a "local installation", --install-dir needs to point to an empty directory.

[ --non-interactive ]

If this option is used, restore will proceed without asking for confirmation.

[ --no-compress ]

If this option is used, the backup will not be compressed (default is compressed). The restore will uncompress if the backup is compressed, regardless of this option.

`ncsc`

ncsc - NCS YANG compiler

Synopsis

ncsc -c [-a | --annotate YangAnnotationFile] [--deviation DeviationFile] [--skip-deviation-fxs] [-o FxsFile] [--verbose] [--fail-on-warnings] [-E | --error ErrorCode...] [-W | --warning ErrorCode...] [--allow-interop-issues] [-w | --no-warning ErrorCode...] [--strict-yang] [--no-yang-source] [--include-doc] [--use-description [always]] [[--no-features] | [-F | --feature Features...]] [-C | --conformance [modulename:]implement | [modulename:]import...] [--datastore operational] [--ignore-unknown-features] [--max-status current | deprecated | obsolete] [-p | --prefix Prefix] [--yangpath YangDir] [--export Agent [-f FxsFileOrDir...]...] -- YangFile

ncsc --strip-yang-source FxsFile

ncsc --list-errors

ncsc --list-builtins

ncsc -c [-o CclFile] ClispecFile

ncsc -c [-o BinFile] [-I Dir] MibFile

ncsc -c [-o BinFile] [--read-only] [--verbose] [-I Dir] [--include-file BinFile] [--fail-on-warnings] [--warn-on-type-errors ] [--warn-on-access-mismatch ] [--mib-annotation MibA] [-f FxsFileOrDir...] -- MibFile FxsFile

ncsc --ncs-compile-bundle Directory [--yangpath YangDir] [--fail-on-warnings] [--ncs-skip-template] [--ncs-skip-statistics] [--ncs-skip-config] [--lax-revsion-merge] [--ncs-depend-package PackDir] [--ncs-apply-deviations] [--ncs-no-apply-deviations] [--allow-interop-issues] --ncs-device-type netconf | snmp-ned | generic-ned | cli-ned --ncs-ned-id ModName:IdentityName --ncs-device-dir Directory

ncsc --ncs-compile-mib-bundle Directory [--fail-on-warnings] [--ncs-skip-template] [--ncs-skip-statistics] [--ncs-skip-config] --ncs-device-type netconf | snmp-ned | generic-ned | cli-ned --ncs-device-dir Directory

ncsc --ncs-compile-module YangFile [--yangpath YangDir] [--fail-on-warnings] [--ncs-skip-template] [--ncs-skip-statistics] [--ncs-skip-config] [--ncs-keep-callpoints] [--lax-revision-merge] [--ncs-depend-package PackDir] [--allow-interop-issues] --ncs-device-type netconf | snmp-ned | generic-ned | cli-ned --ncs-ned-id ModName:IdentityName --ncs-device-dir Directory

ncsc --emit-java JFile [--print-java-filename ] [--java-disable-prefix ] [--java-package Package] [--exclude-enums ] [--fail-on-warnings ] [-f FxsFileOrDir...] [--builtin ] FxsFile

ncsc --emit-python PyFile [--print-python-filename ] [--no-init-py ] [--python-disable-prefix ] [--exclude-enums ] [--fail-on-warnings ] [-f FxsFileOrDir...] [--builtin ] FxsFile

ncsc --emit-mib MibFile [--join-names capitalize | hyphen] [--oid OID] [--top Name] [--tagpath Path] [--import Module Name] [--module Module] [--generate-oids ] [--generate-yang-annotation] [--skip-symlinks] [--top Top] [--fail-on-warnings ] [--no-comments ] [--read-only ] [--prefix Prefix] [--builtin ] -- FxsFile

ncsc --mib2yang-std [-p | --prefix Prefix] [-o YangFile] -- MibFile

ncsc --mib2yang-mods [--mib-annotation MibA] [--keep-readonly] [--namespace Uri] [--revision Date] [-o YangDeviationFile] -- MibFile

ncsc --mib2yang [--mib-annotation MibA] [--emit-doc] [--snmp-name] [--read-only] [-u Uri] [-p | --prefix Prefix] [-o YangFile] -- MibFile

ncsc --snmpuser EngineID User AuthType PrivType PassPhrase

ncsc --revision-merge [-o ResultFxs] [-v ] [-f FxsFileOrDir...] -- ListOfFxsFiles

ncsc --lax-revision-merge [-o ResultFxs] [-v ] [-f FxsFileOrDir...] -- ListOfFxsFiles

ncsc --get-info FxsFile

ncsc --get-uri FxsFile

ncsc --version

Description

During startup the NSO daemon loads .fxs files describing our configuration data models. A .fxs file is the result of a compiled YANG data model file. The daemon also loads clispec files describing customizations to the auto-generated CLI. The clispec files are described in clispec(5).

A yang file by convention uses .yang (or .yin) filename suffix. YANG files are directly transformed into .fxs files by ncsc.

We can use any number of .fxs files when working with the NSO daemon.

The --emit-java option is used to generate a .java file from a .fxs file. The java file is used in combination with the Java library for Java based applications.

The --emit-python option is used to generate a .py file from a .fxs file. The python file is used in combination with the Python library for Python based applications.

The --print-java-filename option is used to print the resulting name of the would be generated .java file.

The --print-python-filename option is used to print the resulting name of the would be generated .py file.

The --python-disable-prefix option is used to prevent prepending the YANG module prefix to each symbol in the generated .py file.

A clispec file by convention uses a .cli filename suffix. We use the ncsc command to compile a clispec into a loadable format (with a .ccl suffix).

A mib file by convention uses a .mib filename suffix. The ncsc command is used for compiling the mib with one or more fxs files (containing OID to YANG mappings) into a loadable format (with a .bin suffix). See the NSO User Guide for more information about compiling the mib.

Take a look at the EXAMPLE section for a crash course.

Options

Common options

-f; --fxsdep <FxsFileOrDir>...

.fxs files (or directories containing .fxs files) to be used to resolve cross namespace dependencies.

--yangpath <YangModuleDir>

YangModuleDir is a directory containing other YANG modules and submodules. This flag must be used when we import or include other YANG modules or submodules that reside in another directory.

-o; --output <File>

Put the resulting file in the location given by File.

Compile options

-c; --compile <File>

Compile a YANG file (.yang/.yin) to a .fxs file or a clispec (.cli file) to a .ccl file, or a MIB (.mib file) to a .bin file

-a; --annotate <AnnotationFile>

YANG users that are utilizing the tailf:annotate extension must use this flag to indicate the YANG annotation file(s).
This parameter can be given multiple times.

--deviation<DeviationFile>

Indicates that deviations from the module in DeviationFile should be present in the fxs file.
This parameter can be given multiple times.
By default, the DeviationFile is emitted as an fxs file. To skip this, use --skip-deviation-fxs. If --output is used, the deviation fxs file will be created in the same path as the output file.

--skip-deviation-fxs

Skips emitting the deviation files as fxs files.

-F<features>; --feature<features>

Indicates that support for the YANG features should be present in the fxs file. <features> is a string on the form <modulename>:[<feature>(,<feature>)*]
This option is used to prune the data model by removing all nodes in all modules that are defined with an "if-feature" that is not listed as <feature>. Therefore, if this option is given, all features in all modules that are supported must be listed explicitly.
If this option is not given, nothing is pruned, i.e., it works as if all features were explicitly listed.
This option can be given multiple times.
If the module uses a feature defined in an imported YANG module, it must be given as <modulename:feature>.

--no-yang-source

By default, the YANG module and submodules source is included in the fxs file, so that a NETCONF or RESTCONF client can download the module from the server.
If this option is given, the YANG source is not included.

--no-features

Indicates that no YANG features from the given module are supported.

--ignore-unknown-features

Instructs the compiler to not give an error if an unknown feature is specified with --feature.

--max-status current | deprecated | obsolete

Only include definitions with status greater than or equal to the given status. For example, to compile a module without support for all obsolete definitions, give --max-status deprecated.
To include support for some deprecated or obsolete nodes, but not all, a deviation module is needed which removes support for the unwanted nodes.

-C<conformance>; --conformance<conformance>

Indicates that the YANG module either is implemented (default) or just compiled for import purposes. conformance is a string on the form <[modulename:]><implement|import>
If a module is compiled for import, it will be advertised as such in the YANG library data.

--datastore<operational>

Indicates that the YANG module is present only in the operational state datastore.

-p; --prefix <Prefix>

NCS needs to have a unique prefix for each loaded YANG module, which is used e.g. in the CLI and in the APIs. By default the prefix defined in the YANG module is used, but this prefix is not required to be unique across modules. This option can be used to specify an alternate prefix in case of conflicts. The special value 'module-name' means that the module name will be used for this prefix.

--include-doc

Normally, 'description' statements are ignored by ncsc. If this option is present, description text is included in the .fxs file, and will be available as help text in the Web UI. In the CLI the description text will be used as information text if no 'tailf:info' statement is present.

--use-description [always]

Normally, 'description' statements are ignored by ncsc. Instead the 'tailf:info' statement is used as information text in the CLI and Web UI. When this option is specified, text in 'description' statements is used if no 'tailf:info' statement is present. If the option always is given, 'description' is used even if 'tailf:info' is present.

--export <Agent> ...

Makes the namespace visible to Agent. Agent is either "none", "all", "netconf", "snmp", "cli", "webui", "rest" or a free-text string. This option overrides any tailf:export statements in the module. The option "all" makes it visible to all agents. Use "none" to make it invisible to all agents.

--fail-on-warnings

Make compilation fail on warnings.

-W <ErrorCode>

Treat <ErrorCode> as a warning, even if --fail-on-warnings 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 dependency mismatch as errors:

-w <ErrorCode>

Do not report the warning <ErrorCode>, even if --fail-on-warnings is given. <ErrorCode> must be a warning.
Use --list-errors to get a listing of all errors and warnings.
The following example ignores the warning TAILF_DEPENDENCY_MISMATCH:

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

--allow-interop-issues

Report YANG_ERR_XPATH_REF_BAD_CONFIG as a warning instead of an error. Be advised that this violates RFC7950 section 6.4.1; a constraint on a config true node contains an XPath expression may not refer to a config false node.

--strict-yang

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

Standard MIB to YANG options

--mib2yang-std MibFile

Generate a YANG file from the MIB module (.mib file), in accordance with the IETF standard, RFC-6643.
If the MIB IMPORTs other MIBs, these MIBs must be available (as .mib files) to the compiler when a YANG module is generated. By default, all MIBs in the current directory and all builtin MIBs are available. Since the compiler uses the tool smidump to perform the conversion to YANG, the environment variable SMIPATH can be set to a colon-separated list of directories to search for MIB files.

-p; --prefix <Prefix>

Specify a prefix to use in the generated YANG module.
An appendix to the RFC describes how the prefix is automatically generated, but such an automatically generated prefix is not always unique, and NSO requires unique prefixes in all loaded modules.

Standard MIB to YANG modification options

--mib2yang-mods MibFile

Generate a combined YANG deviation/annotation file from the MIB module (.mib file), which can be used to compile the yang file generated by --mib2yang-std, to achieve a similar result as with the non-standard --mib2yang translation.

--mib-annotation <MibA>

Provide a MIB annotation file to control how to override the standard translation of specific MIB objects to YANG. See mib_annotations(5).

--revision Date

Generate a revision statement with the provided Date as value in the deviation/annotation file.

--namespace <Uri>

Specify a uri to use as namespace in the generated deviation/annotation module.

--keep-readonly

Do not generate any deviations of the standard config (false) statements. Without this flag, config statements will be deviated to true on yang nodes corresponding to writable MIB objects.

MIB to YANG options

--mib2yang MibFile

Generate a YANG file from the MIB module (.mib file).
If the MIB IMPORTs other MIBs, these MIBs must be available (as .mib files) to the compiler when a YANG module is generated. By default, all MIBs in the current directory and all builtin MIBs are available. Since the compiler uses the tool smidump to perform the conversion to YANG, the environment variable SMIPATH can be set to a colon-separated list of directories to search for MIB files.

-u; --uri <Uri>

Specify a uri to use as namespace in the generated YANG module.

-p; --prefix <Prefix>

Specify a prefix to use in the generated YANG module.

--mib-annotation <MibA>

Provide a MIB annotation file to control how to translate specific MIB objects to YANG. See mib_annotations(5).

--snmp-name

Generate the YANG statement "tailf:snmp-name" instead of "tailf:snmp-oid".

--read-only

Generate a YANG module where all nodes are "config false".

MIB compiler options

-c; --compile <MibFile>

Compile a MIB module (.mib file) to a .bin file.
If the MIB IMPORTs other MIBs, these MIBs must be available (as compiled .bin files) to the compiler. By default, all compiled MIBs in the current directory and all builtin MIBs are available. Use the parameters --include-dir or --include-file to specify where the compiler can find the compiled MIBs.

--verbose

Print extra debug info during compilation.

--read-only

Compile the MIB as read-only. All SET attempts over SNMP will be rejected.

-I; --include-dir <Dir>

Add the directory Dir to the list of directories to be searched for IMPORTed MIBs (.bin files).

--include-file <File>

Add File to the list of files of IMPORTed (compiled) MIB files. File must be a .bin file.

--fail-on-warnings

Make compilation fail on warnings.

--warn-on-type-errors

Warn rather than give error on type checks performed by the MIB compiler.

--warn-on-access-mismatch

Give a warning if an SNMP object has read only access to a config object.

--mib-annotation <MibA>

Provide a MIB annotation file to fine-tune how specific MIB objects should behave in the SNMP agent. See mib_annotations(5).

Emit SMIv2 MIB options

--emit-mib <MibFile>

Generates a MIB file for use with SNMP agents/managers. See the appropriate section in the SNMP agent chapter in the NSO User Guide for more information.

--join-names capitalize

Join element names without separator, but capitalizing, to get the MIB name. This is the default.

--join-names hyphen

Join element names with hyphens to get the MIB name.

--join-names force-capitalize

The characters '.' and '_' can occur in YANG identifiers but not in SNMP identifiers; they are converted to hyphens, unless this option is given. In this case, such identifiers are capitalized (to lowerCamelCase).

--oid <OID>

Let OID be the top object's OID. If the first component of the OID is a name not defined in SNMPv2-SMI, the --import option is also needed in order to produce a valid MIB module, to import the name from the proper module. If this option is not given, a tailf:snmp-oid statement must be specified in the YANG header.

--tagpath Path

Generate the MIB only for a subtree of the module. The Path argument is an absolute schema node identifier, and it must refer to container nodes only.

--import <Module> <Name>

Add an IMPORT statement which imports Name from the MIB Module.

--top <Name>

Let Name be the name of the top object.

--module <Name>

Let Name be the module name. If a tailf:snmp-mib-module-name statement is in the YANG header, the two names must be equal.

--generate-oids

Translate all data nodes into MIB objects, and generate OIDs for data nodes without tailf:snmp-oid statements.

--generate-yang-annotation

Generate a YANG annotation file containing the tailf:snmp-oid, tailf:snmp-mib-module-name and tailf:snmp-row-status-column statements for the nodes. Implies --skip-symlinks.

--skip-symlinks

Do not generate MIB objects for data nodes modeled through symlinks.

--fail-on-warnings

If this option is used all warnings are treated as errors and ncsc will fail its execution.

--no-comments

If this option is used no additional comments will be generated in the MIB.

--read-only

If this option is used all objects in the MIB will be read only.

--prefix <String>

Prefix all MIB object names with String.

--builtin

If a MIB is to be emitted from a builtin YANG module, this option must be given to ncsc. This will result in the MIB being emitted from the system builtin .fxs files. It is not possible to change builtin models since they are system internal. Therefore, compiling a modified version of a builtin YANG module, and then using that resulting .fxs file to emit .hrl files is not allowed.
Use --list-builtins to get a listing of all system builtin YANG modules.

Emit SNMP user options

--snmpuser <EngineID> <User> <AuthType> <PrivType> <PassPhrase>

Generates a user entry with localized keys for the specified engine identifier. The output is an usmUserEntry in XML format that can be used in an initiation file for the SNMP-USER-BASED-SM-MIB::usmUserTable. In short this command provides key generation for users in SNMP v3. This option takes five arguments: The EngineID is either a string or a colon separated hexlist, or a dot separated octet list. The User argument is a string specifying the user name. The AuthType argument is one of md5, sha, sha224, sha256, sha384, sha512 or none. The PrivType argument is one of des, aes, aes192, aes256, aes192c, aes256c or none. Note that the difference between aes192/aes256 and aes192c/aes256c is the method for localizing the key; where the latter is the method used by many Cisco routers, see: https://datatracker.ietf.org/doc/html/draft-reeder-snmpv3-usm-3desede-00, and the former is defined in: https://datatracker.ietf.org/doc/html/draft-blumenthal-aes-usm-04. The PassPhrase argument is a string.

Emit Java options

--emit-java <JFile>

Generate a .java ConfNamespace file from a .fxs file to be used when working with the Java library. The file is useful, but not necessary when working with the NAVU library. JFile could either be a file or a directory. If JFile is a directory the resulting .java file will be created in that directory with a name based on the module name in the YANG module. If JFile is not a directory that file is created. Use --print-java-filename to get the resulting file name.

--print-java-filename

Only print the resulting java file name. Due to restrictions of identifiers in Java the name of the Class and thus the name of the file might get changed if non Java characters are used in the name of the file or in the name of the module. If this option is used no file is emitted the name of the file which would be created is just printed on stdout.

--java-package <Package>

If this option is used the generated java file will have the given package declaration at the top.

--exclude-enums

If this option is used, definitions for enums are omitted from the generated java file. This can in some cases be useful to avoid conflicts between enum symbols, or between enums and other symbols.

--fail-on-warnings

If this option is used all warnings are treated as errors and ncsc will fail its execution.

-f; --fxsdep <FxsFileOrDir>...

.fxs files (or directories containing .fxs files) to be used to resolve cross namespace dependencies.

--builtin

If a .java file is to be emitted from a builtin YANG module, this option must be given to ncsc. This will result in the .java file being emitted from the system builtin .fxs files. It is not possible to change builtin models since they are system internal. Therefore, compiling a modified version of a builtin YANG module, and then using that resulting .fxs file to emit .hrl files is not allowed.
Use --list-builtins to get a listing of all system builtin YANG modules.

NCS device module import options

These options are used to import device modules into NCS. The import is done as a source code transformation of the yang modules (MIBs) that define the managed device. By default, the imported modules (MIBs) will be augmented three times. Once under /devices/device/config, once under /devices/template/config and once under /devices/device/live-status.

The ncsc commands to import device modules can take the following options:

--ncs-skip-template This option makes the NCS bundle compilation skip the layout of the template tree - thus making the NCS feature of provisioning devices through the template tree unusable. The main reason for using this option is to save memory if the data models are very large.

--ncs-skip-statistics This option makes the NCS bundle compilation skip the layout of the live tree. This option make sense for e.g NED modules that are sometimes config only. It also makes sense for the Junos module which doesn't have and "config false" data.

--ncs-skip-config This option makes the NCS bundle compilation skip the layout of the config tree. This option make sense for some NED modules that are typically status and commands only.

--ncs-keep-callpoints This option makes the NCS bundle compilation keep callpoints when performing the ncs transformation from modules to device modules, as long as the callpoints have either tailf:set-hook or tailf:transaction-hook as sub statement.

--ncs-device-dir Directory This is the target directory where the output of the --ncs-compile-xxx command is collected.

--lax-revision-merge When we have multiple revisions of the same module, the ncsc command to import the module will fail if a YANG module does not follow the YANG module upgrade rules. See RFC 6020. This option makes ncsc ignore those strict rules. Use with extreme care, the end result may be that NCS is incompatible with the managed devices.

--ncs-depend-package PackageDir When a package has references to a YANG module in another package, use this flag when compiling the package.

--ncs-apply-deviations This option has no effect, since deviations are applied by default. It is only present for backward compatibility.

--ncs-no-apply-deviations This option will make --ncs-compile-bundle ignore deviations that are defined in one module with a target in another module.

--ncs-device-type netconf | snmp-ned | generic-ned | cli-ned All imported device modules adhere to a specific device type.

--ncs-ned-id ModName:IdentityName The NED id for the package. IdentityName is the name of an identity in the YANG module ModName.

--ncs-compile-bundle <YangFileDirectory>

To import a set of managed device YANG files into NCS, gather the required files in a directory and import by using this flag. Several invocations will populate the mandatory --ncs-device-dir directory with the compiler output. This command also handles revision management for NCS imported device modules. Invoke the command several times with different YangFileDirectory directories and the same --ncs-device-dir directory to accumulate the revision history of the modules in several different YangFileDirectory directories.
Modules in the YangFileDirectory directory having annotations or deviations for other modules are identified, and such annotations and deviations are processed as follows:
Annotations using tailf:annotate are ignored (this annotation mechanism is incompatible with the source code transformation).
Annotations using tailf:annotate-module are applied (but may, depending on the type of annotation and the device type, be ignored by the transformation).
Deviations are applied unless the --ncs-no-apply-deviations option is given.
Typically when NCS needs to manage multiple revisions of the same module, the filenames of the YANG modules are on the form of MOD@REVISION.yang. The --ncs-compile-bundle as well as the --ncs-compile-module commands will rename the source YANG files and organize the result as per revision in the --ncs-device-dir output directory.
The output structure could look like:
where we have the following paths:
modules/fxs contains the FXS files that are revision compiled and are ready to load into NCS.
modules/yang/$MODULE.yang is the augmented YANG file of the latest revision. NCS will run with latest revision of all YANG files, and the revision compilation will annotate that tree with information indication at which revision each YANG element was introduced.
modules/revisions/$MODULE contains the different revisions for $MODULE and also the merged compilation result.

--ncs-compile-mib-bundle <MibFileDirectory>

To import a set of SNMP MIB modules for a managed device into NCS, put the required MIBs in a directory and import by using this flag. The MIB files MUST have the ".mib" extension. The compile also picks up any MIB annotation files present in this directory, with the extension ".miba". See mib_annotations(5) .
This command translates all MIB modules to YANG modules according to the standard translation algorithm defined in I.D-ietf-netmod-smi-yang, then it generates a YANG deviations module in order to handle writable configuration data. When all MIB modules have been translated to YANG, --ncs-compile-bundle is invoked.
Each invocation of this command will populate the --ncs-device-dir with the compiler output. This command also handles revision management for NCS imported device modules. Invoke the command several times with different MibFileDirectory directories and the same --ncs-device-dir directory to accumulate the revision history of the modules in several different MibFileDirectory directories.

--ncs-compile-module <YangFile>

This ncsc command imports a single device YANG file into the --ncs-model-dir structure. It's an alternative to --ncs-compile-bundle, however is just special case of a one-module bundle. From a Makefile perspective it may sometimes be easier to use this version of bundle compilation.

Misc options

--strip-yang-source <FxsFile>

Removes included YANG source from the fxs file. This makes the file smaller, but it means that the YANG module and submodules cannot be downloaded from the server, unless they are present in the load path.

--get-info <FxsFile>

Various info about the file is printed on standard output, including the names of the source files used to produce this file, which ncsc version was used, and for fxs files, namespace URI, other namespaces the file depends on, namespace prefix, and mount point.

--get-uri <FxsFile>

Extract the namespace URI.

--version

Reports the ncsc version.

--emulator-flags <Flags>

Passes Flags unaltered to the Erlang emulator. This can be useful in rare cases for adjusting the ncsc runtime footprint. For instance, --emulator-flags="+SDio 1" will force the emulator to create only one dirty I/O scheduler thread. Use with care.

Example

Assume we have the file system.yang:

To compile this file we do:

If we intend to manipulate this data from our Java programs, we must typically also invoke:

Finally we show how to compile a clispec into a loadable format:

Diagnostics

On success exit status is 0. On failure 1. Any error message is printed to stderr.

Yang 1.1

NCS supports YANG 1.1, as defined in RFC 7950, with the following exceptions:

Type empty in unions and in list keys is not supported.
Type leafref in unions are not validated, and treated as a string internally.
anydata is not supported.
The new scoping rules for submodules are not implemented. Specifically, a submodule must still include other submodules in order to access definitions defined there.
The new XPath functions derived-from() and derived-from-or-self() can only be used with literal strings in the second argument.
Leafref paths without prefixes in top-level typedefs are handled as in YANG 1.

`ncs_cli`

ncs_cli - Frontend to the NSO CLI engine

Synopsis

ncs [options] [File]

ncs [--help] [--host Host] [--ip IpAddress | IpAddress/Port ] [--address Address] [--port PortNumber] [--cwd Directory] [--proto tcp> | ssh | console ] [--interactive] [--noninteractive] [--user Username] [--uid UidInt] [--groups Groups] [--gids GidList] [--gid Gid] [--opaque Opaque] [--noaaa]

Description

The ncs_cli program is a C frontend to the NSO CLI engine. The ncs_cli program connects to NSO and basically passes data back and forth from the user to NSO.

ncs_cli can be invoked from the command line. If so, no authentication is done. The archetypical usage of ncs_cli is to use it as a login shell in /etc/passwd, in which case authentication is done by the login program.

Options

-h; --help

Display help text.

-H; --host <HostName>

Gives the name of the current host. The ncs_cli program will use the value of the system call gethostbyname() by default. The host name is used in the CLI prompt.

-i; --ip <IpAddress> | <IpAddress/Port>

Set the IP (or IP address and port) which NSO reports that the user is coming from. The ncs_cli program by default tries to determine this automatically by reading the SSH_CONNECTION environment variable.

-A; --address <Address>

CLI address to connect to. The default is 127.0.0.1. This can be controlled by either this flag, or the UNIX environment variable NCS_IPC_ADDR. The -A flag takes precedence.

-P; --port <PortNumber>

CLI port to connect to. The default is the NSO IPC port, which is 4569 This can be controlled by either this flag, or the UNIX environment variable NCS_IPC_PORT. The -P flag takes precedence.

-c; --cwd <Directory>

The current working directory for the user once in the CLI. All file references from the CLI will be relative to the cwd. By default the value will be the actual cwd where ncs_cli is invoked.

-p; --proto ssh | tcp | console

The protocol the user is using. If SSH_CONNECTION is set, this defaults to "ssh", otherwise "console".

-n; --interactive

This forces the CLI to run in interactive mode. In non interactive mode, the CLI never prompts the user for any input. This flag can sometimes be useful in certain CLI scripting scenarios.

-N; --noninteractive

This forces the CLI to run in non interactive mode.

-u; --user <User>

Indicates to NSO which username the user has. This defaults to the username of the invoker.

-U; --uid <Uid>

Indicates to NSO which uid the user has.

-g; --groups <GroupList>

Indicates to NSO which groups the user are a member of. The parameter is a comma separated string. This defaults to the actual UNIX groups the user is a member of. The group names are used by the AAA system in NSO to authorize data and command access.

-D; --gids <GidList>

Indicates to NSO which secondary group ids the user shall have. The parameter is a comma separated string of integers. This defaults to the actual secondary UNIX group ids the user has. The gids are used by NSO when NSO executes commands on behalf of the user.

-G; --gid <Gid>

Indicates to NSO which group id the user shall have. This defaults to the actual UNIX group id the user has. The gid is used by NSO when NSO executes commands on behalf of the user.

-O; --opaque <Opaque>

Pass an opaque string to NCS. The string is not interpreted by NCS, only made available to application code. See "built-in variables" in clispec(5) and maapi_get_user_session_opaque() in confd_lib_maapi(3). The string can be given either via this flag, or via the UNIX environment variable NCS_CLI_OPAQUE. The -O flag takes precedence.

--noaaa

Completely disables all AAA checks for this CLI. This can be used as a disaster recovery mechanism if the AAA rules in NSO have somehow become corrupted.

Environment Variables

NCS_IPC_ADDR

Which IP address to connect to.

NCS_IPC_PORT

Which TCP port to connect to.

SSH_CONNECTION

Set by openssh and used by ncs_cli to determine client IP address etc.

TERM

Passed on to terminal aware programs invoked by NSO.

Exit Codes

Normal exit

Failed to read user data for initial handshake.

Close timeout, client side closed, session inactive.

Idle timeout triggered.

Tcp level error detected on daemon side.

Internal error occurred in daemon.

User interrupted clistart using special escape char.

Daemon abruptly closed socket.

Scripting

It is very easy to use ncs_cli from /bin/sh scripts. ncs_cli reads stdin and can then also be run in non interactive mode. This is the default if stdin is not a tty (as reported by isatty())

Here is example of invoking ncs_cli from a shell script.

And here is en example capturing the output of ncs_cli:

The above type of CLI scripting is a very efficient and easy way to test various aspects of the CLI.

`ncs_cmd`

ncs_cmd - Command line utility that interfaces to common NSO library functions

Synopsis

ncs [common options] [filename]

ncs [common options] -c string

ncs -h | -h commands | -h command-name

Common options:

[-r | -o | -e | -S] [-f [w] | [p] | [r | s]] [-a address] [-p port] [-u user] [-g group] [-x context] [-s] [-m] [-h] [-d]

Description

The ncs_cmd utility is implemented as a wrapper around many common CDB and MAAPI function calls. The purpose is to make it easier to prototype and test various NSO issues using normal scripting tools.

Input is provided as a file (default stdin unless a filename is given) or as directly on the command line using the -c string option. The ncs_cmd expects commands separated by semicolon (;) or newlines. A pound (#) sign means that the rest of the line is treated as a comment. For example:

Would print the current start-phase of NSO, and:

would first print the current start-phase, then the current transaction ID of CDB.

Sessions towards CDB, and transactions towards MAAPI are created as-needed. At the end of the script any open CDB sessions are closed, and any MAAPI read/write transactions are committed.

Options

-d

Debug flag. Add more to increase debug level. All debug output will be to stderr.

-m

Don't load the schemas at startup.

Environment Variables

NCS_IPC_ADDR

The address used to connect to the NSO daemon, overrides the compiled in default.

NCS_IPC_PORT

The port number to connect to the NSO daemon on, overrides the compiled in default.

Examples

Getting the address of eth0
Setting a leaf in CDB operational
Making NSO running on localhost the HA primary, with the name node0
Then tell the NSO also running on localhost, but listening on port 4566, to become secondary and name it node1

`ncs-collect-tech-report`

ncs-collect-tech-report - Command to collect diagnostics from an NCS installation.

Synopsis

ncs-collect-tech-report [--install-dir InstallDir] [--full] [--num-debug-dumps Integer]

Description

The ncs-collect-tech-report command can be used to collect diagnostics from an NCS installation. The resulting diagnostics file contains information that is useful to Cisco support to diagnose problems and errors.

If the NCS daemon is running, runtime data from the running daemon will be collected. If the NCS daemon is not running, only static files will be collected.

Options

[ --install-dir InstallDir ]

Specifies the directory for installation of NCS static files, like the --install-dir option to the installer. If this option is omitted, /opt/ncs will be used for <InstallDir>.

[ --full ]

This option is used to also include a full backup (as produced by ncs-backup(1)) of the system. This helps Cisco support to reproduce issues locally.

[ --num-debug-dumps Count ]

This option is useful when a resource leak (memory/file descriptors) is suspected. It instructs the ncs-collect-tech-report script to run the command ncs --debug-dump multiple times.

`ncs-installer`

ncs-installer - NCS installation script

Synopsis

ncs-VSN.OS.ARCH.installer.bin [--local-install] LocalInstallDir

ncs-VSN.OS.ARCH.installer.bin --system-install [--install-dir InstallDir] [--config-dir ConfigDir] [--run-dir RunDir] [--log-dir LogDir] [--run-as-user User] [--keep-ncs-setup] [--non-interactive]

Description

The NCS installation script can be invoked to do either a simple "local installation", which is convenient for test and development purposes, or a "system installation", suitable for deployment.

Local Installation

[ --local-install ] LocalInstallDir

When the NCS installation script is invoked with this option, or is given only the <LocalInstallDir> argument, NCS will be installed in the <LocalInstallDir> directory only.

System Installation

--system-install

When the NCS installation script is invoked with this option, it will do a system installation that uses several different directories, in accordance with Unix/Linux application installation standards. The first time a system installation is done, the following actions are taken:
The directories described below are created and populated.
An init script for start of NCS at system boot is installed.
User profile scripts that set up $PATH and other environment variables appropriately for NCS users are installed.
A symbolic link that makes the installed version the currently active one is created (see the --install-dir option).

[ --install-dir InstallDir ]

This is the directory where static files, primarily the code and libraries for the NCS daemon, are installed. The actual directory used for a given invocation of the installation script is InstallDir/ncs-VSN, allowing for coexistence of multiple installed versions. The currently active version is identified by a symbolic link InstallDir/current pointing to one of the ncs-VSN directories. If the --install-dir option is omitted, /opt/ncs will be used for <InstallDir>.

[ --config-dir ConfigDir ]

This directory is used for config files, e.g. ncs.conf. If the --config-dir option is omitted, /etc/ncs will be used for <ConfigDir>.

[ --run-dir RunDir ]

This directory is used for run-time state files, such as the CDB data base and currently used packages. If the --run-dir option is omitted, /var/opt/ncs will be used for <RunDir>.

[ --log-dir LogDir ]

This directory is used for the different log files written by NCS. If the --log-dir option is omitted, /var/log/ncs will be used for <LogDir>.

[ --run-as-user User ]

By default, the system installation will run NCS as the root user. If a different user is given via this option, NCS will instead be run as that user. The user will be created if it does not already exist. This mode is only supported on Linux systems that have the setcap command, since it is needed to give NCS components the required capabilities for some aspects of the NCS functionality.
When the option is used, the following executable files (assuming that the default /opt/ncs is used for --install-dir) will be installed with elevated privileges:
/opt/ncs/current/lib/ncs/lib/core/pam/priv/epam
Setuid to root. This is typically needed for PAM authentication to work with a local password file. If PAM authentication is not used, or if the local PAM configuration does not require root privileges, the setuid-root privilege can be removed by using chmod u-s.
/opt/ncs/current/lib/ncs/erts/bin/ncs /opt/ncs/current/lib/ncs/erts/bin/ncs.smp
Capability cap_net_bind_service. One of these files (normally ncs.smp) will be used as the NCS daemon. The files have execute access restricted to the user given via --run-as-user. The capability is needed to allow the daemon to bind to ports below 1024 for northbound access, e.g. port 443 for HTTPS or port 830 for NETCONF over SSH. If this functionality is not needed, the capability can be removed by using setcap -r.
/opt/ncs/current/lib/ncs/bin/ip
Capability cap_net_admin. This is a copy of the OS ip(8) command, with execute access restricted to the user given via --run-as-user. The program is not used by the core NCS daemon, but provided for packages that need to configure IP addresses on interfaces (such as the tailf-hcc package). If no such packages are used, the file can be removed.
/opt/ncs/current/lib/ncs/bin/arping
Capability cap_net_raw. This is a copy of the OS arping(8) command, with execute access restricted to the user given via --run-as-user. The program is not used by the core NCS daemon, but provided for packages that need to send gratuitous ARP requests (such as the tailf-hcc package). If no such packages are used, the file can be removed.
When the --run-as-user option is used, all OS commands executed by NCS will also run as the given user, rather than as the user specified for custom CLI commands (e.g. through clispec definitions).

[ --keep-ncs-setup ]

The ncs-setup command is not usable in a "system installation", and is therefore by default excluded from such an installation to avoid confusion. This option instructs the installation script to include ncs-setup in the installation despite this.

[ --non-interactive ]

If this option is given, the installation script will proceed with potentially disruptive changes (e.g. modifying or removing existing files) without asking for confirmation.

`ncs_load`

ncs_load - Command line utility to load and save NSO configurations

Synopsis

ncs [-W] [-S] [common options] [filename]

ncs -l [-m | -r | -j | -n] [-D] [common options] [filename...]

ncs -h | -?

Common options:

[-d] [-t] [-F {x | p | o | j | c | i | t}] [-H | -U] [-a] [-e] [ [-u user] [-g group...] [-c context] | [-i]] [[-p keypath] | [-P XPath]] [-o] [-s] [-O] [-b] [-M]

Description

This command provides a convenient way of loading and saving all or parts of the configuration in different formats. It can be used to initialize or restore configurations as well as in CLI commands.

If you run ncs_load without any options it will print the current configuration in XML format on stdout. The exit status will be zero on success and non-zero otherwise.

Common Options

-d

Debug flag. Add more to increase debug level. All debug output will be to stderr.

-t

Measure how long the requested command takes and print the result on stderr.

-F <format>

Selects the format of the configuration when loading and saving, can be one of following:
x
XML (default)
p
Pretty XML
o
JSON
j
J-style CLI
c
C-style CLI
i
I-style CLI
t
C-style CLI using turbo parser. Only applicable for load config

-H

Hide all hidden nodes. By default, no nodes are hidden unless ncs_load has attached to an existing transaction, in which case the hidden nodes are the same as in that transaction's session.

-U

Unhide all hidden nodes. By default, no nodes are hidden unless ncs_load has attached to an existing transaction, in which case the hidden nodes are the same as in that transaction's session.

-u <user>; -g <group> ...; -c <context>

Loading and saving the configuration is done in a user session, using these options it is possible to specify which user, groups (more than one -g can be used to add groups), and context that should be used when starting the user session. If only a user is supplied the user is assumed to belong to a single group with the same name as the user. This is significant in that AAA rules will be applied for the specified user / groups / context combination. The default is to use the system context, which implies that AAA rules will not be applied at all.
If the environment variables NCS_MAAPI_USID and NCS_MAAPI_THANDLE are set (see the ENVIRONMENT section), or if the -i option is used, these options are silently ignored, since ncs_load will attach to an existing transaction.

-i

Instead of starting a new user session and transaction, ncs_load will try to attach to the init session. This is only valid when NSO is in start phase 0, and will fail otherwise. It can be used to load a “factory default”file during startup, or loading a file during upgrade.

Save Configuration

By default the complete current configuration will be output on stdout. To save it in a file add the filename on the command line (the -f option is deprecated). The file is opened by the ncs_load utility, permissions and ownership will be determined by the user running ncs_load. Output format is specified using the -F option.

When saving the configuration in XML format, the context of the user session (see the -c option) will determine which namespaces with export restriction (from tailf:export) that are included. If the system context is used (this is the default), all namespaces are saved, regardless of export restriction. When saving the configuration in one of the CLI formats, the context used for this selection is always cli.

A number of options are only applicable, or have a special meaning when saving the configuration:

-f <filename>

Filename to save configuration to (option is deprecated, just give the filename on the command line).

-W

Include leaves which are unset (set to their default value) in the output. By default these leaves are not included in the output.

-S

Include the default value of a leaf as a comment (only works for CLI formats, not XML). (Corresponds to the MAAPI_CONFIG_SHOW_DEFAULTS flag).

-p <keypath>

Only include the configuration below <keypath> in the output.

-P <XPath>

Filter the configuration using the <XPath> expression. (Only works for the XML format.)

-o

Include operational data in the output. (Corresponds to the MAAPI_CONFIG_WITH_OPER flag).

-O

Include only operational data, and ancestors to operational data nodes, in the output. (Corresponds to the MAAPI_CONFIG_OPER_ONLY flag).

-b

Include only data stored in CDB in the output. (Corresponds to the MAAPI_CONFIG_CDB_ONLY flag).

-M

Include NCS service-meta-data attributes in the output. (Corresponds to the MAAPI_CONFIG_WITH_SERVICE_META flag).

Load Configuration

When the -l option is present ncs_load will load all the files listed on the command line . The file(s) are expected to be in XML format unless otherwise specified using the -F flag. Note that it is the NSO daemon that opens the file(s), it must have permission to do so. However relative pathnames are assumed to be relative to the working directory of the ncs_load command .

If neither of the -m and -r options are given when multiple files are listed on the command line, ncs_load will silently treat the second and subsequent files as if -m had been given, i.e. it will merge in the contents of these files instead of deleting and replacing the configuration for each file. Note, we almost always want the merge behavior. If no file is given, or "-" is given as a filename, ncs_load will stream standard input to NSO .

-f <filename>

The file to load (deprecated, just list the file after the options instead).

-m

Merge in the contents of <filename>, the (somewhat unfortunate) default is to delete and replace.

-j

Do not run FASTMAP, if FASTMAPPED service data is loaded, we sometimes do not want to run the mapper code. One example is a backup saved in XML format that contains both device data and also service data.

-n

Only load data to CDB inside NCS, do not attempt to perform any update operations towards the managed devices. This corresponds to the 'no-networking' flag to the commit command in the NCS CLI.

-x

Lax loading. Only applies to XML loading. Ignore unknown namespaces, attributes and elements.

-r

Replace the part of the configuration that is present in <filename>, the default is to delete and replace. (Corresponds to the MAAPI_CONFIG_REPLACE flag).

-a

When loading configuration in 'i' or 'c' format, do a commit operation after each line. Default and recommended is to only commit when all the configuration has been loaded. (Corresponds to the MAAPI_CONFIG_AUTOCOMMIT flag).

-e

When loading configuration do not abort when encountering errors (corresponds to the MAAPI_CONFIG_CONTINUE_ON_ERROR flag).

-D

Delete entire config before loading.

-p <keypath>

Delete everything below <keypath> before loading the file.

-o

Accept but ignore contents in the file which is operational data (without this flag it will be an error).

-O

Start a transaction to load only operational data, and ancestors to operational data nodes. Only supported for XML input.

Examples

Reloading all xml files in the cdb directory

Merging in the contents of conf.cli

Print interface config and statistics data in cli format

Using xslt to format output

Using xmllint to pretty print the xml output

Saving config and operational data to /tmp/conf.xml

Measure how long it takes to fetch config

Output all instances in list /foo/table which has ix larger than 10

Environment

NCS_IPC_ADDR

The address used to connect to the NSO daemon, overrides the compiled in default.

NCS_IPC_PORT

The port number to connect to the NSO daemon on, overrides the compiled in default.

NCS_MAAPI_USID; NCS_MAAPI_THANDLE

If set ncs_load will attach to an existing transaction in an existing user session instead of starting a new session.
These environment variables are set by the NSO CLI when it invokes external commands, which means you can run ncs_load directly from the CLI. For example, the following addition to the <operationalMode> in a clispec file (see clispec(5))
will add a show servers command which, when run will invoke ncs_load -F j -p /system/servers. This will output the configuration below /system/servers in curly braces format.
Note that when these environment variables are set, it means that the configuration will be loaded into the current CLI transaction (which must be in configure mode, and have AAA permissions to actually modify the config). To load (or save) a file in a separate transaction, unset these two environment variables before invoking the ncs_load command.

`ncs-maapi`

ncs-maapi - command to access an ongoing transaction

Synopsis

ncs- --get Path

ncs- --set Path Value [PathValue]

ncs- --keys Path

ncs- --exists Path

ncs- --delete Path

ncs- --create Path

ncs- --insert Path

ncs- --revert

ncs- --msg To Message Sender --priomsg To Message --sysmsg To Message

ncs- --cliget Param

ncs- --cliset Param Value [ParamValue]

ncs- --cmd2path Cmd [Cmd]

ncs- --cmd-path [--is-deleta ] [--emit-parents ] [--non-recursive ] Path [Path]

ncs- --cmd-diff Path [Path]

ncs- --keypath-diff Path

ncs- --clicmd [--get-io ] [--no-hidden ] [--no-error ] [--no-aaa ] [--keep-pipe-flags ] [--no-fullpath ] [--unhide <group>] Cli command

Description

This command is intended to be used from inside a CLI command or a NETCONF extension RPC. These can be implemented in several ways, as an action callback or as an executable.

It is sometimes convenient to use a shell script to implement a CLI command and then invoke the script as an executable from the CLI. The ncs-maapi program makes it possible to manipulate the transaction in which the script was invoked.

Using the ncs-maapi command it is possible to, for example, write configuration wizards and custom show commands.

Options

-g; --get <Path> ...

Read element value at Path and display result. Multiple values can be read by giving more than one Path as argument to get.

-s; --set <Path> <Value> ...

Set the value of Path to Value. Multiple values can be set by giving multiple Path Value pairs as arguments to set.

-k; --keys <Path> ...

Good afternoon

ncs

Synopsis

Description

Starting Ncs

Communicating With Ncs

Standalone Options

Environment

Diagnostics

See Also

ncs-backup

Synopsis

Description

Options

ncsc

Synopsis

Description

Options

Common options

Compile options

Standard MIB to YANG options

Standard MIB to YANG modification options

MIB to YANG options

MIB compiler options

Emit SMIv2 MIB options

Emit SNMP user options

Emit Java options

NCS device module import options

Misc options

Example

Diagnostics

Yang 1.1

See Also

ncs_cli

Synopsis

Description

Options

Environment Variables

Exit Codes

Scripting

ncs_cmd

Synopsis

Description

Options

Environment Variables

Examples

ncs-collect-tech-report

Synopsis

Description

Options

ncs-installer

Synopsis

Description

Local Installation

System Installation

ncs_load

Synopsis

Description

Common Options

Save Configuration

Load Configuration

Examples

Environment

ncs-maapi

Synopsis

Description

Options

`ncs`

`ncs-backup`

`ncsc`

`ncs_cli`

`ncs_cmd`

`ncs-collect-tech-report`

`ncs-installer`

`ncs_load`

`ncs-maapi`