# DHCP options

Options are set by name, or by number with a type. Set them in the
settings (every subnet), on a subnet, or on a reservation; the most
specific wins ([subnets.md](subnets.md#options)).

```sh
steward settings set --option domain-name-servers=10.0.10.2,10.0.10.3
steward subnet update office --option routers=10.0.10.1 --unset-option ntp-servers
steward reservation update nas --option 224:string=hello   # an option Steward doesn't know
```

`steward option list` prints the list below; the web UI offers it in each
options editor. (This page is written by scripts/optionsdoc.py from the
catalog in internal/dhcp4/catalog.go.)

## Options by name

| Code | Name | Type | What |
|---:|---|---|---|
| 2 | `time-offset` | int32 | the client's offset from UTC in seconds (obsolete; prefer tcode) |
| 3 | `routers` | ips | default gateways, in order of preference |
| 4 | `time-servers` | ips | RFC 868 time servers (rarely used; see ntp-servers) |
| 6 | `domain-name-servers` | ips | DNS servers, in order of preference |
| 7 | `log-servers` | ips | MIT-LCS UDP log servers |
| 15 | `domain-name` | string | the domain the client's host name belongs to |
| 19 | `ip-forwarding` | bool | whether the client should forward packets |
| 23 | `default-ip-ttl` | uint8 | the TTL for the client's outgoing packets |
| 26 | `interface-mtu` | uint16 | the MTU of the client's interface |
| 28 | `broadcast-address` | ip | the subnet's broadcast address |
| 31 | `perform-router-discovery` | bool | whether the client should solicit routers (RFC 1256) |
| 42 | `ntp-servers` | ips | NTP servers, in order of preference |
| 43 | `vendor-encapsulated-options` | hex | vendor-specific information |
| 44 | `netbios-name-servers` | ips | NetBIOS name servers (WINS) |
| 46 | `netbios-node-type` | uint8 | NetBIOS node type: 1 B, 2 P, 4 M, 8 H |
| 47 | `netbios-scope` | string | NetBIOS scope |
| 60 | `vendor-class-identifier` | string | the server's vendor class (PXE: PXEClient) |
| 66 | `tftp-server-name` | string | the TFTP server for network boot |
| 67 | `boot-file-name` | string | the file to boot from the TFTP server |
| 69 | `smtp-server` | ips | mail servers |
| 100 | `pcode` | string | the time zone as a POSIX TZ string (EST5EDT,M3.2.0,M11.1.0) |
| 101 | `tcode` | string | the time zone by name (Europe/London) |
| 114 | `v4-captive-portal` | string | the captive portal's API URL (RFC 8910) |
| 119 | `domain-search` | domains | domains to try when looking up short names |
| 121 | `classless-static-route` | routes | extra routes: "10.20.0.0/16 via 10.0.10.1" (clients that use it ignore routers, so add 0.0.0.0/0 too) |
| 150 | `tftp-server-address` | ips | TFTP servers by address (Cisco phones and others) |
| 252 | `wpad-url` | string | web proxy auto-discovery URL |

The names are Kea's, so a Kea configuration's options carry over.

## Value types

| Type | How to write it | Example |
|---|---|---|
| ip | an IPv4 address | `10.0.10.255` |
| ips | IPv4 addresses, separated by commas or spaces, in order of preference | `10.0.10.2, 10.0.10.3` |
| string | text, as it is | `lan` |
| uint8, uint16, uint32 | a whole number | `1500` |
| int32 | a whole number, maybe negative | `-3600` |
| bool | `true` or `false` (`yes`/`no`, `on`/`off`, `1`/`0` work too) | `false` |
| domains | domain names, separated by commas or spaces; sent in DNS wire format (RFC 3397) | `lan, home.arpa` |
| routes | `DESTINATION/LENGTH via ROUTER`, separated by commas (Kea's `DEST - ROUTER` works too); RFC 3442 | `10.20.0.0/16 via 10.0.10.1, 0.0.0.0/0 via 10.0.10.1` |
| hex | bytes in hex, with or without colons | `01:02:0a` |

Values are checked when they are set, and stored in a canonical form:
`10.0.10.2,10.0.10.3` becomes `10.0.10.2, 10.0.10.3`.

Clients that use `classless-static-route` ignore `routers`, so give the
default route in it as well (`0.0.0.0/0 via ROUTER`).

## Options by number

An option the list doesn't have is set by its number and type,
`CODE:TYPE=VALUE`; without a type the value is hex:

```sh
steward subnet update office --option 224:string=hello --option 225=01:02
```

In the API, give `{"option": "224", "type": "string", "value": "hello"}`.

## Options Steward sets itself

These can't be set; Steward fills them in (`option_reserved` if you try):

| Code | Why |
|---:|---|
| 0 | pad |
| 1 | the subnet mask comes from the subnet's prefix |
| 12 | set the reservation's host name instead |
| 50 | only clients send the requested address |
| 51 | set the lease time instead |
| 52 | the server handles option overload itself |
| 53 | the message type is set by the server |
| 54 | the server identifier is the interface's address |
| 55 | only clients send the parameter request list |
| 56 | the server writes its own messages |
| 57 | only clients send the maximum message size |
| 58 | the renewal time is half the lease time |
| 59 | the rebinding time is 7/8 of the lease time |
| 61 | only clients send a client identifier |
| 82 | relay agent information is only added by relays |
| 255 | end |