> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/switch-infrastructure/config-manager/llms.txt.
> For full documentation content, see https://docs.nvidia.com/switch-infrastructure/config-manager/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/switch-infrastructure/config-manager/_mcp/server.

# Configuration Guide

## 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:

```text
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:

```bash
# 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:

```bash
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](/switch-infrastructure/config-manager/services/network-ztp/ztp-api) for endpoint details
2. Review the [Architecture Documentation](/switch-infrastructure/config-manager/services/network-ztp/architecture) for system overview
3. Contact your system administrator for environment-specific configuration