3. NISH client

3.1. Overview

This section describes some of the main features of the NISH client, such as the interface for managing multiple SR OS nodes, navigation options, help and assistance options, direct access to Linux, SR OS node configuration, and operational state management.

3.1.1. SR OS node management

The NISH client provides an MD-CLI interface to multiple SR OS nodes. The NISH client uses the model-driven networking capabilities built into SR OS to identify the software version and obtain the MD-CLI schema for each SR OS node. This allows the NISH MD-CLI to generate the correct CLI tree that can be navigated within each SR OS node context. It also ensures that each node context is specific to its own software version.

The NISH client also allows the operator to issue Linux commands on the local machine, without leaving the MD-CLI shell. This capability provides increased productivity during extended management activities.

When launched, the NISH client provides an extensible MD-CLI interface. After the trademark, legal, and disclaimer information, NISH displays the following:

Starting nish application...
admin's password:
Connecting to test1 port 57400
!!! Creating unsecure connection !!!
 
Reading MD-CLI service capabilities...
 
Reading MD-CLI service event context...
[==============================================================================]
 
Reading MD-CLI service schemas...
[==============================================================================]
 
[]
A:admin@test1# ?
 
 admin                 + Enter the admin context
 configure             + Enter the configuration context
 environment           + Enter the environment configuration context
 file                  + Enter the file management context for file operations
 li                    + Enter the lawful intercept context
 password              - Change password command
 state                 + Show state information
 
 Global commands:
 back                  - Move back one or more levels
 delete                - Delete an element from the candidate datastore
 edit-config           - Enter a candidate configuration mode
 enable                - Enable administrative mode
 exec                  - Execute commands from a file
 exit                  - Return to the previous working context or to the → 
operational root
 history               - Show the most recently entered commands
 logout                - Exit the CLI session
 oam                   - Enter the oam context
 ping                  - Ping an IP address or DNS name
 pwc                   - Show the present working context
 ssh                   - Execute ssh command
 telnet                - Telnet to IP address or DNS name
 top                   - Move to the top level of the context
 traceroute            - Trace route to a destination
 tree                  - Show the command tree under the present working context
 
[]
A:admin@test1#

3.1.2. Navigation

Navigation in the NISH client MD-CLI interface is similar to navigation in the MD-CLI interface directly attached to a node. The NISH MD-CLI provides a YANG model-aware tree structure generated by SR OS. Users can navigate the tree structure using the tree, back, top, and exit commands, enter a branch by typing the branch name into the CLI, and enter a list by typing the list name and key.

For more information about navigation in MD-CLI, refer to the 7450 ESS, 7750 SR, and 7950 XRS MD-CLI Command Reference Guide.

3.1.3. Help and assistance

Context-sensitive help and auto-completion are supported within the NISH MD-CLI.

The Linux man pages provide usage assistance for NISH. For more information, see Linux man pages.

3.1.4. Direct Linux access

Unlike operating directly in MD-CLI, the NISH MD-CLI provides a hybrid shell that allows users to enter Linux commands directly on the local workstation, without leaving the MD-CLI shell. This provides a flexible working environment for managing multiple nodes.

The following example shows output of a configure system setup, with execution of both Linux and MD-CLI commands:

(pr)[configure system]
A:admin@test1# ls -la
total 96
dr-xr-x---.  7 root root  4096 Jun 11 13:06 .
dr-xr-xr-x. 18 root root   261 Apr 15 13:21 ..
-rw-------.  1 root root  1860 Apr 15 12:00 anaconda-ks.cfg
-rw-------   1 root root 21113 Jun 11 13:06 .bash_history
-rw-r--r--.  1 root root    18 May 11  2019 .bash_logout
-rw-r--r--.  1 root root   176 May 11  2019 .bash_profile
-rw-r--r--   1 root root   290 May 11 18:24 .bashrc
drwx------   4 root root    32 May 22 12:30 .cache
drwx------   3 root root    18 Apr 15 15:44 .config
-rw-r--r--   1 root root     0 May 22 11:04 config
-rw-r--r--.  1 root root   100 May 11  2019 .cshrc
drwxr-xr-x   2 root root    25 May  6 17:23 .docker
-rw-r--r--   1 root root    62 May  6 13:06 .gitconfig
-rw-------   1 root root    97 Jun  1 14:58 .lesshst
lrwxrwxrwx   1 root root    23 Apr 15 13:28 misc_vol -> /media/gluster/misc_vol
-rw-------   1 root root     0 Jun  4 12:16 .python_history
-rw-r--r--   1 root root 30123 May  6 16:14 screenlog.0
drwx------   2 root root    57 May  6 13:26 .ssh
-rw-r--r--.  1 root root   129 May 11  2019 .tcshrc
-rw-------   1 root root   533 Apr 15 14:50 .viminfo
 
