Search for the product "Network Services Orchestrator" and select the desired version.
There are two versions of the NSO installer, i.e. for macOS and Linux systems. For System Install, choose the Linux OS version.
Identifying the Installer
You need to know your system specifications (Operating System and CPU architecture) 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:
VERSION is the NSO version to install.
OS is the Operating System (linux for all Linux distributions and darwin for macOS).
ARCH is the CPU architecture, for example, x86_64.
Step 3 - Unpack the Installer
If your downloaded file is a signed.bin file, it means that it has been digitally signed by Cisco, and upon execution, you will verify the signature and unpack the installer.bin.
If you only have installer.bin, skip to the next step.
To unpack the installer:
In the terminal, list the binaries in the directory where you downloaded the installer, for example:
nso-VERSION.OS.ARCH.installer.bin: The NSO installer.
nso-VERSION.OS.ARCH.installer.bin.signature: Signature generated for the NSO image.
tailf.cer: An enclosed Cisco signed x.509 end-entity certificate containing the public key that is used to verify the signature.
README.signature: File with further details on the unpacked content and steps on how to run the signature verification program. To manually verify the signature, refer to the steps in this file.
cisco_x509_verify_release.py: Python program that can be used to verify the 3-tier x.509 certificate chain and signature.
Multiple .tar.gz files: Bundled packages, extending the base NSO functionality.
Multiple .tar.gz.signature files: Digital signatures for the bundled packages.
Since NSO version 6.3, a few additional NSO packages are included. They contain the following platform tools:
HCC
Observability Exporter
Phased Provisioning
Resource Manager
For platform tools documentation, refer to individual package's README file or to the online documentation.
NED Packages
The NED Packages that are available with the NSO Installation are netsim-based example NEDs. These NEDs are used for NSO examples only.
Fetch the latest production-grade NEDs from Cisco Software Download using the URLs provided on your NED license certificates.
Manual Pages
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 PDF format and from the online documentation located on NCS man-pages, Volume 1 in Manual Pages.
Following is a list of a few of the installed manual pages:
ncs(1): Command to start and control the NSO daemon.
ncsc(1): NSO Yang compiler.
ncs_cli(1): Frontend to the NSO CLI engine.
ncs-netsim(1): Command to create and manipulate a simulated network.
ncs-setup(1): Command to create an initial NSO setup.
ncs.conf: NSO daemon configuration file format.
For example, to view the manual page describing the NSO configuration file you should type:
$manncs.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
Installer Help
Run the sh nso-VERSION.linux.x86_64.installer.bin --help command to view additional help on running binaries. More details can be found in the ncs-installer(1) manual page included with NSO.
Notice the two options for --local-install or --system-install.
shnso-6.0.linux.x86_64.installer.bin--help
Step 4 - Run the Installer
To run the installer:
Navigate to your Install Directory.
Run the installer with the --system-install option to perform System Install. This option creates an Install of NSO that is suitable for deployment.
The System Install by default creates the following directories:
The Installation Directory is created in /opt/ncs, where the distribution is available.
The Configuration Directory is created in /etc/ncs, where the ncs.conf file, SSH keys, and WebUI certificates are created.
The Running Directory is created in /var/opt/ncs, where runtime state files, CDB database, and packages are created.
The Log Directory is created in /var/log/ncs, where the log files are populated. Also, init scripts are created in /etc/init.d/ncs and system-wide environment variables are created in /etc/profile.d/ncs.sh.
For the --system-install option, you can also choose a 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.
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)
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 NSO aborts due to failure to allocate memory, NSO will produce a system dump by default before aborting. When starting NSO from a non-root user, set the NCS_DUMP environment variable to point to a filename in a directory that the non-root user can access. The default setting is NCS_DUMP=ncs_crash.dump, where the file is written to the NSO run-time directory, typically NCS_RUN_DIR=/var/opt/ncs. If the user running NSO cannot write to the directory the NCS_DUMP environment variable points to, generating the system dump file will fail, and the debug information will be lost.
Step 5 - Set Up User Access
The installation is configured for PAM authentication, with group assignment based on the OS group database (e.g. /etc/group file). Users that need access to NSO must belong to either the ncsadmin group (for unlimited access rights) or the ncsoper group (for minimal access rights).
To set up user access:
To create the ncsadmin group, use the OS shell command:
# groupadd ncsadmin
To create the ncsoper group, use the OS shell command:
# groupadd ncsoper
To add an existing user to one of these groups, use the OS shell command:
# usermod -a -G 'groupname' 'username'
Step 6 - Set Environment Variables
To set environment variables:
Change to Super User privileges.
$sudo-s
The installation program creates a shell script file in each NSO installation which sets the environment variables needed to run NSO. With the --system-install option, by default, these settings are set on the shell. To explicitly set the variables, source ncs.sh or ncs.csh depending on your shell type.
# source /etc/profile.d/ncs.sh
Start NSO.
# /etc/init.d/ncs start
Once you log on with the user that belongs to ncsadmin or ncsoper, you can directly access the CLI as shown below:
$ncs_cli-C
Step 7 - Runtime Directory Creation
As part of the System Install, the NSO daemon ncs is automatically started at boot time. You do not need to create a Runtime Directory for System Install.
Step 8 - Generate License Registration Token
To conclude the NSO installation, a license registration token must be created using a (CSSM) account. This is because NSO uses Cisco Smart Licensing to make it easy to deploy and manage NSO license entitlements. Login credentials to the Cisco Smart Software Manager (CSSM) account are provided by your Cisco contact and detailed instructions on how to create a registration token can be found in the Cisco Smart Licensing. General licensing information covering licensing models, how licensing works, usage compliance, etc., is covered in the Cisco Software Licensing Guide.
To generate a license registration token:
When you have a token, start a Cisco CLI towards NSO and enter the token, for example:
admin@ncs# license smart register idtoken
YzIzMDM3MTgtZTRkNC00YjkxLTk2ODQtOGEzMTM3OTg5MG
Registration process in progress.
Use the 'show license status' command to check the progress and result.
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 development entitlement for the NSO instance itself is requested.
Inspect the requested entitlements using the command show license all (or by inspecting the NSO daemon log). An example output is shown below.
If no registration token is provided, NSO enters a 90-day 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
...
Communication Send Error
During upgrades, If you experience a 'Communication Send Error' during license registration, restart the Smart Agent.
If You are Unable to Access Cisco Smart Software Manager
In a situation where the NSO instance has no direct access to the Cisco Smart Software Manager, one option is the Cisco Smart Software Manager Satellite which 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.
License Registration in HA Mode
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.
Licensing Log
Licensing activities are also logged in the NSO daemon log as described in Monitoring NSO. 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"
Check Registration Status
To check the registration status, use the command show license status.
admin@ncs# show license status
Smart Licensing is ENABLED
Registration:
Status: REGISTERED
Smart Account: Network Services 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
System Install FAQs
Frequently Asked Questions (FAQs) about System Install.
Is there a dependency between the NSO Installation Directory and Runtime Directory?
No, there is no such dependency.
Do you need to source the ncsrc file before starting NSO?
No. By default, the environment variables are configured and set on the shell with System Install.
Can you start NSO from a directory, which is not a NSO runtime directory?
Yes.
Can you stop NSO from a directory, which is not a NSO runtime directory?
Yes.
For evaluation and development purposes, instead of a Local Install, you performed a System Install. Now you cannot build or run NSO examples as described in README files. How can you proceed further?
The easiest way is to Uninstall the System install using ncs-uninstall --all and do a Local Install from scratch.
Can we move NSO Installation from one folder to another ?
