4.1. Overview

The NISH manager is a Linux service that provides a dynamic inventory of SR OS nodes that can be managed to the NISH client.

The NISH manager is positioned between the NISH clients and the SR OS nodes and correlates information about which nodes and which clients are available.

Figure 5 shows NISH CLI management of a BNG CUPS deployment with two CP nodes, three UP nodes, and the NISH manager.

Figure 5:  NISH manager overview 

The SR OS nodes register with the NISH manager when configured to do so through the SR OS Remote Manager feature. Figure 6 shows the SR OS remote-management communication with the NISH manager.

For more information about the SR OS Remote Manager feature, refer to the 7450 ESS, 7750 SR, 7950 XRS, and VSR System Management Guide.

Figure 6:  SR OS remote management communication with NISH manager 

When a NISH client is started in manager mode, it registers with the NISH manager. The NISH manager provides the details of the available SR OS nodes to the NISH client, including the names, device labels, and IP address and port information.

Figure 7 shows the NISH client communication with the NISH manager.

Figure 7:  NISH client communication with NISH manager 

The NISH manager runs as a standalone application in the foreground or background of the Linux shell or as a systemd service on the CentOS 7 Linux distribution. Using user-specified IP address and port combinations, the NISH manager listens for connections from a NISH client and SR OS nodes that are configured with the SR OS Remote Manager. By default, the NISH manager listens on all available IP interfaces and on the default gRPC port (57400).

The NISH manager does not make any outbound connections to the SR OS nodes or to the NISH client, although it does respond to both.

4.2. Installing the NISH manager

The NISH manager is delivered as a set of RPM packages and is supported on the CentOS 7 Linux distribution.

To install the NISH manager, perform the following steps:

The installation process installs the following:

4.3. Execution options

By default, the NISH manager is installed as a systemd Linux service and must be started to operate. The operator can also start the NISH manager as an interactive process.

4.3.1. Interactive process

When the preferred method of execution is an interactive process, the operator can start the NISH manager from the Linux command line, as shown in the following example:

[root@server ~]# nish-manager

2020-06-16 18:57:16.329 WARNING: Failed to read backup file: →

'/var/lib/nish-manager/connections.bkp'

2020-06-16 18:57:16.329 WARNING: Could not restore Db from: →

'/var/lib/nish-manager/connections.bkp'

2020-06-16 18:57:16.330 INFO: Server listening on [::]:57400

Note: To use the nish-manager command to start the NISH manager service, the user must have the required Linux permissions to bind the service to an IP address and TCP port. The IP address and port number specified cannot conflict with an instance of the NISH manager service that is already running. This also applies if the running instance of the NISH manager service is running within systemd. To run the NISH manager service in the background, append an ampersand (&) to the command. For information about additional command options, see Command options. The displayed warnings about the connections.bkp file are the expected behavior for the first run because there is no backup file yet; see Backup file.

The nish-manager command can also be started as an interactive process using a configuration file that contains the required variables to start an instance of the NISH manager. For more information about configuration files, see NISH manager configuration files.

To start the NISH manager as an interactive process using a configuration file, append the filename to the nish-manager command as shown in the following example:

[root@server ~]# nish-manager myconfigfile.conf

4.3.2. Linux service

The NISH manager is installed as a Linux systemd service, which for security reasons is installed as follows:

1. in a stopped state (not running)
2. disabled (does not start automatically on reboot)

The operator can either start and enable the NISH manager within systemd at the same time or independently.

To start the NISH manager service within systemd and ensure that it restarts when the service or workstation is rebooted, issue the following commands:

[root@server ~]# systemctl enable nish-manager --now

The enable operation ensures that the NISH manager is started on system boot. The --now switch ensures that the NISH manager service starts immediately.

It is also possible to perform the start and enable operations independently. To do so, issue the following commands:

[root@server ~]# systemctl start nish-manager

[root@server ~]# systemctl enable nish-manager

To disable and stop the NISH manager within systemd, issue the following command:

[root@server ~]# systemctl disable nish-manager --now

The disable operation ensures that NISH manager is no longer started upon reboot. The --now switch ensures that the NISH manager service stops immediately.

To perform the stop and disable operations independently, issue the following commands:

