ze install

Pre-Alpha. This page describes behavior that may change.

ze install remote is a one-command provisioning server that PXE-boots target machines with a gokrazy image containing Ze.

How it works

1. The operator runs ze install remote on an existing Ze device connected to the provisioning network.
2. Ze generates a config enabling DHCP (with PXE extensions), TFTP, and an HTTP image server, then forks itself (ze -) with the config piped to stdin.
3. A target machine PXE-boots: DHCP assigns an IP and directs it to the TFTP bootloader, which chain-loads the installer kernel and initrd via HTTP.
4. The installer writes the gokrazy image to disk and reboots.
5. The target boots into Ze in bootstrap mode: discovers all interfaces, enables a DHCP client on each ethernet NIC, and starts SSH for operator access.

Quick start

ze install remote \
  --interface eth0 \
  --network 192.168.1.0/24 \
  --image /path/to/gokrazy.img \
  --ssh-username admin \
  --ssh-password changeme

This starts three servers on eth0:

Protocol	Port	Purpose
DHCP	67/udp	IP assignment with PXE options (bootfile, next-server).
TFTP	69/udp	Bootloader delivery (iPXE for BIOS/UEFI), read-only per RFC 1350.
HTTP	80/tcp	Disk image and boot file serving (supports Range requests).

The server IP is resolved from the interface's first IPv4 address. Use --address to override.

Flags

Flag	Required	Default	Description
--interface	Yes		Network interface to bind all servers.
--network	Yes		Provisioning subnet CIDR (/8 to /30).
--image	Yes		Path to gokrazy disk image file.
--ssh-username	Yes		Admin username for the installed target.
--ssh-password	Yes		Admin password (bcrypt-hashed before embedding).
--address	No	First IPv4 on interface	Server IP override.
--kernel	No		Path to installer kernel (auto-staged to TFTP).
--initrd	No		Path to installer initrd (auto-staged to TFTP).

PXE boot

The DHCP server detects PXE clients via option 60 (PXEClient:) and reads option 93 (client architecture) to select the bootfile. It also serves PXE-related options 43 (vendor-specific), 66 (next-server / TFTP server name), 67 (bootfile name), and 77 (user-class for iPXE detection).

Architecture	Bootfile
BIOS (type 0)	ipxe.pxe
UEFI (type 6, 7, 9)	ipxe.efi

iPXE chainloading is automatic: the DHCP server detects iPXE clients via user-class option 77 and responds with a boot-script-url pointing to a dynamically generated boot.ipxe script that includes ze.server, ze.image, and ze.port kernel command-line parameters. Stock iPXE binaries are bundled in tools/ipxe-binaries/ and auto-staged to the TFTP directory.

The TFTP server implements RFC 2347 option negotiation (OACK), which is required for UEFI PXE boot.

Installer initrd

The target PXE-boots an installer kernel plus initrd, not the disk image directly. The installer initrd (tools/installer-initrd/) is a minimal busybox-based Linux image that performs the disk write on the target:

1. Parses ze.server, ze.port, and ze.image from the kernel command line.
2. Downloads the gokrazy disk image over HTTP from the install server.
3. Writes it to the first non-removable block device (selected via the sysfs removable attribute; virtual, optical, floppy, and mtdblock flash devices are skipped).
4. Mounts partition 4 (ext4, /perm) and injects database.zefs (the pre-provisioned SSH credentials) onto it.
5. Reboots into Ze.

Build it with:

make -C tools/installer-initrd

On a download failure, missing disk, or missing server IP, the init script drops to a shell for debugging instead of rebooting.

Bootstrap mode

When Ze starts with a zefs database but no config file and no template (the state after a freshly-provisioned device boots), it enters bootstrap mode:

1. Interface discovery enumerates all OS network interfaces.
2. A minimal config is generated: a DHCP client on every ethernet interface, SSH server enabled.
3. DHCP clients acquire addresses and SSH becomes reachable.

Non-ethernet interfaces (bridge, veth, dummy, loopback, wireguard, xfrm) are skipped. The SSH credentials come from zefs (written by the installer initrd), not from the generated config. Once you SSH in, configure Ze with ze config edit and commit; the committed config replaces the bootstrap config on the next restart.

Requirements

• Root privileges (DHCP, TFTP, and HTTP bind to privileged ports).
• Bootloader files in /var/lib/ze/install/tftp/ (iPXE binaries).
• Installer kernel and initrd in /var/lib/ze/install/boot/.
• Disk image at the path specified by --image.

See also

• Appliance for building gokrazy images.
• Install for other installation methods.

Adapted from main/docs/guide/ze-install.md.