NISH manager

NISH manager overview

The NISH manager is an optional Linux service that provides the NISH client with a dynamic inventory of the SR OS nodes that can be managed. It correlates information about the nodes that are available. The following figure shows the inventory communication flow for the NISH client when used in conjunction with a NISH manager in a BNG CUPS deployment with two CPF nodes and three UPF nodes.

Communication with the NISH manager

SR OS nodes register with the NISH manager when configured to do so through the SR OS remote management feature. The following figure shows the SR OS remote management communication with the NISH manager.

See the 7450 ESS, 7750 SR, 7950 XRS, and VSR System Management Guide, section ‟Remote Management Using a Remote Network Interface Shell Manager” for more information about the SR OS remote management feature.

Figure 2. SR OS remote management communication with the 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 names, device labels, and IP address and port information.

The following figure shows the NISH client communication with the NISH manager.

Figure 3. 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 the NISH client and the SR OS nodes that are configured with the SR OS remote management feature. 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.

SR OS node state transitions in the NISH manager

When an SR OS node registers with the NISH manager, its state in the database of the NISH manager is up.

If the NISH manager misses the specified number of consecutive hello messages from the SR OS node, the state of the node transitions to stale in the database. Stale nodes appear in the NISH client but are not usable.

When the specified retention interval has passed, an SR OS node in the stale state transitions to the down state in the NISH manager database. The NISH manager removes SR OS nodes in the down state from its database immediately. Nodes in the down state are not shown.

If the number of hello messages is not configured, is set to 0, or the SR OS node does not support the state transition functionality, nodes transition from the up to the down (deleted) state when the specified retention interval has passed. They do not transition through the stale state.

To set the number of hello messages and the retention interval, see Command options and NISH manager configuration files.

Installing the NISH manager

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

The installation process installs the following:

NISH manager in /usr/bin/nish-manager
nish-manager as a systemd service
End User License Agreement (EULA) in /usr/share/licenses/nish-manager/EULA
Linux man pages for nish-manager
log rotation schedule in /etc/logrotate.d/nish-manager
CentOS firewalld definition in /usr/lib/firewalld/services/nish-manager.xml
example configuration file in /etc/nish-manager/nish-manager.conf

To install the NISH manager, perform the following steps:

Put the RPMs in a local directory on the target machine.

Use the YUM package manager built into CentOS 7, as shown in following example.

[root@server ~]# yum localinstall -y nish-manager-23.3-R1.el7.x86_64.rpm 
Last metadata expiration check: 1:54:38 ago on Sun 1 Jan 2023 16:19:23 CEST. 
Dependencies resolved. 
=================================================================================== 
Package Architecture Version Repository Size 
===================================================================================
Installing:
 nish-manager x86_64 23.3-R1.el7 @commandline 86 k
Transaction Summary 
=================================================================================== 
Install 2 Packages 
Total size: 4.0 M 
Installed size: 14 M 
Downloading Packages: 
Running transaction check 
Transaction check succeeded. 
Running transaction test 
Transaction test succeeded. 
Running transaction
  Preparing : 
1/1 Running scriptlet: nish-manager-23.3-R1.el7.x86_64 
1/1 Installing : nish-manager-23.3-R1.el7.x86_64 
1/1 Running scriptlet: nish-manager-23.3-R1.el7.x86_64 
1/1 Verifying : nish-manager-23.3-R1.el7.x86_64 
1/1 Installed : nish-manager-23.3-R1.el7.x86_64
Complete!

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.

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

Linux service

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

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

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

To start the NISH manager service within the systemd service 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 option 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 the systemd service, 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 option 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.

Command options

The Linux man pages provide an overview of the options and flags for the nish-manager command.

The following table describes some of the options and flags that can be used when starting the NISH manager.

