# 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 default IPC socket. If the daemon is not listening on its standard port/path, set the environment variables `NCS_IPC_ADDR`/`NCS_IPC_PORT` or `NCS_IPC_PATH` accordingly. The used values should match those specified in either the /ncs-config/ncs-ipc-address or /ncs-config/ncs-local-ipc of the [ncs.conf(5)](https://nso-docs.cisco.com/guides/resources/man/ncs.conf.5) (if both sets are provided, `NCS_IPC_PATH` takes precedence). See the section on IPC in the Admin Guide for details.

`--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...] [Subtrees...]`

> 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.
>
> Specify subtrees to prevent printing the entire database.
>
> `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.
>
> `help`
>
> > Print help text.
>
> 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.

The environment variables `NCS_IPC_PORT`, `NCS_IPC_ADDR` and `NCS_IPC_PATH` control how to connect to a running NCS daemon. These variables generally have no effect when starting the daemon, since the values are read from the configuration file [ncs.conf(5)](https://nso-docs.cisco.com/guides/resources/man/ncs.conf.5). The exception is `NCS_IPC_PATH`, which overrides the configuration file if set, enabling the Unix domain socket at the specified path.

## 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)](https://nso-docs.cisco.com/guides/resources/man/ncs.conf.5).

## See Also

`ncs.conf(5)` - NCS daemon configuration file format