NSO adapter

The NSO adapter connects to NSO using the web UI port and NETCONF port. Each time the NSO adapter establishes a connection to NSO, the adapter reads the service models advertised by NSO. To securely configure the NSO adapter, ensure the HTTP hostname is configured with the same hostname in the common name of the NSO server certificate.

• NSO must be installed on a server that Itential Platform can access.
• NSO does not need to be installed on the same server as Itential Platform.
• Refer to the NSO Version Support policy.

See Cisco NSO Service Manager for more information.

Adapter properties

Sample configuration

Configure at minimum the following properties before deploying:

• http.host
• http.port
• ssl.enabled
• ssl.caFile
• ssl.ciphers
• netconf.host
• netconf.port
• credentials.user
• credentials.passwd

The default configuration uses machineLogin for all transactions. To enable individual user authorization handled by NSO, NSO must be configured with an external authentication script capable of returning external group memberships for a given user ID. Ensure NSO is configured for external authentication and set authenticationStrategy.method to tokenLogin.

1
{
2
  "id": "nso",
3
  "type": "NSO",
4
  "properties": {
5
    "http": {
6
      "host": "localhost",
7
      "port": 8888
8
    },
9
    "ssl": {
10
      "enabled": true,
11
      "acceptInvalidCerts": false,
12
      "caFile": "/etc/ssl/ca.cert",
13
      "ciphers": "DHE-RSA-AES256-SHA"
14
    },
15
    "netconf": {
16
      "host": "localhost",
17
      "port": 2022,
18
      "protocol": "ssh",
19
      "frame_size": 16736
20
    },
21
    "credentials": {
22
      "user": "admin",
23
      "passwd": "admin"
24
    },
25
    "authenticationStrategy": {
26
      "type": "dynamic",
27
      "location": "NSO",
28
      "method": "machineLogin"
29
    },
30
    "netconfSubscriptions": [ "ncs-events", "ncs-alarms", "device-notifications", "service-state-changes" ],
31
    "commitWait": 30000,
32
    "commitQueue": false,
33
    "max_reconnect_attempts": 0,
34
    "total_reconnect_window": 120,
35
    "min_reconnect_interval": 30,
36
    "max_reconnect_interval": 900,
37
    "entity_cache_TTL": 24,
38
    "max_cache_entries": 5000,
39
    "poolSize": 3,
40
    "yangdirs": []
41
  }
42
}

itential-tools package compatibility with NSO

To support various versions of Cisco NSO, Itential offers two packages: itential-tools and itential-tools-nso6.4.

itential-tools

itential-tools is compatible with NSO versions: 5.6.x, 5.7.x (LTS), 5.8.x, 6.0.x, 6.1.x (LTS), 6.2.x, and 6.3.x.

itential-tools-nso6.4

itential-tools-nso6.4 is built specifically to support NSO 6.4 and above.

If you are using NSO 6.4 and above with itential-tools-nso6.4, you must use one of the following minimum versions of adapter-nso:

• Platform 6.0.3 or later
• 2023.2.14 or later
• 2023.1.34 or later

itential-tools in the Nexus repository

The Nexus repository contains two folder types: itential_tools and itential_tools-64. Each folder contains the assets and components necessary for Itential Platform to interact with NSO.

itential-tools 1.23.x supports Cisco NSO 5.6.x, 5.7.x (LTS), 5.8.x, 6.0.x, 6.1.x (LTS), 6.2.x, and 6.3.x.

itential-tools-64 supports Cisco NSO 6.4.x and above, and contains itential-tools-64-1.23.48 as the first package release.

Download from the Nexus repository

$
cd /var/opt/ncs/packages

$
tar xzf itential_tools_VERSION.tgz

$
cd itential-tools/src && make clean all -s && cd -

$
ncs_cli -u admin -C --noaaa > package reload

NSO external authentication installation

To use external authentication, install the ph-auth script and configure the ncs.conf file. The NSO external authentication script requires Python and the requests module.

Network connectivity is required between NSO and Itential Platform (typically port 3000).

$
yum install -y python python-pip
$
pip install requests

$
/var/opt/ncs/packages/itential-tools/external_auth