Table 1. Options and flags for the nish-manager command
Option or Flag	Description	Reference
--retention -r	Defines a retention or cleanup interval	See Backup file
--backup -b	Defines a location for the backup file	See Backup file
--ca-cert -t	Specifies a CA certificate	See Configuring NISH security
--server-cert -k	Provides the NISH manager server certificate	See Configuring NISH security
--server-key -K	Provides the NISH manager server key file	See Configuring NISH security
--log-level -l	Defines the log level for the NISH manager log file	See NISH manager logging
--listen-address -a	Specifies an IP address for the NISH manager to listen on ^¹^,^²^,^³	—
--listen-port -p	Specifies a port for the NISH manager to listen on ^¹^,^²^,^³	—
--stale-after -s	Defines the number of missed hello messages to transition a node from the up to the stale state	SR OS node state transitions in the NISH manager

¹ Several listen addresses can be defined.

² If the operator omits the address and port for the NISH manager to listen on, the NISH manager listens by default on all IP interfaces available and on the default gRPC port (57400).

³ Multiple instances of the NISH manager can run on a single server or workstation, if the IP address and port combinations of the instances do not clash.

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 flag or --retention option 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 flag or --backup option 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.

NISH manager logging

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

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

Setting the verbosity level for the log file

You can set the verbosity level of the messages in the log file to the following supported options:

e - error
w - warning
i - info
d - debug

Enter the nish-manager command with the -l flag or --log-level option and the verbosity level setting.

nish-manager [-l | --log-level] level

nish-manager -l w

Changing the syslog facility

The facility that the NISH manager sends to the syslog service can be configured in the NISH manager configuration file.

Perform the following steps to change the syslog facility:

Change the value of the NISH_MANAGER_SYSLOG_FACILITY option in the NISH manager configuration file. See NISH manager configuration files.
Restart the NISH manager.

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.

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.

The following table describes the options that are supported in a NISH manager configuration file.

Table 2. Supported variables in NISH manager configuration file
Variable	Description	Multiple options per file
NISH_MANAGER_RETENTION	Time that an SR OS node or NISH client connection is retained as a valid node within the NISH manager without an update message, before it is expunged from the NISH manager	No
NISH_MANAGER_LISTEN_ ADDRESS	IPv4 or IPv6 address to which the NISH manager binds; if multiple addresses are required, multiple NISH_ MANAGER_LISTEN_ADDRESS lines must be provided, with one address per line Default is "::", which indicates to bind to all IPv4 and IPv6 addresses present on the system	Yes
NISH_MANAGER_LISTEN_ PORT	TCP port to which the NISH manager binds; if multiple ports are required, multiple NISH_MANAGER_ LISTEN_PORT lines must be provided with one port per line Default 57400 is used unless a NISH_ MANAGER_ LISTEN_PORT line is supplied	Yes
NISH_MANAGER_BACKUP_ FILE	Path to the filename that the NISH manager service reads from and writes to, for a persistent cache of connected SR OS nodes and NISH clients Default is /var/lib/nish-manager/connections.bkp	No
NISH_MANAGER_LOG_LEVEL	Logging verbosity level of the NISH manager process Default is "i" (informational)	No
NISH_MANAGER_SYSLOG_FACILITY	Syslog facility setting for logging data Default is "local7"	No
NISH_MANAGER_CA_CERT	Path to the CA TLS certificate	No
NISH_MANAGER_SERVER_ CERT	Path to the server TLS certificate	No
NISH_MANAGER_SERVER_ KEY	Path to the service TLS key	No
NISH_MANAGER_STALE_HELLO_COUNT	The number of missed hello messages to transition a node from the up to the stale state	No

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

Table 3. Example address to port bindings for configuration file variable
Example configuration file variables	Example address to port bindings
NISH_MANAGER_LISTEN_ADDRESS=1.1.1.1	1.1.1.1:57401
NISH_MANAGER_LISTEN_PORT=57401	1.1.1.1:57402
NISH_MANAGER_LISTEN_ADDRESS=2.2.2.2	2.2.2.2:57402
NISH_MANAGER_LISTEN_PORT=57402	2.2.2.2:57403