erbium.conf(5) File formats and configuration files erbium.conf(5)

erbium.conf - Configuration for erbium

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.

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.

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.

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.

(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.

(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.

(defaults to no value) This sets the default DNS search path. This is supported by both the DHCP and router advertisements protocols.

(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.

(defaults to bind-unspecified) This sets the default bind style for DNS and DHCP requests.
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.
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.
(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.

(default see the ACLs section below) This introduces the array of ACLs.

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.

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 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.

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.
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.

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.

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.
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.
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.
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).

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.

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:

A simple string in any of YAMLs string formats.
An integer, in any of YAMLs integer formats.
An IPv4 address. eg: 192.0.2.0 This can also be the keyword $self4.
A YAML list of IPv4 addresses. This list can also contain the keyword $self4. eg: [$self4, 192.0.2.1, 192.0.2.2].
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).
This is specified as a colon (:) separated list of hexadecimal octets. For example: 00:00:5E:00:53:00.
Routes are specified with a prefix and nexthop. eg: { prefix: 192.0.2.0/24, next-hop: 192.0.2.254 }

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.

(default 0) Set the hop limit for hosts on this network. If set to 0 or null, then it will not set that information.
(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)
(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)
(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.
(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.
(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.
(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.
(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.
(defaults based on dns-servers in the top level configuration) hash configuring the recusive DNS servers,
(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.
(defaults to the setting of the interface lifetime) This sets the amount of time that the recursive DNS servers addresses are valid.
(hash configuring the DNS search list)
(defaults to the domains listed in the top level dns-search configuration) This sets the ordered list of domain suffixes that should be tried.
(defaults to the setting of the interface lifetime) This sets the amount of time that the DNS search list domain suffixes are valid.
(a hash configuring the NAT64 prefix range used by this network)
(defaults to none) This configures the NAT64 prefix used by this network.
(defaults to 10 minutes) This configures how long the NAT64 prefix is valid for.
(list of hash configuring addresses)
(defaults to no prefix) This configures a prefix to be announced in router advertisement.
(defaults to true) This configures if all addresses in this prefix are considered "on link".
(defaults to true) This configures if hosts should autonomously configure one or more addresses from this prefix.
(defaults to 30 days) This configures how long this prefix is considered valid and usable.
(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.

(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.
(defaults to the empty list) This is a list of DNS routes.
(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.
(defaults to forward) This configures what to do with domain names that end in this suffix.
This is used to forward queries that desire recursion to another set of nameservers.
This will forge a NXDOMAIN reply for this, and all subdomains.
(defaults to the empty list) Only used by type "forward". This specifies the nameservers that the queries should be forwarded to.

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.

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.
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.
(default: empty list) This specifies which accesses the matched clients are permitted.
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".
Allows DNS recursion.
Allows access to the non-API parts of the HTTP server.
Allows access to the /metrics endpoint of the HTTP server.
Allows access to the list of active leases over HTTP.
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"]


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.

This has the addresses 192.0.2.254/24, and 2001:db8::1/64.
This has the addresses 198.51.100.254/24, and 2001:db8:0:1::1/64.
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.

erbium.conf

erbium is currently under active development, and many important features and protocols are not yet complete, or even implemented yet.

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

2022-05-30 Linux