NSO Local Install

Introduction

Local Install should always be used for evaluation and development purposes. All the NSO examples and README steps provided with the installation are based on Local Install only. For production deployment, use System Install.

Before installing NSO:

Choose the correct Operating System. Local Install is supported on Linux and OS X for x86_64 architecture.
Before installing NSO, ensure that Java JDK-7.0 or higher is installed. For building and running NSO examples install applications mentioned in Introduction Prerequisites section.

Installation

Procedure 1. Local Install Steps

Local Install of NSO Software is performed in a single user specified directory, for example in your home directory $HOME. It is always recommended to install NSO in a directory named as the version of the release.
```
$ sh nso-VERSION.OS.ARCH.installer.bin $HOME/ncs-VERSION --local-install
```
The variables in the command VERSION refers to the NSO version to install, OS refers to the Operating System (linux for any Linux distribution and darwin for OS X) and ARCH refers to the CPU architecture (x86_64). The --local-install parameter is an optional parameter. For Example:
```
$ sh nso-4.0.linux.x86_64.installer.bin $HOME/nso-4.0
```
The installation program creates a shell script file named ncsrc in each NSO installation, which sets the environment variables. Source this file to get these settings in your shell. You may want to add this sourcing command to your login sequence, such as .bashrc.

For csh/tcsh users there is a ncsrc.tcsh file using csh/tcsh syntax. The example below assumes that you are using bash, other versions of /bin/sh may require that you use . instead of source.
```
$ source $HOME/ncs-VERSION/ncsrc
```
Create a runtime directory for NSO to keep its database, state files, logs and other files. In these instructions we assume that this directory is $HOME/ncs-run.
```
$ ncs-setup --dest $HOME/ncs-run
```
Start the NSO daemon ncs.
```
$ cd $HOME/ncs-run
$ ncs
```
When you start NSO, make sure that you are situated in the deployment directory since by default NSO reads its config files from its current working directory (i.e. .).

There are a set of examples available in the installation directory $NCS_DIR/examples.ncs

Please go through the examples for information on how to create run-time directories, start ncs, and other important NSO functionalities.
NSO uses Cisco Smart Licensing, as described in Cisco Smart Licensing in NSO 5.7 Administration Guide , to make it easy to deploy and manage NSO license entitlements. To conclude the NSO installation a license registration token must be created using a Cisco Smart Software Manager (CSSM) account. Login credentials to a CSSM account should have been provided by your Cisco contact and detailed instructions on how to create a registration token can be found in Cisco Smart Licensing in NSO 5.7 Administration Guide .

Note

If you intend to use NSO instance for development purposes you should enable development mode using the command license smart development enable. When development mode is enabled the NSO instance will only consume a single development NSO license entitlement and nothing else.

When you have a token, start a Cisco CLI towards NSO and enter the token, i.e.
```
admin@ncs# license smart register idtoken YzIzMDM3MTgtZTRkNC00YjkxLTk2ODQtOGEzMTM3OTg5MG
Registration process in progress.
Use the 'show license status' command to check the progress and result.
```
The command show license status can be used to keep track of the registration status, e.g
```
admin@ncs# show license status

Smart Licensing is ENABLED

Registration:
  Status: REGISTERED
  Smart Account: Network Service Orchestrator
  Virtual Account: Default
  Export-Controlled Functionality: Allowed
  Initial Registration: SUCCEEDED on Apr 21 09:29:11 2016 UTC
  Last Renewal Attempt: SUCCEEDED on Apr 21 09:29:16 2016 UTC
  Next Renewal Attempt: Oct 18 09:29:16 2016 UTC
  Registration Expires: Apr 21 09:26:13 2017 UTC
  Export-Controlled Functionality: Allowed

License Authorization:

License Authorization:
  Status: IN COMPLIANCE on Apr 21 09:29:18 2016 UTC
  Last Communication Attempt: SUCCEEDED on Apr 21 09:26:30 2016 UTC
  Next Communication Attempt: Apr 21 21:29:32 2016 UTC
  Communication Deadline: Apr 21 09:26:13 2017 UTC
```
Note

During Upgrades, If you find 'Communication Send Error' while license registration, please restart the Smart Agent.

Licensing activities are also logged in the NSO daemon log as described in the section called “Monitoring NSO” in NSO 5.7 Administration Guide . For example, a successful token registration results in the following log entry:
```
<INFO> 21-Apr-2016::11:29:18.022 miosaterm confd[8226]:
  Smart Licensing Global Notification:
    type = "notifyRegisterSuccess"
```
If no registration token is provided NSO enters a 90 days evaluation period and the remaining evaluation time is recorded hourly in the NSO daemon log:
```
...
<INFO> 13-Apr-2016::13:22:29.178 miosaterm confd[16260]:
  Starting the NCS Smart Licensing Java VM
<INFO> 13-Apr-2016::13:22:34.737 miosaterm confd[16260]:
  Smart Licensing evaluation time remaining: 90d 0h 0m 0s
...
<INFO> 13-Apr-2016::13:22:34.737 miosaterm confd[16260]:
  Smart Licensing evaluation time remaining: 89d 23h 0m 0s
...
```
Upon successful registration NSO automatically requests a license entitlement for its own instance and for the number of devices it orchestrates and their NED types. If development mode has been enabled only an development entitlement for the NSO instance itself is requested.

