ServicesNetwork ZTP Service

Configuration Guide

View as Markdown

Overview

This guide explains how to configure network devices and clients to use the NVIDIA Config Manager ZTP Server for Zero Touch Provisioning.

Prerequisites

Before configuring devices for ZTP, ensure:

  1. Devices are registered in the device management system
  2. Device IP addresses are correctly configured in the device management system
  3. Firmware images are available for your device platform and version
  4. Configuration files are prepared and stored in the configuration store

Device Configuration

DHCP Configuration

How the DHCP server tells a device where to fetch ZTP artifacts depends on the NOS:

Cumulus Linux — cumulus-provision-url (and often boot-file-name) pointing at the boot script:

option cumulus-provision-url "http://ztp.example.com/v1/device/{device_uuid}/boot-script";

NV-OS — boot-file-name pointing at ztp.json:

option boot-file-name "http://ztp.example.com/v1/device/{device_uuid}/config/ztp.json";

Juniper Junos — DHCP option 43 (vendor-encapsulated) with HTTP transfer-mode. The bundled platform context sets:

  • transfer-mode: http
  • image-file-name: http://ztp.example.com/v1/device/{device_uuid}/firmware
  • config-file-name: http://ztp.example.com/v1/device/{device_uuid}/config/full-config

full-config is the intended Junos configuration rendered by operator or plugin templates. The ZTP API does not synthesize a placeholder file.

Replace ztp.example.com with your ZTP server URL and {device_uuid} with the device UUID from the device management system.

ONIE Configuration

For ONIE-based devices, the boot file URL can point to either:

  • Boot script: http://ztp.example.com/v1/device/{device_uuid}/boot-script
  • Firmware image: http://ztp.example.com/v1/device/{device_uuid}/onie

The ONIE installer will automatically append .ztp to the URL if it points to a firmware image.

Network Requirements

Ensure devices can reach the ZTP server:

  • DHCP traffic: Devices must be able to exchange DHCP packets with the Config Manager DHCP service on UDP 67/68.
  • ZTP service traffic: Devices must be able to access the configured HTTP or HTTPS bootstrap listener and TCP 2222 for the default Cumulus rendered-configuration download.
  • DNS resolution: Devices must be able to resolve the ZTP server hostname, which requires UDP/TCP 53 if hostnames are used.
  • IP address registration: Device IP addresses must be registered in the device management system.

API Usage

Authentication

Device endpoints accept either a registered device request or an authenticated user request:

  • Device-originated requests must come from IP addresses registered for the device
  • Device-originated requests do not require additional authentication headers
  • User-originated requests must come through the Envoy gateway as authenticated users when SSO is enabled for the deployment
  • Admin endpoints require authenticated user access

Request Headers

Standard HTTP headers are used:

  • Content-Type: application/json for JSON request bodies
  • Accept: application/json for JSON responses (where applicable)

Error Handling

Handle common error responses:

  • 403 Forbidden: Check that the device IP address is registered correctly
  • 404 Not Found: Verify the device UUID and resource path are correct
  • 500 Internal Server Error: Contact system administrator

Firmware Verification

Always verify firmware images using the checksum endpoint:

# Get checksum
CHECKSUM=$(curl -s https://ztp.example.com/v1/device/{device_uuid}/firmware/checksum | jq -r .checksum)
# Download firmware
curl -O https://ztp.example.com/v1/device/{device_uuid}/firmware
# Verify checksum
echo "$CHECKSUM  firmware-image.bin" | sha256sum -c

Configuration Files

Configuration files are retrieved using:

curl https://ztp.example.com/v1/device/{device_uuid}/config/{configlet}

The default Cumulus boot script instead retrieves startup.yaml through the source-IP-authorized SFTP service:

sftp://ztp.example.com:2222/device/{device_uuid}/startup.yaml

The HTTP endpoint remains available for compatibility and troubleshooting.

Common configuration file names:

  • boot-script: Cumulus Linux initial boot script
  • ztp.json: NV-OS ZTP sequence
  • full-config: Junos hierarchical configuration (operator- or plugin-rendered)
  • startup.yaml: Cumulus / NV-OS intended configuration
  • system.cfg: System configuration
  • interfaces.cfg: Interface configuration

Contact your system administrator for the specific configuration file names for your environment.

Troubleshooting

Device Cannot Access ZTP Server

Symptoms:

  • Device cannot download boot script or firmware
  • Connection timeouts or DNS resolution failures

Solutions:

  1. Verify network connectivity from device to ZTP server
  2. Check DNS resolution: nslookup ztp.example.com
  3. Verify firewall rules allow the configured HTTP/HTTPS bootstrap traffic and SFTP on TCP 2222
  4. Check that device IP is registered in device management system

Authorization Failures

Symptoms:

  • 403 Forbidden responses
  • “Unauthorized” error messages

Solutions:

  1. Verify device IP address is registered in device management system
  2. Check that requests are coming from the registered IP address
  3. Ensure device is using the correct device UUID
  4. Contact system administrator if IP address has changed

Missing Resources

Symptoms:

  • 404 Not Found responses
  • “Device not found” or “File not found” errors

Solutions:

  1. Verify device UUID is correct
  2. Check that device is registered in device management system
  3. Verify firmware version is available for the device platform
  4. Ensure configuration files exist in the configuration store

Firmware Download Issues

Symptoms:

  • Incomplete firmware downloads
  • Checksum verification failures

Solutions:

  1. Use curl with -O flag for reliable downloads
  2. Verify checksum after download
  3. Check network stability during large file transfers
  4. Retry download if checksum verification fails

Best Practices

Security

  1. Protect rendered configuration: Use the default SFTP transport for Cumulus startup.yaml; restrict bootstrap HTTP to the private provisioning network
  2. Verify Checksums: Always verify firmware checksums before installation
  3. Validate Serial Numbers: Use the serial validation endpoint before provisioning
  4. Monitor Provisioning: Correlate the ZTP http-lb and sftp container logs during provisioning

Reliability

  1. Retry Logic: Implement retry logic for transient failures
  2. Timeout Handling: Set appropriate timeouts for large file downloads
  3. Error Logging: Log all API errors for troubleshooting
  4. Status Monitoring: Monitor device provisioning status

Performance

  1. Parallel Downloads: Download firmware and configurations in parallel when possible
  2. Connection Reuse: Reuse HTTP connections for multiple requests
  3. Caching: Cache boot scripts and configuration metadata locally
  4. Streaming: Use streaming for large firmware files

Support

For additional support:

  1. Check the API Documentation for endpoint details
  2. Review the Architecture Documentation for system overview
  3. Contact your system administrator for environment-specific configuration