Zero Touch Provisioning¶
Configuring nodes via Zero Touch Provisioning (ZTP) is a core design goal of Sherpa. Every supported device has a method to apply a configuration to a node on first boot.
Default Node Configuration¶
The following configuration parameters are applied to nodes via ZTP:
- Hostname
- Management IPv4/6 addresses
- Default route
- DNS domain
- DNS name servers
- DNS search domains
- Your login: your Sherpa username, your registered SSH keys and your
device password, written in the form the device takes. Where a device
stores a hash, the configuration carries a salted hash, not the password. Fixed vendor accounts
such as
admintake the device password too. Aruba AOS-CX gets your keys only, withadminlocked. See Your Login on Nodes.
The configurations served over TFTP or HTTP carry only hashes of the device password, and Aruba AOS-CX's carries none.
Who Can Read a Node's Configuration¶
A node's configuration holds its logins, and a custom ztp.config holds whatever you put in it.
On the Sherpa server, Sherpa writes every configuration it renders for a node as the
sherpa account, readable by that account only, in folders only it can open, whatever the
server's umask. People in the sherpa group cannot read them; use sudo to look at one. A VM's
boot files are removed once its boot media are in the storage pool, container configurations
when the node is destroyed, and TFTP and HTTP configurations when the lab is destroyed.
TFTP configurations are the one exception: the lab router's TFTP service serves only files
every account can read, so they are readable by accounts outside the sherpa group too, but not
by the group. Those accounts cannot reach the lab's folder on the server, so on the server the
effect is the same.
On the lab's management network, the TFTP and HTTP configurations are
served without credentials. Any node in the lab, or anything else that reaches the lab router,
can fetch any node's TFTP or HTTP configuration while the lab exists, not only its own. Each
service serves only its own files: HTTP on port 8080 serves the files of the nodes that boot by
HTTP and nothing else, not the TFTP configurations and not the lab router's DHCP leases (see
HTTP). Keep this in mind before you
give a TFTP or HTTP node a custom ztp.config with a secret in it. Configurations delivered on
a CD-ROM, disk or USB disk, by cloud-init, NoCloud or Ignition, or as container volumes are not
served on the network.
The ZTP Setting¶
Every node image has one ZTP setting: disabled, or the method Sherpa provisions its nodes by.
sherpa image show prints it as ZTP, and an administrator changes it on the image's edit page
in the web UI.
| Setting | Method | Used by |
|---|---|---|
disabled |
Sherpa provisions nothing | any node |
cloud-init |
Cloud-Init | Linux, BSD and Windows virtual machines |
nocloud |
NoCloud | Talos Linux |
ignition |
Ignition | Flatcar Linux |
usb |
USB Disk | Cumulus Linux, Juniper vEvolved |
disk |
Config Disk | Cisco IOSv, IOSvL2 and ISE, MikroTik CHR |
cdrom |
CDROM | Cisco IOS XE, ASAv, Nexus, IOS XR and FTDv, Juniper vRouter, vSwitch and vSRX, Palo Alto PAN-OS |
tftp |
TFTP | Arista vEOS, Aruba AOS-CX, Juniper vEvolved |
http |
HTTP | the SONiC virtual machine |
volume |
Container Volumes | Arista cEOS, Nokia SR Linux, Juniper cEvolved, Cisco IOL, FRR, the SONiC container |
A model takes only the methods listed against it, and all but one take one: Juniper vEvolved
takes tftp or usb. Application containers and unikernels take
only disabled. Sherpa refuses any other setting when the image is saved, when a manifest is
validated, and before sherpa up or sherpa redeploy changes anything.
Per Node¶
A node can set its own with ztp.method in the manifest. Without it the
node uses its image's setting.
# manifest.toml
[[nodes]]
name = "dev01"
model = "frr_linux"
[nodes.ztp]
method = "disabled"
[[nodes]]
name = "dev02"
model = "juniper_srxv3"
[nodes.ztp]
method = "tftp"
To change a node's method in a running lab, change ztp.method and run
sherpa redeploy -n <node>. When the node moves onto or off tftp or http, the lab router's
DHCP options for it change too, and Sherpa recreates the lab router, which runs the lab's DHCP,
DNS, TFTP and HTTP services, for that. Lab nodes keep their addresses, but those services and
the lab's outside access pause for a few seconds while it is recreated. A redeploy that keeps the node's method does not restart it. The files of the node's
old method are removed.
Disabled¶
A node with ZTP disabled boots as its image ships: Sherpa generates no configuration and adds
no login. The generated configuration is
also what gives a node its management IP address, so a node with ZTP disabled has none unless
its image configures one itself, and sherpa ssh cannot reach it. A virtual machine gets no
configuration media. A container gets only what it needs to start, as described under
Container Volumes.
Custom Node Configuration¶
User defined configuration can be applied to devices by specifying
the location with the ztp.config parameter in the manifest.toml
file.
A custom ztp.config is supported for nodes whose ZTP setting is tftp, nocloud, cdrom,
disk, usb or volume. Sherpa refuses it, before the lab is created, on nodes that use
cloud-init, ignition or http, and on nodes whose ZTP is disabled. The exception is
HashiCorp Vault, where ztp.config is
Vault's own configuration file.
Example¶
# manifest.toml
[[nodes]]
name = "dev01"
model = "cisco_cat8000"
[nodes.ztp]
config = "/some/path/dev01.conf"
ZTP Methods¶
Cloud-Init¶
Cloud-init is the default ZTP method. Configuration is delivered via an ISO image mounted as a CDROM device with the volume label cidata.
The ISO contains three files:
user-data— system configuration, user provisioning, and startup scriptsmeta-data— instance metadata such as hostnamenetwork-config— network interface configuration
Sherpa writes these files as JSON, which cloud-init reads as YAML. Every
value keeps its type, so a MAC address such as 52:54:00:21:47:08 or a value such as yes
is never read as a number or a boolean. user-data still starts with the #cloud-config line.
On boot, the cloud-init service detects the cidata volume and applies the configuration automatically.
NoCloud¶
Like cloud-init, NoCloud configuration is delivered on a cidata CD-ROM. The difference is
user-data: instead of a cloud-init config, it holds the node's native configuration, either
your ztp.config or one Sherpa generates. Sherpa adds meta-data and a network-config with
the static management address.
Ignition¶
Ignition is a declarative provisioning system. Configuration is delivered as a JSON file in the storage pool, which libvirt passes to the VM through QEMU's firmware configuration device (fw_cfg).
A secondary EXT4 data disk is also created for container storage.
USB Disk¶
Configuration is written to a FAT32 disk image that is attached to the VM as a removable USB device. On boot, the device detects the USB disk and reads the configuration files.
Config Disk¶
Configuration is written to a secondary disk image attached to the VM. Depending on the device, the disk may be formatted as FAT32 or EXT4.
- FAT32 — files are written to the disk using
mcopy. - EXT4 — files are written to the disk using
e2cp.
On boot, the device detects the secondary disk and applies the configuration.
CDROM¶
Configuration files are packaged into an ISO image and mounted as a read-only CDROM device. The device scans the CDROM for a specific filename during boot.
TFTP¶
Configuration is served over the network via TFTP from the lab router. A dnsmasq instance provides both DHCP and TFTP services for the lab. DHCP options 66 and 67 direct the device to the TFTP server and configuration filename.
HTTP¶
Configuration is served over the network via HTTP on port 8080 of the lab router. A dnsmasq instance provides DHCP services that direct the device to the config URL using DHCP options 67 and 239.
Only the files of the nodes that boot by HTTP are served, from the root of the server: today
SONiC's, <node>.conf (the ZTP file that DHCP names), <node>_config_db.json and
<node>_ztp_user.sh (your account). The TFTP configurations are served over TFTP only, and the
lab router's DHCP leases are not served.
Container Volumes¶
Arista cEOS, Nokia SR Linux, Juniper cEvolved, Cisco IOL, FRR and SONiC containers use the
volume method. Sherpa
writes the node's configuration files on the Sherpa server and bind mounts them into the
container, which reads them on startup. The configuration carries your login.
With ZTP disabled, one of these containers starts with its image, environment and command
only. Sherpa mounts no configuration and adds no login, so sherpa ssh cannot log in to it. What
the node does with its management address depends on its image: cEOS and SR Linux leave it
unconfigured, FRR answers on it with no SSH server, cJunosEvolved configures it with SSH for
the image's own admin user, and IOL boots with no configuration and runs its own autoinstall.
A SONiC container is the exception: Sherpa still mounts its start script, which waits for the
data interfaces and starts the SSH server, but adds no login and no configuration. Each model's page says how to reach it. The node's container.volumes
from the manifest are mounted instead, so you can supply a configuration of your own.
Every other container has no ZTP method. It is configured when the container is created, from
the node's environment_variables, container.commands and container.volumes in the
manifest.