The following actions are possible after installing NSO.

After Local Install

After System Install

One of the included scripts with an NSO installation is the ncs-setup, which makes it very easy to create instances of NSO from a Local Install. You can look at the --help or ncs-setup(1) in Manual Pages for more details, but the two options we need to know are:

• --dest defines the directory where you want to set up NSO. if the directory does not exist, it will be created.

• --package defines the NEDs that you want to have installed. You can specify this option multiple times.

To create an NSO instance:

1. Run the command to set up an NSO instance in the current directory with the IOS, NX-OS, IOS-XR and ASA NEDs. You only need one NED per platform that you want NSO to manage, even if you may have multiple versions in your installer neds directory.

   Use the name of the NED folder in ${NCS_DIR}/packages/neds for the latest NED version that you have installed for the target platform. Use the tab key to complete the path, after you start typing (alternatively, copy and paste). Verify that the NED versions below match what is currently on the sandbox to avoid a syntax error. See the example below.

   Copy

   ncs-setup --package ~/nso-6.0/packages/neds/cisco-ios-cli-6.44 \
   --package ~/nso-6.0/packages/neds/cisco-nx-cli-5.15 \
   --package ~/nso-6.0/packages/neds/cisco-iosxr-cli-7.20 \
   --package ~/nso-6.0/packages/neds/cisco-asa-cli-6.8 \
   --dest nso-instance

2. Check the nso-instance directory. Notice that several new files and folders are created.

   Copy

   $ ls nso-instance/
   logs  ncs-cdb  ncs.conf  packages  README.ncs  scripts  state
   $ ls -l nso-instance/packages/
   total 0
   lrwxrwxrwx 1 user docker 51 Mar 19 12:44 cisco-asa-cli-6.8 ->
   /home/user/nso-6.0/packages/neds/cisco-asa-cli-6.8
   
   lrwxrwxrwx 1 user docker 52 Mar 19 12:44 cisco-ios-cli-6.44 ->
   /home/user/nso-6.0/packages/neds/cisco-ios-cli-6.44
   
   lrwxrwxrwx 1 user docker 54 Mar 19 12:44 cisco-iosxr-cli-7.20 ->
   /home/user/nso-6.0/packages/neds/cisco-iosxr-cli-7.20
   
   lrwxrwxrwx 1 user docker 51 Mar 19 12:44 cisco-nx-cli-5.15 ->
   /home/user/nso-6.0/packages/neds/cisco-nx-cli-5.15
   $

   Following is a description of the important files and folders:

   • ncs.conf is the NSO application configuration file, and is used to customize aspects of the NSO instance (for example, to change ports, enable/disable features, and so on.) See ncs.conf(5) in Manual Pages for information.

   • packages/ is the directory that has symlinks to the NEDs that we referenced in the --package arguments at the time of setup. See NSO Packages in Development for more information.

   • logs/ is the directory that contains all the logs from NSO. This directory is useful for troubleshooting.

3. Start the NSO instance by navigating to the nso-instance directory and typing the ncs command. You must be situated in the nso-instance directory each time you want to start or stop NSO. If you have multiple instances, you need to navigate to each one and use the ncs command to start or stop each one.

4. Verify that NSO is running by using the ncs --status | grep status command.

   Copy

   $ ncs --status | grep status
   status: started
   db=running id=31 priority=1 path=/ncs:devices/device/live-status-protocol/device-type

5. Add Netsim or lab devices using the command ncs-netsim -h.

This section provides an overview of how to run the examples provided with the NSO installer. By working through the examples, the reader should get a good overview of the various aspects of NSO and hands-on experience from interacting with it.

General Instructions

1. Make sure that NSO is installed with a Local Install according to the instructions in Local Install.

2. Source the ncsrc file in the NSO installation directory to set up a local environment. For example:

   Copy

   $ source ~/nso-6.0/ncsrc

3. Proceed to the example directory:

   Copy

   $ cd $NCS_DIR/examples.ncs/getting-started/using-ncs/1-simulated-cisco-ios

4. Follow the instructions in the README files that are located in the example directories.

