Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Apstra ZTP (Devices)

Apstra ZTP Overview

Note:

This document applies to Apstra ZTP 4.0 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 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
  • Installing license (Cumulus only)
  • On-box or Off-box Device System Agent installation

See also vendor-specific information:

Note:

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:

  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. I Agent Installation Phase
    • The ZTP script makes an API call to install a device system agent on the device.

Apstra ZTP 4.0 VM Server Resource Requirements

Apstra ZTP 4.0 runs as an Ubuntu 18.04 LTS server running a DHCP, HTTP, and TFTP server and includes Apstra provided ZTP scripts that must be customized for the 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 4.0 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 Commincation Ports for more information.

Beginning with Apstra ZTP 4.0.0 and Apstra 4.0.0, 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" icon.

Log files for all processes can be found in the /containers_data/logs directory

Beginning with Apstra ZTP 4.0.0 and Apstra 4.0.0, 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

Apstra ZTP software is delivered on a standalone Apstra ZTP VM
  1. As a registered support user, download the appropriate Apstra VM image from Juniper Support Downloads.
    VMware OVA image apstra-ztp-4.0.*-<build-version>.ova (example: apstra-ztp-4.0.1-11.ova)
    Microsoft Hyper-V apstra-ztp-4.0.*-<build-version>.vhdx.gz (example: apstra-ztp-4.0.1-11.vhdx.gz)
    Linux KVM QCOW2 image apstra-ztp-4.0.*-<build-version>.qcow2.gz (example: apstra-ztp-4.0.1-11.qcow2.gz)
  2. Validate the downloaded file against the SHA512/MD5 checksums provided.
  3. Deploy the VM with the appropriate resources.
  4. TFTP, NGINX (HTTP), DHCPd, Status. and MySQL Docker containers are enabled and run by default.
  5. If you do not want to use the Apstra ZTP DHCP Server, stop and disable the dhcpd container.

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.

  1. SSH into the Apstra server as user admin. (ssh admin@<apstra-server-ip> where <apstra-server-ip> is the IP address of the Astra server.)
  2. Edit the /etc/netplan/01-netcfg.yaml file to configure the static management IP address. See example below. (For more information about using netplan, see https://netplan.io/examples)
  3. Apply the change with one of the following methods:
    • Reboot the Apstra server with the command sudo reboot.
    • Run the command sudo netplan apply.

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 devices, you must ensure the server contains the following, so devices download the Apstra ZTP junos_apstra_ztp_bootstrap.sh file.

DHCP configuration files are on the Apstra ZTP VM in the /containers_data/dhcp directory.

Note:

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.
  1. Edit the dhcpd.conf file with vi or nano text editor.
  2. Add a "group" corresponding to the management network:
    tftp-server-name IP address of ZTP server (not a URL)
    subnet IP management network and netmask
    range Range of dynamic DHCP IP addresses. Ensure the full range is available and no statically configured IP addresses from that range are used.
    option routers Default gateway router for management network
    host Static DHCP IP address
    hardware ethernet of the management interface used for DHCP negotiations
    fixed-address for device with hardware ethernet MAC. Use the Switch MAC address
  3. The following DHCP parameters are optional:
  4. If you're using ZTP with Cumulus Linux, you must edit the following:
    • cumulus-provision-url: TFTP URL with IP address of ZTP server
  5. If you're using ZTP with SONiC, you must edit the following:
    sonic-provision-url: TFTP URL with IP address of ZTP server
  6. After modifying any DHCP configuration, restart the Apstra ZTP DHCP process with the sudo docker restart dhcpd command.

Configure Controller IP Address for ZTP

The controller IP and the Apstra ZTP username must be configured in the /containers_data/status/app/aos.conf file on the Apstra ZTP 4.0 Server.

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.

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.
  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 (“cumulus”, “nxos”, “eos”, "junos", "sonic") unless more specific keys are defined. 
    "cumulus": {
  "cumulus-versions": ["3.7.13"],
  "cumulus-image": "http://192.168.59.4/cumulus-linux-3.7.13-bcm-amd64.bin",
  "license": "cumulus_license_file",
  "custom-config": "cumulus_custom.sh",
}
    model - Values are used for all devices for a specific device model (for example “N9K-C93180YC-FX”). 
    "N9K-C93180YC-FXC3396": {
  "custom-config": "93180_cumulus_custom.sh",
}
    serial number - Values are used for a device matching a specific device serial number ("525400B3C311" for example). 
    "525400B3C311": {
  "cumulus-versions": [ "3.7.13" ],
  "cumulus-image": "http://192.168.59.4/cumulus-linux-3.7.13-bcm-amd64.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 be loaded 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"

    Thisexample 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 be loaded 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 be loaded 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 be loaded 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.
    cumulus-versions - Valid versions for Cumulus Linux devices. If a device is not running a version in this list, ZTP upgrades the device with the cumulus-image image. "cumulus-versions": [ "3.7.12", "3.7.13" ]
    cumulus-image - Filename of the Cumulus Linux ONIE BIN image to be loaded if the running version does not match a version in the cumulus-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: "cumulus-image": "cumulus-linux-3.7.13-bcm-amd64.bin"
    • To use any HTTP server for image transfer, enter a valid HTTP URL with IP address. For example: "cumulus-image": "http://192.168.59.4/cumulus-linux-3.7.13-bcm-amd64.bin"

    This example uses HTTP from the ZTP server to transfer the Cumulus Linux 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"
    license - Filename of the Cumulus Linux license file in the TFTP directory or a URL pointing to the file on a HTTP server. "license": "cumulus_license_file"
    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": "cumulus_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 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 off-box agents only) Set to the device platform ("eos", "nxos", "junos"). Must be in all lowercase. "platform": "junos"
    open_options - (off-box agents only) Set to enable HTTPS between off-box 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.