(pr)[configure system]
A:admin@test1# cat .bashrc
# .bashrc
 
# User specific aliases and functions
alias rm='rm -i'
alias cp='cp -i'
alias mv='mv -i'
 
# Source global definitions
if [ -f /etc/bashrc ]; then
. /etc/bashrc
 
fi

If a command exists in both the MD-CLI and the Linux shell, the MD-CLI command takes precedence. This is shown in the following output example, which uses the time command:

(pr)[configure system]
A:admin@test1# time echo “hello world”
                    ^^^^
MINOR: MGMT_CORE #2201: Unknown element - 'echo'
(pr)[configure system]
A:admin@test1# time 
(pr)[configure system time]
A:admin@test1# time echo “hello world” 
"hello world"
0.00user 0.00system 0:00.00elapsed 93%CPU (0avgtext+0avgdata 1944maxresident)k
0inputs+0outputs (0major+84minor)pagefaults 0swaps
 
(pr)[configure system time]
A:admin@test1#

3.1.5. SR OS node configuration

The NISH MD-CLI provides the ability to see and edit individual router configurations using the transactional configuration modes available in MD-CLI (private, exclusive, global, and read-only).

The following example shows this ability:

[]
A:admin@test1# edit-config private
INFO: CLI #2070: Entering private configuration mode
INFO: CLI #2061: Uncommitted changes are discarded on configuration mode exit
 
(pr)[]
A:admin@test1# configure system
 
(pr)[configure system]
A:admin@test1# name example
 
*(pr)[configure system]
A:admin@test1# compare
-   name "test1"
+   name "example"
 
*(pr)[configure system]
A:admin@test1# commit
 
(pr)[configure system]
A:admin@example#

3.1.6. SR OS node operational state

The NISH MD-CLI provides the ability to obtain the operational state of the SR OS node, using the info command within the state tree, as shown in the following example:

[]
A:admin@example# /state
 
[state]
A:admin@example# system
 
[state system]
A:admin@example# info | match oper-name
    oper-name "example"

3.2. Installing the NISH client

The NISH client is delivered as a set of RPM packages and is supported on the CentOS 7 Linux distribution. The NISH RPMs are placed into a local directory on the target machine and installed using the YUM package manager built into CentOS 7.

Prerequisites

  1. RPMs downloaded from the Nokia support portal
  2. CentOS 7
  3. Linux administrative user access rights