$
PH_ADDRESS = "localhost"
$
PH_PORT = "3000"

$
python /var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py

$
[test;test;]

$
reject

NSO external authentication configuration

Configure the ncs.conf file to use external authentication. Both external-authentication and either local-authentication or PAM should be enabled. Itential Platform initially connects using a global service account with admin privileges.

When performing transactions that can bind a request to a human user account, Itential Platform makes calls on behalf of a specific user (for example, bobjones instead of admin).

$
vi /etc/ncs/ncs.conf

1
<aaa>
2
    <ssh-server-key-dir>${NCS_CONFIG_DIR}/ssh</ssh-server-key-dir>
3
4
    <!-- Depending on OS - and also depending on user requirements -->
5
    <!-- the pam service value must be tuned. -->
6
7
    <pam>
8
        <enabled>false</enabled>
9
        <service>system-auth</service>
10
    </pam>
11
    <external-authentication>
12
        <enabled>true</enabled>
13
        <executable>/var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py</executable>
14
    </external-authentication>
15
    <local-authentication>
16
        <enabled>false</enabled>
17
    </local-authentication>
18
19
    <expiration-warning>prompt</expiration-warning>
20
</aaa>

Restart NSO:

$
service ncs restart

Configure default authgroup mappings

If the tokenLogin feature of the NSO adapter will be used, verify that users properly map to the appropriate southbound credentials. Ensure credentials are configured for the default umap inside NSO. Run this command for each authentication group, applying the appropriate device credentials as remote-name and remote-password:

$
ncs_cli -u admin -C
$
config
$
devices authgroups group default default-map remote-name admin remote-password admin
$
commit

NSO NACM rules

To use Itential Platform with an NSO NETCONF Access Control Model (NACM) implementation, reference the sample set of NACM rules provided with this package.

The NACM rules assume the following groups model:

These groups are shared across both Itential Platform and NSO. Using the sample external authentication script, Itential Platform provides the set of groups defined inside Itential Platform and discovered from the configured AAA system to NSO, to be applied to the NACM rule-lists.

The following rule-lists are provided in the sample rules:

Adjust the groups associated with these rule-lists to ensure they are mapped to the correct user accounts.

Install NACM rules in NSO

Load sample-nacm-rules.xml into the NSO CDB using the load merge feature of ncs_cli:

$
ncs_cli -u admin -C
$
config
$
load merge sample-nacm-rules.xml
$
commit dry-run
$
commit

Configure device whitelists

The sample NACM rules contain a rule-list for whitelisting devices to the users group. Configure the sample rule-list or create your own to associate devices with groups of users:

$
ncs_cli -u admin -C
$
config
$
nacm rule-list whitelist-devices rule permit-device-mydevicename path /devices/device[name='mydevicename'] action permit
$
commit

Configure service whitelists

The sample NACM rules contain a rule-list for whitelisting service instances to the users group. Add all service instances for a model to the users whitelist:

$
ncs_cli -u admin -C
$
config
$
nacm rule-list whitelist-services rule permit-service-cisco-ios path /services/cisco-ios action permit
$
commit

To add a single instance instead:

$
ncs_cli -u admin -C
$
config
$
nacm rule-list whitelist-services rule permit-service-cisco-ios-101 path /services/cisco-ios[vlan=101] action permit
$
commit

NSO NETCONF events in workflows

Configure workflows in Itential Platform to wait for Cisco NSO northbound NETCONF event notifications before proceeding.

Cisco NSO emits notifications over NETCONF for various events. The NSO adapter can be configured to listen to NSO NETCONF event streams, and the Itential Platform Event System can consume and process these events within a workflow.

Configure NSO NETCONF event streams

Event streams are configured in NSO within the ncs.conf file. NSO allows the following event streams:

• ncs-alarms
• ncs-events
• device-notifications
• service-state-changes
• NETCONF

This example configures an ncs-alarms event stream inside ncs.conf:

1
<notifications>
2
    <event-streams>
3
      <stream>
4
        <name>ncs-alarms</name>
5
        <description>NCS alarms according to tailf-ncs-alarms.yang</description>
6
        <replay-support>false</replay-support>
