Showing results for 
Search instead for 
Did you mean: 
Akira Iwamoto
Cisco Employee
Cisco Employee

What is ncs_cmd command?

NSO can accept "commands" via many ways, and northbound APIs are ones of many. IPC communications port are opened for localhost, at default, and service packages are making sockets to it work with. ncs_cmd command enables users to kick a feature that applications are not implementing. Because it's with low level APIs, users needs more understanding of it to use.

As you might already know, service packages can be created with Java and Python. Actually C and Erlang are also options. ncs_cmd is built with C API, and it's included in NSO installer. The source code is coming together, so developers can refer how the application is created. It is indeed a good sample application using C API.

It is useful for users too, and some parts in documentations have example of using this tool.

The usage of ncs_cmd command

ncs_cmd command has many options. Running the command with '-h' option gives the help of it.

$ ncs_cmd -h


  ncs_cmd [options] [filename]

  ncs_cmd [options] -c <script>

  ncs_cmd -h | -h commands | -h <command-name>

A utility that provides a command line interface towards some cdb

and maapi functions. Commands are expected in filename (or stdin

if not provided). Commands can also be given using the -c option.

Valid options are:

  -d            Increase debug level for each -d flag

  -a <address>  Connect to NCS at <address> (default

  -p <port>      Connect to NCS at <port> (default 4565)

  -r            Commands work on 'running' database

  -S            Commands work on 'startup' database

  -o            CDB commands work on CDB operational database

  -e            MAAPI commands work on candidate database

  -f [w][p][r|s] Use cdb_start_session2() to start the CDB session - values

                w/p/r/s set the CDB_LOCK_WAIT/PARTIAL/REQUEST/SESSION flags

  -u <user>      Connect to maapi as <user>

  -g <group>    Connect to maapi with group <group> (more than one allowed)

  -x <ctxt>      Connect to maapi with context <ctxt> (default system)

  -s            Perform each command in a different session

  -c <string>    Commands are read from <string> instead of a file

  -m            Don't call confd_load_schemas()

  -U            Make all output unbuffered

  -L            diff_iterate on leaf-lists as leaf, not list [deprecated]

  -h            Display this text and exit

  -h <cmd-name>  Show help for <cmd-name> and exit

  -h commands    List all available commands and exit


These are options to prepare the IPC communications environments. Defaults are fine for trials.

ncs_cmd accepts commands to know what users want to do. You can list it with "-h commands" option.

$ ncs_cmd -h commands

ncs_cmd: available commands:

cdb_get|get|g <path>

get_case <path> <choice>

cdb_cd|cd <path>


cdb_exists|exists <path>

get_object <path>

get_object_tag <path>

get_objects <start> <num> <path>

get_values <path> <leaf-node>...

  Use cdb_get_values() to get all leafs requested

cdb_set|set|s <path> <value>




Obtain leaf data

Let's get /aaa/authentication/users/user/admin, for example. It's a leaf, and we can access to it with CDB API or MAAPI API.


$ ncs_cmd -c 'cdb_get /aaa/authentication/users/user{admin}/uid'




$ ncs_cmd -c 'maapi_get /aaa/authentication/users/user{admin}/uid'



Setting data to leaf

Setting data using maapi.

$ ncs_cmd -c 'mset /aaa/authentication/users/user{admin}/uid 1000'

$ ncs_cmd -c 'maapi_get /aaa/authentication/users/user{admin}/uid'



Creating a list instance

Here, let's create a user "test" on NSO. To create a user, we need to set several information together, so it's ended with errors.

$ ncs_cmd -c 'mcreate /aaa/authentication/users/user{test}'

apply failed: CONFD_ERR, Error: notset (12): /aaa:aaa/authentication/users/user{test}/ssh_keydir is not configured, in function do_maapi_commit, line 1381


We need to commit needed data (did / gid / password / ssh_keydir /homedir) to commit together.

multiple commands can be separated with ";" semi-colon.

$ COMMAND='mcreate /aaa:aaa/authentication/users/user{test};

mset /aaa:aaa/authentication/users/user{test}/uid 1;

mset /aaa:aaa/authentication/users/user{test}/gid 1;

mset /aaa:aaa/authentication/users/user{test}/password 1;

mset /aaa:aaa/authentication/users/user{test}/ssh_keydir /tmp/.ssh;

mset /aaa:aaa/authentication/users/user{test}/homedir /tmp'

$ ncs_cmd -c "$COMMAND"


Check how many users are registered in NSO

num_instances returns the number of list entries.

$ ncs_cmd -c 'num_instances /aaa:aaa/authentication/users/user'



Reopen logs

NSO is kept writing logs into log files. There are a chance that we want to log-rotate and delete it for a moment, and after doing it, NSO loses the access to the file. reopen_logs can re-open log files again.

$ ncs_cmd -c 'reopen_logs'


HA related commands (master, slave, none, ha_status)

It's the work of HA Framework to tell NSO that this node should be master, for example. HA Framework, eg. hcc, is telling NSO so, but we can directly tell NSO to do so. (This may break hcc framework behavior, so be careful)

be_master (make a node master)

$ ncs_cmd -c 'master node1'

be_slave (make a node slave)

$ ncs_cmd -c 'slave node2 node1'

"ncs_cmd" (argv[0]) is used as the token. If you are trying on HA established environment, it would show error for bad credentials.

To try, you need to change the token to "ncs_cmd", or change the executable name to the used string as the token.

be_none (make a node none)

$ ncs_cmd -c 'none'


$ ncs_cmd -c 'ha_status'

master 1 slaves node2


Getting Started

Find answers to your questions by entering keywords or phrases in the Search bar above. New here? Use these resources to familiarize yourself with the NSO Developer community:

Recognize Your Peers
Quick Links