Network Services Orchestrator (NSO) v5.7
NSO 5.7

NSO System Install

Introduction

NSO System Install results in system wide Installation and Deployment. Use this Install option only for Production deployment. For Development and Evaluation purposes, you should use only Local Install procedure.

Before installing NSO:

  1. Ensure that the root permissions are enabled.

  2. Choose the correct Operating System (Linux). Currently only Linux OS is supported.

  3. Ensure that Java JDK-8.x or 11.x is installed.

Installation

Procedure 1. System Install Steps

  1. Use --system-install option to perform system installation. This option creates a system install of NSO, suitable for deployment. By default, Installation Directory is created in /opt/ncs, Configuration Directory is created in /etc/ncs, Running Directory is created in /var/opt/ncs and Log Directory is created in /var/log/ncs. 

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

    The variables in the command VERSION refers to the NSO version to install. OS refers to the Operating System (linux). ARCH refers to the CPU architecture (x86_64).For example: 

    $ sudo sh nso-4.2.linux.x86_64.installer.bin --system-install

    Here, as part of the system installation, in the Installation directory /opt/ncs “ncs-4.2” distribution is available. A symbolic link /opt/ncs/current is created, pointing to the newly installed version, in this example /opt/ncs/ncs-4.2

    In the Configuration directory /etc/ncs/ ncs.conf file, SSH keys, WebUI certificates are created. In Run directory /var/opt/ncs ncs run-time state files, CDB database, packages are created.

    In Log directory /var/log/ncs ncs 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 .

    The installation has been 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 create the 'ncsadmin' group, use OS shell command: 

    # groupadd ncsadmin

    To create the 'ncsoper' group, use OS shell command: 

    # groupadd ncsoper

    To add an existing user to one of these groups, use OS shell command: 

    # usermod -a -G 'groupname' 'username'

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

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

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

    Note

    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.

    Note

    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.

    Note

    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.

  2. Change to Super User priviliges.

    $ sudo -s

  3. The installation program creates a shell script file in each NSO installation which sets environment variables needed to run NSO. With --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

  4. Start NSO.

    # /etc/init.d/ncs start

    Note

    Once you log on with the user that belongs to ncsadmin or ncsoper you can directly access the CLI. 

    $ ncs_cli -C

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

Version Upgrade

A local install allows you to create multiple runtime directories, so you can use separate directories for different NSO versions. However, for a system install, data and program state are kept in a central location, /var/opt/ncs/ by default. If you wish to use a newer version, you must perform an NSO release upgrade.

Depending on your setup and requirements, the upgrade may be quite intricate. the section called “Upgrading” in NSO 5.7 Administration Guide covers best practices and provides detailed guidance.

The recommended approach is to use the nct command, but in some simpler scenarios (single instance, no HA) the additional nct setup may present a relatively significant amount of extra work. The preceding link includes description of a manual upgrade, which you might consider in such cases.

Roughly, you upgrade an NSO instance by installing the new NSO release alongside the old one, change the /opt/ncs/current link to point to the new version, and run the new NSO with the existing data. On the first start, NSO will perform automatic upgrade of the data.

Usually the most complex part is ensuring that /var/opt/ncs/packages contains packages compiled for the new version and they are loaded on the first start, using the /etc/init.d/ncs start-with-package-reload or similar command. This is paramount and cannot be stressed enough.

As the upgrade touches data, you are also strongly encouraged to create a backup before attempting one.

NSO Uninstallation

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

    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

  • # ncs-uninstall --all

    Removes the Installation directory /opt/ncs including symbolic links, Configuration directory /etc/ncs, Run directory /var/opt/ncs, Log directory /var/log/ncs, init scripts from /etc/init.d and user profile scripts from /etc/profile.d

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

Next