{# SPDX-FileCopyrightText: 2025 Marcin Zieba #} {# SPDX-License-Identifier: Apache-2.0 #} {% extends "generic/object.html" %} {% block content %}
Add DHCPv{{ dhcp_version }} Option Definition
{% if dhcp_version == 4 %}
Options 66 (tftp-server-name), 67 (bootfile-name), 43 (vendor-encapsulated-options), and 125 (vivso-suboptions) are already predefined in the Kea dhcp4 option space. Only add a custom definition here if you need to override the standard data type.
{% elif dhcp_version == 6 %}
Option 59 (OPT_BOOTFILE_URL) is predefined in the Kea dhcp6 option space. Only add a custom definition here if you need to override the standard data type.
{% endif %}
{% csrf_token %} {% for field in form %}
{{ field }} {% if field.help_text %}
{{ field.help_text }}
{% endif %} {% for error in field.errors %}
{{ error }}
{% endfor %}
{% endfor %} Cancel
{# ── ZTP / Common option examples ───────────────────────────────────── #}

Two-step workflow: this form only defines the option schema (code, name, data type). The value is set separately — after saving the definition go to the Subnets tab (or Server → Option Data) and add an option-data entry referencing this option code.

Custom option definitions let you add non-standard DHCP options to Kea. Below are the most common ones used for Zero Touch Provisioning (ZTP) and vendor-specific use cases. {% if dhcp_version == 4 %} See the Kea docs for full reference. {% else %} See the Kea docs for full reference. {% endif %}

{% if dhcp_version == 4 %}
Code Name Type Use case
66 tftp-server-name string TFTP server hostname/IP for legacy IOS bootstrap
67 bootfile-name string Bootstrap file/URL — IOS XE ZTP script, NX-OS POAP URL, IOS startup config
43 vendor-encapsulated-options binary Vendor-specific data (Cisco POAP, Aruba Central, etc.) — see sub-option examples below
125 vivso-suboptions record (uint32, binary) Vendor-Identifying Vendor-Specific Options (RFC 3925) — used by some Aruba/HP devices
Cisco ZTP — option 67 (bootfile-name)

Used to deliver the bootstrap script URL to Cisco IOS XE, NX-OS, and IOS devices. Define the option once, then set its value per subnet or globally. 

{
  "code": 67,
  "name": "bootfile-name",
  "type": "string",
  "space": "dhcp4"
}

Then set the option value on the subnet (or globally):

  • IOS XE: http://10.0.0.1:8080/ztp/ztp.py
  • NX-OS POAP: http://10.0.0.1/poap/poap.py
  • Legacy IOS: tftp://10.0.0.1/startup-config.cfg
Cisco option 43 — vendor-specific sub-options

Option 43 carries vendor-specific data as a binary TLV blob. For Cisco IOS ZTP/POAP the value encodes a sub-option pointing to the configuration server. Example sub-option layout (hex): 

# Sub-option 1 (type=0x01), value = "http://10.0.0.1/poap.py"
# TLV: 01 <length> <ASCII bytes of URL>
#
# Kea binary value (hex string, no spaces):
# 0117687474703a2f2f31302e302e302e312f706f61702e7079
#  ^^  ^^ = type 01, length 0x17 = 23, then URL bytes

Where to put this value: after saving the definition (code 43, type binary), go to the target subnet's Option Data section and add an option-data entry with code 43 and the hex string above as the value.

For Aruba networks pointing to Aruba Central, the option 43 value contains the Central provisioning URL as sub-option 1. Refer to your vendor's DHCP provisioning guide for the exact encoding.

Typical ZTP workflow
  1. Define the option code here (e.g. code 67, type string)
  2. Go to the subnet (or server global options) and add an option-data entry for this definition
  3. Set the value to the URL of your ZTP/POAP bootstrap script
  4. New devices that DHCP on that subnet receive the URL on first boot
{% else %}

DHCPv6 ZTP typically uses vendor-specific options or option 59 (OPT_BOOTFILE_URL). Refer to your device vendor's provisioning guide for the exact option codes required.

{% endif %}
{# ── /ZTP examples ──────────────────────────────────────────────────── #}
{% endblock %}