Skip to content

Installing the agent#

The onboarding of an NDK agent onto the SR Linux system is simply a task of copying the agent and its files over to the SR Linux filesystem and placing them in the relevant directories.

This table summarizes an agent's components and the recommended locations to use.

Component Filesystem location
Executable file /usr/local/bin/
YANG modules /opt/$agentName/yang
Config file /etc/opt/srlinux/appmgr/$agentName.yml
Other files /opt/$agentName/

The agent installation procedure can be carried out in different ways:

  1. manual copy of files via scp or similar tools
  2. automated files delivery via configuration management tools (Ansible, etc.)
  3. creating an rpm package for the agent and its files and installing the package on SR Linux

The first two options are easy to execute, but they are a bit more involved as the installers need to maintain the remote paths for the copy commands. When using the rpm option, though, it becomes less cumbersome to install the package. All the installers deal with is a single .rpm file and a copy command.
Of course, the build process of the rpm package is still required, and we would like to explain this process in detail.

RPM package#

One of the easiest ways to create an rpm, deb, or apk package is to use the nFPM tool - a simple, 0-dependencies packager.

The only thing that nFPM requires of a user is to create a configuration file with the general instructions on how to build a package, and the rest will be taken care of.

nFPM installation#

nFPM offers many installation options for all kinds of operating systems and environments. In the course of this guide, we will use the universal nFPM docker image.

nFPM configuration file#

nFPM configuration file is the way of letting nFPM know how to build a package for the software artifacts that users created.

The complete list of options the nfpm.yml file can have is documented on the project's site. Here we will have a look at the configuration file that is suitable for a typical NDK application written in Go.

The file named ndkDemo.yml with the following contents will instruct nFPM how to build a package:

name: "ndkDemo"       # name of the go package
arch: "amd64"         # architecture you are using 
version: "v1.0.0"     # version of this rpm package
maintainer: "John Doe <[email protected]>"
description: Sample NDK agent # description of a package
vendor: "JD Corp"     # optional information about the creator of the package
license: "BSD 2"
contents:                              # contents to add to the package
  - src: ./ndkDemo                     # local path of agent binary
    dst: /usr/local/bin/ndkDemo        # destination path of agent binary

  - src: ./yang                        # local path of agent's YANG directory
    dst: /opt/ndkDemo/yang             # destination path of agent YANG

  - src: ./ndkDemo.yml                 # local path of agent yml
    dst: /etc/opt/srlinux/appmgr/      # destination path of agent yml

Running nFPM#

When nFPM configuration and NDK agent files are present, proceed with building an rpm package.

Consider the following file layout:

.
β”œβ”€β”€ ndkDemo          # agent binary file
β”œβ”€β”€ ndkDemo.yml      # agent config file
β”œβ”€β”€ nfpm.yml         # nFPM config file
└── yang             # directory with agent YANG modules
    └── ndkDemo.yang

1 directory, 4 files

With these files present we can build an RPM package using the containerized nFPM image like that:

docker run --rm -v $PWD:/tmp -w /tmp goreleaser/nfpm package \
    --config /tmp/nfpm.yml \
    --target /tmp \
    --packager rpm

This command will create ndkDemo-1.0.0.x86_64.rpm file in the current directory that can be copied over to the SR Linux system for installation.

Installing RPM#

Delivering the available rpm package to a fleet of SR Linux boxes can be done with any configuration management tools. For demo purposes, we will utilize the scp utility:

# this example copies the rpm via scp command to /tmp dir
scp ndkDemo-1.0.0.x86_64.rpm admin@<srlinux-mgmt-address>:/tmp

Once the package has been delivered to the SR Linux system, it is ready to be installed. First, we login to SR Linux CLI and drill down to the Linux shell:

ssh admin@<srlinux-address>

admin@clab-srl-srl's password: 
Using configuration file(s): []
Welcome to the srlinux CLI.
Type 'help' (and press <ENTER>) if you need any help using this.
--{ running }--[  ]--
A:srl# bash

Once in the bash shell, install the package with yum install or rpm:

sudo rpm -U /tmp/ndkDemo-1.0.0.x86_64.rpm

Tip

To check if the package was installed, issue rpm -qa | grep ndkDemo

admin@srl ~]$ rpm -qa | grep ndkDemo
ndkDemo-1.0.0-1.x86_64

During the package installation, the agent related files are copied over to the relevant paths as stated in the nFPM config file:

# check the executable location
[admin@srl ~]$ ls -la /usr/local/bin/ | grep ndkDemo
-rw-r--r-- 1 root root    12312 Nov  4 11:28 ndkDemo

# check YANG modules dir is present
[admin@srl ~]$ ls -la /opt/ndkDemo/yang/
total 8
drwxr-xr-x 2 root root 4096 Nov  4 12:58 .
drwxr-xr-x 3 root root 4096 Nov  4 12:53 ..
-rw-r--r-- 1 root root    0 Nov  4 11:28 ndkDemo.yang

# check ndkDemo config file is present
[admin@srl ~]$ ls -la /etc/opt/srlinux/appmgr/
total 16
drwxr-xr-x+  2 root    root    4096 Nov  4 12:58 .
drwxrwxrwx+ 10 srlinux srlinux 4096 Nov  4 12:53 ..
-rw-r--r--+  1 root    root       0 Nov  4 11:28 ndkDemo.yml

All the agent components are available by the paths specified in the nFPM configuration file.

Note

To update the SR Linux NDK app, the package has to be removed first

sudo yum remove ndkDemo-1.0.0 # using yum
sudo rpm -e ndkDemo-1.0.0     # using rpm

Congratulations, the agent has been installed successfully.

Loading the agent#

SR Linux's Application Manager is in charge of managing the applications lifecycle. App Manager controls both the native apps and customer-written agents.

After a user installs the agent on the SR Linux system by copying the relevant files, they need to reload the app_mgr process to detect new applications. App Manager gets to know about the available apps by reading the app configuration files located at the following paths:

Directory Description
/opt/srlinux/appmgr/ SR Linux embedded applications
/etc/opt/srlinux/appmgr/ User-provided applications

To reload the App Manager:

/ tools system app-management application app_mgr reload

Once reloaded, App Manager will detect the new applications and load them according to their configuration. The users will be able to see their app in the list of applications:

/show system application <app-name>

Managing the agent's lifecycle#

An application's lifecycle can be managed via any management interface by using the following knobs from the tools schema.

/ tools system app-management application <app-name> <start|stop|reload|restart>

The commands that can be given to an application are translated to system signals as per the following table:

Command Description
start Executes the application
reload Send SIGHUP signal to the app. This signal can be handled by the app and reload its config and change initialization values if necessary
stop Send SIGTERM signal to the app. The app should handle this signal and exit gracefully
quit Send SIGQUIT signal to the app. Default behavior is to terminate the process and dump core info
kill Send SIGKILL signal to the app. Kills the process without any cleanup

Comments