Every example directory is a complete NSO run-time directory. The README file and the detailed instructions later in this guide show how to generate a simulated network and NSO configuration for running the specific examples. Basically, the following steps are done:

1. Create a simulated network using the ncs-netsim --create-network command:

   Copy

   $ ncs-netsim create-network cisco-ios-cli-3.8 3 ios

   This creates 3 Cisco IOS devices called ios0, ios1, and ios2.

2. Create an NSO run-time environment using the ncs-setup command:

   Copy

   $ ncs-setup --dest .

   This command uses the --dest option to create local directories for logs, database files, and the NSO configuration file to the current directory (note that . refers to the current directory).

3. Start NCS netsim:

   Copy

   $ ncs-netsim start

4. Start NSO:

   Copy

   $ ncs

$ cd $NCS_DIR/examples.ncs/getting-started/1-simulated-cisco-ios
$ ncs-netsim start
$ ncs
$ ncs-netsim stop
$ ncs --stop

Common Mistakes

Some of the most common mistakes are:

$ ncs
-bash: ncs: command not found

$ ncs
Bad configuration: /etc/ncs/ncs.conf:0: "./state/packages-in-use: \
   Failed to create symlink: no such file or directory"
Daemon died status=21

$ ncs
Cannot bind to internal socket 127.0.0.1:4569 : address already in use
Daemon died status=20
$ ncs-netsim start
DEVICE c0 Cannot bind to internal socket 127.0.0.1:5010 : \
  address already in use
Daemon died status=20
FAIL

$ ncs --stop
$ cd ncs-cdb/
$ ls
A.cdb
C.cdb
O.cdb
S.cdb
netsim_devices_init.xml
$ rm *.cdb
$ ncs

If you intend to use your NSO instance for development purposes, enable the development mode using the command license smart development enable.

To uninstall Local Install, simply delete the Install Directory.

The command ncs -h shows various options when starting NSO. By default, NSO starts in the background without an associated terminal. It is recommended to add NSO to the /etc/init scripts of the deployment hosts. For more information, see the in Manual Pages.

Whenever you start (or reload) the NSO daemon, it reads its configuration from ./ncs.conf or ${NCS_DIR}/etc/ncs/ncs.conf or from the file specified with the -c option. Parts of the configuration can also be placed in the ncs.conf.d directory that must be placed next to the actual ncs.conf file.

Since all the NSO examples and README steps that come with the installer are primarily aimed at Local Install, you need to modify them to run them on a System Install.

To work with the System Install structure, this may require a little or bigger modification depending on the example.

For example, to port the example.ncs/development-guide/nano-services/basic-vrouter example to the System Install structure:

1. Make the following changes to the basic-vrouter/ncs.conf file:

2. Copy the Local Install $NCS_DIR/var/ncs/cdb/aaa_init.xml file to the basic-vrouter/ folder.

Other, more complex examples may require more ncs.conf file changes or require a copy of the Local Install default $NCS_DIR/etc/ncs/ncs.conf file together with the modification described above, or require the Local Install tool $NCS_DIR/bin/ncs-setup to be installed, as the ncs-setup command is usually not useful with a System Install. See for more information.

Before starting NSO, it is recommended to explore the installation contents.

Navigate to the newly created Installation Directory, for example:

Contents of the Installation Directory

The installation directory includes the following contents:

Documentation

Along with the binaries, NSO installs a full set of documentation available in the doc/ folder in the Installation Directory. There is also an online version of the documentation available from .

Run index.html in your browser to explore further.

Examples

Local Install comes with a rich set of examples to start using NSO.

Network Element Drivers (NEDs)

In order to communicate with the network, NSO uses NEDs as device drivers for different device types. Cisco has NEDs for hundreds of different devices available for customers, and several are included in the installer in the /packages/neds directory.

In the example below, NEDs for Cisco ASA, IOS, IOS XR, and NX-OS are shown. Also included are NEDs for other vendors including Juniper JunOS, A10, ALU, and Dell.

Install New NEDs

Like the NSO installer, the NEDs are signed.bin files that need to be run to validate the download and extract the new code.

To install new NEDs:

1. Change to the working directory where your downloads are. The filenames indicate which version of NSO the NEDs are pre-compiled for (in this case NSO 6.0), and the version of the NED. An example output is shown below.
2. Use the sh command to run signed.bin to verify the certificate and extract the NED tar.gz and other files. Repeat for all files. An example output is shown below.
3. You now have three tar (.tar.gz) files. These are compressed versions of the NEDs. List the files to verify as shown in the example below.
4. Navigate to the packages/neds directory for your Local Install, for example:
5. In the /packages/neds directory, extract the .tar files into this directory using the tar command with the path to where the compressed NED is located. An example is shown below.

   Here is a sample list of the newer NEDs extracted along with the ones bundled with the installation:

Shell Scripts

The last thing to note is the files ncsrc and ncsrc.tsch. These are shell scripts for bash and tsch that set up your PATH and other environment variables for NSO. Depending on your shell, you need to source this file before starting NSO.

If you already have a Local Install with existing data that you would like to convert into a System Install, the following procedure allows you to do so. However, a reverse migration from System to Local Install is not supported.

The following procedure assumes that NSO is installed as described in the NSO Local Install process, and will perform an initial System Install of the same NSO version. After following these steps, consult the NSO System Install guide for additional steps that are required for a fully functional System Install.

The procedure also assumes you are using the $HOME/ncs-run folder as the run directory. If this is not the case, modify the following path accordingly.

To migrate to System Install:

1. Stop the current (local) NSO instance, if it is running.

2. Take a complete backup of the Runtime Directory for potential disaster recovery.

3. Change to Super User privileges.

4. Start the NSO System Install.

5. If you have multiple versions of NSO installed, verify that the symbolic link in /opt/ncs points to the correct version.

6. Copy the CDB files containing data to the central location.

7. Ensure that the /var/opt/ncs/packages directory includes all the necessary packages, appropriate for the NSO version. However, copying the packages directly could later on interfere with the operation of the nct command. It is better to only use symbolic links in that folder. Instead, copy the existing packages to the /opt/ncs/packages directory, either as directories or as tarball files. Make sure that each package includes the NSO version in its name and is not just a symlink, for example:

8. Link to these packages in the /var/opt/ncs/packages directory.

   The reason for prepending ncs-VERSION to the filename is to allow additional NSO commands, such as nct upgrade and software packages to work properly. These commands need to identify which NSO version a package was compiled for.

9. Edit the /etc/ncs/ncs.conf configuration file and make the necessary changes. If you wish to use the configuration from Local Install, disable the local authentication, unless you fully understand its security implications.

10. When starting NSO at boot using systemd, make sure that you set the package reload option from the /etc/ncs/ncs.systemd.conf environment file to true. Or, for example, set NCS_RELOAD_PACKAGES=true before starting NSO if using the ncs command.

11. Review and complete the steps in NSO System Install, except running the installer, which you have done already. Once completed, you should have a running NSO instance with data from the Local Install.

12. Remove the package reload option if it was set.

13. Update log file paths for Java and Python VM through the NSO CLI.

14. Verify that everything is working correctly.

At this point, you should have a complete copy of the previous Local Install running as a System Install. Should the migration fail at some point and you want to back out of it, the Local Install was not changed and you can easily go back to using it as before.

In the unlikely event of Local Install becoming corrupted, you can restore it from the backup.

NSO can be uninstalled using the ncs-installer(1) option only if NSO is installed with --system-install option. Either part of the static files or the full installation can be removed using ncs-uninstall option. Ensure to stop NSO before uninstalling.

# ncs-uninstall --all

Executing the above command removes the Installation Directory /opt/ncs including symbolic links, Configuration Directory /etc/ncs, Run Directory /var/opt/ncs, Log Directory /var/log/ncs, systemd service file /etc/systemd/system/ncs.service, systemdenvironment file /etc/ncs/ncs.systemd.conf, and user profile scripts from /etc/profile.d.

To make sure that no license entitlements are consumed after you have uninstalled NSO, be sure to perform the deregister command in the CLI:

admin@ncs# license smart deregister