[root@server ~]# systemctl stop nish-manager

[root@server ~]# systemctl disable nish-manager

The following example shows the nish-manager.log output file after startup. After the trademark, legal, and disclaimer information, NISH displays the following:

2020-06-16 18:52:47.952 WARNING: Failed to read backup file: →

'/var/lib/nish-manager/connections.bkp'

2020-06-16 18:52:47.952 WARNING: Could not restore Db from: →

'/var/lib/nish-manager/connections.bkp'

2020-06-16 18:52:47.953 INFO: Server listening on [::]:57400

Note: The displayed warnings about the connections.bkp file are the expected behavior for the first run because there is no backup file yet; see Backup file.

Multiple NISH manager systemd services can be started simultaneously and each one can maintain its own configuration in a NISH manager configuration file; see NISH manager configuration files for more information.

By default, when the NISH manager is started as a systemd service (for example, using systemctl start nish-manager) it reads from the /etc/nish-manager/nish-manager.conf configuration file, if this file exists. If this file does not exist, the default values are used.

The NISH manager can also be started by systemd using the values specified in a specific NISH manager configuration file. This configuration file must be located in the /etc/nish-manager directory and .conf must be appended to the file extension.

To start a systemd instance of the NISH manager using a configuration file, issue the commands as shown in the following example:

[root@server ~]# systemctl start nish-manager@example1

[root@server ~]# systemctl enable nish-manager@example1

The start command runs the service and reads from the configuration filename provided in the command after the @ symbol. In this example, the nish-manager Linux service starts and reads the configuration file /etc/nish-manager/example1.conf for its instantiation variables.

These commands can be combined together as shown in the following example:

[root@server ~]# systemctl enable nish-manager@example1 --now

Another systemd NISH manager service can be started by adding the configuration filename (without the .conf file extension) after the @ symbol. In the following example, a NISH manager service instance starts and reads the /etc/nish-manager/example2.conf configuration file for its instantiation variables:

[root@server ~]# systemctl enable nish-manager@example2 --now

Multiple systemd NISH manager services can run in parallel if the IP address and TCP port combination bindings do not overlap.

4.4. Command options

The Linux man pages provide an overview of the options/flags for the nish-manager command. Table 3 describes some of the specific options/flags that can be used when starting the NISH manager.

4.5. Backup file

The NISH manager retains state information in a backup file. It writes the state information to the backup file for every change in the node connections.

To set the retention or cleanup time for connection registrations, use the -r or --retention flag followed by a value in minutes. The NISH manager discards connections that have a timestamp older than the retention period (default is 60 minutes).

To set the location of the backup file, use the -b or --backup flag followed by the absolute or relative path to the backup file. When the flag is present without a path, no backup file is created. When the flag is absent, the backup file is in the default location: /var/lib/nish-manager/connections.bkp.

When the NISH manager starts, it checks whether it was previously run. If a backup file is present, the NISH manager loads the previous state into its dynamic inventory.

4.6. Logging

When running a systemd service, the NISH manager writes logs continually into a plain text logfile located at /var/log/nish-manager/nish-manager.log on the local file system.

When running as a standalone program, the NISH manager writes logs continually to STDOUT.

To set the verbosity level for the log file, use the -l or --log-level flag. The following are the allowed values:

4.7. NISH manager configuration files

The NISH manager provides the ability to place commonly used attributes into a configuration file that is provided when the NISH manager starts. The configuration file can be used when executing the NISH manager as an interactive process or as a Linux service.

Note: When a configuration file is provided, the user does not need to manually provide any variables on the command line. However, if variables are provided on the command line, they overwrite the variables provided in the configuration file.

Configuration file location

After the NISH manager installation is completed, an example (and default) configuration file can be found in /etc/nish-manager/nish-manager.conf.

When executing the nish-manager command as a systemd service or as an interactive service, the configuration file must be placed in the /etc/nish-manager directory. This is the only location that the system checks for the file.

Configuration file variables

Table 4 describes the variables that are supported in a NISH manager configuration file.

It is permitted to provision multiple variables in the configuration file for the NISH manager listen address and listen port. Table 5 lists example address/port bindings when multiple variables are used in the configuration file.