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 from the Apstra GUI, you can manually install Apstra agents from the CLI. Only in rare exceptions would you need to manually install agents, which requires more effort and is error-prone. Before manually installing agents, you should have an in-depth understanding of the various device states, configuration stages, and agent operations . For assistance, contact Juniper Support.


You can also use Apstra ZTP to automatically boot and install agents and prerequisite configuration on switches. Using Apstra ZTP is simpler and easier to support at scale than manually installing agents.

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

  • Update the guestshell disk size, memory and cpu, then enable/reboot the guestshell.
  • Install the device agent.
  • Update the aos.config file.
  • Start service.

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.

If you configure NX-OS "system jumbomtu" with a value lower than the MTUs that Apstra uses, then Apstra MTU commands will fail.

Device Configuration Requirements

Configure the device in the following order: VRF, NXAPI, GuestShell, Create Management VRF. To allow for agent-server communication Apstra's device agent uses the VRF name management. Ensure these lines appear in the running configuration.

Resize and Enable Guestshell

  1. Run the following commands to resize the disk space, memory and CPU:
  2. If the guestshell is not enabled, run the command guestshell enable to activate the changes.
  3. If the guestshell was already enabled, run the command guestshell reboot to restart the shell and activate the changes.
  4. Run the command switch# show guestshell detail and verify that the guestshell has been activated.

Download Agent Installer

You 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.


To retrieve the agent file, the Cisco device connects to the Apstra server using HTTPS. Before proceeding, make sure this connectivity is functioning.

Apstra ships with 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. For the Apstra server version (4.1.0-115 for example), navigate to Platform > About).

Validate that the file was downloaded correctly.

Install Cisco Device Agent


We recommend that you run the command copy running-config startup-config to save your latest changes, in case any issues arise.

From the Cisco NX-OS switch guestshell, run the command to install the agent as shown below:

Update Agent Config File and Start Service

After installing the agent and before starting service, update the aos.conf file so it will connect to the server.

Configure the Cisco NX-OS device agent configuration file located at /etc/aos/aos.conf. See Apstra device agent configuration file for parameters.

After updating the file, run the command service aos start to start the Apstra device agent.

Activate Apstra Devices on 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

Within the guest shell, ping to the Apstra server to check ICMP Ping. When running commands within the context of a VRF, use the command chvrf <vrf> In this case, it's 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

It takes a few minutes for the GuestShell on Cisco NX-OS to initialize the NXAPI within the LXC container. This is normal. To account for this delay, a wait-delay has been added to the Apstra script initialization.

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