7
        <builtin-replay-store>
8
          <enabled>false</enabled>
9
          <dir>./state</dir>
10
          <max-size>S10M</max-size>
11
          <max-files>50</max-files>
12
        </builtin-replay-store>
13
      </stream>
14
    </event-streams>
15
</notifications>

Configure the NSO adapter to listen to NETCONF streams

Define which NSO NETCONF event streams to subscribe to using the netconfSubscriptions property in the adapter properties. Restart the NSO adapter after updating the adapter properties. The netconfSubscriptions values should correspond to the desired NSO NETCONF streams defined in ncs.conf.

Example adapter-nso properties with netconfSubscriptions defined:

1
{
2
  "id": "NSO",
3
  "type": "NSO",
4
  "properties": {
5
    "netconfSubscriptions": [
6
      "ncs-events",
7
      "ncs-alarms",
8
      "device-notifications",
9
      "service-state-changes"
10
    ],
11
    "http": {
12
      "host": "localhost",
13
      "port": 8080
14
    },
15
    "netconf": {
16
      "host": "localhost",
17
      "port": 2022,
18
      "protocol": "ssh"
19
    },
20
    "ssh": {
21
      "port": 22
22
    },
23
    "credentials": {
24
      "user": "admin",
25
      "passwd": "admin"
26
    },
27
    "commitWait": 5000,
28
    "commitQueue": false
29
  },
30
  "groups": [],
31
  "brokers": [
32
    "device",
33
    "method",
34
    "service"
35
  ]
36
}

Workflow configuration

The Workflow Engine eventListener task is used to listen for events from applications and adapters deployed inside the platform.

When a job is created, it processes all the tasks it can. Upon reaching the eventListener task, the job waits in a running state until it receives an event. The event it waits for is configured within the task itself.

Event Listener inputs

Event schema filter examples

This example processes the eventListener task only when the following payload is received:

1
{
2
  "eventTime": "2019-09-19T18:56:14.227091+01:00",
3
  "plan-state-change": {
4
    "service": {
5
      "_": "/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']"
6
    },
7
    "component": "self",
8
    "state": {
9
      "_": "ncs:init"
10
    },
11
    "operation": "created",
12
    "status": "reached"
13
  }
14
}

The JSON schema for the Event Schema Filter:

1
{
2
  "type": "object",
3
  "properties": {
4
    "eventTime": {
5
      "type": "string",
6
      "default": "2019-09-19T18:56:14.227091+01:00",
7
      "examples": ["2019-09-19T18:56:14.227091+01:00"],
8
      "format": "date-time"
9
    },
10
    "plan-state-change": {
11
      "type": "object",
12
      "properties": {
13
        "service": {
14
          "type": "object",
15
          "properties": {
16
            "_": {
17
              "type": "string",
18
              "default": "/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']",
19
              "enum": ["/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']"]
20
            }
21
          },
22
          "required": ["_"],
23
          "additionalProperties": false
24
        },
25
        "component": {
26
          "type": "string",
27
          "default": "self",
28
          "examples": ["self"]
29
        },
30
        "state": {
31
          "type": "object",
32
          "properties": {
33
            "_": {
34
              "type": "string",
35
              "default": "ncs:init",
36
              "examples": ["ncs:init"]
37
            }
38
          },
39
          "required": ["_"],
40
          "additionalProperties": false
41
        },
42
        "operation": {
43
          "type": "string",
44
          "default": "created",
45
          "examples": ["created"]
46
        },
47
        "status": {
48
          "type": "string",
49
          "default": "reached",
50
          "examples": ["reached"]
51
        }
52
      },
53
      "required": ["service", "component", "state", "operation", "status"],
54
      "additionalProperties": false
55
    }
56
  },
57
  "required": ["eventTime", "plan-state-change"],
58
  "additionalProperties": false
59
}

Itential Tools Rules Engine

The Itential Tools Rules Engine allows users to define scripts that execute prior to NSO command-sets being run. These scripts modify (add or change) values in the NSO command-sets before execution.

The rules engine has two parts: a rule engine and a script engine. The script engine reads the script files defined for the command that is passed in, reads in the defined rules, then passes the rules to the rule engine for processing.

