Installation

Primary requirements to do a Local Install include:

Additional requirements to, for example, build and run NSO examples, service, include:

You need to know your system specifications (Operating System and CPU architecture) in order to choose the appropriate NSO Installer.

NSO is delivered as an OS/CPU specific signed self-extractable archive. The signed archive file has the pattern nso-VERSION.OS.ARCH.signed.bin that after signature verification extracts the nso-VERSION.OS.ARCH.installer.bin archive file, where:

The following contents are unpacked:

sh nso-6.0.darwin.x86_64.installer.bin --help

# Output
This is the NCS installation script.
Usage: ./nso-6.0.darwin.x86_64.installer.bin [--local-install] LocalInstallDir
Installs NCS in the LocalInstallDir directory only.
This is convenient for test and development purposes.
Usage: ./nso-6.0.darwin.x86_64.installer.bin --system-install
[--install-dir InstallDir]
[--config-dir ConfigDir] [--run-dir RunDir] [--log-dir LogDir]
[--run-as-user User] [--keep-ncs-setup] [--non-interactive]

Does a system install of NCS, suitable for deployment.
Static files are installed in InstallDir/ncs-<vsn>.
The first time --system-install is used, the ConfigDir,
RunDir, and LogDir directories are also created and
populated for config files, run-time state files, and log files,
respectively, and an init script for start of NCS at system boot
and user profile scripts are installed. Defaults are:

InstallDir - /opt/ncs
ConfigDir  - /etc/ncs
RunDir     - /var/opt/ncs
LogDir     - /var/log/ncs

By default, the system install will run NCS as the root user.
If the --run-as-user option is given, the system install will
instead run NCS as the given user. The user will be created if
it does not already exist.
If the --non-interactive option is given, the installer will
proceed with potentially disruptive changes (e.g. modifying or
removing existing files) without asking for confirmation.

The installation program unpacks the NSO manual pages from the documentation archive in $NCS_DIR/man. ncsrc makes an addition to $MANPATH, allowing you to use the man command to view them. The manual pages are also available in the PDF format and from the online documentation located on NCS man-pages, Volume 1 in Manual Pages .

Following is a list of few of the installed manual pages:

For example, to view the manual page describing NSO configuration file you should type:

$ man ncs.conf

Apart from the manual pages, extensive information about command line options can be obtained by running ncs and ncsc with the --help (abbreviated -h) flag.

$ ncs --help

$ ncsc --help

A common misunderstanding is that there exists a dependency between the Runtime Directory and the Installation Directory. This is not true. For example, say that you have two NSO installations .../ncs-2.3.1 and .../ncs-2.3.2. The following sequence runs ncs-2.3.1 but using an example and configuration from ncs-2.3.2.

  $ cd .../ncs-2.3.1
  $ . ncsrc
  $ cd .../ncs-2.3.2/examples.ncs/datacenter-qinq
  $ ncs

Since the Runtime Directory is self-contained, this is also the way to move between examples. And since the Runtime Directory is self-contained including the database files, you can compress a complete directory and distribute it. Unpacking that directory and starting NSO from there gives an exact copy of all instance data.

  $ cd $NCS_DIR/examples.ncs/data-center-qinq
  $ ncs
  $ ncs --stop
  $ cd $NCS_DIR/examples.ncs/getting-started/1-simulated-cisco-ios
  $ ncs
  $ ncs --stop

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

During upgrades, if you experience the 'Communication Send Error' with license registration, restart the Smart Agent.

In a situation where NSO instance has no direct access to the Cisco Smart Software Manager, one option is Cisco Smart Software Manager Satellite that 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 desired 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:

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/, then any corresponding configuration done via the CLI is ignored.

When configuring NSO in 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 NSO High Availability in Administration Guide .

Licensing activities are also logged in the NSO daemon log as described in the section called “Monitoring NSO” in 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"

To check registration status, use the command show license status An example output is shown below..

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

A large number of pre-built supported NEDs are available which can be acquired and downloaded by the customers from Cisco Software Download. Note that the specific file names and versions that you download may be different from the ones in this guide. Therefore, remember to update the paths accordingly.

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:

Primary requirements to do a System Install include:

Additional requirements to, for example, build and run NSO production deployment examples, include:

You need to know your system specifications (Operating System and CPU architecture) in order to choose the appropriate NSO Installer.

