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

Configure your DHCP server to provide the ZTP boot file URL in the boot-file-name option:

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

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 ZTP server on TCP 80 and/or TCP 443 for boot scripts, configuration, and firmware fetches.
  • 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}

Common configuration file names:

  • boot-script: Initial boot script
  • 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 HTTP/HTTPS traffic
  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. Use HTTPS: Always use HTTPS endpoints in production
  2. Verify Checksums: Always verify firmware checksums before installation
  3. Validate Serial Numbers: Use the serial validation endpoint before provisioning
  4. Monitor Provisioning: Monitor device provisioning status and logs

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