The requested entitlements can be inspected using the command show license all (or by inspecting the NSO daemon log):
```
admin@ncs# show license all
...
<INFO> 21-Apr-2016::11:29:18.022 miosaterm confd[8226]:
  Smart Licensing Global Notification:
    type = "notifyRegisterSuccess",
    agentID = "sa1",
    enforceMode = "notApplicable",
    allowRestricted = false,
    failReasonCode = "success",
    failMessage = "Successful."
<INFO> 21-Apr-2016::11:29:23.029 miosaterm confd[8226]:
  Smart Licensing Entitlement Notification: type = "notifyEnforcementMode",
    agentID = "sa1",
    notificationTime = "Apr 21 11:29:20 2016",
    version = "1.0",
    displayName = "regid.2015-10.com.cisco.NSO-network-element",
    requestedDate = "Apr 21 11:26:19 2016",
    tag = "regid.2015-10.com.cisco.NSO-network-element",
    enforceMode = "inCompliance",
    daysLeft = 90,
    expiryDate = "Jul 20 11:26:19 2016",
    requestedCount = 8
...
```
Tip

In a situation whereas the NSO instance has no direct access to the Cisco Smart Software Manager one option is a Cisco Smart Software Manager satellite can be installed to manage software licenses on the premises. Install the satellite and use the command call-home destination address http <url:port> to point to the satellite.

Another option when direct access is not wanted is to configure an HTTP or HTTPS proxy, e.g.: smart-license smart-agent proxy url https://127.0.0.1:8080 If you plan to do this, take the note below regarding ignored CLI configurations into account.

Tip

When configuring NSO in High Availability (HA) mode the license registration token must be provided to the CLI running on the primary node. Read more about HA and node types in High Availability in NSO 5.7 Administration Guide .

Note

Note that if ncs.conf contains configuration for any of java-executable, java-options, override-url/url or proxy/url under the configure path /ncs-config/smart-license/smart-agent/ any corresponding configuration done via the CLI is ignored.

Migrate to System Install

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

The following steps assume NSO is installed as described in NSO Local Install and will perform the initial system installation of the same NSO version. Afterwards, please consult NSO System Install for the additional steps required for a fully functional system installation.

It is also possible to perform the migration and upgrade to a newer NSO version at the same time, however, that introduces additional complexity. If you run into issues, please first do the migration and then the upgrade, separately.

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

Stop the current (local) NSO instance, if it is running.
```
$ ncs --stop
```
Take a complete backup of the runtime directory for potential disaster recovery.
```
$ tar -czf $HOME/ncs-backup.tar.gz -C $HOME ncs-run
```
Change to Super User privileges.
```
$ sudo -s
```

Start the NSO system install.

$ sh nso-VERSION.OS.ARCH.installer.bin --system-install

If you have multiple versions of NSO installed, verify the symbolic link in /opt/ncs points to the correct version.
Copy the CDB files containing data to the central location.
```
# cp $HOME/ncs-run/ncs-cdb/*.cdb /var/opt/ncs/cdb
```
You also need to ensure the /var/opt/ncs/packages directory includes all the necessary packages, appropriate for the NSO version. However, copying the packages directly could later 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 each package includes the NSO version in its name and is not just a symlink, for example:
```
# cd $HOME/ncs-run/packages
# for pkg in *; do cp -RL $pkg /opt/ncs/packages/ncs-VERSION-$pkg; done
```
Then link to these packages in the /var/opt/ncs/packages directory.
```
# cd /var/opt/ncs/packages/
# rm -f *
# for pkg in /opt/ncs/packages/ncs-VERSION-*; do ln -s $pkg; done
```
The reason for prepending “ncs-VERSION” to the file name is to allow additional NSO commands, such as nct upgrade and software packages, to work correctly. These commands need to identify which NSO version a package was compiled for.
Edit the /etc/ncs/ncs.conf configuration file and make the necessary changes. If you wish to use the configuration from local install, you should at least disable the local authentication (unless you fully understand its security implications).
```
<local-authentication>
  <enabled>false</enabled>
</local-authentication>
```
When starting the NSO later on, make sure you set the package reload option, or use start-with-package-reload instead of start with /etc/init.d/ncs.
```
# export NCS_RELOAD_PACKAGES=true
```
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.
Remove the package reload option if it was set.
```
# unset NCS_RELOAD_PACKAGES
```

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

$ ncs_cli -C -u admin
admin@ncs# config
Entering configuration mode terminal
admin@ncs(config)# unhide debug
admin@ncs(config)# show full-configuration java-vm stdout-capture file
java-vm stdout-capture file ./logs/ncs-java-vm.log
admin@ncs(config)# java-vm stdout-capture file /var/log/ncs/ncs-java-vm.log
admin@ncs(config)# commit
Commit complete.
admin@ncs(config)# show full-configuration java-vm stdout-capture file
java-vm stdout-capture file /var/log/ncs/ncs-java-vm.log
admin@ncs(config)# show full-configuration python-vm logging log-file-prefix
python-vm logging log-file-prefix ./logs/ncs-python-vm
admin@ncs(config)# python-vm logging log-file-prefix /var/log/ncs/ncs-python-vm
admin@ncs(config)# commit
Commit complete.
admin@ncs(config)# show full-configuration python-vm logging log-file-prefix
python-vm logging log-file-prefix /var/log/ncs/ncs-python-vm
admin@ncs(config)# exit
admin@ncs#
admin@ncs# exit

Finally, 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.

$ sudo /etc/init.d/ncs stop
$ source $HOME/ncs-VERSION/ncsrc
$ cd $HOME/ncs-run
$ ncs

In the unlikely case the local install became corrupted, you can restore it from backup.

$ rm -rf $HOME/ncs-run
$ tar -xzf $HOME/ncs-backup.tar.gz -C $HOME

NSO Uninstallation

Uninstallation of NSO local install is straightforward.

Note

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

Then stop the NSO if it is running.

$ ncs --stop

Finally, simply delete the NSO installation directory and the runtime directory.

$ rm -rf $HOME/ncs-VERSION
$ rm -rf $HOME/ncs-run