NSO is delivered as an OS/CPU specific signed self-extractable archive. The signed archive file has the pattern nso-VERSION.OS.ARCH.signed.bin that after signature verification extracts the nso-VERSION.OS.ARCH.installer.bin archive file, where:

The following contents are unpacked:

sh nso-6.0.linux.x86_64.installer.bin --help

The System Install by default creates the following directories:

For the --system-install option, you can also choose user-defined (non-default) Installation Directory, Configuration Directory, Running Directory, and Log Directory with --install-dir, --config-dir, --run-dir and --log-dir parameters, and specify that NSO should run as a different user than root with the --run-as-user parameter.

If you choose a non-default Installation Directory by using --install-dir, you need to specify --install-dir for subsequent installs and also for backup and restore.

For more information on ncs-installer, see the ncs-installer(1) man page.

For an extensive guide to NSO deployment, refer to Deployment Example in Administration Guide .

The installation program will unpack the NSO manual pages from the documentation archive, allowing you to use the man command to view them. The manual pages are also available in the PDF format and from the online documentation located on NCS man-pages, Volume 1 in Manual Pages

Following is a list of few of the installed manual pages:

For example, to view the manual page describing NSO configuration file you should type:

$ man ncs.conf

Apart from the manual pages, extensive information about command line options can be obtained by running ncs and ncsc with the --help (abbreviated -h) flag.

$ ncs --help

$ ncsc --help

By default, the Linux kernel allows overcommit of memory. However, memory overcommit produces an unexpected and unreliable environment for NSO since the Linux Out Of Memory Killer, or OOM-killer, may terminate NSO without restarting it if the system is critically low on memory. Also, when the OOM-killer terminates NSO, no system dump file will be produced, and the debug information will be lost. Thus, it is strongly recommended that overcommit is disabled.

To achieve this with immediate effect, give the command:

# echo 2 > /proc/sys/vm/overcommit_memory

When overcommit_memory = 2, the /proc/sys/vm/overcommit_ratio parameter defines the percent of the physical RAM + swap space used. The default is "50", or 50%. This setting will underutilize RAM usage if the system has more physical RAM than 50%.

Setting the overcommit_ratio parameter to "100" will include any swap if present. On-disk memory (swap) gives the advantage of having more memory available in case an application needs more RAM than physically available momentarily. But it is usually slow, and thus best practice is to refrain from using the swap for NSO. To allocate physical RAM only, set the overcommit_ratio parameter to 100 * ((RAM - swap space) / RAM).

If the system's physical RAM (MemTotal) is less than or equal to the swap space (SwapTotal), using the swap cannot be avoided and the overcommit_ratio should be set to '100'.

Example 1 - physical RAM (MemTotal) > swap space (SwapTotal):

# cat /proc/meminfo | grep "MemTotal\|SwapTotal"
MemTotal:    8039352 kB
SwapTotal:   1048572 kB

Calculate the overcommit ratio:

100 * ((8039352-1048572)/8039352) = ~86.9%

To set both overcommit parameters with immediate effect:

# echo 2 > /proc/sys/vm/overcommit_memory
# echo 86.9 > /proc/sys/vm/overcommit_ratio

Example 2 - physical RAM (MemTotal) == swap space (SwapTotal):

# cat /proc/meminfo | grep "MemTotal\|SwapTotal"
MemTotal:    16000000 kB
SwapTotal:   16000000 kB

To set both overcommit parameters with immediate effect:

# echo 2 > /proc/sys/vm/overcommit_memory
# echo 100 > /proc/sys/vm/overcommit_ratio

To ensure the overcommit remains disabled after reboot, adjust the overcommit_ratio parameter to match your system memory and add the two lines to the /etc/sysctl.conf file. See the Linux sysctl.conf(5) manual page for details.

Refer to the Linux proc(5) manual page for more details on the overcommit_memory and overcommit_ratio parameters.

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

During upgrades, If you experience 'Communication Send Error' during license registration, restart the Smart Agent.

In a situation where NSO instance has no direct access to the Cisco Smart Software Manager, one option is Cisco Smart Software Manager Satellite that 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 desired 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:

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/, then any corresponding configuration done via the CLI is ignored.

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 Administration Guide .

Licensing activities are also logged in the NSO daemon log as described in the section called “Monitoring NSO” in 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"

To check registration status, use the command show license status.

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