To install the NISH client, perform the following steps:

  1. Put the NISH client RPM packages in a local directory on the target machine.
  2. Use the YUM package manager built into CentOS 7 to install the NISH RPMs.
    Example
    [root@server ~]# yum localinstall -y nish-20.7-R1.el7.x86_64.rpm →
    nish-deps-20.7 R1.e17.x86_64.rpm Last metadata expiration check: 2:33:56 ago on 
    Thu 11 Jun 2020 11:42:12 CEST.
    Dependencies resolved.
    ===================================================================================
    Package     Architecture    Version       Repository            Size
    ===================================================================================
    Installing:
     nish       x86_64          20.7-R1.el7   @commandline          1.4 M
     nish-deps  x86_64          20.7-R1.el7   @commandline          3.9 M
    Transaction Summary
    ===================================================================================
    Install  2 Packages
    Total size: 5.3 M
    Installed size: 18 M
    Downloading Packages:
    Running transaction check
    Transaction check succeeded.
    Running transaction test
    Transaction test succeeded.
    Running transaction
      Preparing        :
    1/1  Installing       : nish-deps-20.7-R1.el7.x86_64
    1/2  Running scriptlet: nish-deps-20.7-R1.el7.x86_64
    1/2  Installing       : nish-20.7-R1.el7.x86_64
    2/2  Running scriptlet: nish-20.7-R1.el7.x86_64
    2/2  Verifying        : nish-20.7-R1.el7.x86_64
    1/2  Verifying        : nish-deps-20.7-R1.el7.x86_64
    2/2  Installed        : nish-20.7-R1.el7.x86_64 nish-deps-20.7-R1.el7.x86_64
    Complete!
    The installation process performs the following activities:
    1. installs the NISH client into /usr/bin/nish
    2. installs the End User License Agreement (EULA) in /usr/share/licenses/nish/EULA
    3. installs an example connections file in /etc/nish/connections
    4. installs an example local schema file in /etc/nish/local-schema
    5. installs the global NISH run commands (rc) file into /etc/nish/nishrc
    6. installs the Linux man pages for the nish command
    For more information about connections, local schema files, NISH rc files, and the features they support, see Connections file, Local schema file, and NISH rc files, respectively.

3.3. Modes of operation

When installed on the Linux platform, the NISH client offers the following modes of operation:

  1. 1:1 direct mode
    In 1:1 direct mode, the NISH client connects directly to a single SR OS node and operates the MD-CLI from a local Linux workstation.
  2. 1:n static mode
    In 1:n static mode, the NISH client manages multiple SR OS nodes from a single MD-CLI shell, operates the MD-CLI from a local Linux workstation, and defines the SR nodes statically in a local configuration file.
  3. 1:n manager mode
    In 1:n manager mode, the NISH client manages multiple SR OS nodes from a single MD-CLI shell, operates the MD-CLI from a local Linux workstation, uses a Linux service to dynamically identify the SR OS nodes that are available, and automatically tracks additions and removals from the SR OS node clusters. This mode requires the installation of the NISH Manager service; see NISH manager.

Figure 2 shows the node configurations for the modes of operation supported by the NISH client.

Figure 2:  NISH client modes 

3.3.1. Using 1:1 direct mode

In 1:1 direct mode, the NISH client connects directly to a single SR OS node and operates the MD-CLI from a local Linux workstation.

Prerequisites

  1. permission to access the gRPC interface and the MD-CLI gRPC service of the target node

To start the NISH client in direct mode, perform the following steps:

  1. Execute the nish command from the command line, providing a username, hostname (or IP address), and port number of the target SR OS node:
    nish [OPTIONS] [-l user] [-p port-number] [user@]hostname
    The operator can specify the user with the -l or --login-name flag, together with the hostname in the format user@hostname or in the $NISH_USER environment variable. If no user is specified with any of these options, the default $USER environment variable is used.
    The port number defines the target node TCP port. If not set, the default port 57400 is used. The operator can specify a non-default port number with the -p or --port flag.
    The hostname defines the target SR OS node. FQDN, hostname, IPv4 address, or IPv6 address formats are accepted.
    Both the hostname and the port number can also be defined using environment variables or a NISH rc file; see NISH rc files.
    For information about the other command options, see Command options.
    Note:

    When user, target host, and target port are all defined in environment variables or in a NISH rc file, and no other options are needed, the command can be reduced to nish.

    The reduced command option only works if the arguments for another mode of operation are not defined in environment variables or a NISH rc file. The defined arguments for another mode of operation cause the NISH client to fail to determine the mode of operation and return an error.

    In the following example, admin is the username of the SR OS node user who has the required permissions. The hostname of the node is test1. The port number is the default port 57400, which does not need to be specified explicitly.
    [root@server ~]# nish admin@test1
  2. Enter the password for the SR OS node when prompted.

Figure 3 shows the communication for 1:1 direct mode.

Figure 3:  Communication between the NISH client and the SR OS node 

3.3.2. Using 1:n static mode

One of the prerequisites to start the NISH client in static mode is a connections file. The connections file contains the details of the SR OS nodes that are available for direct connections. The connections file may list multiple SR OS nodes. For more information, see Connections file.

Note:

The presence of a node in the connections file does not guarantee that the referenced node is online and available to receive NISH connections.

The referenced node must be configured correctly with gRPC, a user with gRPC access, and the gRPC MD-CLI service. The correct TLS-enabled connectivity is also recommended. For more information, see the 7450 ESS, 7750 SR, and 7950 XRS and VSR documentation.

Prerequisites

  1. a connections file; see Connections file
  2. the referenced node configured correctly with gRPC, a user with gRPC access, and the gRPC MD-CLI service; refer to the 7450 ESS, 7750 SR, and 7950 XRS and VSR documentation
  3. the correct TLS-enabled connectivity is recommended; refer to the 7450 ESS, 7750 SR, and 7950 XRS and VSR documentation

To start the NISH client in static mode, perform the following step:

  1. Execute the nish command from the command line, providing the relative or absolute path to the connections file:
    nish [OPTIONS] [-s local-schema-file] -c connection-file
    Specify the absolute or relative path to the connections file with the -c flag or --connection-file in a NISH rc file or in an environment variable; see NISH rc files.
Note:

If the path to the connections file is missing or incorrect, the NISH application starts without available nodes. The output of the command shows that the connections file is missing.

The local schema file contains the details of the locally defined NISH MD-CLI schema; see Local schema file. For information about the other options, see Command options.

Note:

When the path to the connections file is defined in an environment variable or a NISH rc file, and no other options are needed, the command can be reduced to nish.

The reduced command option only works if the arguments for another mode of operation are not defined in environment variables or in a NISH rc file. The defined arguments for another mode of operation cause the NISH client to fail to determine the mode of operation and return an error.

In the following example, the locally defined schema file is absent and the connections file is present in the same directory as the nish command:

[root@server ~]# nish -c connections-demo

When the path to the connections file is present and correct and no local schema file is defined, NISH starts with a minimal built-in MD-CLI schema. This schema defines a number of standard commands and some MD-CLI branches. The following output shows an example:

Starting nish application...
Reading local schema...
[==============================================================================]
[]
root@#
 connections           + Configuration of all devices.
 environment           + Enter the environment configuration context
 Global commands:
 back                  - Move back one or more levels
 delete                - Delete an element from the candidate datastore
 exec                  - Execute commands from a file
 exit                  - Return to the previous working context or to →
the operational root
 history               - Show the most recently entered commands
 logout                - Exit the CLI session
 pwc                   - Show the present working context
 top                   - Move to the top level of the context
 tree                  - Show the command tree under the present working context

SR OS nodes are accessed by navigating to the connections branch. In the connections branch, each node is shown under the connection list.

To connect to the required node, perform the following step:

  1. Enter connection followed by the name of the node, as shown in the following output:
[connections]
root@# connection <tab>
 test1
 test2
 
[connections]
root@# connection test1
Login: admin
admin's password: password
 
Connecting to 172.16.123.1 port 57400
!!! Creating unsecure connection !!!
 
Reading MD-CLI service capabilities...
WARNING: Unknown capability
Reading MD-CLI service event context...
[==============================================================================]
 
Reading MD-CLI service schemas...
[==============================================================================]
 
[connections connection "test1"]
A:admin@test1#

The connection list name is a device label. The connection device label is a reserved label and displays all routers that can be managed by NISH regardless of any more granular groupings. For more information about device labels, see Device labels.

When navigating to the SR OS node in the tree, NISH prompts for the username and password of an SR OS user with the appropriate access and permissions.

Navigation to alternative SR OS nodes within the MD-CLI interface is supported using the usual navigation techniques. When entering a new node, NISH prompts for the username and password for that node. The credentials for each node are cached during the established session between the NISH client and the SR OS node. For more information about credentials, see Authentication credentials.

The following example shows a multi-node navigation:

Starting nish application...
Reading local schema...
[==============================================================================]
[]
root@# connections connection ?
 
 test1
 test2
 
[]
root@# connections connection test1
Login: admin
admin's password: password
Connecting to 172.16.123.1 port 57400
!!! Creating unsecure connection !!!
 
Reading MD-CLI service capabilities...
Reading MD-CLI service event context...
[==============================================================================]
Reading MD-CLI service schemas...
[==============================================================================]
 
