Configure the NSO adapter

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

• NSO needs to 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.

Adapter properties

Sample configuration

The following sample configuration is provided for reference. Configure these properties: http.host, http.port, ssl.enabled, ssl.caFile, ssl.ciphers, netconf.host, netconf.port, credentials.user, credentials.passwd.

By default, the configuration uses machineLogin for all transactions. To have NSO handle individual user authorization, configure NSO with an external authentication script capable of returning external group memberships for a given user ID. Configure NSO for external authentication and set authenticationStrategy.method to tokenLogin instead of machineLogin.

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

Two packages support various Cisco NSO versions in integration with Itential Platform: 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, 6.3.x.

itential-tools-nso6.4

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

If you are using NSO 6.4 and above along with the itential-tools-nso6.4 package, 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 manager has two folder types: itential_tools and itential_tools-64. Each folder contains the assets and components that Itential Platform needs to interact with NSO.

itential-tools 1.23.x

The itential-tools 1.23.x folder contains assets that support Cisco NSO versions: 5.6.x, 5.7.x (LTS), 5.8.x, 6.0.x, 6.1.x (LTS), 6.2.x, 6.3.x.

itential-tools-64

The itential-tools-64 folder supports Cisco NSO 6.4.x and above, and contains itential-tools-64-1.23.48, which is the first package release of itential-tools-64.

Download instructions

$
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 get started with external authentication, install the ph-auth script and then 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) for use with the external authentication script.

$
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 ncs.conf to use external authentication. Enable both external-authentication and either location-authentication or PAM. Itential Platform initially connects using a global service account with admin privileges.

For transactions bound to a specific user account, Itential Platform makes calls on behalf of that 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
  <pam>
4
    <enabled>false</enabled>
5
    <service>system-auth</service>
6
  </pam>
7
  <external-authentication>
8
    <enabled>true</enabled>
9
    <executable>/var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py</executable>
10
  </external-authentication>
11
  <local-authentication>
12
    <enabled>false</enabled>
13
  </local-authentication>
14
  <expiration-warning>prompt</expiration-warning>
15
</aaa>

Restart NSO:

$
service ncs restart

Configure default authgroup mappings

If you use the tokenLogin feature, verify that all users map to the correct southbound credentials. Run this command for each authentication group and set 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

Sample NSO NACM rules

To use Itential Platform with an NSO NETCONF Access Control Model (NACM), refer to the sample NACM rules provided with this package.

The NACM rules assume the following groups model:

These groups are shared across Itential Platform and NSO. Using the sample external authentication script, Itential Platform provides the groups defined in Itential Platform—discovered from the configured AAA system—to NSO for use in NACM rule-lists.

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

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

Install NACM rules in NSO

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

Configure device allowlists

The sample NACM rules include a rule-list for allowlisting devices to the users group. Configure the sample rule-list or create your own to associate devices with groups of users. To add devices to the users allowlist:

$
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 allowlists

The sample NACM rules include a rule-list for allowlisting service instances to the users group. Configure the sample rule-list or create your own to associate services with groups of users.

To add all service instances for a model to the users allowlist:

$
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 to the users allowlist:

$
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

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

Cisco NSO emits notifications over NETCONF for various system events. You can configure the NSO adapter to listen to NSO NETCONF event streams and the Itential Platform Event System to consume and process these events in a workflow.

Configure NSO NETCONF event streams

Event streams are configured in NSO within the ncs.conf file. NSO allows the following event streams to be configured: ncs-alarms, ncs-events, device-notifications, service-state-changes, NETCONF.

This example shows how to configure an ncs-alarms event stream inside the NSO ncs.conf file:

1
<notifications>
2
  <event-streams>
3
    <stream>
4
      <n>ncs-alarms</n>
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

Configure the NSO adapter to specify which NSO NETCONF event streams to subscribe to. The event streams are defined in adapter properties using the netconfSubscriptions key. After updating adapter properties, restart the NSO adapter to begin listening to the configured streams. The netconfSubscriptions values must correspond to the NETCONF streams defined in ncs.conf.

Example configuration:

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": ["device", "method", "service"]
32
}

Workflow configuration

Use the Workflow Engine eventListener task to listen for events from applications and adapters deployed in the platform.

When a job is created, it processes all available tasks. When it reaches the eventListener task, it waits in a running state until it receives an event. You configure the specific event within the task.

Defined event listener inputs

Event schema filter examples

The following example processes the eventListener task only when this 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 is:

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 lets you define scripts that run before NSO command sets are executed. These scripts 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 for the incoming command, then reads the defined rules and passes them to the rule engine for processing.

The following files are required:

Development tools and libraries

System design

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

Script Engine

The Script Engine is the main driver for script processing. It receives the command file containing the request to modify the NSO command set. It performs the following steps:

• Read the command file.
• Locate the command to get the script file to execute.
• Read the script file to execute. This file contains the rules to run against the NSO command set.
• Call the rule engine to process the rules.
• Modify the NSO command set.
• Return the modified command set to the calling system.

Any errors are handled and returned to the calling system.

Rule Engine

The Rule Engine processes each rule. It takes the rule and NSO command set as input and returns the modified NSO command set as output. It performs the following steps:

• Receive parameters.
• Determine which rule to process.
• Process the rule and modify the NSO command set.
• Return the modified NSO command set.
• Pass any errors back to the Script Engine’s error handler.

Script Validation Engine

The Script Validation Engine validates the script format and verifies that all commands have the correct number of parameters for their command type.

If validation fails, a custom Java exception is thrown with an error message and code, and passed back to the calling system.

Validation commands

$DLC_REPLACE — four parameters:

• 1st — Any String
• 2nd — Any String
• 3rd — Int value
• 4th — Int value

$DLC_INSERT — five parameters:

• 1st — Any String
• 2nd — Any String
• 3rd — Before or After value
• 4th — Int value
• 5th — Int value

Rule command format and usage

Arguments

Supported options within the “new string” argument

$STRING

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

• $STRING — A single value or an array of strings separated by a pipe (|) symbol that will be printed out. An array will cause a loop.

$LOOP

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

• {start}:[int] — The starting number of the loop.
• {end}:[int] — The ending number of the loop.
• {string to print out}:[string] — Any string to print out.
• $LOOP_VAR:[int] — The integer value of the current loop iteration. Multiple references to $LOOP_VAR are allowed.

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

The Rule Engine implementation includes the following features:

• Integration into the itential-tools Java application.
• A mechanism to refresh the list of available commands without restarting itential-tools.
• An option to bypass the refresh feature.
• The ability for users to update commands and scripts.

Rule Engine integration

To integrate the Rule Engine into the itential-tools application, include the Java JAR file generated by the Rule Engine application in the private-jar or shared-jar directory.

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
}

Integration features

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(localhost):portNumber(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 setup

The following principles apply to the NSO adapter in an NSO 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, and no other service models use that exact same name/path.

For the following LSA architecture:

1. An “upper” NSO service that has service models defined.
2. One or more “lower” NSO services that connect 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 and point it to a 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 use an Itential Platform broker to support this setup. When you use an app task like saveInstances, provide the device name to the task. The Itential Platform broker queries all adapter-nso instances to find which one has that service model and uses that instance. The same principle applies to any tasks that interact directly with devices. For example, the golden config feature in Configuration Manager uses a broker to determine which adapter-nso instances manage each device.