Apstra ZTP (Devices)

Apstra ZTP is a Zero-Touch-Provisioning server for data center infrastructure systems. (Apstra ZTP replaces the community-supported Aeon-ZTPS software that was previously used for ZTP implementation in the Apstra environment.) Apstra ZTP enables you to bootstrap Apstra data center devices without considering the differences in underlying NOS mechanisms. ZTP, from an Apstra perspective, is a process that takes a device from initial boot to a point where it is managed by Apstra via device system agents.

Depending on how ZTP is configured, the process may include (but not always) the following capabilities:

• A DHCP service
• Setting the device admin/root password
• Creating a device user for device system agent
• Upgrading / downgrading NOS
• Onbox or Offbox Device System Agent installation

See also vendor-specific information:

• Juniper Junos
• Enterprise SONiC
• Cisco NX-OS
• Arista EOS

You can use an Apstra-provided VM image (.ova, .qcow2.gz, .vhdx.gz) or build your own ZTP server and use the Apstra-provided device provisioning scripts as part of the existing ZTP/DHCP process to automatically install agents on devices as part of the boot process. The Apstra ZTP reference implementation consists of the following three phases:

1. Generic DHCP Phase
   • The device requests an IP address via DHCP.
   • The device receives the assigned IP address and a pointer to a script to execute (or an OS image to install if using the Apstra-provided VM image).
2. Initialization Phase
   • The device downloads the ZTP script using TFTP.
   • The device executes the downloaded script to prepare it to be managed. This includes verifying that the device is running a supported OS.
3. Agent Installation Phase
   • The ZTP script makes an API call to install a device system agent on the device.

Apstra ZTP VM Server Resource Requirements

Apstra ZTP runs as an Ubuntu 18.04 LTS server running a DHCP, HTTP, and TFTP server and includes Apstra provided ZTP scripts that you must customize for your environment. The table below shows the minimum server specifications for a production environment:

Apstra ZTP Network requirements

In addition to the ZTP-specific network requirements, the Apstra ZTP server and device agents require connectivity to the controller. Refer to Required Communication Ports in the Juniper Apstra Installation and Upgrade Guide for more information.

You can monitor device ZTP status from the Apstra GUI. From the left navigation menu, navigate to Devices > ZTP Status > Devices.

Each device interacting with DHCP and ZTP is listed along with its System ID (serial number) if known, ZTP Status, ZTP Latest Event and when the device status was last updated.

To see the full DHCP and ZTP log for the device, click the "Show Log" icon.

Any device that interacts with DHCP or ZTP is listed. If you don't need the logs for a device anymore, click the Delete button.

Log files for all processes are in the /containers_data/logs directory.

root@apstra-ztp:/containers_data/logs# ls -l
total 7132
-rw-r--r-- 1 root root 6351759 Oct 28 17:47 debug.log
drwxr-xr-x 2 root root    4096 Oct 27 19:20 devices
-rw------- 1 root root       0 Oct 23 20:02 dhcpd.leases
-rw-r--r-- 1 root root  926980 Oct 28 17:39 info.log
-rw------- 1 root root      58 Oct 23 20:02 README
-rw------- 1 root root     469 Oct 27 02:13 rsyslog.log
root@apstra-ztp:/containers_data/logs# tail info.log
2020-10-28 17:16:38,786     root.status    INFO Incoming: dhcpd dhcpd[18]: DHCPACK on 192.168.59.9 to 04:f8:f8:6b:36:91 via eth0
2020-10-28 17:18:04,299     root.status    INFO Incoming: dhcpd dhcpd[18]: DHCPREQUEST for 192.168.59.9 from 04:f8:f8:6b:36:91 via eth0
2020-10-28 17:18:04,300     root.status    INFO Incoming: dhcpd dhcpd[18]: DHCPACK on 192.168.59.9 to 04:f8:f8:6b:36:91 via eth0
2020-10-28 17:19:29,250     root.status    INFO Incoming: dhcpd : -- MARK --
2020-10-28 17:19:29,442     root.status   ERROR Failed to update status of all containers: /api/ztp/service 404 b'{"errors":"Resource not found"}'
2020-10-28 17:33:29,353     root.status    INFO Incoming: tftp : -- MARK --
2020-10-28 17:33:29,538     root.status   ERROR Failed to update status of all containers: /api/ztp/service 404 b'{"errors":"Resource not found"}'
2020-10-28 17:33:34,768     root.status    INFO Incoming: status : -- MARK --
2020-10-28 17:39:29,349     root.status    INFO Incoming: dhcpd : -- MARK --
2020-10-28 17:39:29,539     root.status   ERROR Failed to update status of all containers: /api/ztp/service 404 b'{"errors":"Resource not found"}'
root@apstra-ztp:/containers_data/logs#

You can monitor the ZTP services on the Apstra ZTP server from the Apstra GUI. From the left navigation menu, navigate to Devices > ZTP Status > Services.

Each service name includes its Docker IP address, service status and when the service status was last updated.

