Provided by: erbium_1.0.5-1_amd64 
NAME
erbium.conf - Configuration for erbium
DESCRIPTION
erbium is a daemon that provides network services for small/home networks. erbium.conf
provides configuration for erbium(8).
erbium.conf is in YAML format, and involves multiple sections.
Executable Configuration
If erbium.conf is not executable, then erbium will read the file directly for
configuration.
If erbium.conf is executable, then erbium will execute the configuration file, and expect
a valid erbium configuration on standard output. This allows for generating erbium
configurations at runtime via whatever custom tooling is appropriate for your environment
(eg shellscript, python script, ELF binary etc). This tooling could provide templating or
whatever functionality is needed for the local environment.
Configuration wide options
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.
Top level Configuration
The top level configuration provides 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, you
can instead configure each protocol individually, it is provided as a convenience measure.
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 inteface (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.
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.
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.
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 configuration for erbium is 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.
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 information 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.
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.
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.
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.
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).
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. Thus you can have an outer policy that
contains a "apply-subnet: 192.0.2.0/24", then have a subpolicy for 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.
DHCP Options
┌────┬────────────────┬──────────┬─────────┬──────────────────────────────────────────────────┐
│Num │ Option name │ Type │ Ref │ Description │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 1 │ netmask │ ip4 │ RFC2131 │ The netmask for this network. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 2 │ time-offset │ seconds │ RFC2131 │ The current timezone offset in seconds. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 3 │ routers │ ip4 list │ RFC2131 │ List of default gateways. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 4 │ time-servers │ ip4 list │ RFC2131 │ List of time servers. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 5 │ name-servers │ ip4 list │ RFC2131 │ List of IEN-116 name servers. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 6 │ dns-servers │ ip4 list │ RFC2131 │ List of DNS servers for recursive resolution. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 7 │ log-servers │ ip4 list │ RFC2131 │ List of MIT-LCS UDP log servers (obsolete). │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 8 │ quote-servers │ ip4 list │ RFC2131 │ List of quote of the day servers (RFC865). │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 9 │ lpr-servers │ ip4 list │ RFC2131 │ List of LPR print servers. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 12 │ hostname │ string │ RFC2131 │ Hostname of the client. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 15 │ domain-name │ string │ RFC2131 │ Domain name of the client. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 19 │ forward │ boolean │ RFC2131 │ If the client should enable IP forwarding. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 22 │ max-reassembly │ seconds │ RFC2131 │ How long to wait for IP fragment reassembly. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 23 │ default-ttl │ integer │ RFC2131 │ The default TTL. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 24 │ mtu-timeout │ integer │ RFC2131 │ How long to cache MTU path discovery for. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 26 │ mtu │ integer │ RFC2131 │ The MTU the client should use. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 27 │ mtu-subnet │ integer │ RFC2131 │ The MTU for the local subnet. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 28 │ broadcast │ ip4 │ RFC2131 │ The broadcast address of the local subnet. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 35 │ arp-timeout │ integer │ RFC2131 │ ARP cache timeout. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 42 │ ntp-servers │ ip4 list │ RFC2131 │ A list of NTP servers to use. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 69 │ smtp-servers │ ip4 list │ RFC2131 │ A list of SMTP servers to use. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 70 │ pop3-servers │ ip4 list │ RFC2131 │ A list of POP3 servers to use. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 71 │ nntp-servers │ ip4 list │ RFC2131 │ A list of NNTP servers to use. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 77 │ user-class │ string │ RFC2131 │ A user configurable class. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│ 80 │ fqdn │ string │ RFC2131 │ The fully qualified domain name of the client. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│100 │ tz-rule │ string │ RFC4833 │ The POSIX complaint timezone rule specification. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│101 │ tz-name │ string │ RFC4833 │ A tzdata timezone name. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│114 │ captive-portal │ string │ RFC8910 │ The URL for a captive portal. │
├────┼────────────────┼──────────┼─────────┼──────────────────────────────────────────────────┤
│121 │ routes │ routes │ RFC3442 │ A list of static routes. │
└────┴────────────────┴──────────┴─────────┴──────────────────────────────────────────────────┘
(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)
The different types are expected to be:
string A simple string in any of YAMLs string formats.
integer
An integer, in any of YAMLs integer formats.
ip4 An IPv4 address. eg: 192.0.2.0 This can also be the keyword $self4.
ip4 list
A YAML list of IPv4 addresses. This list can also contain the keyword $self4. eg:
[$self4, 192.0.2.1, 192.0.2.2].
seconds
This can be an integer number of seconds (in any of YAMLs integer formats), or it
can be a string with numbers suffixed with "s" (for seconds), "m" (for minutes),
"h" (for hours), or "d" (for days). Multiple units can be combined, and if the
unit is left off it is assumed to be seconds. For example "4h20m5" is considered
to be 4 hours, 20 minutes, and 5 seconds (which is the same as the number 15605).
hardware address
This is specified as a colon (:) separated list of hexadecimal octets. For
example: 00:00:5E:00:53:00.
routes Routes are specified with a prefix and nexthop. eg: { prefix: 192.0.2.0/24, next-
hop: 192.0.2.254 }
Router Advertisement Configuration
Router Advertisements can be configured in erbium under a router-advertisements section.
This should be a yaml hash of interfaces, keyed by the interface name, and the value being
a a yaml hash with some keywords configuring the announcements for an interface.
hop-limit: integer
(default 0) Set the hop limit for hosts on this network. If set to 0 or null, then
it will not set that information.
managed: boolean
(default false) Configures the "Managed address configuration" bit, configuring if
hosts on this network should use DHCPv6 to get an address. (Hosts ignore this if
the "Other" bit is set)
other: boolean
(default false) Configures the "Other configuration" bit. This tells the hosts on
this network that there is more configuration available via DHCPv6. (Hosts ignore
this if the "managed" bit is set)
lifetime: duration
(default 0s if there is no default route or if the default route points back out
the same interface, 1h otherwise) This configures the "Router Lifetime". This
configures how long this host should be considered a default router. Setting this
to 0 means that the erbium host is not a default router.
reachable: duration
(default 0ms) This configures the "Reachable Time" for hosts on the network. This
is how long a host on the local network should consider a host reachable after
having confirmation of reachability. Setting this to 0 means that this is not
specified by this router.
retransmit: duration
(default 0ms) This configures the "Retrans Timer" for hosts on the network. The
time between retransmitted Neighbor Solicitation messages. Setting this to 0 means
that this is not specified by this router.
mtu: mtu
(defaults to the MTU of the interface) This configures the MTU of the link. This
can be set to null so that this router will not specify this.
captive-portal: url
(defaults to captive-portal in the top level configuration) This configures a URL
to the captive portal (RFC7710). This can be set to null so that this router will
not specify this.
dns-servers:
(defaults based on dns-servers in the top level configuration) hash configuring the
recusive DNS servers,
addresses: list-of-ipv6-addresses
(defaults to the IPv6 addresses listed in the dns-servers top level
configuration) This sets the IPv6 addresses for the router addresses. It is
possible to use $self6 here to refer to the local interface address.
lifetime: duration
(defaults to the setting of the interface lifetime) This sets the amount of
time that the recursive DNS servers addresses are valid.
dns-search:
(hash configuring the DNS search list)
domains: list-of-domain-suffixes
(defaults to the domains listed in the top level dns-search configuration)
This sets the ordered list of domain suffixes that should be tried.
lifetime: duration
(defaults to the setting of the interface lifetime) This sets the amount of
time that the DNS search list domain suffixes are valid.
pref64:
(a hash configuring the NAT64 prefix range used by this network)
prefix: ip6-prefix
(defaults to none) This configures the NAT64 prefix used by this network.
lifetime: duration
(defaults to 10 minutes) This configures how long the NAT64 prefix is valid
for.
prefixes:
(list of hash configuring addresses)
prefix: cidr6-prefix/len
(defaults to no prefix) This configures a prefix to be announced in router
advertisement.
on-link: boolean
(defaults to true) This configures if all addresses in this prefix are
considered "on link".
autonomous: boolean
(defaults to true) This configures if hosts should autonomously configure
one or more addresses from this prefix.
valid: duration
(defaults to 30 days) This configures how long this prefix is considered
valid and usable.
preferred: duration
(defaults to 7 days) The duration that addresses generated from the prefix
via stateless address autoconfiguration remain preferred, and should be used
for new connections.
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.
dns-routes: list-of-dns-routes
(defaults to the empty list) This is a list of DNS routes.
domain-suffixes: list-of-domain-suffixes
(defaults to the empty list) This is the list of domain suffixes that this
route should apply to. This will match this domain, and all sub-domains.
For example "example.com" matches "foo.example.com" and "example.com" but
not "example.net". The longest suffix match wins. Use the empty string ""
to use this as a default match.
type: forward|forge-nxdomain
(defaults to forward) This configures what to do with domain names that end
in this suffix.
forward
This is used to forward queries that desire recursion to another set
of nameservers.
forge-nxdomain
This will forge a NXDOMAIN reply for this, and all subdomains.
dns-servers: list-of-socket-addresses
(defaults to the empty list) Only used by type "forward". This specifies
the nameservers that the queries should be forwarded to.
ACLs (Access Control Lists)
To change which clients can do what, erbium has a customisable ACL system. ACLs are
defined under the heading "acls:" at the top level, and are an ordered list of rules of
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.
match-subnets: array-of-subnets
If specified, this requires that the access granted by this ACL applies only to
clients that have a source address that matches one of subnets provided. If not
specified, then the source address is not matched.
match-unix: boolean
If specified, this 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 not specified, 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.
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.
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.
If you 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
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.
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
BUGS
erbium is currently under active development, and many important features and protocols
are not yet complete, or even implemented yet.
SEE ALSO
erbium.conf(5), erbium-dns(8), erbium-dhcp(8), erbium-conftest(8)