Switch zero-touch provisioning (ZTP)

Zero-touch provisioning lets a network switch configure itself on first boot: it requests a DHCP lease, receives ZTP boot options, downloads a boot image and a recipe from the controller, and applies an admin-supplied configuration — no manual console session required. Luna manages the switch's ZTP settings and serves the recipe and configuration over its boot endpoints.

Experimental — availability

Switch ZTP is experimental and available from Luna 2.1u8 and higher. It is validated with Cumulus Linux and ONIE switches (see below); other switch families may work but are not yet covered.

Enabling ZTP on a switch

ZTP fields are set on a switch with luna switch add or luna switch change:

luna switch add <name> -N <network> -I <ip> -M <mac> \
    --netboot y \
    --default-url files/<image>.bin \
    --ztpformat commands \
    --quick-ztpconfig <path-or-inline-config>
Field Flag Meaning
Netboot -nb / --netboot Toggle the ZTP netboot DHCP options for the switch (y/n)
OS type -ot / --ostype Switch OS family: cumulus, nvos or generic. Gates ZTP options — cumulus adds option 239 (see below)
Default URL -du / --default-url Boot image path, controller-relative, e.g. files/<image>.bin. Optional
Bootfile -bf / --bootfile Override for the recipe path advertised over DHCP. Optional; defaults to boot/switch/<name>
ZTP format -zf / --ztpformat Format the recipe serves the config in: commands or yaml
ZTP config -zc / --ztpconfig Config served by ZTP; opens an editor
ZTP config (quick) -qz / --quick-ztpconfig Same, given inline or as a file path
URL scheme -up / --url_protocol Recipe/config URL scheme: secure (API over HTTPS) or plain (webserver over HTTP). Default auto
URL host -us / --url_server Override the host in the served URLs (IP or hostname). Default: the known controller
TFTP -te / --tftp_enable Advertise TFTP (option 66) to the switch, e.g. for ONIE/TFTP install. Default off
Vendor --vendor Switch vendor name (metadata)

Use --ztpconfig to edit the served configuration in an editor, or --quick-ztpconfig to pass it directly (a file path, or the configuration text inline).

Bootfile and default URL are both optional

The recipe path handed to the switch over DHCP defaults to boot/switch/<name>, so --bootfile is only needed to override that path. --default-url points at a boot image and can be left unset when the switch only needs to fetch its configuration — the recipe is still served, just without an image URL.

Note

Luna advertises the switch's netboot DHCP options only when at least one of --default-url or --bootfile is set. To do ZTP with no boot image, set --bootfile boot/switch/<name> explicitly — if both are left empty, netboot is skipped for that switch.

Switch OS types: Cumulus and ONIE

ZTP is validated with two switch provisioning styles, selected by --ostype and --tftp_enable.

Cumulus Linux — set --ostype cumulus. On top of the normal boot options, the switch reservation then carries DHCP option 239 (cumulus-provision-url) pointing at the switch's recipe, which is what Cumulus ZTP reads to fetch and run its provisioning. nvos and generic never receive option 239.

luna switch change <name> --ostype cumulus --netboot y \
    --default-url files/<image>.bin --quick-ztpconfig <path-or-inline-config>

ONIE — the Open Network Install Environment fetches its installer image from the DHCP-advertised URL. For ONIE switches that install over TFTP, enable option 66 with --tftp_enable y; the switch is then given a TFTP server name (the controller, or the --url_server host when one is set). With TFTP disabled (the default) HTTP ZTP goes straight through and option 66 is suppressed.

luna switch change <name> --ostype generic --netboot y \
    --tftp_enable y --default-url files/<installer>.bin

Note

`--ostype` only gates which options are advertised; it does not change the recipe or the served configuration. A switch of any OS type still fetches the same recipe and config endpoints described below.

URL scheme and host

By default the recipe advertises URLs pointing at the controller over its secure API. Two flags override this when a switch needs something else:

  • --url_protocol selects the scheme: secure serves the URLs over the HTTPS API, plain serves them over the plain HTTP webserver. Left unset, luna picks automatically.
  • --url_server replaces the host in the served URLs (and the boot next-server, and the option-66 TFTP host) with a given IP or hostname — useful when the switch must reach the controller by a different address than the one luna knows.

What the controller serves

With netboot enabled, luna hands the switch its ZTP DHCP options and exposes two unauthenticated boot endpoints:

Endpoint Serves
/boot/switch/<name> The ZTP recipe (JSON): image URL, config format, and the commands URL
/boot/switch/<name>/commands The configuration applied by ZTP — the admin ztpconfig, or a default template when none is set

You can preview exactly what a switch will receive:

curl -sk https://<controller>:7050/boot/switch/<name>
curl -sk https://<controller>:7050/boot/switch/<name>/commands

Note

The ZTP boot endpoints are served over HTTPS on port 7050 and are intentionally unauthenticated — a factory-fresh switch has no credentials when it boots.

Typical flow

  1. The switch boots with no configuration and requests DHCP.
  2. Luna's DHCP server returns the ZTP boot options (image path and bootfile URL).
  3. The switch fetches /boot/switch/<name>, learns the image and commands URLs.
  4. The switch downloads the boot image (default-url) and the configuration from /boot/switch/<name>/commands.
  5. The switch applies the configuration and comes up ready.

Verifying

Confirm the recipe and configuration render as expected before wiring a live switch:

luna switch show <name>
curl -sk https://<controller>:7050/boot/switch/<name>
curl -sk https://<controller>:7050/boot/switch/<name>/commands

The first URL should return recipe JSON referencing the second; the second should return exactly the configuration you set with --ztpconfig / --quick-ztpconfig.