You can use any configured Apstra GUI user that has API write access (such as admin), but we recommend that you create a designated user (for example "ztp") that is assigned the predefined role device_ztp. The device_ztp role allows users with that role to make API calls to the controller to request device system agent installation. For more information, see User / Role Management.

Configure the controller IP and Apstra ZTP username in the /containers_data/status/app/aos.conf file on the Apstra ZTP server.

admin@apstra-ztp:~$ sudo nano /containers_data/status/app/aos.conf
admin@apstra-ztp:~$ sudo nano /containers_data/status/app/aos.conf

{
   "ip": "192.168.59.3",
   "user": "ztp",
   "password": "ztp-user-password"
}

Apstra ZTP VM includes a TFTP and nginx HTTP server. These servers do not require configuration. Both servers serve files out of the /containers_data/tftp directory. (Cumulus is no longer supported as of Apstra version 4.1.0.)

admin@apstra-ztp:~$ sudo ls -l /containers_data/tftp/
total 232
-rwxr-xr-x 1 root root  2448 Apr 24 00:47 config_verifier.py
-rwxr-xr-x 1 root root   393 Apr 24 00:47 container_init.sh
-rwxr-xr-x 1 root root   170 Apr 24 00:47 cumulus_custom.sh
-rwxr-xr-x 1 root root    55 Apr 24 00:47 cumulus_license_file
-rwxr-xr-x 1 root root   192 Apr 24 00:47 Dockerfile
-rwxr-xr-x 1 root root   107 Apr 24 00:47 eos_custom.sh
-rwxr-xr-x 1 root root  5393 Apr 24 00:47 junos_apstra_ztp_bootstrap.sh
-rwxr-xr-x 1 root root  1799 Apr 24 00:47 junos_custom.sh
-rwxr-xr-x 1 root root    86 Apr 24 00:47 nxos_custom.sh
-rwxr-xr-x 1 root root   205 Apr 24 00:47 poap-md5sum
-rwxr-xr-x 1 root root  1843 Apr 24 00:47 rsyslog.conf
-rwxr-xr-x 1 root root   170 Apr 24 00:47 sonic_custom.sh
-rwxr-xr-x 1 root root  1910 Apr 24 00:47 ztp.json
-rwxr-xr-x 1 root root 86599 Apr 24 00:48 ztp.py
-rw------- 1 root root 86556 Apr 24 00:48 ztp.py.md5
admin@apstra-ztp:~$

The ztp.json file contains all configuration for the Apstra ZTP script ztp.py.

1. Edit the ztp.json file with vi or nano text editor.
   content_copy zoom_out_map

   admin@apstra-ztp:~$ sudo nano /containers_data/tftp/ztp.json

2. The ztp.json file is organized by the following:

   defaults - Values are used for all devices unless more specific keys are defined.	"defaults": { "device-root-password": "root-password-123", "device-user": "admin", "device-user-password": "admin-password-123", "system-agent-params": { "agent_type": "onbox", "install_requirements": false } }
   platform - Values are used for all devices for a network platform (“nxos”, “eos”, "junos", "sonic") unless more specific keys are defined.	"sonic": { "sonic-versions": ["SONiC-OS-3.4.0-Enterprise_Advanced"], "sonic-image": "http://10.85.24.52/sonic/3.4.0/sonic-3.4.0-GA-adv-bcm.bin", "device-root-password": "admin", "device-user": "admin", "device-user-password": "admin", "custom-config": "sonic_custom.sh", "system-agent-params": { "agent_type": "onbox", "job_on_create": "install" } }
   model - Values are used for all devices for a specific device model (for example “QFX10002-36Q”).	"QFX10002-36Q": { "junos-versions": ["21.2R1-S2.2"], "junos-image": "http://10.85.24.52/juniper/21.2R1-S2.2/jinstall-host-qfx-10-f-x86-64-21.2R1-S2.2-secure-signed.tgz" }
   serial number - Values are used for a device matching a specific device serial number (for example "TH0TFD6TCET0015G0015").	"TH0TFD6TCET0015G0015": { "sonic-versions": ["SONiC-OS-4.0.5-Enterprise_Advanced"], "sonic-image": "http://10.85.24.52/sonic/4.0.5/sonic-broadcom-enterprise-advanced-4.0.5-GA.bin" }

   More specific data takes precedence over other data. For example, data for a specific serial number takes precedence over any other data, then model, then platform, then finally default data.

