NAME

bootd.hcl — bootd configuration file

DESCRIPTION

bootd(8) reads its configuration from one file in HCL, HashiCorp's configuration language: attributes are written name = value, blocks type "label" {...}, strings are quoted, lists are written ["a", "b"] and maps { key = "value" }. Comments start with #, // or are enclosed in /* */.

The file describes the networks bootd(8) is attached to, the services (protocols) it offers, and the hosts it serves, with the services each may use and the files it may load. classes hold what several hosts share.

bootd check reports errors and warnings with file and line.

TOP LEVEL

root = path

The directory relative paths of files, disks, exports and NIS maps are relative to. A relative root is relative to the directory of the configuration file, which is also the default.

log {...}

Logging:

level = string: debug, info (the default), warn or error.
format = string: text (the default) or json.
file = path: Where to log: stderr (the default), stdout, or a file.
services = map: The level for single services, e.g. { tftp = "debug" }.

resolve {...}

How addresses that a host does not give are looked up:

ethers = path: The ethers(5) file for Ethernet addresses, by host name. The default is /etc/ethers; an empty string disables it.
dns = bool: Whether to look up IP addresses with the system resolver, which includes /etc/hosts. The default is true.

NETWORKS

network "name" {...}

An Ethernet segment. bootd(8) has its own Ethernet and IP address on it and runs its own IP stack there. Frames are exchanged over UDP with udp, or captured on an interface with pcap.

address = address/prefix

bootd's IPv4 address and prefix length on the network, e.g. 192.168.1.250/24. Required.

mac = address

bootd's Ethernet address on the network. The default is a locally administered address derived from the network's name. interface uses the address of the pcap interface, which Wi-Fi needs.

udp = addr:port

The UDP address to exchange Ethernet frames on, one frame per datagram, with bootbridge(8), simh or QEMU. Addresses that send to it are learned as peers.

peers = list

UDP addresses that always receive frames, and a keepalive every minute.

l2tp {...}

Wrap the frames sent over udp in static L2TPv3, as bootbridge(8), Linux and QEMU speak it:

session = number: The session ID in both directions. The default is 1.
cookie = string: 8 or 16 hex digits, the same in both directions, e.g. "0x0123456789abcdef". Datagrams without it are ignored.
counter = bool: Whether frames carry the L2-specific sublayer with a sequence number. The default is true.

pcap = interface

Capture on a network interface directly, instead of udp. This needs privileges.

SERVICES

service "name" {...}

Enable a protocol. Requests for a protocol without a service block are not answered.

networks = list: The networks the service is offered on. The default is every network.

The other settings depend on the protocol:

service "rarp"

Reverse ARP. It answers with bootd's address on the network, and needs the host's Ethernet and IP address. No settings.

service "rmp"

HP Remote Maintenance Protocol, for HP 9000/300 and /400 boot ROMs. Clients without a host entry are matched to a class by the machine type they send. The boot ROM lists the host's files in configuration order.

server_name = string: The name sent to clients asking for the server. The default is the host name.

service "nd"

Sun Network Disk, for diskless Sun-2s running SunOS 1 and 2: the boot PROM reads public unit 0 before it knows its IP address, and the kernel takes its root, swap and other units from the host's disks. The host needs an Ethernet address and an IP address; clients learn theirs from bootd's replies.

window = number: 1 KB packets sent before waiting for the client. The default is 6.
send_delay = milliseconds: The pause before each packet, for clients that cannot keep up. The default is 10.

service "tftp"

TFTP, read only, with the blksize, tsize and timeout options. Clients are identified by IP address. A request for a path such as /tftpboot/name also matches a file named name. Refusals of requests sent to a broadcast address are only logged, so that another server can answer.

port = number: The default is 69.
timeout = seconds: Before retransmitting, unless the client asks for another timeout. The default is 2.
retries = number: How often a packet is sent before giving up. The default is 5.
max_blksize = number: The largest blksize option accepted. The default, 1468, keeps packets within one Ethernet frame.

service "bootparam"

Sun bootparam, with a built-in portmapper. GETFILE name answers with the host's export "name", so bootparam and NFS always agree; dump gets an empty answer when there is no such export, and gateway the router and netmask. Unknown clients and keys get no answer, so that another server can answer.

server_name = string: The name announced as the NFS server. The default is the host name.
domain = string: The NIS domain announced to clients. The default is the nis service's domain, for hosts that may use nis.
router = address: The default is bootd's address on the network.

service "nfs"

NFS version 2 and MOUNT version 1 over UDP, read only. It serves the host's exports; a client may only mount its own. No settings.

service "nis"

NIS (YP), read only, for one domain. The maps are made from files in /etc format in the maps directory: passwd, group, hosts, ethers, netgroup, services, protocols, rpc, networks, netmasks, aliases, publickey and bootparams, keyed as SunOS's /var/yp/Makefile keys them. A missing file means no map. The configured hosts are added to the hosts and ethers maps, and so is bootd itself, with its address on each network.

