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.
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.
The NISH manager runs as a standalone application in the foreground or background of the Linux shell or as a systemd service on the 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 Debian packages and is supported on the Ubuntu 24.04 LTS 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
-
Linux man pages for nish-manager
-
log rotation schedule in /etc/logrotate.d/nish-manager
-
Ubuntu uncomplicated firewall (ufw) application definition in /etc/ufw/applications.d/nish-manager.ufw
-
example configuration file in /etc/nish-manager/nish-manager.conf
To install the NISH manager, put the packages in a local directory on the target machine and run the Ubuntu built-in APT package manager.
- Put the NISH packages in a local directory on the target machine.
-
Run the APT package manager built into Ubuntu to install the NISH
packages.
sudo apt-get install -y ./nish-manager-24.10-R1.deb
Reading package lists... Done Building dependency tree... Done Reading state information... Done Note, selecting 'nish-manager' instead of './nish-manager-24.10-R1.deb' The following NEW packages will be installed: nish-manager 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded. Need to get 0 B/2912 kB of archives. After this operation, 8860 kB of additional disk space will be used. Get:1 /home/ubuntu/nish-manager-24.10-R1.deb nish-manager amd64 24.10-R1 [2912 kB] Selecting previously unselected package nish-manager. (Reading database ... 71876 files and directories currently installed.) Preparing to unpack .../ubuntu/nish-manager-24.10-R1.deb ... Unpacking nish-manager (24.10-R1) ... Setting up nish-manager (24.10-R1) ... Processing triggers for ufw (0.36.2-6) ... Processing triggers for man-db (2.12.0-4build2) ... Scanning processes... Scanning linux images... Running kernel seems to be up-to-date. No services need to be restarted. No containers need to be restarted. No user sessions are running outdated binaries. No VM guests are running outdated hypervisor (qemu) binaries on this host.
Execution options
By default, the NISH manager is installed as a systemd Linux service and must be started to operate. The user can also start the NISH manager as an interactive process.
Interactive process
nish-manager
SR OS Software Copyright (c) Nokia 2021. All Rights Reserved.
Trademarks
Nokia and the Nokia logo are registered trademarks of Nokia. All other
trademarks are the property of their respective owners.
IMPORTANT: READ CAREFULLY
The SR OS Software (the "Software") is proprietary to Nokia and is subject
to and governed by the terms and conditions of the End User License
Agreement accompanying the product, made available at the time of your order,
or posted on the Nokia website (collectively, the "EULA"). As set forth
more fully in the EULA, use of the Software is strictly limited to your
internal use. Downloading, installing, or using the Software constitutes
acceptance of the EULA and you are binding yourself and the business entity
that you represent to the EULA. If you do not agree to all of the terms of
the EULA, then Nokia is unwilling to license the Software to you and (a) you
may not download, install or use the Software, and (b) you may return the
Software as more fully set forth in the EULA.
This product contains cryptographic features and is subject to United States
and local country laws governing import, export, transfer and use. Delivery
of Nokia cryptographic products does not imply third-party authority to
import, export, distribute or use encryption.
If you require further assistance please contact us by sending an email
to support@nokia.com.
2024-08-22 19:56:37.944 WARNING: Failed to find backup file: '/var/lib/nish-manager/connections.bkp'
2024-08-22 19:56:37.944 WARNING: Could not restore Db from: '/var/lib/nish-manager/connections.bkp'
2024-08-22 19:56:37.950 INFO: Server listening on [::]:57400
-
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.
It is also possible to start an instance of the NISH manager as an interactive process using a configuration file that contains the nish-manager command and required variables.
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.
Starting NISH manager as an interactive process
nish-manager myconfigfile.conf
See
NISH manager configuration files for more information
about configuration files.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)
You can start and enable the NISH manager within the systemd service at the same time or independently. Use the following command at the Linux shell prompt to start the NISH manager service within the systemd service. The enable operation ensures that the NISH manager starts when the system boots. The --now option ensures that the NISH manager service starts immediately.
sudo systemctl enable nish-manager --now
Use the following commands at the Linux shell prompt to perform the start and enable operations independently.
sudo systemctl start nish-manager
sudo systemctl enable nish-manager
Use the following command at the Linux shell prompt to disable and stop the NISH manager within the systemd service. The disable operation ensures that the NISH manager is no longer started upon reboot. The --now option ensures that the NISH manager service stops immediately.
sudo systemctl disable nish-manager --now
Use the following commands at the Linux shell prompt to perform the stop and disable operations independently.
sudo systemctl stop nish-manager
sudo 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 error log information.
NISH manager error log
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
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.
You can also start the NISH manager 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.
In the following example, the start command runs the service and reads from the configuration filename provided in the command after the @ symbol. The nish-manager Linux service starts and reads the configuration file /etc/nish-manager/example1.conf for its instantiation variables.
Start a specific instance of the Linux service and read its configuration file for instantiation variables
sudo systemctl start nish-manager@example1
sudo systemctl enable nish-manager@example1
You can also use these commands combined together.
Combine commands for NISH manager Linux services to read the configuration file
sudo systemctl enable nish-manager@example1 --now
To start another systemd NISH manager service, add 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.
Start another instance of the Linux service and read its configuration file for instantiation variables
sudo 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.
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 |
|
--server-cert -k |
Provides the NISH manager server certificate |
|
--server-key -K |
Provides the NISH manager server key file |
|
--log-level -l |
Defines the log level for the NISH manager log file |
|
--listen-address -a |
Specifies an IP address for the NISH manager to listen on 1,2,3 |
— |
--listen-port -p |
— |
|
--stale-after -s |
Defines the number of missed hello messages to transition a node from the up to the stale state |
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
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.
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.
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.
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 |