[connections connection "test1"]
A:admin@test1# back
[]
root@# connections connection test2
 
Login: admin
admin's password: password
Connecting to 172.16.123.2 port 57400
!!! Creating unsecure connection !!!
 
Reading MD-CLI service capabilities...
Reading MD-CLI service event context...
[==============================================================================]
Reading MD-CLI service schemas...
[==============================================================================]
 
[connections connection "test2"]
A:admin@test2# back
 
[]
root@# connections connection test1
 
[connections connection "test1"]
A:admin@test1#

3.3.3. Using 1:n manager mode

This section describes how to use the NISH client in manager mode.

Prerequisites

  1. A working NISH manager with known IP address and port number; see NISH manager.
  2. If the NISH manager is on a different host from the NISH client, the firewall permissions between the NISH client and the NISH manager must be set correctly.

To start the NISH client in manager mode, perform the following step:

  1. Execute the nish command from the command line, providing the IP address and port number to which the NISH manager service is bound:

nish [OPTIONS] [-s local-schema-file] -m address:port

Specify the address and port number of the NISH manager with the --manager or -m flag, in a NISH rc file or in an environment variable; see NISH rc files.

The local schema file contains the details of the locally defined NISH MD-CLI schema; see Local schema file.

For information about the other options, see Command options.

Note:

When the address and port number of the NISH manager are defined in environment variables or a NISH rc file, and no other options are needed, the command can be reduced to nish.

The reduced command option only works if the arguments for another mode of operation are not defined in environment variables or in a NISH rc file. The defined arguments for another mode of operation cause the NISH client to fail to determine the mode of operation and return an error.

In the following example, the local schema file is absent and the NISH manager service is bound to IP address 127.0.0.1 (the localhost) and port number 57400:

[root@server ~]# nish -m 127.0.0.1:57400

When the NISH client starts in manager mode, it makes a gRPC connection to the NISH manager service and obtains the inventory of nodes. The NISH manager uses an ON_CHANGE gRPC streaming method to ensure the inventory of nodes is continually updated.

Navigation and operation of NISH in manager mode is the same as navigation and operation of NISH in static mode. The NISH client makes direct connections to the nodes and the user traverses into them within the NISH MD-CLI; see Using 1:n static mode.

3.4. Command options

The Linux man pages provide an overview of the options and arguments for the nish command. Table 1 describes some of the options/flags that can be used when starting the NISH client.

Table 1:  Options/flags for the nish command 

Option/Flag

Description

References

--insecure-credential-cache

Enables caching of SR OS node credentials in static or manager mode

See Authentication credentials

--ca-cert

-t

Specifies TLS mode

See Security

--color

NISH_COLORS

Specifies the color scheme for the NISH environment

See NISH rc files

--no-proxy

Disables system-defined proxy settings and ignores the http_proxy and https_proxy environment variables

—

--disable-auto-completion-authorization

Disables authorization checks for the command auto-completion 1

—

    Note:

  1. Auto-completion ensures that only authorized commands are displayed in the auto-completion. Whether a user is authorized to execute a command is checked against an authorization server or local profile. Disabling this option can improve performance but allows the auto-completion to display all commands, including the commands that cannot be executed due to failing authorization. Users are not able to execute commands for which they do not have authorization. For more information about authorization, refer to the 7450 ESS, 7750 SR, 7950 XRS, and VSR System Management Guide, section “Authorization”.

3.5. Authentication credentials

By default, the NISH client prompts for user credentials when connecting to each SR OS node. The user credentials are cached for the duration of the NISH client session with the node.

It is common in SR OS node cluster deployments for a user’s credentials to be the same over all devices. This is either because a centralized provisioning and management system configures the user manually on all devices, or because an external system such as TACACS or RADIUS manages the user.

The NISH client can streamline such environments by caching a single username and password combination and automatically authenticating against each node as the user navigates into them, without further prompting.

To enable this feature, start the NISH client with the --insecure-credential-cache flag.

When the NISH client is started with this feature enabled, it prompts immediately for the username and password combination, and caches this information until the NISH client is closed.

Note:

