Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Configure Apstra ZTP

After you've installed Apstra ZTP, it's time to configure it.

  1. 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 ZTP server as user admin. (ssh admin@<apstra-server-ip> where <apstra-server-ip> is the IP address of the Apstra ZTP 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 ZTP server with the command sudo reboot.
      • Run the command sudo netplan apply.
  2. Configure Apstra 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.

  3. Configure Apstra ZTP GUI Credentials
    The Apstra ZTP GUI supports password credentials only for the admin user.
    1. From the latest web browser version of Google Chrome or Mozilla FireFox, enter the URL https://<apstra_server_ip> where <apstra_server_ip> is the IP address of the Apstra server (or a DNS name that resolves to the IP address of the Apstra server).
    2. If a security warning appears, click Advanced and Proceed to the site. The warning occurs because the SSL certificate that was generated during installation is self-signed, and you didn't replace it with a signed one when you installed the software. We recommend, for security reasons, that you replace the SSL certificate.
    3. From the login page, enter username admin and the default password admin.
    4. After your first login as admin, you must change the password. The new password must be strong with at least 9 characters: minimum 1 uppercase, 1 lowercase, 1 number, and 1 special symbol. (You can access the Change Password dialog in the Apstra ZTP GUI in the future at Settings > Change Password
    5. After you change the admin password, you must log back in with the new password you set. (You can change the password
  4. Configure Apstra Server Details
    1. After you log in with the new admin password, the Apstra ZTP UI will start a configuration wizard. Step 1 of the wizard will configure the Apstra server details so the Apstra ZTP server and devices will be able to connect to the Apstra server API for logging and system agent creation.
    2. Enter the IP address of the Apstra server, the username (e.g. "ztp"), and the user password.
    3. The Apstra server credentials will be verified and you will see an error if they are incorrect.
    4. If you do not want to use the integration to the Apstra server you can skip this step. This can be configured later in the Apstra ZTP UI under "Settings", "Configure Apstra Server Details".
  5. Configure Apstra ZTP DHCP Server via Apstra ZTP GUI

    The Apstra ZTP UI configuration wizard will direct you to configure the DHCP (dhcpd.conf) configuration.

    The Apstra ZTP UI will have a "Code Editor" tab to edit the dhcpd.conf file directly and a "Configurator" tab to create the DHCP (dhcpd.conf) configuration.

    For the "Configurator" tab, the first section is to edit "options" which include DHCP domain-search, domain-name, and domain-name-servers options.

    The next section is to edit "groups" which include DHCP "tftp-server-name", "subnet", "netmask", "range_start", "range_end", and "routers" options.

    If you have additional subnets, additional subnets can be configured by clicking the "additional subnet" link.

    Next in "groups", the user can configure static DHCP hosts to map a device hardware ethernet address to an IP fixed-address.

    If you have additional hosts, additional hosts can be configured by clicking the "additional hosts" link.

    If you click on the "Code Editor" tab, entries entered in configurator will be in the dhcpd.conf file.

    When you are finished, click "Save & Proceed". Apstra ZTP will automatically restart DHCP with the updated configuration. If there are errors in the configuration, Apstra ZTP will alert you with an error.

    To make any changes to the Apstra ZTP DHCP configuration using the UI, click on "dhcpd.conf" in the Apstra ZTP UI.

  6. Configure Apstra ZTP DHCP Server via dhcpd.conf File

    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.

    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 SONiC, you must edit the following:
      sonic-provision-url: TFTP URL with IP address of ZTP server
    5. After modifying any DHCP configuration, restart the Apstra ZTP DHCP process with the sudo docker restart dhcpd command.
  7. Edit Apsra ZTP Configuration File via Apstra ZTP GUI

    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. This can be configured from the Apstra ZTP UI or directly via the ztp.json file.

    The Apstra ZTP UI configuration wizard will direct you to configure the Apstra ZTP configuration file (ztp.json).

    The Apstra ZTP UI will have a "Code Editor" tab to edit the ztp.json file directly and a "Configurator" tab to create the Apstra ZTP configuration file.

    For the "Configurator" tab, there will be groups organized by the following:

    • defaults - Values are used for all devices unless more specific keys are defined.

    • platform - Values are used for all devices for a network platform (“nxos”, “eos”, "junos", "sonic") unless more specific keys are defined.

    • model - Values are used for all devices for a specific device model (for example “QFX10002-36Q”)

    • serial number - Values are used for a device matching a specific device serial number (for example "TH0TFD6TCET0015G0015")

    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 "Toggle Empty Fields" option improves visibilty by hiding field without any data.

    You can add or delete more groups with the "Additional SN/Platform/Model" and "Delete SN/Platform/Model" link.

    The Apstra ZTP configuration file (ztp.json) uses the following keys:


  8. Edit Apstra ztp.json File
    1. Edit the ztp.json file with vi or nano text editors.
    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.

  9. Replace Apstra ZTP SSL Certificate

    For security, we recommend that you replace the Apstra ZTP default self-signed SSL certificate with one from your own certificate authority. Web server certificate management is the responsibility of the end user. Juniper support is best effort only.

    When you boot up the Apstra ZTP server for the first time, a unique self-signed certificate and key are automatically generated and stored on the Apstra ZTP NGINX container. The certificate is used for encrypting the Apstra ZTP server. We recommend replacing the default SSL certificate.

    Follow these steps to install a new SSL certificate.

    1. Create a new OpenSSL private key with the built-in openssl command.
    2. Create a certificate signing request. If you want to create a signed SSL certificate with a Subjective Alternative Name (SAN) for your Apstra server HTTPS service, you must manually create an OpenSSL template. For details, see Juniper Support Knowledge Base article KB37299.
    3. Submit your Certificate Signing Request (nginx.csr) to your Certificate Authority. The required steps are outside the scope of this document; CA instructions differ per implementation. Any valid SSL certificate will work. The example below is for self-signing the certificate.
    4. Verify that the SSL certificates match: private key, public key, and CSR.
    5. Edit the NGINX SSL configuration file /containers_data/nginx/conf.d/ssl.conf pointing ssl_certificate and ssl_certificate_key to the new key and certificate files. Note, the files in the /containers_data/nginx are mapped from files in the /data directory in the NGINX container.
    6. To load the new certificate, restart the nginx container.
    7. Confirm that the new certificate is in your web browser and that the new certificate common name matches (e.g. 'aos-server.apstra.com').

Related Documentation