Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Cumulus Device Agent

Although the preferred method of installing device system agents is by creating agents in the Apstra GUI, you can manually install Apstra agents from the CLI. Only in rare exceptions is it needed to manually install agents, which requires more effort and is error-prone. An in-depth understanding of the various device states, configuration stages, and agent operations is required before manually installing agents. For assistance, contact Juniper Support.

Quick start

This section is a quick-start steps for installing the Cumulus device agent. The remaining sections describe the steps in detail.

  1. Configure management IP and VRF
  2. Activate cumulus license.
  3. Download Apstra agent.
  4. Set IP of Apstra server and enable configuration service.
  5. Restart Apstra agent
  6. Approve device in Apstra.
  7. Assign device to blueprint.

Cumulus Initial Configuration

Prior to being used with the Apstra software, Cumulus device agents require certain configuration. We've added a local username admin with password admin as part of our provisioning process. By default, the Cumulus credentials are username cumulus and password CumulusLinux! - Apstra does not depend on the username to be changed.


If you're deploying CumulusVX, (Virtual appliance), ensure the virtual switch is provided at least 1 vCPU and 2GB RAM. Cumulus VX 3.1.1 OVA template provides only for 512MB RAM. This will need to be increased.

Management Interface


Cumulus device agents require a management VRF to be set up before running the Apstra device installer. The ‘bash’ shell must also be running under the context of the management VRF prior to installation to ensure the Apstra agent can communicate to the Apstra server.

By default, Cumulus management VRF is not activated.

Add a new auto mgmt interface as a VRF and activate the eth0 interface for vrf mgmt.

After the VRF is activated, reload the network file with ifreload -a, and log back into the switch afterwards. This ensures the Bash prompt is under the management VRF routing context. Pay particular note to the new bash prompt, admin@cumulus:mgmt-vrf:~$ which indicates bash is running under the mgmt-vrf context.

Install Cumulus License

To run properly on most platforms, a license must be installed for the switch. If a license is not installed, deployment failures may occur because the command ifreload -a will fail because the switchd service isn't running.

You can pre-provision a Cumulus license for the Apstra ZTP server. You can install it manually.

If a license isn't installed, and this is not a cumulus VX platform, the command cl-license will fail.

Add the license key.

After the license is installed, restart the switchd service.

Download Agent Installer

Apstra device agent installation files for Cumulus are available from the Apstra server, served from the URL https://aos-server/device_agent_images/

For validating the downloaded file, a .md5 file is also available. Copy the .run file to the Cumulus switch, with the command vrf task exec mgmt wget -nv --no-check-certificate https://aos-server/device_agent_images/


This command assumes bash is running under the 'mgmt' vrf context. If this is not the case, omit the section vrf task exec mgmt and download the file normally.

Install Cumulus Device Agent

To install the Apstra device agent on cumulus, run the ‘.run’ file available from the Apstra Server. Once the file is downloaded, run it as a shell command. Make sure that the Apstra device agent is installed while bash is under the mgmt-vrf routing-context.

Run sudo sh

If an aos.conf file doesn't exist at first agent startup, the Apstra software creates one.

Device Agent Configuration File

You manage gevice agent configuration by editing the device agent configuration file directly. The Cumulus device agent config file is located at /etc/aos/aos.conf. See Apstra device agent configuration file for parameters. After updating the file, restart the Apstra device agent.

Device Agent Management

Bootstrap Configuration

The concept of bootstrap configuration relates to the /etc/network/interfaces configuration section as applicable to the management IP address. Bootstrap configuration is prepended to configuration jobs that Apstra pushes. This helps ensure that Apstra does not overwrite any network configuration that may prevent the agent from reaching the controller.

The bootstrap configuration is typically pushed by configuration by the user, or automated with software such as Apstra's Aeon ZTP server, or the Apstra device installer project.

Bootstrap configuration contains the minimum necessary network settings for Apstra to connect to the Apstra controller.