Both static and manager NISH client modes support caching of credentials.

3.6. Device labels

Using device labels, an operator can group SR OS nodes within the NISH MD-CLI schema. A device label is a string value chosen by the operator to reference a group of SR OS nodes.

The connection device label is present by default and contains all SR OS nodes.

Groups are not predefined. The operator has the freedom to group nodes in the best way for the organization. The following are examples of SR OS node groupings:

  1. In a BNG CUPS deployment, the operator groups the user plane nodes with the UP device label and the control plane nodes with the CP device label.
  2. In a multi-platform deployment, the operator groups the SR OS nodes running on physical 7750 SR routers with the physical device label and the VSR nodes with the virtual device label.
Note:

Device labels can only contain letters and integers. Special characters are not supported.

The operator defines the device labels in a local schema file. The NISH schema in the NISH MD-CLI uses the device labels in the local schema file to group SR OS nodes; see Local schema file.

In the NISH client static mode, the operator applies the device labels defined in the local schema file to the nodes in the connections file; see Connections file.

In the NISH client manager mode, the operator applies the device labels defined in the local schema file to the nodes, using the SR OS Remote Manager feature. For more information about the configuration of remote management on an SR OS device, refer to the 7450 ESS, 7750 SR, and 7950 XRS MD-CLI Command Reference Guide, section “gRPC MD-CLI”.

When the device labels are defined in the local schema file and applied to the SR OS nodes, the NISH MD-CLI shows the SR OS nodes in the branch that matches the device label, for example:

  1. test1 is configured with the device label UP
  2. test2 is configured with the device label CP
[]
root@# connections <tab>
 connection  UP  CP
[]
root@# connections UP <tab>
 <ip>
 test1
[]
root@# connections CP <tab>
 <ip>
 test2
[]
root@# connections connection <tab>
 <ip>
 test1
 test2
Note:

A device can have only one user-defined device label and has by default the system-defined connection device label.

If the operator applies to an SR OS node a device label that is not defined in the local schema file, the node appears only under the connection device label. Only device labels defined in the local schema file are visible in the NISH MD-CLI.

If the operator defines a device label in the local schema file and does not apply it to a node, the device label appears in the NISH MD-CLI without any member nodes.

3.7. Connections file

A NISH client operating in static mode uses a connections file. The connections file is a text file that contains the details of the SR OS nodes that are available within the NISH MD-CLI.

There are no requirements for the filename.

The following are the connection file requirements:

  1. the NISH client must have access to the file location
  2. the Linux user running the NISH client must have read permissions for the file

The connections file defines a registration for each SR OS node. Each registration has the following fields:

  1. id
    The id field is the identifier string, which is usually the system name.
  2. label
    An optional device label can be used to add the node to a group; see Device labels for more information.
  3. address
    The address field consists of the IP address and port number to which the gRPC server on the SR OS node is bound. If a proxy server is used to facilitate IP address or port redirection, the IP address or port number of the proxy server can be entered.

The following example shows a connections file with one registration:

registration {
  id: "routername"
  label: "myLabel"
  address {
    address: "10.11.12.13"
    port: 57400
  }
}
Note:

String fields are enclosed in quotation marks.

Multiple devices are added in serial order within a connections file. The following example shows a connections file with two registrations:

registration {
  id: "test1"
  label: "UP"
  address {
    address: "172.16.123.1"
    port: 57400
  }
}
registration {
  id: "test2"
  label: "CP"
  address {
    address: "172.16.123.2"
    port: 57400
  }
}

After installation, there is an example connections file in /etc/nish/connections. The connections file can be edited at any time. The NISH client periodically reads the connections file and updates the list of nodes.

Note:

If the connections file is updated while using the NISH client, the operator should disable auto-save.

3.8. Local schema file

When the NISH client starts, it provides an initial MD-CLI tree to the user. This MD-CLI environment is based on a local MD-CLI schema definition. The NISH client provides a default built-in local schema. To enable user extensibility in the MD-CLI environment, the operator can create a locally defined MD-CLI schema file.

The local schema file is a text file that contains the details of the locally defined NISH MD-CLI schema extensibility definitions. It can be used in static and manager mode. There are no requirements for the filename.