domain = string: The NIS domain. Required.
maps = path: The directory with the source files.
server_name = string: The master's name, added to the hosts maps. The default is the host name up to the first dot.

HOSTS AND CLASSES

host "name" {...}

A client. Its name is also its host name for bootparam and NIS.

mac = address: The Ethernet address. The default is looked up in the ethers file.
ip = address: The IP address. The default is looked up by name.
class = name: A class whose services, files, disks and exports the host gets as well. The host's own take precedence over the class's of the same name.
services = list: The services the host may use. The default is the class's, or every enabled service; "all" means every enabled service.
file, disk, export: See FILES, below.

class "name" {...}

Settings shared by hosts, with services, file, disk and export as in a host.

match = map: Serve clients that have no host entry when they identify as the given model. The only key is rmp_machtype, the machine type an HP boot ROM sends, e.g. { rmp_machtype = "HPS300" }.

FILES

file "path" {...}

A file a host may load.

name = string: The name the client asks for. The default is the base name of path; "*" matches any name.
aliases = list: Other names for the file.
services = list: The services that may serve it. The default is all the host's services.

disk "name" {...}

A disk served over ND.

path = path: The disk image, or the first-stage boot program. Required.
mode = string: image (the default), a disk image, or bootfile, which works like NetBSD's ndbootd: the boot program in path (at most 15 blocks) is served from block 1 on. A bootfile disk is also served as public unit 0 (ndp0), which the Sun-2 PROM boots from.
boot2 = path: For bootfile disks, a second-stage boot program served from block 16 on.
partition = letter: For images, serve one partition (a to h) of an image with a Sun disk label.
offset = sectors
size = sectors: For images, serve part of the image instead, like /etc/nd.local; a size of 0, the default, means up to the end.
boot = path: For images, a boot program such as SunOS's bootnd served in place of blocks 1 to 15, where the PROM loads it from.
unit = number: The unit number: ndn, or ndpn with public. The default is 0.
public = bool: Serve the disk as public unit ndpn, shared by clients and read only.
writable = bool: Let the client write to the disk, e.g. its root and swap. The default is false; writes to read-only disks get an error.

export "name" {...}

A directory served over NFS and announced by bootparam, usually "root" and "swap".

path = path: Required.
server = string: Another NFS server that serves the export, which bootparam announces instead of bootd.
spec = path: An mtree(5) specification of the export's files. The owners, modes, device nodes and symbolic links it lists are served as given, so that a root file system extracted without root privileges can be served, e.g. with a specification made by
tar -cf root.mtree --format=mtree @root.tgz
export_path = path: The path clients mount and bootparam announces. The default is the absolute path. NetBSD keeps server:path in 90 bytes.
writable = bool: Not supported yet.

EXAMPLES

A SPARCstation that loads its boot program over TFTP and mounts its root over NFS, attached through bootbridge(8):

root = "/srv/netboot"

network "lab" {
  address = "192.168.1.250/24"
  udp     = "127.0.0.1:4712"
  peers   = ["127.0.0.1:4711"]
}

service "rarp" {}
service "tftp" {}
service "bootparam" {}
service "nfs" {}

host "kali" {
  # mac and ip are looked up in /etc/ethers and DNS.
  services = ["rarp", "tftp", "bootparam", "nfs"]

  # The boot PROM asks for its IP address in hex.
  file "files/sparc/solaris-2.5.1-sun4c" { name = "*" }
  export "root" { path = "/export/hosts/kali/root" }
  export "swap" { path = "/export/hosts/kali/swap" }
}

HP 9000/300 machines without host entries, chosen by machine type:

service "rmp" {}

class "hp300" {
  match    = { rmp_machtype = "HPS300" }
  services = ["rmp"]

  file "files/hp300/netbsd-uboot" { name = "netbsd" }
}

A Sun-2 booting NetBSD over ND:

host "sun2" {
  services = ["rarp", "nd", "bootparam", "nfs"]

  disk "boot" {
    path  = "files/sun2/bootyy"
    boot2 = "files/sun2/netboot"
    mode  = "bootfile"
  }
  export "root" {
    path = "/export/hosts/sun2/root"
    spec = "/export/hosts/sun2/root.mtree"
  }
}

A network reached over L2TPv3 from bootbridge(8) on another machine:

network "remote" {
  address = "192.168.1.251/24"
  udp     = "0.0.0.0:1701"
  peers   = ["192.168.1.10:1701"]
  l2tp { cookie = "0x0123456789abcdef" }
}

The packages include a commented example with every setting, in /usr/share/doc/gobootd/examples/bootd.hcl on Debian and Ubuntu.