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
Usage:
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 127.0.0.1)
-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_getcwd|cwd
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>
...
<snip>
Examples
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.
With CDB API.
$ ncs_cmd -c 'cdb_get /aaa/authentication/users/user{admin}/uid'
65534
$
With MAAPI API.
$ ncs_cmd -c 'maapi_get /aaa/authentication/users/user{admin}/uid'
65534
$
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'
1000
$
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'
5
$
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 192.168.1.1'
"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'
ha_status
$ ncs_cmd -c 'ha_status'
master 1 slaves node2
$