The following are the requirements for the local schema file:

  1. The NISH client requires access to the file location.
  2. The Linux user running the NISH client requires read permissions for the file.
    Note:

    It is not mandatory for the local schemas to be the same for all users of the NISH client in static or manager modes. This allows administrators and users to define customized MD-CLI schemas for their own purposes.

To use a local schema file, start the NISH client with the --local-schema-file or --s flag followed by the relative or absolute path to the local schema file, or define the path to the local schema file in an environment variable or a NISH rc file. See NISH rc files.

The local schema file defines a structure called schemas. The schemas structure contains one or more schema branches that can be linked hierarchically. The schema branches are either local or remote.

  1. Local schemas
    Local schemas define branches in the NISH MD-CLI tree that operate locally on the Linux host; these are currently not supported.
  2. Remote schemas
    Remote schemas define branches in the NISH MD-CLI tree that connect to SR OS nodes.

The schema names create hierarchical structures within the MD-CLI and define device labels. The connection and all device labels are reserved and cannot be used; see Device labels.

The following example shows a local schema file with a branch containing two remote schemas. The devices schema defines the devices branch within the NISH MD-CLI. The sub-schemas UP and CP are remote schemas under the devices branch.

schemas {
  schema {
    name: "devices"
    shortDescription: "Configuration of all devices"
    schema {
      name: "UP"
      shortDescription: "User plane devices"
      schemaType: remote
    }
    schema {
      name: "CP"
      shortDescription: "Control plane devices"
      schemaType: remote
    }
  }
}
Note:

If reserved device labels are used in the local schema file, the NISH client exits with an error, as shown in the following example:

ERROR: Specified local-schema-file contains reserved schema name 'connection'

After the initial installation, there is an example local schema file in /etc/nish/local-schema.

3.9. NISH rc files

NISH provides the ability to place commonly used attributes into one or more run commands (rc) files. A NISH rc file defines variables used when starting the NISH client on the command line. When a NISH rc file is present, the user does not need to enter the defined variables manually on the command line.

After the NISH client installation, there is an example NISH rc file in /etc/nish/nishrc.

A NISH rc file can be located in the following places in the file system:

  1. globally
    The file is present in /etc/nish/nishrc and has global significance. All user instances of the NISH client use the global file.
  2. locally
    The file is present in ~/.nishrc and has local user significance (the tilda symbol (~) is equivalent to the user’s home directory or could also be referenced as $HOME/.nishrc). The specific user instance of the NISH client uses the local file. The local file takes precedence over the global file.

A user can also set the variables supported in the NISH rc file as Linux environment variables. The user-defined environment variables take precedence over the local and central NISH rc file.

User-specific command line arguments take precedence over all variables defined in the global file, the local file, or in user-defined environment variables.

Table 2 describes the supported variables in a NISH rc file.

Table 2:  NISH rc file variables 

Variable

Description

Notes

NISH_COLORS

Specifies the color scheme for the NISH environment, using the same syntax rules as the grep command

Options:

  1. mo — mode
  2. co — context
  3. uc — uncommitted changes
  4. cs — card slot
  5. un — username
  6. at — at (@)
  7. sn — system name
  8. pc — prompt character
  9. er — error message
  10. if — info message
  11. wa — warning message
  12. nt — normal text

NISH_CONNECTIONS_FILE

Defines the path to the connections file

See Connections file

NISH_HOST

Defines the address of the target node

—

NISH_LOCAL_SCHEMA_FILE

Defines the path to the local schema file

See Local schema file

NISH_MANAGER

Defines the IP address and port number of the NISH manager service in the format IP:PORT

See Using 1:n manager mode

NISH_PORT

Defines the port of the target node

—

NISH_SERVER_CACHE_PATH

Defines the location of the cached downloaded device schemas

—

NISH_USER

Defines the username that used to connect with the target node

—

3.10. Multi-node operations

The NISH client provides the ability to manage multiple nodes from a single MD-CLI shell.

