Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Cisco Device Agent

Cisco NX-OS Device Agent Overview

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.

Manually installing an agent for Cisco devices involves the following steps:

  • Modify the guestshell disk size, memory and cpu, and restart the guestshell in order to take effect.
  • Copy the device agent from the Apstra Server and installing it.
  • Modify the aos_config file.

The Cisco GuestShell is not partitioned to be unique with Apstra. If there are other applications hosting on the guestshell, any changes in the guestshell could impact them.


Commands in the "Bootstrap" or "Pristine" configuration may interfere with Apstra configuration added during fabric deployment.

Adding NX-OS configuration "system jumbomtu" with a value lower than MTUs used by Apstra causes Apstra MTU commands to fail.

Device Configuration Requirements

Configuration steps must happen in order on NX-OS - VRF, NXAPI, GuestShell, Create Management VRF. Apstra's device agent requires the use of VRF of the name management to allow for agent-server communication. Ensure these lines appear in the running configuration.

Resize and Enable Guestshell

Either the guestshell is running or not restarting or enabling the service is required after the the following step.

Resize the guestshell disk space, memory and cpu by executing the next commands:

If the guestshell is not enable, proceed to activate it by executing "guestshell enable", otherwise, if it was already running please run "guestshell reboot" command in order to restart the shell.

Verify that the guestshell is activated again:

Download Agent Installer

We can easily copy the installation agents over HTTPS from the Apstra server. After downloading, confirm the MD5sum of your downloaded copy matches what Apstra stores.


The Cisco device needs to connect to the Apstra server using HTTPS in order to retrieve the agent file, please make sure that this connectivity is OK before proceeding.

Apstra ships the agent from the Apstra Server. We can copy it to the /volatile, or volatile: filesystem location. Apstra also ships with an md5sum file in the /home/admin folder on the Apstra Server.

Replace the aos_server_ip variable and aos_version from the run file below, you can find this exact version from the Apstra Server, Platform --> About (i.e '3.2.2-12')

Validate that the file was downloaded correctly.

Install Cisco Device Agent

The Apstra agent on Cisco is installed by running it as a shell script directly as root on the Cisco NXOS switch. This command must be done within the guest shell. After installing the agent and before starting the service, aos.conf file needs to be modified to connect to the server.


We recommend that you save your current running-config to the startup-config 'copy running-config startup-config' to save your latest changes in case of any issue.

Change the required parameters in the Apstra configuration file before enabling the Apstra service (see next steps).

Device Agent Configuration File

You can configure the Cisco NX-OS device agent configuration file directly at /etc/aos/aos.conf. See Apstra device agent configuration file for parameters. After updating the file, start the Apstra device agent. with the command service aos start.

Activate Apstra Devices on the Apstra Server

When the Apstra device agent communicates with Apstra, it uses a ‘device key’ to identify itself. For Cisco NXOS switches, the device key is the MAC address of the management interface ‘eth0’.

Deploy Device

From the left navigation menu of the Apstra GUI, navigate to Devices > Managed Devices. When the agent is up and running it appears in this list, and can be acknowledged and assigned to a Blueprint using the GUI per standard procedure.

Reset Apstra Device Agent

If you need to reset the Apstra agent for some reason (changing blueprints, redeploying, restoring device from backup, etc.) it's best to clear the Apstra agent metadata, re-register the device, and redeploy to the blueprint.

Uninstall Apstra Device Agent

To uninstall the agent, first undeploy and unassign it from the blueprint per standard procedures using the GUI. You can also delete it entirely from the Managed Devices page.

To remove the Apstra package from NX-OS, destroy the guestshell. Do this only if no other applications are using the guestshell:

Remove Apstra EEM Scripts

The Apstra device agent installs some event manager applets to assist with telemetry. These can be safely removed

C9K-172-20-65-5(config)# no event manager applet AOS_PROTO_VSH_LAUNCH C9K-172-20-65-5(config)# no event manager applet AOS_STATS_VSH_LAUNCH C9K-172-20-65-5(config)# no event manager applet aos_bgp_applet C9K-172-20-65-5(config)# no event manager applet aos_ifdown_applet C9K-172-20-65-5(config)# no event manager applet aos_ifup_applet

Cisco Agent Troubleshooting

The Apstra agent runs under the NXOS guestshell to interact with the underlying bash and Linux environments. This is an internal Linux Container (LXC) in which Apstra operates. Under LXC, Apstra makes use of the NXAPI and other methods to directly communicate with NXOS. For security reasons, Cisco partitions much of the LXC interface away from the rest of the NXOS device, so we must drop to the guest shell bash prompt to perform more troubleshooting commands.

Confirm the Guest Shell is running on NX-OS The Apstra agent runs under the NXOS Guest Shell to interact with the underlying bash and linux environments. This is an internal Linux Container (LXC) in which Apstra operates. We are checking to make sure the guest shell is activated and running.

Showing registered services

Confirm Network Reachability to Apstra

Check ICMP Ping to the Apstra Server by pinging within the guest shell. On NXOS, we have to use the ‘chvrf <vrf>’ command to run commands within the context of a VRF. In this case, ‘management’ VRF.

Confirm Agent Installation

Check if the Apstra device agent package is installed. In NXOS, the Apstra agent installs to /etc/rc.d/init.d/aos to start when the guestshell instance starts.

Check that Apstra Agent is Running

Check the running system state with the ‘service’ command, and check running processes with the ‘ps’ command. We are looking to confirm aos_agent is running properly.

Check for Presence of Files in /etc/aos

Under the guest shell, Apstra stores a number of configuration files under /etc/aos.

Check for Apstra Data in /var/log/aos

Apstra writes the internal database to /var/log/aos

Determine Apstra Agent Version

The Apstra agent version is available in /etc/aos/version. Before executing this command we need to attach to aos service.

DNS Resolution Failure

Apstra agent is sensitive to the DNS resolution of the metadb connection. Ensure that the IP and/or DNS from /etc/aos/aos.conf is reachable from the device eth0 management port.

Apstra Service Takes Long Time to Start on Cisco NX-OS

The GuestShell feature on Cisco NXOS takes a few minutes to initialize the NXAPI within the LXC container. Apstra does not have control over this to make it any faster. Apstra Engineering has added a wait-delay to the initialization of the Apstra scripts to account for this delay. This wait is normal.

Apstra Stops and ails Without Errors (MGMT VRF)

Ensure that the guestshell is properly behind management VRF.

We should not be able to ping the Apstra server when running ‘ping’ command by default:

Below - we expect a ping from global default routing table to Apstra server at to fail, but succeed under the guest shell.

Verify MGMT VRF in NX-OS Guest Shell