Installing a Test Agent Application¶
This page describes how to install a Test Agent Application under Linux. The Test Agent Application download includes all software needed for installation on top of your existing operating system.
The Test Agent Application can be run either in a Docker container or as a native app in Linux. The two possibilities are covered below.
Note that a Test Agent Application always needs a counterpart to be able to run performance and stability tests: either another Test Agent Application, installed on a separate PC or server, or a Test Agent of a different type. If you need assistance, please contact Juniper Networks technical support at https://support.juniper.net/support/requesting-support.
Note
For installing Test Agent Applications on Juniper routers, please turn to the Junos® OS Evolved Software Installation and Upgrade Guide. This document is found in TechLibrary under “Junos OS Evolved”:
Prerequisites¶
If you have a firewall in place on the device or in the network, make sure that the Test Agent Application is allowed to establish an outgoing session towards the Paragon Active Assurance server on TCP port 6800.
You do not need to open any incoming connections, since the Paragon Active Assurance server will communicate in the reverse direction on the same TCP session that the Test Agent Application initiated.
Installing a Test Agent Application in a Docker container¶
To install and run the Test Agent in a Docker container, you can use either the official Paragon Active Assurance Docker image, available on Docker Hub, or a Docker image of your own. We cover both options in what follows.
For general Docker documentation, go to docs.docker.com.
Getting the official Docker image¶
The official Docker image is available on Docker Hub at https://hub.docker.com/r/netrounds/test-agent-application. Instructions on how to register and start the Test Agent are given on that page.
Building your own custom Docker image¶
To build your own Docker image for the Test Agent Application, you first need to download the release tarball from Control Center.
Click Test Agents in the main menu.
Click the Download button in the top right corner.
In the dialog that appears, download the Test Agent Application tarball.
Unpack the tarball:
tar -xvzf paa-test-agent-application_<version_architecture>.tar.gz # Remove the version from the directory name mv paa-test-agent-application_<version> paa-test-agent-application/Create a custom Dockerfile in the directory where you unpacked the Test Agent tarball. An example is given below:
FROM debian:bullseye-slim RUN apt-get update && \ apt-get install -y ca-certificates iproute2 socat && \ rm -rf /var/lib/apt/lists/* COPY paa-test-agent-application/ /opt/paa-test-agent-application/ ENTRYPOINT ["/opt/paa-test-agent-application/paa-test-agent-application"]
To build your own Docker container for the Test Agent Application, you use the
docker buildcommand:docker build -t mycustom/paa-test-agent-application .
You can replace the name mycustom... with whatever you like. It is however used in the commands that follow below.
Running the custom container¶
Register the Test Agent Application to Control Center if you have not already done so:
docker run --rm -v $(pwd):/config mycustom/paa-test-agent-application \ register --config /config/agent.conf \ --ncc-host <Control Center hostname> \ --account <Control Center account> \ --email <Control Center user email> \ --password <Control Center user password> \ --api-token <API token for user in Control Center> \ --name <Test Agent name>
The configuration file written by the Test Agent is now stored as
agent.confin the current directory.Then start the Test Agent with the configuration file:
docker run --network=host --cap-add=NET_ADMIN --device=/dev/net/tun -d \ --privileged -v $(pwd):/config -v /var/run/netns:/var/run/netns \ --log-opt max-size=10m --log-opt max-file=2 <Test Agent docker image> \ --config /config/agent.conf -A [-T]
Note
If you want the Test Agent to use hardware timestamping, you need to add the -T option.
Note
If you want to do 5G core network testing, you need to remove the -A option from the register-run command and add the option –enable-interface-daemon to that command.
The options --cap-add=NET_ADMIN, --device=/dev/net/tun, and -D are necessary for 5G RAN interfaces to work.
The --privileged option and the /var/run/netns:/var/run/netns argument allow the Test Agent to use network namespaces to route the traffic independently.
The -A option causes the Test Agent to detect all available namespaces and their interfaces.
The --log-opt option is used to limit the size and number of the logfiles produced by the Test Agent (these files can be inspected with the command docker logs <container ID>, which is useful for container management generally). Limiting the logfiles in some way is necessary since otherwise they will grow without limit. Above, the maximum logfile size is set to 10 MB and the maximum number of logfiles to 2, with log rotation applied to the data.
See the help output for more information about the command line arguments:
docker run --rm mycustom/paa-test-agent-application --help
Installing a Test Agent Application as a native app in Linux¶
Downloading the application¶
See above.
Installing the application¶
# Unpack the Test Agent Application tarball
tar -xvzf paa-test-agent-application_<version_architecture>.tar.gz
# Move the contents of the directory to a more permanent location
sudo mv paa-test-agent-application_<version> /opt/paa-test-agent-application
# Set root as owner and group of the new directory
sudo chown -R root:root /opt/paa-test-agent-application
Registering the application¶
To connect the Test Agent to Control Center, run the command below.
This command will register the Test Agent Application to Control Center and write its credentials to a file /etc/paa-test-agent-application.conf. The Test Agent Application will be tied to your Paragon Active Assurance account through an encrypted and secure connection, and it will appear in the Test Agents view in Control Center with an “offline” icon next to it.
If Control Center does not have a valid SSL certificate, add the --ssl-no-check option to the command. Note that this is not recommended for security reasons.
sudo /opt/paa-test-agent-application/paa-test-agent-application register \
--config /etc/paa-test-agent-application.conf \
--ncc-host <Control Center hostname> \
--account <Control Center account> \
--email <Control Center user email> \
--password <Control Center user password> \
--api-token <API token for user in Control Center> \
--name <Test Agent name>
If you specify the Control Center user email as a command line argument, but do not specify a password, the Test Agent will prompt for the Control Center user password. For example:
sudo /opt/paa-test-agent-application/paa-test-agent-application register \
--config /etc/paa-test-agent-application.conf \
--ncc-host app.netrounds.com \
--account myaccount \
--email me@example.com \
--name "My Test Agent"
Enter password for dev@netrounds.com in PAA Control Center:
If you do not specify an email address either, the Test Agent will prompt for the API token of the user in Control Center:
sudo /opt/paa-test-agent-application/paa-test-agent-application register \
--config /etc/paa-test-agent-application.conf \
--ncc-host app.netrounds.com \
--account myaccount \
--name "My Test Agent"
Enter API token for user in PAA Control Center:
Note that, for enhanced security, the two methods just mentioned are the preferred ways to pass the user credentials during registration. However, in scenarios where other restrictions prevent an interactive registration of the Test Agent, you can instead pass credentials as command arguments --password <user password> and --api-token <user API token>, as indicated in the beginning of this section.
Make sure you escape any special characters in the password correctly in your shell.
Starting the application¶
To start up the registered Test Agent, run this command:
/opt/paa-test-agent-application/paa-test-agent-application \
--config /etc/paa-test-agent-application.conf -A
Optionally, an explicit command run can be given here:
/opt/paa-test-agent-application/paa-test-agent-application run \
...
The -A option causes the Test Agent to detect all available namespaces and their interfaces.
On being started, the Test Agent will appear as “ready” in Control Center.
If Control Center does not have a valid SSL certificate, add the --ssl-no-check option to the above command. Again, note that this is not recommended for security reasons.
Registering and starting the application in one command¶
A special command register-run is provided which first registers the Test Agent with Control Center and then starts it. Its syntax combines that of the register and run commands given above.
For a Test Agent in a Docker container, use this:
docker run --network=host --cap-add=NET_ADMIN --device=/dev/net/tun -d \
--privileged -v $(pwd):/config -v /var/run/netns:/var/run/netns \
--log-opt max-size=10m --log-opt max-file=2 <Test Agent docker image> \
register-run --config /config/agent.conf -A [-T] \
--ncc-host <Control Center hostname> \
--account <Control Center account> \
--email <Control Center user email> \
--password <Control Center user password> \
--api-token <API token for user in Control Center> \
--name <Test Agent name>
Note
If you want to do 5G core network testing, you need to remove the -A option from the register-run command and add the option –enable-interface-daemon to that command.
For a Test Agent installed as a native app in Linux, use this:
sudo /opt/paa-test-agent-application/paa-test-agent-application register-run \
--config /etc/paa-test-agent-application.conf -A \
--ncc-host <Control Center hostname> \
--account <Control Center account> \
--email <Control Center user email> \
--password <Control Center user password> \
--api-token <API token for user in Control Center> \
--name <Test Agent name>
Note
If the registration cannot be done interactively, the register-run command should not be used since it would require storing user credentials in start-up scripts. In such a situation it is better to perform a two-step start-up where you first register the Test Agent and then start it.
Automatic application start¶
To have systemd start a previously registered Test Agent Application automatically on boot, add the following to /etc/systemd/system/paa-test-agent-application.service:
[Unit]
Description=Paragon Active Assurance Test Agent Application
After=network.target
[Service]
ExecStart=/opt/paa-test-agent-application/paa-test-agent-application \
--config /etc/paa-test-agent-application.conf
[Install]
WantedBy=default.target
If Control Center does not have a valid SSL certificate, add the --ssl-no-check option to the ExecStart command.
Reload the systemd units, then enable and start the Test Agent Application:
systemctl daemon-reload
systemctl enable paa-test-agent-application.service
systemctl start paa-test-agent-application.service
Check if the Test Agent Application service started:
systemctl status paa-test-agent-application.service
The application’s status icon should turn green in the Test Agents view, meaning that the application is ready to use.
Using the Test Agent Application¶
Log in to Control Center with your user credentials. If you have successfully registered and started the Test Agent, it should now be listed as online in the Control Center web interface, and you can start using it for measurements.
Troubleshooting¶
Check that no firewalls are blocking the connection to Control Center on TCP port 6800.
Check that Control Center has a valid SSL certificate or that you have added the
--ssl-no-checkoption to the agent command.Check the logs from the agent. If you are using
systemdto start the agent, the logs will be available using the commandjournalctl -u test-agent-application.To get more detailed logs, enable debug logging by adding the
--log-level DEBUGoption to the Test Agent Application start command.If you are still having problems, please contact Juniper Networks technical support at https://support.juniper.net/support/requesting-support.