3. The ztp.json file uses the following keys:

   junos-versions - Valid versions for Juniper Junos devices. If a device is not running a version in this list, ZTP upgrades the device with the junos-image image.	"junos-versions": [ "20.2R2-S3.5" ]
   junos-image - Filename of the Juniper Junos TGZ image to load if the running version does not match a version in the junos-versions list.	By default, the image name is loaded from the ZTP server via TFTP from the ZTP server’s /container_data/tftp/ directory. For example: "junos-image": "jinstall-host-qfx-5-20.2R2-S3.5-signed.tgz" To use any HTTP server for image transfer, enter a valid HTTP URL with IP address. For example: "junos-image": "http://192.168.59.4/jinstall-host-qfx-5-20.2R2-S3.5-signed.tgz" This example uses HTTP from the controller to transfer the Juniper Junos image.
   sonic-versions- Valid versions for SONiC devices. If a device is not running a version in this list, ZTP upgrades the device with the sonic-image image.	"sonic-versions": [ "SONiC-OS-3.1.0a-Enterprise_Base" ]
   sonic-image - Filename of the SONiC ONIE BIN image to load if the running version does not match a version in the sonic-versions list.	By default, the image name is loaded from the ZTP server via TFTP from the ZTP server’s /container_data/tftp/ directory. For example: "sonic-image": "sonic-3.1.0a-bcm.bin" To use any HTTP server for image transfer, enter a valid HTTP URL with IP address. For example: "sonic-image": "http://192.168.59.3/sonic-3.1.0a-bcm.bin" This example uses HTTP from the controller to transfer the SONiC image.
   nxos-versions - Valid versions for NX-OS devices. If a device is not running a version in this list, ZTP upgrades the device with the nxos-image image.	"nxos-versions": [ "9.2(2)", "9.3(6)" ]
   nxos-image - Filename of the NX-OS image to load if the running version does not match a version in the nxos-versions list.	By default, the image name is loaded from the ZTP server via TFTP from the ZTP server’s /container_data/tftp/ directory. For example: "nxos-image": "nxos.9.3.6.bin" To use any HTTP server for image transfer, enter a valid HTTP URL with IP address. For example: "nxos-image": "http://192.168.59.4/nxos.9.3.6.bin" This example uses HTTP from the ZTP server to transfer the Cisco NX-OS image.
   eos-versions - Valid versions for Arista EOS devices. If a device is not running a version in this list, ZTP upgrades the device with the eos-image image.	"eos-versions": [ "4.22.3M", "4.24.5M" ]
   eos-image - Filename of the Arista EOS SWI image to load if the running version does not match a version in the eos-versions list.	By default, the image name is loaded from the ZTP server via TFTP from the ZTP server’s /container_data/tftp/ directory. For example: "eos-image": "EOS-4.24.5M.swi" To use any HTTP server for image transfer, enter a valid HTTP URL with IP address. For example: "eos-image": "http://192.168.59.3/dos_images/EOS-4.24.5M.swi" This example uses HTTP from the controller to transfer the Arista EOS image.
   device-root-password - The ZTP process sets the device root password to this value. For Arista EOS and Cisco NX-OS devices, the device-root-password is used to set the password for the system admin password.	"device-root-password": "root-admin-password"
   device-user / device-user-password - Username and password that is used for the device system agent. Also, if necessary, the ZTP process creates a user on the device with this username and password.	"device-user": "aosadmin", "device-user-password": "aosadmin-password"
   custom-config - The filename of the custom configuration shell script in the TFTP directory or a URL pointing to the file on a HTTP server. This shell script runs during ZTP allowing you to add custom configuration to the device. See Platform Specific Information section below for more information.	"custom-config": "sonic_custom.sh"
   system-agent-params	Information that is used to create new users and device system agents on devices, as described below..
   agent_type - Agent type, onbox or offbox	"agent_type": "onbox"
   install_requirements - Always set to false. Not currently needed for any supported Network Operating System.	"install_requirements": false
   job_on_create - Set to install to install the onbox agent on the device	"job_on_create": "install" Junos Example { "junos": { "junos-versions": ["21.2R1-S2.2"], "junos-image": "http://10.85.24.52/juniper/21.2R1-S2.2/jinstall-host-qfx-5e-x86-64-21.2R1-S2.2-secure-signed.tgz", "device-root-password": "root123", "device-user": "admin", "device-user-password": "admin", "system-agent-params": { "platform": "junos", "agent_type": "offbox", "job_on_create": "install" } }, "QFX10002-36Q": { "junos-versions": ["21.2R1-S2.2"], "junos-image": "http://10.85.24.52/juniper/21.2R1-S2.2/jinstall-host-qfx-10-f-x86-64-21.2R1-S2.2-secure-signed.tgz" }, "JNP10002-60C [QFX10002-60C]": { "junos-versions": ["21.2R1-S1.3"], "junos-image": "http://10.85.24.52/juniper/21.2R1-S1.3/junos-vmhost-install-qfx-x86-64-21.2R1-S1.3.tgz" } }
   platform - (Required for offbox agents only) Set to the device platform ("eos", "nxos", "junos"). Lowercase only.	"platform": "junos"
   open_options - (offbox agents only) Set to enable HTTPS between offbox agent to device API interface. If open_options is not defined, the connection defaults to HTTP.	"open_options": { "proto": "https", "port": "443" }
   packages - Set to configure which additional SDK or extended telemetry packages to upload to the system agent.	"packages": [ "aos-deployment-helper-nxos", "aosstdcollectors-builtin-nxos", "aosstdcollectors-custom-nxos" ]

For REST API documentation for all available system-agent-params options in /api/system-agents, refer to Swagger.