Cumulus Device Configuration Management

The Cumulus device agent manages the following files on the filesystem:

  • /etc/cumulus/ports.conf - specifies how port breakouts are consumed on the Cumulus platform
  • /etc/frr/frr.conf - contains all routing information for BGP on the device
  • /etc/network/interfaces - handles all Layer 2 and Layer 3 configuration on the device, including CLAG, VLANs, VXLAN, IP Routing
  • /etc/hostname - the file that Apstra manages the device hostname through
  • /etc/default/isc-dhcp-relay - specifies interfaces that participate in DHCP Relay

Deploy Device

Once the Agent is up and running it appears under Managed Devices, and can be Acknowledged and assigned to a Blueprint using the GUI per standard procedure.

Uninstall Apstra Device Agent

To remove the Apstra device agent you'll stop the agent, remove it from Apstra, then uninstall the agent.

You can unstall the Apstra device Agent on Cumulus with the steps below. Since the Apstra agent itself is mostly a compressed (squashfs) image, it can be uninstalled in a few steps.

When uninstalling the Apstra configuration applied to the various files (frr.conf, /etc/network/interfaces, etc) is removed.

Stop Apstra Service

To prevent the agent from immediately re-registering to the Apstra server, stop Apstra service on the agent before uninstalling the agent.

Remove Device

Using the Apstra GUI, undeploy and unassign the device from the blueprint per standard procedures. You can also delete it entirely from the Managed Devices page.


If you uninstall the agent before removing it from the Apstra GUI, existing configuration can no longer be erased.

Remove Apstra Package from Cumulus

Remove the Apstra package with the following command:

Clean up any other lingering files left on the filesystem.

Check if any other Apstra files remain on the filesystem.

Optionally, remove the management VRF from /etc/network/interfaces.

Cumulus Agent Troubleshooting

Check Apstra Status

Running service aos status provides output of Apstra service status.

List Running Processes

You can attach to the Apstra container with service aos attach command, then run normal Linux commands within the container. Any changes within this container are lost/destroyed after the container restarts again, it’s a read-only instance.

Display and Read Apstra Log Files

Apstra log files are stored in the /var/log/aos folder. There is typically one log file for each Apstra agent that runs. The Apstra device agent spawns off a series of other device agents for various purposes - telemetry, configuration rendering, counters, and agent health. You can read the plain-text .err files with any text editor.

  • DeviceTelemetryAgent.err - contains all diagnostic output as it relates to device telemetry.
  • DeviceKeeperAgent.err - tracks the health of the Apstra agent itself and how it mounts Apstra Graph Datastore to the Apstra Server
  • DeploymentProxyAgent.err - This file logs all configuration options managed by Apstra, and describes whether the configuration job is a complete apply or partial apply. All configuration changes by Apstra are seen here.
  • CounterProxyAgent.err - captures any custom counter collectors deployed on the switch
  • aos.log - Unused
  • XXXXXXXXXXXXX-0.err - Unused

The .tel files are tacc event logs output, used for internal support at Apstra.

Configuration not Pushed

If configuration did not get pushed, the device agent could be in 'telemetry-only' mode. Check/etc/aos/aos.conf for enable_configuration_service = 0.

You may also observe these log lines in /var/log/aos/DeviceProxyAgent.err, stating Configuration service disabled. Not setting mount timer.

Correcting this shows handle device deployment config in the log file.

Can't Ping Apstra or Use Other Network Tools

If you ping the Apstra Server on the CLI while the device is configured in a VRF, you may get confusing error messages. Make sure to use ping -I mgmt on an ICMP echo to source it from the management VRF properly.

For other commands, use vrf task exec mgmt.

Avg State is CRITICAL

When the Cumulus VM runs out of RAM, we get kernel panics and the system continues to restart by itself. The cumulus default OVA VM ships with 512MB by default.

The root cause here is there was not enough RAM to run the VM.