Apstra ZTP (Devices)
Apstra ZTP Overview
This document applies to Apstra ZTP 4.1 versions. Use the Apstra ZTP version corresponding to the Juniper Apstra version you are using. (Apstra versions earlier than 4.0 use Apstra ZTP versions 1.0.0 or 2.0.0. For more information, see the Juniper Apstra 3.3.0 User Guide.)
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:
To prevent being locked out of a device when there is a problem during the ZTP process, ZTP uses default, hard-coded credentials. These credentials are:
- root / admin
- aosadmin / aosadmin
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:
- 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).
- 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.
- 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:
| Resource | Setting |
|---|---|
| Guest OS Type | Ubuntu 18.04 LTS 64-bit |
| Memory | 2 GB |
| CPU | 1 vCPU |
| Disk Storage | 64 GB |
| Network | At least 1 network adapter. Configured for DHCP initially |
Apstra ZTP Network requirements
| Source | Destination | Ports | Role |
|---|---|---|---|
| Device agents | DHCP Server (renewals) & Broadcast (requests) | udp/67 -> udp/68 | DHCP Client |
| Device agents | Apstra ZTP | any -> tcp/80 | Bootstrap and API scripts |
| Arista and Cisco Device agents | Apstra ZTP | any -> udp/69 | TFTP for POAP and ZTP |
| Apstra ZTP | Controller | any -> tcp/443 | Device System Agent Installer API |
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.
Download and Deploy Apstra ZTP VM
Configure Static Management IP Address (Apstra ZTP)
By default, the Apstra ZTP server attempts to assign an IP address for its eth0 interface via DHCP. If you're using the Apstra ZTP Server as a DHCP server, you must set a static management IP address.
Configure ZTP User
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 DHCP Server
Apstra software comes with an ISC DHCP server for the device management network. If you use a different DHCP server, it's your responsibility to configure the same options as described in this guide for the Apstra-supplied DHCP server.
For example, if you’re using Juniper Junos OS or Junos OS Evolved devices, you must ensure the server contains the following, so the device loads the proper configuration file.
option space JUNIPER
option JUNIPER.config-file-name code 1 = text
option JUNIPER-encapsulation code 43 = encapsulate JUNIPER
option user-class-information code 77 = text;
class "juniper" { match if (substring(option vendor-class-identifier, 0, 7) = "Juniper") and
not (suffix(option user-class-information, 4) = "-EVO");
option JUNIPER.config-file-name "junos_apstra_ztp_bootstrap.sh";
}
class "juniper-evo" {
match if (substring(option vendor-class-identifier, 0, 7) = "Juniper") and
(suffix(option user-class-information, 4) = "-EVO");
option JUNIPER.config-file-name "ztp.py";
}DHCP configuration files are on the Apstra ZTP VM in the
/containers_data/dhcp directory.
admin@apstra-ztp:~$ sudo ls -l /containers_data/dhcp total 16 -rw------- 1 root root 2533 Oct 21 00:35 dhcpd.conf -rw------- 1 root root 146 Oct 21 00:35 Dockerfile -rw------- 1 root root 932 Oct 21 00:35 init.sh -rw------- 1 root root 1896 Oct 21 00:35 rsyslog.conf admin@apstra-ztp:~$
All configuration files are owned by root. You must use sudo
to run commands as root using the sudo
command or after becoming root with the sudo
-s command.
Configure Controller IP Address for ZTP
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"
}ip |
IP Address of the controller |
user |
Username of the ZTP or admin user |
password |
User's password |
Edit Apstra ZTP Configuration File
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.
- Edit the
ztp.jsonfile with vi or nano text editor.admin@apstra-ztp:~$ sudo nano /containers_data/tftp/ztp.json
- The
ztp.jsonfile 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.
- The
ztp.jsonfile 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 thejunos-imageimage."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 thejunos-versionslist.- 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 thesonic-imageimage."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 thesonic-versionslist.- 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 thenxos-imageimage."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 thenxos-versionslist.- 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 theeos-imageimage."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 theeos-versionslist.-
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, thedevice-root-passwordis used to set the password for the systemadminpassword."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-paramsInformation 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": falsejob_on_create- Set toinstallto 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" ]
- By default, the image name is loaded from the ZTP
server via TFTP from the ZTP server’s
For REST API documentation for all available system-agent-params
options in /api/system-agents, refer to Swagger.