When operating in 1:n manager or 1:n static mode, the NISH client generates a pseudo-node named “all” within the connection device-label (/connections connection “all” in the MD-CLI path). The operator can navigate to this pseudo-node in the same way as to a single node within the NISH client. The pseudo-node addresses supported commands to all nodes that the NISH client knows about.

In 1:n manager or 1:n static mode, the NISH client also generates a pseudo-node named “all” in each device-label context it is aware of. By navigating into the pseudo-node within a specific device-label, the supported commands are addressed to all the nodes with that specific device-label that the NISH client knows about.

3.10.1. Multi-node configuration modes

The exclusive candidate configuration mode is the only supported candidate configuration mode for NISH client multi-node operation.

To enter the exclusive candidate configuration mode, use the explicit edit-config exclusive command or the implicit configure exclusive command.

When the operator tries to enter the exclusive candidate configuration mode within a multi-node context, the NISH client attempts the following actions:

  1. connects to each SR OS node prompting for authentication credentials, if required
  2. obtains an exclusive lock on all the nodes

A warning is displayed for every node for which the NISH client cannot obtain an exclusive lock. The operator can optionally continue the configuration activities with the remaining nodes or exit from configuration mode.

A list of the nodes for which the NISH client has successfully obtained an exclusive candidate configuration lock is stored in memory, and the MD-CLI configuration commands are executed against this set of nodes.

Note:

  1. The list of nodes is created to ensure that operators have full knowledge of the set of nodes they are addressing with the configuration changes.
  2. Any node that is added, removed, renamed, or re-labeled using the NISH connections file or from the NISH manager while the exclusive lock remains in force, is ignored until the operator returns to the operational mode.

When the operator is presented with the exclusive configuration mode, the prompt changes. When the operator leaves the exclusive configuration mode, all candidate configurations on all nodes are discarded.

3.10.2. Configuration load operation

The NISH client provides the ability to provision a template-based configuration on multiple SR OS nodes with a specific device-label grouping. This operation is completed using the MD-CLI load command.

Note:

Using the MD-CLI load command is the only supported method of multi-node configuration from the NISH client. See the 7450 ESS, 7750 SR, 7950 XRS, and VSR MD-CLI Command Reference Guide for more information about the load command.

When using the load command within NISH for multiple node configuration, the merge and full-replace options are supported. The referenced configuration file supplied to the load command must be accessible from each individual SR OS node within the addressed set of nodes.

Example 1

If the command load merge cf3:/myconfig.cfg is issued, the myconfig.cfg file containing the configuration changes must be accessible in the root directory of cf3: on every node in the addressed set.

Example 2

If the command load merge ftp://user:password@100.0.0.1/myconfig.cfg is issued, every node in the set must be able to successfully connect to the FTP server at 100.0.0.1 and authenticate using the user and password credentials.

3.10.3. Multi-node commit operation

Committing configuration changes in a multi-node environment from the NISH client should be an atomic operation. This means that at the end of a commit operation for a specified set of nodes, every node should successfully commit the configuration or all the nodes should return to their configuration state prior to the commit.

The multi-node commit process driven from the NISH client utilizes standard SR OS MD-CLI features to achieve the atomic commit. There are three phases to the multi-node commit operation:

  1. validation (validate command)
  2. conditional commit (commit confirmed command)
  3. final commit (commit confirmed accept command)

At every stage, each node is processed in turn, to ensure that every node is in the desired state before the next stage.

Figure 4 shows an overview of the multi-node commit process.

Figure 4:  Multi-node commit process 

3.11. Device name conflict resolution

The NISH client can manage multiple different devices that have the same device name. This may occur in the following situations:

  1. multiple devices have the same configured system-name within the SR OS configuration
  2. multiple devices have the same device-name configured within the remote-management context
  3. an SR OS device is reached through different proxies on different TCP ports

If the NISH client is managing multiple devices and a device-name conflict exists, the devices will be presented to the operator in the MD-CLI in the following format:

<device-name>-<ip-address>-<tcp-port>

For example, two devices both named “mydevice” with different IP addresses appear as follows:

mydevice-172.16.100.3-57400

mydevice-172.16.200.5-57400

Note:

Any device with the device-name or system name “all” is always presented in the following format:

<device-name>-<ip-address>-<tcp-port>