Building Third-Party Applications
Junos OS Evolved supports packages of signed third-party applications developed in C,
C++, and Python with the JET SDK for Junos OS Evolved. The Junos OS Evolved application
manager (SysMan) or the Linux system manager (systemd)
controls these third-party applications based on the nature and usage of the
application.
JET SDK for Junos OS Evolved
Before building a third-party application to run on your device, you must first generate signing keys to give your application permission to run. See Generating Signing Keys for more information.
Junos OS Evolved release 22.4R1 and later versions support the JET SDK for Junos OS Evolved on the following platforms:
| ACX Series | PTX Series | QFX Series |
|---|---|---|
| ACX7100-32C | PTX10001-36MR | QFX5130-32CD |
| ACX7100-48L | PTX10003 | QFX5130-48C |
| ACX7509 | PTX10004 | QFX5220 |
| PTX10008 | ||
| PTX10016 |
Downloading the JET SDK and JET Toolkit
Before you begin building a third-party application, download and install the JET SDK for Junos OS Evolved and the JET Toolkit for Junos OS Evolved. You can find these files on the Juniper Extension Toolkit (For Junos Evolved) page:
-
The JET SDK for Junos OS Evolved: jet-junos-evo-sdk-release-EVO.deb
-
The JET Toolkit for Junos OS Evolved: jet-junos-evo-toolkit-release-EVO.tar.gz
Installing the JET SDK and JET Toolkit for Junos OS Evolved
After downloading the JET Toolkit for Junos OS
Evolved, unpack the tar file and extract the Jet-evo
utility from the package.
Starting in Junos OS Evolved release 23.2R1 and later you can also
extract the Jet-evo-bundle-iso utility for creating
bundled ISOs. For more information on bundled ISOs, see
Creating a Bundled ISO.
After downloading the SDK, install and source it. The JET SDK for Junos OS Evolved is a Debian package that you can install on Debian-based Linux distributions like Ubuntu and Debian. Use the following Linux command to install the JET SDK for Junos OS Evolved release 22.4R1:
user@host:~$ dpkg -i
jet-junos-evo-sdk-22.4R1.10-EVO.debThe dpkg
command will install the SDK into the
/opt/jnpr/sdk/3.0.2-31 folder.
Next, you need to source the SDK for your third-party package. Use the following commands to source the JET SDK for Junos OS Evolved for a package in Junos OS Evolved release 22.4R1:
user@host:~/package-name$ source /opt/jnpr/sdk/3.0.2-31/environment-setup-core2-32-poky-linux user@host:~/package-name$ source/opt/jnpr/sdk/3.0.2-31/environment-setup-core2-64-poky-linux user@host:~~/package-name$ source /opt/jnpr/sdk/3.0.2-31/environment-setup-x86-pokymllib32-linux
SysMan and systemd Controlled Applications
The native Junos OS Evolved application manager (SysMan), or the
Linux system manager (systemd) can control third-party
applications. SysMan controlled applications can take advantage of
Junos OS Evolved's distributed infrastructure and run across multiple nodes.
Meanwhile, systemd managed applications can only run on a single
node, so SysMan is the preferred application manager in most
cases.
SysMan and systemd managed applications use
different methods to define policy through service files. Applications managed
through SysMan use .yaml files to define policy
and assign services. See .yaml Files for more
information.
Applications managed through systemd define policy and assign
services through .service files. See Service Files for more information.
When routing engine switchover occurs, SysMan managed applications
will start automatically on the new primary Routing Engine, but
systemd managed applications will continue running on the
original Routing Engine. We recommend using SysMan controlled
applications when possible on dual Routing Engine systems.
Folder Structure for Third-Party Applications
Third-party application packages follow a specific folder structure in Junos OS Evolved.
root-fs Folder Structure
The root-fs folder contains the following folders:
-
usr/sbin (mandatory): Contains the binary executable file for the application.
-
usr/lib64 (optional): Contains the necessary libraries for the application.
-
etc/sytemd/sytem (optional): Contains
systemdservice unit files forsystemdcontrolled applications (mandatory forsystemdmanaged applications). -
usr/conf (optional): Contains
.yamlfiles for policy generation (mandatory forSysManmanaged applications).
You can find the following optional folders outside the root-fs
folder:
-
scripts (optional): Contains the preinstall, post-install and pre-uninstall scripts.
-
etc/config (optional): Contains application specific configurations.
Post-install Folder Structure
After you install the third-party package, it will store the files at the following paths by default:
-
/usr/sbin/: Contains the binary executable files for applications in the package.
-
/usr/lib64/: Contains the libraries for applications in the package.
-
/data/var/external/current-evo-version/: Contains pre-install, post-install, and pre-uninstall script files, as well as
.bom,.sh,.fsand.imafiles for the applications in the package. -
/etc/systemd/system/: Contains
.servicefiles for setting application policies and attached services. -
/usr/conf/: Contains
.yamlfiles forSysMancontrolled applications.
You can find the files for libraries and binaries in
read-only folders. We do not recommend placing
libraries and binaries in read-write enabled folders like
/etc or /var.
Third-Party Application Files
Third-party application packages include several types of files. Keep reading for more information about the different file types:
Makefile
The Makefile is a necessary file for building and installing your third-party
application. The Makefile needs to include the paths for other files like the
SRC file, configuration file, and .yaml file. It also controls
the installation location of the necessary files.
SRC Files
SRC files contain the source code for your application. You can write SRC files in C, C++ or Python. These files are necessary for the function of your third-party application.
Script Files
Script files include pre-install, post-install and pre-uninstall scripts. These optional files are shell scripts that you can customize to fit the needs of your application.
-
Pre-install scripts run before installing your third-party package. These scripts are typically used for testing and checking various factors on your device. For example you could create a pre-install script to check the version of Junos OS Evolved that is running before starting installation.
-
Post-install scripts run after installing your third-party package. These scripts contain that commands to run after finishing installation. For example, creating additional log files or a logging directory for your package.
-
Pre-uninstall scripts run before uninstalling your third-party package. These scripts are typically used to clean up folders and files created during the installation of your third-party package.
All scripts must return zero upon successful execution and nonzero upon failure.
Scripts can be created in any folder. During the third-party package creation
process with the Jet-evo tool, you can enter the paths to each
type of script and they will be installed in the
/data/var/external/current-evo-version/
folder on your device. For more information on the Jet-evo
tool, see Jet-evo Tool Configuration.
If you are creating custom scripts, we recommend that you do not use any
bash commands that will create additional CLI output.
You can redirect CLI output to your own log file.
Service Files
Service files are mandatory files for systemd controlled
applications. These files control application policy and determine which nodes
and Routing Engines the application runs on.
You must place the service files inside the
etc/systemd/system/ folder in the
root-fs directory for your package.
The following example is a .service file for
an
application named
Sample
App. This .service file defines
the path to start the
application,
and the system state required to run the
application.
[Unit] Description="Sample App" After=syslog.target sysman.service network.target network-online.target Before=pre-evoapp-shutdown.service OnFailure=failure_handler@%p.service [Service] EnvironmentFile=/usr/conf/system/system_env TimeoutStopSec=60 WorkingDirectory=/usr/sbin ExecStart=/usr/evo/evostart -d /usr/sbin -p %p /usr/bin/python /usr/sbin/sample/sample_app.py ExecStop=/usr/sbin/exit_foo.py --bar ExecStopPost=/usr/evo/exit_handler.sh %p Restart=no StartLimitBurst=3 StartLimitInterval=300 MemoryLimit=2G RemainAfterExit=true SyslogIdentifier=sample_app
The following fields are mandatory and should be used with the same syntax as the example file:
-
After
-
Before
-
OnFailure
-
WorkingDirectory
-
ExecStart
-
ExeStopPost
.yaml Files
.yaml files are mandatory files for SysMan
controlled applications. These files are used to pass application specific
policies that are used in the creation of systemd based service
units and SysMan based policies during installation.
.yaml files are also used to determine which nodes and
Routing Engines the application runs on.
If you include both .yaml and .service
files for the same application in a package, then the
.service file attributes will take precedence and the
application will be treated as a sysman controlled
application.
Third-party packages can have more than one service attached with the package.
Each application controlled by SysMan must have a separate
.yaml file for each attached service, with the service
names as the .yaml filenames. .yaml filenames
should match with the service names, rather the package name, because
third-party package names can be different from the services included with the
package.
You must place .yaml files inside the usr/conf
folder in the root-fs directory for your package.
A .yaml file consists of multiple fields containing information
about the corresponding application. See the following list for definitions of
the .yaml file fields:
| binpath |
Defines the path to the binary executable file. |
| exec-start |
Defines how to start the application, including the path and the
arguments required for starting the application. This field
corresponds to the |
| working-dir |
Defines the path to the parent directory with binaries. |
| id |
Controls the name of the application. Should match the
|
| network |
Sets the network type, with values of |
| on-exit |
Controls the setting for restarting the application upon exit.
|
| resource |
Sets the limits to system resources used by the application:
|
The following sample .yaml file shows the configuration for a
sample application that will run on the primary Routing Engine with only 1
instance. Setting the all_nodes field to false
prevents the application from running on all Routing Engines. Setting the
max_number_of_instances field to 1 limits
the application to 1 instance. Setting the node-attribute field
to -re makes the application run on the Routing Engine. With
this configuration, if the primary Routing Engine goes down, the application
will automatically start on the backup Routing Engine.
description: "Sample app"
binpath: /usr/sbin/sample/sample_app.py
exec-start: "/usr/bin/python /usr/sbin/sample/sample_app.py"
working-dir: /usr/sbin
id: sample-app
network: internal
on-exit:
restart: true
resource:
instances:
all_nodes: false
max_num_of_instances: 1
node-attributes: - re
max-memory: 2G
startup: trueCreating a Third-Party Package
The Jet-evo tool creates third-party packages using the
applications, binaries, and libraries created by the application developer. The
process for creating a third-party package differs based on whether the Junos OS
Evolved SysMan process or the Linux systemd
process will manage the package. See below for more details on each specific
scenario:
Create a SysMan Managed Package
External applications managed by SysMan need to have
.yaml files for the services attached to the
application.
- Build and compile the application with C, C++, or Python using the JET SDK for Junos OS Evolved.
- Create the necessary folders as explained in Folder Structure for Third-Party Applications.
- Keep the binary executable in the usr/sbin/ folder.
- Keep the
.yamlfiles in the usr/conf/ folder and configuration files in the etc/config/ folder. - Run the
Jet-evotool using options specific to your package. See Jet-evo Tool Configuration for more information about the configuration options in theJet-evotool.
You can optionally package your own systemd file along
with the .yaml file if you need to use complex
functions of systemd that cannot be included in a
.yaml file. Place the service file in the
etc/systemd/system/ folder and
.yaml file in the usr/conf
folder.
Create a systemd Managed Package
External applications managed by systemd need to have a
.service file for the services attached to the
application.
- Build and compile the application with C, C++, or Python using the JET SDK for Junos OS Evolved.
- Create the necessary folders as explained in Folder Structure for Third-Party Applications.
- Keep the binary executable in the usr/sbin/ folder.
- Keep the service file in the etc/systemd/system/ folder.
- Run the
Jet-evotool using options specific to your package. See Jet-evo Tool Configuration for more information about the configuration options in theJet-evotool.
Jet-evo Tool Configuration
The Jet-evo tool is used to name your third-party package, set
the version number, run installation scripts, and set the installation location
for your third-party package. These variables are all controlled by options set
when you run the jet-evo command:
$ ./Jet-evo -h
usage: Jet-evo [-h] -n NAME -r ROOT [-v VERSION] [-a ARCH] [-N NODE]
[-i PREINSTALL] [-p POSTINSTALL] [-u PREUNINSTALL]
[-d DIRECTORY] [-x] [-t] [-l LOGFILE] [-k KEY]See Generating Signing Keys for information on generating a private key to use with the
Jet-evo tool.
Required Arguments
The following arguments are required:
| -n name |
Set the name of your third-party package. |
| -r root: |
Define the root paths to the applications included in your package, separated by commas. |
| -v version: |
Set a version number for your package. |
Optional Arguments
The following arguments are optional:
| -h |
Displays a help message explaining the |
| -a architecture |
Choose the architecture targeted by your third-party package. |
| -n node |
Define the nodes targeted by your third-party package. |
| -i pre-install |
Specify file paths to pre-install scripts. |
| -p post-install |
Specify file paths to post-install scripts. |
-u
pre-uninstall |
Specify file paths to pre-uninstall scripts. |
| -d directory |
Set the target directory for installing your package. |
| -x |
Strips all debug files from the package. |
| -t |
Create a TAR file with all the output of the
|
| -l name |
Set the name and path of the packager logging file. |
| -k key |
Private key used for signing the third-party package. |
Example Syntax
The following is an example of the syntax for the jet-evo
command using a package named sample_package with version
1.0.1:
$ jet-evo -n sample_package -v 1.0.1 -t
-i ./src/scripts/sample_package_preinstall
-p ./src/scripts/sample_package_postinstall
-u ./src/scripts/sample_package_preuninstall
-d ./target/ -r ./install/
-k ima-privkey.pem Installing a Third-Party Package
After you have built or obtained a third-party application package, you can install it onto a Junos OS Evolved device. A package can install multiple applications together. The installation process will overwrite any previously installed application that exists in the package. We recommend keeping applications inside packages unique across different packages.
Before installing a third-party application, you must first install the appropriate signing keys and certificates on all REs. Installation will fail if signing keys are not properly generated. See Generating Signing Keys for more information.
You can view installed keys by using the show security integrity
extended-keyring command.
You can install third-party packages using the request system software
add package-name command. For example:
request system software add sample_package.1.0.1.tgz
Third-party packages can only be installed from the master Routing Engine.
After successfully installing a third-party package, the installation process
will copy all associated files into the
/data/var/external/current-evo-version/
folder. The show version output will display all of the
third-party packages on each Routing Engine for a particular software version
under the External Software field:
user@host> show version Hostname: sample_host Model: ptx10008 Junos: 22.4I20221214083306-EVO Yocto: 3.0.2 Linux Kernel: 5.2.60-yocto-standard-gae998d995 JUNOS-EVO OS 64-bit [junos-evo-install-ptx-x86-64-22.4I20221214083306-EVO] External Software: JET app sample_package 1.0.1
To display all the versions of Junos OS Evolved installed on your device, and the
third-party packages installed for the current version on each node and each
Routing Engine, you can use the show software list command:
user@host> show system software list | no-more
-------------------------------
node: re0
-------------------------------
Active boot device is primary: /dev/vda
List of installed version(s) :
'-' running version
'>' next boot version after upgrade/downgrade
'<' rollback boot version
'*' deleted JSU version
> junos-evo-install-ptx-x86-64-22.4I20221214085042 - [2022-12-14 09:14:39]
- junos-evo-install-ptx-x86-64-22.4I20221214083306 - [2022-12-14 08:58:24]
< junos-evo-install-ptx-x86-64-22.4I20221214072149 - [2022-12-14 08:04:20]
junos-evo-install-ptx-x86-64-22.4I20221214055215 - [2022-12-14 06:39:46]
External Software:
JET app sample_package 1.0.1
-------------------------------
node: re1
-------------------------------
Active boot device is primary: /dev/vda
List of installed version(s) :
'-' running version
'>' next boot version after upgrade/downgrade
'<' rollback boot version
'*' deleted JSU version
> junos-evo-install-ptx-x86-64-22.4I20221214085042 - [2022-12-14 09:16:48]
- junos-evo-install-ptx-x86-64-22.4I20221214083306 - [2022-12-14 08:58:59]
< junos-evo-install-ptx-x86-64-22.4I20221214072149 - [2022-12-14 08:04:52]
junos-evo-install-ptx-x86-64-22.4I20221214055215 - [2022-12-14 06:40:38]
External Software:
JET app sample_package 1.0.1