The following files are required:

Development tools and libraries

The main framework for the Java-based application is the Java Spring framework.

System design

The Itential Tools Rules Engine has three functional areas: Script Engine, Rule Engine, and Script Validation Engine.

Script Engine — The main driver for script processing. It receives the command file containing the request to modify the NSO command-set, locates the command to get the script file to execute, reads in the script file, calls the rule engine to process the rules, modifies the NSO command-set appropriately, and returns the modified command-set. Errors are handled and returned to the calling system.

Rule Engine — Responsible for processing each rule. Input parameters are the rule and the NSO command-set. Output is the modified NSO command-set. Steps: receive parameters, determine which rule to process, perform the rule process and modify the command-set, return the modified command-set, and handle errors by passing them back to the Script Engine.

Script Validation Engine — Validates that the script has the correct format and that commands are valid with the correct number of parameters. If any validation fails, a custom Java exception is thrown with the appropriate error message and code.

Validation commands

$DLC_REPLACE — Four parameters: 1st (Any String), 2nd (Any String), 3rd (Int), 4th (Int).

$DLC_INSERT — Five parameters: 1st (Any String), 2nd (Any String), 3rd (Before or After), 4th (Int), 5th (Int).

Rule command format and usage

Arguments

Supported options within the “new string” argument

$STRING

Syntax: $STRING['my string'|'2nd string'|'3rd string']

A single value or an array of strings separated by a pipe (|) that will be printed out. An array causes a loop.

$LOOP

Syntax: $LOOP[{start}-{end}|$STRING['{string to print out}']$LOOP_VAR]

Parameters: {start} (starting int), {end} (ending int), {string to print out} (any string), $LOOP_VAR (the current loop iteration integer). Multiple references to $LOOP_VAR are supported.

Example:

1
$DLC_INSERT("access-list","new text here",AFTER,1);
2
$DLC_INSERT("access-list","new text here",BEFORE,1);
3
$DLC_INSERT("","\n$LOOP[1-100|$STRING['vlan ']$LOOP_VAR]\n",AFTER,1,1);
4
$DLC_INSERT("","\n$STRING['my string'|'2nd string'|'3rd string']\n",BEFORE,1,1)

Implementation design

Implementation of the Rules Engine includes: integration into the current itential-tools Java application, a mechanism to refresh the command list without restarting itential-tools, an option to bypass the refresh, and the ability for users to update commands and scripts.

Rule Engine integration — Include the Java jar file generated by the Rule Engine application in the private-jar or shared-jar directory to build the itential-tools application. Import the com.itential.datalore_utils.ScriptEngine package into the calling class:

1
import com.itential.datalore_utils.ScriptEngine;
2
3
ScriptEngine scriptEngine = new ScriptEngine(sCommand, sNSOCommandSet);
4
5
try {
6
    sNSOCommandSet = scriptEngine.processCommand();
7
} catch (Exception e) {
8
    e.printStackTrace();
9
}

Configure NSO for SSL

NSO SSL configuration

$
NCS_CONFIG_DIR=/etc/ncs
$
cp $NSO_SERVER_PRIV_KEY $NCS_CONFIG_DIR/ssl/cert/host.key
$
cp $CERT_DIR/$NSO_SERVER_CERTIFICATE $NCS_CONFIG_DIR/ssl/cert/host.cert

$
cp $CA_SELF_SIGNED_CERT /etc/pki/ca-trust/source
$
update-ca-trust

$
/etc/ncs/ncs.conf

1
<ncs-config xmlns="http://tail-f.com/yang/tailf-ncs-config">
2
  <webui>
3
    <transport>
4
      <ssl>
5
        <enabled>true</enabled>
6
        <ip>0.0.0.0</ip>
7
        <port>8888</port>
8
        <key-file>${NCS_CONFIG_DIR}/ssl/cert/host.key</key-file>
9
        <cert-file>${NCS_CONFIG_DIR}/ssl/cert/host.cert</cert-file>
10
      </ssl>
11
    </transport>
12
  </webui>
13
</ncs-config>

1
<ncs-config xmlns="http://tail-f.com/yang/tailf-ncs-config">
2
  <netconf-north-bound>
