erbium.conf(5)

📦 version 1.0.8, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

📖 NAME

erbium.conf — the config file for erbium, bestie 💖

🌸 DESCRIPTION

okay so first things first: erbium is a daemon that hands out network services for small/home networks. and erbium.conf? that's where you tell erbium(8) what to do. it's giving "settings app but make it YAML". 🎀

erbium.conf is in YAML format, and it's got multiple sections, so buckle up.

✨ Executable Configuration

here's the cute part:

if erbium.conf is not executable, then erbium just reads the file directly for config. simple. no drama. 🫶
if erbium.conf is executable, then erbium will actually execute the config file, and it expects a valid erbium config to come out on standard output. 💅

so why would you do that?? because it lets you generate erbium configs at runtime with whatever custom tooling fits your environment (eg shellscript, python script, ELF binary etc — go off, honestly 👑). that tooling could do templating, or literally whatever functionality your local environment needs. main character energy fr fr.

🌈 Configuration wide options

quick thing before we go any further: IP addresses can be specified as the string $self4 or $self6, which will use the local IPv4 or IPv6 address of the interface the request arrived on respectively. noted? noted. ⭐

🦋 Top level Configuration

the top level config gives you defaults for the other protocol implementations in erbium. for most networks, only the top level configuration is necessary — but for more advanced users, per protocol configuration can be used to override these defaults (or disable them by setting their value to null). top level configuration is not required though! you can instead configure each protocol individually. it's provided as a convenience measure. it's a gift, not a requirement. 🎁

addresses: list-of-subnets — (defaults to no value) this provides both the list of interfaces to configure for router advertisements and DHCP, and the IP ranges to give out. the subnets must match exactly the subnets on the interface (including the prefix length), and the network address. for DHCP this will give out addresses on this interface except for the network address, broadcast address, and the local interface IPv4 address. DHCP will also exclude any address given in a normal policy, in the same way that sub policies work below. for router advertisements, this will configure the IPv6 prefix for SLAAC addressing. 💫
dns-servers: list-of-ip-addresses — (defaults to no value) this sets the default dns servers to be handed out by DHCP and Router Advertisements. DHCP is limited by the design of the protocol to only support handing out IPv4 addresses. similarly router advertisements are limited by design to only support handing out IPv6 addresses. the protocol said so, not me. 😭
dns-search: list-of-domain-names — (defaults to no value) this sets the default DNS search path. this is supported by both the DHCP and router advertisements protocols. slay. ✨
captive-portal: url — (defaults to no value) this sets the URL to the captive portal, as specified in RFC8910. this is used by both DHCP and router advertisements. 🎀
default-listen-style: bind-unspecified|bind-addresses-interfaces — (defaults to bind-unspecified) this sets the default bind style for DNS and DHCP requests.
- bind-unspecified — this binds to the unspecified address (0.0.0.0 or [::]). this means that interfaces do not need to be fully operational when erbium starts. erbium will discard packets that have no matching configuration. this is the default. 💤
- bind-addresses-interfaces — this binds to addresses that are configured on interfaces that are within the prefixes listed in the addresses field. this allows erbium to share a machine with systemd-resolved or other DNS/DHCP servers that are used for other interfaces. this however has the downside that the interfaces must be up and fully configured before erbium can start, which can cause race conditions with dynamic addressing systems and duplicate address detection. 😬 be careful bestie.
api-listeners: list-of-socket-addresses — (defaults to [/var/lib/erbium/control]) this sets the addresses that the API HTTP server will listen on. by default this is only a unix domain socket, which can be easily secured. IPv4 (ip:port) and IPv6 ([ip]:port) are also supported. you may wish to use ["/var/lib/erbium/control", "[::1]:9968"] to allow scraping prometheus metrics from ip6-localhost. 📊
acls: array-of-acls — (default see the ACLs section below) this introduces the array of ACLs.

💜 DHCP Configuration