3
    <enabled>true</enabled>
4
    <transport>
5
      <ssh>
6
        <enabled>true</enabled>
7
        <ip>0.0.0.0</ip>
8
        <port>2022</port>
9
      </ssh>
10
      <tcp>
11
        <enabled>false</enabled>
12
        <ip>127.0.0.1</ip>
13
        <port>2023</port>
14
      </tcp>
15
    </transport>
16
  </netconf-north-bound>
17
</ncs-config>

Itential Platform NSO SSL configuration

$
CERT_DIR=/etc/ssl/certs
$
CA_SELF_SIGNED_CERT=${CERT_DIR}/certificate_authority.crt
$
NSO_HOST=nso-hostname

1
{
2
  "loggerProps": {
3
    "description": "Logging",
4
    "log_max_files": 10,
5
    "log_max_file_size": 10485760,
6
    "log_level": "debug",
7
    "log_directory": "/var/log/pronghorn",
8
    "log_filename": "my_nso.log",
9
    "log_timezone_offset": 0,
10
    "console_level": "info",
11
    "syslog": {
12
      "level": "info",
13
      "host": "10.1.0.211",
14
      "port": 1514,
15
      "protocol": "udp4",
16
      "facility": "local0",
17
      "type": "BSD"
18
    }
19
  },
20
  "isEncrypted": true,
21
  "model": "@itential/adapter-nso",
22
  "name": "my_nso",
23
  "type": "Adapter",
24
  "properties": {
25
    "id": "my_nso",
26
    "type": "NSO",
27
    "properties": {
28
      "http": {
29
        "host": "nso-hostname",
30
        "port": 8888
31
      },
32
      "ssl": {
33
        "enabled": true,
34
        "acceptInvalidCerts": false,
35
        "caFile": "/etc/ipa/ca.crt",
36
        "ciphers": "ECDHE-RSA-AES128-GCM-SHA256"
37
      },
38
      "netconf": {
39
        "host": "nso-hostname",
40
        "port": 2022,
41
        "protocol": "ssh"
42
      },
43
      "ssh": {
44
        "port": 22
45
      },
46
      "credentials": {
47
        "user": "nso_user",
48
        "passwd": "nso_pass"
49
      },
50
      "authenticationStrategy": {
51
        "type": "dynamic",
52
        "location": "NSO",
53
        "method": "tokenLogin"
54
      },
55
      "commitWait": 5000,
56
      "commitQueue": false,
57
      "max_reconnect_attempts": 0,
58
      "total_reconnect_window": 0,
59
      "min_reconnect_interval": 30,
60
      "max_reconnect_interval": 900
61
    },
62
    "groups": [],
63
    "brokers": ["device", "method", "service"]
64
  }
65
}

$
openssl s_client -connect NSOServer.com:8080

SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES128-GCM-SHA256
    Session-ID: 1A1D51D03BFB624A617626DCEEDACAF6AD0317DF9C34DF7F55802BAA776EC112
    Master-Key: 4B7827941C
    Start Time: 1595966521
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)

NSO LSA (Layered Service Architecture) setup

The following principles apply to the NSO adapter in an LSA architecture:

• Itential does not support multiple NSO instances having devices of the same name. Only one NSO instance manages a given device, and no other devices use that exact same name.
• Itential does not support multiple NSO instances having service models of the same name/path. Only one NSO instance manages a given service model.

For the following LSA architecture — an “upper” NSO service with service models defined, and one or more “lower” NSO services connected to devices — set up Itential Platform as follows:

1. Create an adapter-nso instance and point it to the upper node.
2. Create an additional adapter-nso instance for every lower node.

With this setup, you can use service models (for example, with tasks such as saveInstances) and perform device management (for example, with Configuration Manager).

NSO can also utilize an Itential Platform broker to further support this setup. When an app task like saveInstances is used, you provide the device name to the task. The Itential Platform broker queries all adapter-nso instances to see which one has that service model and uses that adapter instance. The same principle applies to tasks that directly interact with devices — for example, the golden config feature in Configuration Manager uses a broker to determine which adapter-nso instances manage which device.