DHCP config for erbium lives under a dhcp-policies heading. dhcp-policies is a a list of policies to apply to incoming DHCP packets. each policy is considered in turn, with the first policy that successfully matches being the policy that is applied. first come, first served, periodt. 👑

a policy section contains 0 or more match-condition fields, and 0 or more apply-option fields.

🔍 DHCP Matches

all match conditions in a policy must match (the conditions are AND'd together). a policy section that contains no matches only matches if one of it's subpolicies matches. (see below for info about subpolicies 👇).

match-subnet: cidr4-prefix/len — match-subnet is how the DHCP standards expect you to match incoming packets. when a DHCP packet from a client is received, then the IP address of the interface where it is received is noted, and can be matched with match-subnet. this works even for packets that are relayed, in which case the IP address of the relay is used. 🛰️

an example is: match-subnet: 192.168.0.0/24.

match-hardware-address: hardware-address — clients send a "client hardware address" (chaddr) in DHCP request packets. this allows matching on that address. this is most useful when matching on individual hosts to assign them a static address. one host, one address, iconic. 🎯
match-dhcpoption: option-value — for every DHCP option supported by erbium, you can match on it by prefixing its name with match-. note that most DHCP clients do not send many options, so in practise there isn't much you can match on here. some obvious and useful options for matching on are match-host-name and match-class-id. 💀

erbium will log options received from each client to make finding useful options to match on easier. if you specify null as the value to match on, then it will only match if the client does not provide that option. sneaky but valid.

🎁 Applying DHCP Options

each policy contains a list of option values to apply to a client (assuming the client requested the option). for nested subpolicies (see below), options are applied for the outer policies first, then the subpolicies can choose to override those values. layers on layers, we love to see it. 🧅

apply-address: ip4addr — this adds one IP address to the pool for the policy. this can be provided multiple times to add multiple individual IP addresses to a pool, and then the client will be assigned one. 🍓
apply-subnet: cidr4-prefix/len — this adds an entire subnet worth of addresses to the address pool for the policy. this can be provided multiple times to add multiple subnets. the first and last addresses of the subnet are not applied, as these are the network and broadcast addresses respectively. 🙅
apply-range: { start: start-ip4, end: last-ip4} — this applies a range of IP addresses, from start-ip4 to last-ip4 inclusive. this is a YAML hash type, with the keys start and end. the text above shows this using YAML's single line syntax, but it can be in any of YAML's formats for a hash. flexible queen. 💅
apply-option: value — this lets you apply an arbitrary value for a DHCP option. the syntax for the values varies based on the option. (see a list of options and their types below). you can also set an option to null to unset it (if, for example, the value was inherited in a sub policy, or to override erbium's internal defaults for a value). undo button, but for config. ↩️

🪆 Subpolicies

as well as having match and apply rules for each policy, a policy can also contain subpolicies. a subpolicy is only attempted to be matched if all the enclosing policies matched. sub-policies have their own DHCP IP pools. if you add an IP address to a policy then it will be excluded from all parent pools. 🤯

so like: you can have an outer policy that contains a apply-subnet: 192.0.2.0/24, then have a subpolicy that matches an individual host that contains only apply-address: 192.0.2.53, and that address will only be given to the individual host. (see the example below). a policy that does not specify an new addresses will continue to use the addresses for it's parent pool. (again, see example below). sub-policies are introduced by adding a policies: section to a policy. nesting dolls but make it networking. 🎀

✨ DHCP Options ✨

okay bestie, this is the whole DHCP options menu and it is giving comprehensive 💅 the columns are Num, Option name, Type, Ref, and Description — and we are doing every single one, no skips, no summarising, periodt ✨

Num 1 · netmask — type ip4 · ref RFC2131 — the netmask for this network 🌸
Num 2 · time-offset — type seconds · ref RFC2131 — the current timezone offset in seconds ⏰
Num 3 · routers — type ip4 list · ref RFC2131 — list of default gateways 🚪
Num 4 · time-servers — type ip4 list · ref RFC2131 — list of time servers ⏳
Num 5 · name-servers — type ip4 list · ref RFC2131 — list of IEN-116 name servers 📛
Num 6 · dns-servers — type ip4 list · ref RFC2131 — list of DNS servers for recursive resolution 🔍
Num 7 · log-servers — type ip4 list · ref RFC2131 — list of MIT-LCS UDP log servers (obsolete) 💀
Num 8 · quote-servers — type ip4 list · ref RFC2131 — list of quote of the day servers (RFC865) 💬
Num 9 · lpr-servers — type ip4 list · ref RFC2131 — list of LPR print servers 🖨️
Num 12 · hostname — type string · ref RFC2131 — hostname of the client 🏷️
Num 15 · domain-name — type string · ref RFC2131 — domain name of the client 🌐
Num 19 · forward — type boolean · ref RFC2131 — if the client should enable IP forwarding 🔀
Num 22 · max-reassembly — type seconds · ref RFC2131 — how long to wait for IP fragment reassembly 🧩
Num 23 · default-ttl — type integer · ref RFC2131 — the default TTL ⏱️
Num 24 · mtu-timeout — type integer · ref RFC2131 — how long to cache MTU path discovery for 🛣️
Num 26 · mtu — type integer · ref RFC2131 — the MTU the client should use 📏
Num 27 · mtu-subnet — type integer · ref RFC2131 — the MTU for the local subnet 🏘️
Num 28 · broadcast — type ip4 · ref RFC2131 — the broadcast address of the local subnet 📢
Num 35 · arp-timeout — type integer · ref RFC2131 — ARP cache timeout ⏲️
Num 42 · ntp-servers — type ip4 list · ref RFC2131 — a list of NTP servers to use 🕰️
Num 69 · smtp-servers — type ip4 list · ref RFC2131 — a list of SMTP servers to use 📧
Num 70 · pop3-servers — type ip4 list · ref RFC2131 — a list of POP3 servers to use 📬
Num 71 · nntp-servers — type ip4 list · ref RFC2131 — a list of NNTP servers to use 📰
Num 77 · user-class — type string · ref RFC2131 — a user configurable class 🎨
Num 80 · fqdn — type string · ref RFC2131 — the fully qualified domain name of the client 🏠
Num 100 · tz-rule — type string · ref RFC4833 — the POSIX complaint timezone rule specification 🕰️ (yes, it says complaint, bestie, we don't make the rules)
Num 101 · tz-name — type string · ref RFC4833 — a tzdata timezone name 🌍
Num 114 · captive-portal — type string · ref RFC8910 — the URL for a captive portal 🛜

│ 121 │ routes         │ routes   │ RFC3442 │ A list of static routes.                         │

okay bestie real talk 🫶 that's where the table runs out, and the docs author literally says so:

(Note more options than this exist, but I ran out of time writing these docs. Patches updating and extending this list based on src/dhcp/dhcppkt.rs appreciated)

so like… if you know more, go off, send the patch, we love that for you 💅

the types, because YAML needs ✨shapes✨

every value you drop in is gonna be one of these, so let's vibe-check them:

string — a plain string, in any of YAML's string formats. flexible queen 💖
integer — a whole number, in any of YAML's integer formats.
ip4 — an IPv4 address. like 192.0.2.0. it can also be the keyword $self4. 🎀
ip4 list — a YAML list of IPv4 addresses. this list can also contain the keyword $self4. e.g. [$self4, 192.0.2.1, 192.0.2.2].
seconds — either an integer count of seconds (any of YAML's integer formats), or a string of numbers with suffixes: "s" for seconds, "m" for minutes, "h" for hours, "d" for days. you can combine multiple units, and if you leave the unit off it just assumes seconds. so "4h20m5" = 4 hours, 20 minutes, and 5 seconds, which is literally the same as the number 15605. math is math 🧮✨
hardware address — written as a colon (:) separated list of hexadecimal octets. for example: 00:00:5E:00:53:00. iconic MAC energy 🦋
routes — routes get a prefix and a nexthop. e.g. { prefix: 192.0.2.0/24, next-hop: 192.0.2.254 }

🛰️ ROUTER ADVERTISEMENT CONFIGURATION 🛰️

so Router Advertisements get their own little section in erbium, called router-advertisements. under it you drop a yaml hash of interfaces — keyed by the interface name, iykyk — and the value is a yaml hash with the keywords that configure the announcements for that interface. very main character 💅

hop-limit: integer — (default 0) sets the hop limit for hosts on this network. if it's 0 or null, erbium just won't set that information at all. no thoughts, no hop limit 🙈
managed: boolean — (default false) configures the "Managed address configuration" bit, i.e. whether hosts on this network should use DHCPv6 to get an address. heads up: hosts ignore this if the "Other" bit is set. (yes, they gossip about each other)
other: boolean — (default false) configures the "Other configuration" bit. this tells hosts on this network that there's more configuration available via DHCPv6. and again: hosts ignore this if the "managed" bit is set. they really can't both be the drama 👑
lifetime: duration — (default 0s if there's no default route, or if the default route points back out the same interface; 1h otherwise) this sets the "Router Lifetime" — how long this host should be considered a default router. set it to 0 and it means the erbium host is not a default router. periodt.
reachable: duration — (default 0ms) configures the "Reachable Time" for hosts on the network. it's how long a host on the local network should consider another host reachable after it's had confirmation of reachability. setting it to 0 means this router doesn't specify it. lowkey a shrug ✨
retransmit: duration — (default 0ms) configures the "Retrans Timer" for hosts on the network — the time between retransmitted Neighbor Solicitation messages. 0 means this router doesn't specify it either. same shrug, different key 🫠
mtu: mtu — (defaults to the MTU of the interface) configures the MTU of the link. you can set it to null and this router just won't specify it. opting out is valid 💅
captive-portal: url — (defaults to captive-portal in the top level configuration) configures a URL to the captive portal (RFC7710). set it to null and this router won't specify it. bye girl 👋
dns-servers — (defaults based on dns-servers in the top level configuration) a hash configuring the recursive DNS servers:
- addresses: list-of-ipv6-addresses — (defaults to the IPv6 addresses listed in the dns-servers top level configuration) sets the IPv6 addresses for the router addresses. you can use $self6 here to refer to the local interface address. 🎀
- lifetime: duration — (defaults to the setting of the interface lifetime) sets how long the recursive DNS server addresses stay valid.
dns-search — (a hash configuring the DNS search list)
- domains: list-of-domain-suffixes — (defaults to the domains listed in the top level dns-search configuration) sets the ordered list of domain suffixes that should be tried.
- lifetime: duration — (defaults to the setting of the interface lifetime) sets how long the DNS search list domain suffixes stay valid.
pref64 — (a hash configuring the NAT64 prefix range used by this network)
- prefix: ip6-prefix — (defaults to none) configures the NAT64 prefix used by this network.
- lifetime: duration — (defaults to 10 minutes) configures how long the NAT64 prefix is valid for.
prefixes — (a list of hashes configuring addresses)
- prefix: cidr6-prefix/len — (defaults to no prefix) configures a prefix to be announced in the router advertisement.
- on-link: boolean — (defaults to true) configures whether all addresses in this prefix are considered "on link".
- autonomous: boolean — (defaults to true) configures whether hosts should autonomously configure one or more addresses from this prefix.
- valid: duration — (defaults to 30 days) configures how long this prefix is considered valid and usable.
- preferred: duration — (defaults to 7 days) how long addresses generated from the prefix via stateless address autoconfiguration remain preferred, and should be used for new connections. slay 🦋

🌐 DNS CONFIGURATION 🌐

dns-listeners: list-of-socket-addresses — (defaults to [::]:53 if default-listen-style is bind-unspecified, otherwise the interface addresses listed in addresses) this configures which addresses the DNS server will listen on. pick your spots bestie 🎯
dns-routes: list-of-dns-routes — (defaults to the empty list) this is a list of DNS routes. and yes, each one has its own little keys:
- domain-suffixes: list-of-domain-suffixes — (defaults to the empty list) the list of domain suffixes this route should apply to. it matches this domain and all sub-domains. so for example "example.com" matches "foo.example.com" and "example.com", but not "example.net". the longest suffix match wins. and if you want this to be a default match, use the empty string "". no cap 🧢
- type: forward|forge-nxdomain — (defaults to forward) this configures what to do with domain names that end in this suffix:
  - forward — used to forward queries that desire recursion to another set of nameservers.
  - forge-nxdomain — this will forge an NXDOMAIN reply for this, and all subdomains. it's giving "no such thing, don't ask again" 💀
- dns-servers: list-of-socket-addresses — (defaults to the empty list) only used by type "forward". it specifies the nameservers that the queries should be forwarded to. 🫶

💅 ACLs (Access Control Lists) 💅

okay so bestie, if u wanna change which clients can do what, erbium has a customisable ACL system. ACLs are defined under the heading acls: at the top level, and they're an ordered list of rules: which clients this particular ACL applies to, and what access this client has. ACLs are applied in a strict first-match basis. Any client that does not match any ACL will not be granted any access. periodt. 💅

match-subnets: array-of-subnets — if u set this, it requires that the access granted by this ACL applies only to clients that have a source address that matches one of subnets provided. If u don't set it, then the source address is not matched. no cap.
match-unix: boolean — if u set this, it requires that the access granted by this ACL applies only to clients over a unix domain socket (if true), otherwise must not be a unix domain socket (if false). If u don't set it, then if the client arrives over a unix domain socket is not matched.
apply-access: array-of-access-strings — (default: empty list) this specifies which accesses the matched clients are permitted. here's the breakdown, bestie:
- dhcp-client — Permissions required for DHCP clients with default settings. This is used to support future versions that may add additional protocols for DHCP clients. Currently an alias for dns-recursion. 🦋
- dns-recursion — Allows DNS recursion. slay.
- http — Allows access to the non-API parts of the HTTP server. 💖
- http-metrics — Allows access to the /metrics endpoint of the HTTP server.
- http-leases — Allows access to the list of active leases over HTTP.
- http-ro — An alias for http-metrics and http-leases. This is used to support future versions that may add additional read only HTTP end points that users can use to collect information. By using http-ro instead of http-metrics and http-leases independently, as new accesses are added then this configuration will include them. iykyk. ✨

if u specify any ACLs then all the defaults are overridden and need to be specified. The defaults for ACLs are as follows:

acls:
 # Allow DHCP clients to perform DNS queries, and talk to the HTTP API server (if enabled)
 - match-subnets: [the-contents-of-the-top-level-addresses-field]
   apply-access: ["dns-recursion", "http-ro"]
 # Allow localhost to perform DNS queries, any talk to the HTTP API server (if enabled)
 - match-subnets: [127.0.0.0/8, ::1/128]
   apply-access: ["dns-recursion", "http-ro"]
 # Allow all users via Unix domain sockets to talk to the HTTP API server (if enabled)
 - match-unix: true
   apply-access: ["http-ro"]

✨ EXAMPLE ✨

okay so here's a whole example, bestie. this is the vibe:

dns-servers: [$self4, $self6, 8.8.8.8, 2001:4860:4860::8888]
dns-search: [example.com, example.org]
addresses: [192.0.2.0/24, 2001:db8::/64]
dhcp-policies:
  - apply-ntp-servers: [192.0.2.123]

    policies:
     - match-subnet: 198.51.100.0/24
       apply-range:
         start: 198.51.100.100
         end: 198.51.100.199
       apply-routes:
        - prefix: 203.0.113.0/24
          next-hop: $self4
       policies:
        - { match-hardware-address: 00:00:5E:00:53:01, apply-address: 198.51.100.110, apply-dns-servers: null }
        - { match-hardware-address: 00:00:5E:00:53:02, apply-address: 198.51.100.111, apply-dns-servers: [8.8.8.8] }

     - apply-subnet: 203.0.113.0/24
       policies:
        - { match-hardware-address: 00:00:5E:00:53:F0 }
        - { match-hardware-address: 00:00:5E:00:53:F1 }

router-advertisements:
 eth1:
   lifetime: 30m
   prefixes:
    - prefix: 2001:db8:0:1::/64
   dns-servers:
    addresses: [2001:db8::53]

dns-routes:
  - domain-suffixes: [""]
    type: forward
    dns-servers: [2001:4860:4860::8888]

Imagine a router with 3 interfaces. bestie, here's the setup:

eth0 — This has the addresses 192.0.2.254/24, and 2001:db8::1/64.
eth1 — This has the addresses 198.51.100.254/24, and 2001:db8:0:1::1/64.
eth2 — This has the address 203.0.113.254/24.

A client on eth0 will be assigned an IP out of the range 192.0.2.1 to 192.0.2.253 (192.0.2.0 being the network address, 192.0.2.254 being in use by the local interface, and 192.0.2.255 being the broadcast address, all are excluded).

A client on eth1 with the mac address 00:00:5E:00:53:01 on eth1 will get given the IP address 198.51.100.110 (and no other). It will not be given any DNS servers (overriding the top level configuration),

A client on eth1 with the mac address 00:00:5E:00:53:02 on will get given the IP address 198.51.100.111. It will get assigned only 8.8.8.8 as the DNS server address.

Other clients on eth1 will get assigned an IPv4 address between 198.51.100.100 and 198.51.100.200, but not 198.51.100.110 or 198.51.100.111, as these are reserved in a subpolicy. Other clients will get 192.0.2.254 and 8.8.8.8 as IPv4 DNS servers (Inherited from the top level configuration, IPv6 addresses filtered out).

On eth2, only the two hosts 00:00:5E:00:53:F0 and 00:00:5E:00:53:F1 will be allocated addresses between 203.0.113.1 and 203.0.113.254 (as the default allocated addresses is calculated from the match-address directive).

All IPv4 clients on all interfaces will get assigned the NTP server 192.0.2.123.

Despite there being no explicit router configuration section for eth0, clients with IPv6 on eth0 will allocate themselves an address in 2001:db8::/64, due to addresses matching this interface being configured at the top level. They will have 2001:db8::1 and 2001:4860:4860::8888 as their DNS servers (again inherited from the top level), and a dns search path of example.com and example.org.

Clients with IPv6 on eth1 will allocate themselves an address in 2001:db8:0:1:/64, and will use the DNS server 2001:db8::53.

📁 FILES 📁

erbium.conf

that's it. that's the file. 💅

💀 BUGS 💀

erbium is currently under active development, and many important features and protocols are not yet complete, or even implemented yet. so yeah, bestie, it's giving work-in-progress. don't expect everything to be slaying just yet. 😭

👀 SEE ALSO 👀

go read these too, bestie:

erbium.conf(5)
erbium-dns(8)
erbium-dhcp(8)
erbium-conftest(8)

this page came from Linux, dated 2022-05-30, for erbium.conf(5). stay iconic, bestie. 💖✨🦋

📦 where this page comes from

debian trixie: erbium 1.0.5-2+b7 · Apache-2.0
ubuntu noble: erbium 1.0.5-2 · Apache-2.0
ubuntu questing: erbium 1.0.5-2build1
ubuntu resolute: erbium 1.0.6-1 · Apache-2.0
ubuntu stonking: erbium 1.0.8-1 · Apache-2.0
📜 the page's license: Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms