Debian Codegraph @

debian/patches/test-data

raw
1 commit adfc309ecfc5dba21968f487a6c389fd94987060
2 Author: Jelmer Vernooij <[email protected]>
3 Date: Sun May 21 18:46:53 2023 +0100
4
5 Move files used in tests to crates/erbium-core
6
7 Index: erbium-core/erbium.conf.example
8 ===================================================================
9 --- /dev/null
10 +++ erbium-core/erbium.conf.example
11 @@ -0,0 +1,133 @@
12 +## Copyright 2021 Perry Lorier
13 +##
14 +## Licensed under the Apache License, Version 2.0 (the "License");
15 +## you may not use this file except in compliance with the License.
16 +## You may obtain a copy of the License at
17 +##
18 +## http://www.apache.org/licenses/LICENSE-2.0
19 +##
20 +## Unless required by applicable law or agreed to in writing, software
21 +## distributed under the License is distributed on an "AS IS" BASIS,
22 +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
23 +## See the License for the specific language governing permissions and
24 +## limitations under the License.
25 +##
26 +## SPDX-License-Identifier: Apache-2.0
27 +##
28 +##
29 +## Example configuration for erbium
30 +##
31 +## See erbium.conf(5) for more details.
32 +
33 +### Minimal required to get running.
34 +
35 +## The addresses you want to hand out.
36 +## This becomes the default addresses for Router Advertisements (for v6) and DHCP (for v4).
37 +## Addresses will be assigned on interfaces that have an address that is included within the range.
38 +addresses: [192.0.2.0/24, 2001:db8::/64]
39 +
40 +## DNS routing for where to relay DNS queries.
41 +dns-routes:
42 + # An empty domain suffix matches all.
43 + - domain-suffixes: [""]
44 + # Domains with this suffix should be forwarded
45 + type: forward
46 + # Forward to Google Public DNS. Change this to relay elsewhere.
47 + # Currently only one address is supported here, despite it being a list.
48 + dns-servers: [8.8.8.8]
49 + # Other routes are possible, the most specific suffix is used.
50 + - domain-suffixes: ["invalid"]
51 + # forge-nxdomain forges a "does not exist" for this and all subdomains.
52 + type: forge-nxdomain
53 +
54 +### DNS search path
55 +## This is included in DHCP (for v4) and Router Advertisments DNSSL (for v6) by default.
56 +## This defaults to the empty list.
57 +# dns-search: [example.com, example.org]
58 +
59 +### DNS servers
60 +## This is the DNS servers included in DHCP (for v4) and Router Advertisements RDNSS (for v6) by default.
61 +## $self4 and $self6 are the v4 and v6 receiving addresses respectively.
62 +## This defaults to [$self4, $self6]
63 +# dns-servers: [$self4, $self6]
64 +
65 +### Listener addresses
66 +# api-listeners: ["/var/lib/erbium/control", "@erbium", "[::]:9968"]
67 +# dns-listeners: ["[::]:53"]
68 +## This lets you configure the default bind style. Set this to "bind-interfaces-addresses" if you're having
69 +## problems with address already in use.
70 +# default-listen-style: bind-unspecified
71 +
72 +### ACLs
73 +## ACLs are a list of match rules, and permissions to apply if the match rule
74 +## succeeds. First match wins. If nothing matches, no permissions are granted.
75 +## See erbium.conf(5) for descriptions of the permissions. If any ACLs are
76 +## specified, the defaults are overridden, so remember to include the other
77 +## entries if you want to change just one.
78 +#
79 +# acls:
80 +# # Allow addresses we hand out to use our services (dns, http api)
81 +# - match-subnets: [the-contents-of-the-top-level-addresses-field]
82 +# apply-access: ["dns-recursion", "http-ro"]
83 +# # Allow localhost/ip6-localhost to use our services
84 +# - match-subnets: [127.0.0.0/8, ::1/128]
85 +# apply-access: ["dns-recursion", "http-ro"]
86 +# # Allow readonly access to the API server over the unix domain socket.
87 +# - match-unix: true
88 +# apply-access: ["http-ro"]
89 +
90 +### Router Advertisements
91 +## This lets you override the defaults for router advertisements.
92 +## You can use "null" to unset a default.
93 +# router-advertisements:
94 +# # This is a list of interface names
95 +# eth0:
96 +# hop-limit: 64 # The hop limit to use on this interface
97 +# managed: false # Should the client get an address from DHCPv6
98 +# other: false # Should the client get other configuration from DHCPv6
99 +# lifetime: 1h # How long this router should be considered a viable default route
100 +# reachable: 5m # How long a neighbour is considered reachable after comfirmation.
101 +# mtu: 1480 # The Maximum Transfer Unit for this interface.
102 +# dns-servers:
103 +# addresses: [2001:4860:4860::8888]
104 +# lifetime: 1h
105 +# dns-search:
106 +# domains: [custom.example.com]
107 +# lifetime: 1h
108 +# pref64:
109 +# prefix: 64:ff9b::/96
110 +# lifetime: 10m
111 +# prefixes:
112 +# - prefix: 2001:db8:0:1::/64
113 +# on-link: true # Can other hosts with this prefix be talked to
114 +# # directly, or should they go through the default gateway
115 +# autonomous: true # Should hosts allocate themselves an address from this prefix.
116 +# valid: 30d # How long this prefix is valid for.
117 +# preferred: 7d # How long this prefix should be used as a preferred prefix.
118 +
119 +### DHCP policy
120 +## This lets you override and customise the DHCP configuration
121 +## First match wins.
122 +# dhcp-policies:
123 +# - apply-ntp-servers: [192.0.2.123]
124 +# policies:
125 +# - match-subnet: 198.51.100.0/24
126 +# apply-range:
127 +# start: 198.51.100.100
128 +# end: 198.51.100.199
129 +# apply-routes:
130 +# - prefix: 203.0.113.0/24
131 +# next-hop: $self4
132 +# policies:
133 +# # This is an example of how to provide configuration per host, including static IPs
134 +# - { match-hardware-address: 00:00:5E:00:53:01, apply-address: 198.51.100.110 }
135 +# # This doesn't have a match, so won't apply to anything, but will reserve the address.
136 +# # This is useful to reserve addresses for hosts that have static IP configuration.
137 +# - { apply-address: 198.51.100.120 }
138 +#
139 +# # This has no match block, so noone will be allocated this by default
140 +# - apply-subnet: 203.0.113.0/24
141 +# policies:
142 +# # This policy has a match, but no addresses, so it will allocate an address out of the parent.
143 +# - { match-hardware-address: 00:00:5E:00:53:F0 }
144 +
145 Index: erbium-core/man/erbium.conf.5
146 ===================================================================
147 --- /dev/null
148 +++ erbium-core/man/erbium.conf.5
149 @@ -0,0 +1,538 @@
150 +.\" Copyright 2023 Perry Lorier
151 +.\"
152 +.\" Licensed under the Apache License, Version 2.0 (the "License");
153 +.\" you may not use this file except in compliance with the License.
154 +.\" You may obtain a copy of the License at
155 +.\"
156 +.\" http://www.apache.org/licenses/LICENSE-2.0
157 +.\"
158 +.\" Unless required by applicable law or agreed to in writing, software
159 +.\" distributed under the License is distributed on an "AS IS" BASIS,
160 +.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
161 +.\" See the License for the specific language governing permissions and
162 +.\" limitations under the License.
163 +.\"
164 +.\" SPDX-License-Identifier: Apache-2.0
165 +.TH erbium.conf 5 2022-05-30 Linux "File formats and configuration files"
166 +.SH NAME
167 +erbium.conf \- Configuration for erbium
168 +.SH DESCRIPTION
169 +erbium is a daemon that provides network services for small/home networks.
170 +erbium.conf provides configuration for \fBerbium\fP\fR(8)\fP.
171 +.PP
172 +erbium.conf is in YAML format, and involves multiple sections.
173 +
174 +.SS Executable Configuration
175 +If erbium.conf is not executable, then erbium will read the file directly for
176 +configuration.
177 +
178 +If erbium.conf is executable, then erbium will execute the configuration file,
179 +and expect a valid erbium configuration on standard output. This allows for
180 +generating erbium configurations at runtime via whatever custom tooling is
181 +appropriate for your environment (eg shellscript, python script, ELF binary
182 +etc). This tooling could provide templating or whatever functionality is
183 +needed for the local environment.
184 +
185 +.SS Configuration wide options
186 +IP addresses can be specified as the string $self4 or $self6 which will use the
187 +local IPv4 or IPv6 address of the interface the request arrived on
188 +respectively.
189 +
190 +.SS Top level Configuration
191 +The top level configuration provides defaults for the other protocol
192 +implementations in erbium.
193 +For most networks, only the top level configuration is necessary, but for more
194 +advanced users per protocol configuration can be used to override these
195 +defaults (or disable them by setting their value to \fBnull\fP.
196 +Top level configuration is not required, you can instead configure each
197 +protocol individually, it is provided as a convenience measure.
198 +
199 +.IP "\fBaddresses:\fP \fIlist-of-subnets\fP"
200 +(defaults to no value)
201 +This provides both the list of interfaces to configure for router
202 +advertisements and DHCP, and the IP ranges to give out.
203 +The subnets must match exactly the subnets on the inteface (including the prefix length),
204 +and the network address.
205 +For DHCP this will give out addresses on this interface except for the network
206 +address, broadcast address, and the local interface IPv4 address.
207 +DHCP will also exclude any address given in a normal policy, in the same way
208 +that sub policies work below.
209 +For router advertisements, this will configure the IPv6 prefix for SLAAC
210 +addressing.
211 +
212 +.IP "\fBdns-servers:\fP \fIlist-of-ip-addresses\fP"
213 +(defaults to no value)
214 +This sets the default dns servers to be handed out by DHCP and Router
215 +Advertisements.
216 +DHCP is limited by the design of the protocol to only support
217 +handing out IPv4 addresses.
218 +Similarly router advertisements are limited by design to only support handing
219 +out IPv6 addresses.
220 +
221 +.IP "\fBdns-search:\fP \fIlist-of-domain-names\fP"
222 +(defaults to no value)
223 +This sets the default DNS search path.
224 +This is supported by both the DHCP and router advertisements protocols.
225 +
226 +.IP "\fBcaptive\-portal:\fP \fIurl\fP"
227 +(defaults to no value)
228 +This sets the URL to the captive portal, as specified in RFC8910.
229 +This is used by both DHCP and router advertisements.
230 +
231 +.IP "\fBdefault-listen-style\fP \fBbind-unspecified\fP|\fBbind-addresses-interfaces\fP"
232 +(defaults to bind-unspecified)
233 +This sets the default bind style for DNS and DHCP requests.
234 +.RS
235 +.IP \fBbind-unspecified\fP
236 +This binds to the unspecified address (0.0.0.0 or [::]).
237 +This means that interfaces do not need to be fully operational when erbium
238 +starts.
239 +Erbium will discard packets that have no matching configuration.
240 +This is the default.
241 +.IP \fBbind-addresses-interfaces\fP
242 +This binds to addresses that are configured on interfaces that are within the prefixes listed in the "addresses" field.
243 +This allows erbium to share a machine with systemd-resolved or other DNS/DHCP servers that are used for other
244 +interfaces.
245 +This however has the downside that the interfaces must be up and fully configured before erbium can start, which can
246 +cause race conditions with dynamic addressing systems and duplicate address detection.
247 +.RE
248 +.IP "\fBapi\-listeners:\fP \fIlist\-of\-socket\-addresses\fP"
249 +(defaults to [/var/lib/erbium/control])
250 +This sets the addresses that the API HTTP server will listen on.
251 +By default this is only a unix domain socket, which can be easily secured.
252 +IPv4 (ip:port) and IPv6 ([ip]:port) are also supported.
253 +You may wish to use ["/var/lib/erbium/control", "[::1]:9968"] to allow scraping
254 +prometheus metrics from ip6-localhost.
255 +
256 +.IP "\fBacls:\fP \fIarray-of-acls\fP"
257 +(default see the ACLs section below)
258 +This introduces the array of ACLs.
259 +
260 +.SS DHCP Configuration
261 +
262 +DHCP configuration for erbium is under a \fBdhcp-policies\fP heading.
263 +\fBdhcp-policies\fP is a a list of policies to apply to incoming
264 +DHCP packets.
265 +Each policy is considered in turn, with the first policy that successfully
266 +matches being the policy that is applied.
267 +.PP
268 +A policy section contains 0 or more \fBmatch\-\fP\fIcondition\fP fields, and 0
269 +or more \fBapply\-\fP\fIoption\fP fields.
270 +.SS DHCP Matches
271 +All match conditions in a policy must match (the conditions are AND'd together).
272 +A policy section that contains no matches only matches if one of it's
273 +subpolicies matches. (See below for information about subpolicies).
274 +.\"
275 +.IP "\fBmatch\-subnet:\fP \fIcidr4\-prefix/len\fP"
276 +\fBmatch\-subnet\fP is how the DHCP standards expect you to match incoming
277 +packets. When a DHCP packet from a client is received, then the IP address of
278 +the interface where it is received is noted, and can be matched with
279 +\fBmatch-subnet\fP. This works even for packets that are relayed, in which
280 +case the IP address of the relay is used.
281 +
282 +An example is: \fBmatch-subnet: 192.168.0.0/24\fP.
283 +.IP "\fBmatch\-hardware\-address:\fP \fIhardware\-address\fP"
284 +Clients send a "client hardware address" (chaddr) in DHCP request packets.
285 +This allows matching on that address.
286 +This is most useful when matching on individual hosts to assign them a static address.
287 +.\"
288 +.IP "\fBmatch\-\fP\fIdhcpoption\fP\fB:\fP \fIoption\-value\fP"
289 +For every DHCP option supported by erbium, you can match on it by prefixing
290 +its name with \fBmatch-\fP. Note that most DHCP clients do not send many
291 +options, so in practise there isn't much you can match on here. Some obvious
292 +and useful options for matching on are \fBmatch-host-name\fP and
293 +\fBmatch-class-id\fP.
294 +
295 +erbium will log options received from each client to make finding useful
296 +options to match on easier.
297 +If you specify \fBnull\fP as the value to match on, then it will only match
298 +if the client \fIdoes not\fP provide that option.
299 +.SS Applying DHCP Options
300 +Each policy contains a list of option values to apply to a client (assuming the
301 +client requested the option). For nested subpolicies (see below), options
302 +are applied for the outer policies first, then the subpolicies can choose to
303 +override those values.
304 +.IP "\fBapply\-address:\fP \fIip4addr\fP"
305 +This adds one IP address to the pool for the policy.
306 +This can be provided multiple times to add multiple individual IP addresses to
307 +a pool, and then the client will be assigned one.
308 +.IP "\fBapply\-subnet:\fP \fIcidr4\-prefix/len\fP"
309 +This adds an entire subnet worth of addresses to the address pool for the
310 +policy.
311 +This can be provided multiple times to add multiple subnets.
312 +The first and last addresses of the subnet are not applied, as these are the
313 +network and broadcast addresses respectively.
314 +.IP "\fBapply\-range: { start:\fP \fIstart-ip4\fP\fB, end:\fP \fIlast-ip4\fP\fB}\fR"
315 +This applies a range of IP addresses, from \fIstart-ip4\fP to \fIlast-ip4\fP inclusive.
316 +This is a YAML hash type, with the keys "start" and "end".
317 +The text above shows this using YAML's single line syntax, but it can be in any
318 +of YAML's formats for a hash.
319 +.IP "\fBapply\-\fP\fIoption\fP\fB:\fP \fIvalue\fP"
320 +This lets you apply an arbitrary value for a DHCP option.
321 +The syntax for the values varies based on the option.
322 +(See a list of options and their types below).
323 +You can also set an option to \fBnull\fP to unset it (if, for example, the
324 +value was inherited in a sub policy, or to override erbium's internal defaults
325 +for a value).
326 +.\"
327 +.SS Subpolicies
328 +As well as having match and apply rules for each policy, a policy can also
329 +contain subpolicies.
330 +A subpolicy is only attempted to be matched if all the enclosing policies
331 +matched.
332 +Sub\-policies have their own DHCP IP pools.
333 +If you add an IP address to a policy then it will be excluded from all parent
334 +pools.
335 +Thus you can have an outer policy that contains a "apply\-subnet:
336 +192.0.2.0/24", then have a subpolicy for
337 +that matches an individual host that contains only "apply\-address: 192.0.2.53",
338 +and that address will only be given to the individual host.
339 +(See the example below).
340 +A policy that does not specify an new addresses will continue to use the
341 +addresses for it's parent pool.
342 +(Again, see example below).
343 +Sub\-policies are introduced by adding a \fBpolicies:\fP section to a policy.
344 +.\"
345 +.SH DHCP Options
346 +.TS
347 +allbox tab(,);
348 +nllll.
349 +Num,Option name,Type,Ref,Description
350 +1,netmask,ip4,RFC2131,The netmask for this network.
351 +2,time-offset,seconds,RFC2131,The current timezone offset in seconds.
352 +3,routers,ip4 list,RFC2131,List of default gateways.
353 +4,time-servers,ip4 list,RFC2131,List of time servers.
354 +5,name-servers,ip4 list,RFC2131,List of IEN-116 name servers.
355 +6,dns-servers,ip4 list,RFC2131,List of DNS servers for recursive resolution.
356 +7,log-servers,ip4 list,RFC2131,List of MIT-LCS UDP log servers (obsolete).
357 +8,quote-servers,ip4 list,RFC2131,List of quote of the day servers (RFC865).
358 +9,lpr-servers,ip4 list,RFC2131,List of LPR print servers.
359 +12,hostname,string,RFC2131,Hostname of the client.
360 +15,domain-name,string,RFC2131,Domain name of the client.
361 +19,forward,boolean,RFC2131,If the client should enable IP forwarding.
362 +22,max-reassembly,seconds,RFC2131,How long to wait for IP fragment reassembly.
363 +23,default-ttl,integer,RFC2131,The default TTL.
364 +24,mtu-timeout,integer,RFC2131,How long to cache MTU path discovery for.
365 +26,mtu,integer,RFC2131,The MTU the client should use.
366 +27,mtu-subnet,integer,RFC2131,The MTU for the local subnet.
367 +28,broadcast,ip4,RFC2131,The broadcast address of the local subnet.
368 +35,arp-timeout,integer,RFC2131,ARP cache timeout.
369 +42,ntp-servers,ip4 list,RFC2131,A list of NTP servers to use.
370 +69,smtp-servers,ip4 list,RFC2131,A list of SMTP servers to use.
371 +70,pop3-servers,ip4 list,RFC2131,A list of POP3 servers to use.
372 +71,nntp-servers,ip4 list,RFC2131,A list of NNTP servers to use.
373 +77,user-class,string,RFC2131,A user configurable class.
374 +80,fqdn,string,RFC2131,The fully qualified domain name of the client.
375 +100,tz-rule,string,RFC4833,The POSIX complaint timezone rule specification.
376 +101,tz-name,string,RFC4833,A tzdata timezone name.
377 +114,captive-portal,string,RFC8910,The URL for a captive portal.
378 +121,routes,routes,RFC3442,A list of static routes.
379 +.TE
380 +.PP
381 +(Note more options than this exist, but I ran out of time writing these docs.
382 +Patches updating and extending this list based on src/dhcp/dhcppkt.rs
383 +appreciated)
384 +.PP
385 +The different types are expected to be:
386 +.IP \fIstring\fP
387 +A simple string in any of YAMLs string formats.
388 +.IP \fIinteger\fP
389 +An integer, in any of YAMLs integer formats.
390 +.IP \fIip4\fP
391 +An IPv4 address. eg: 192.0.2.0
392 +This can also be the keyword $self4.
393 +.IP "\fIip4 list\fP"
394 +A YAML list of IPv4 addresses.
395 +This list can also contain the keyword $self4.
396 +eg: [$self4, 192.0.2.1, 192.0.2.2].
397 +.IP \fIseconds\fP
398 +This can be an integer number of seconds (in any of YAMLs integer formats), or it can be a string with numbers
399 +suffixed with "s" (for seconds), "m" (for minutes), "h" (for hours), or "d" (for days).
400 +Multiple units can be combined, and if the unit is left off it is assumed to be
401 +seconds.
402 +For example "4h20m5" is considered to be 4 hours, 20 minutes, and 5 seconds
403 +(which is the same as the number 15605).
404 +.IP "\fIhardware address\fP"
405 +This is specified as a colon (:) separated list of hexadecimal octets. For example: 00:00:5E:00:53:00.
406 +.IP "\fIroutes\fP"
407 +Routes are specified with a prefix and nexthop. eg: { prefix: 192.0.2.0/24, next-hop: 192.0.2.254 }
408 +.\"
409 +.SH Router Advertisement Configuration
410 +Router Advertisements can be configured in erbium under a \fBrouter-advertisements\fP section.
411 +This should be a yaml hash of interfaces, keyed by the interface name, and the
412 +value being a a yaml hash with some keywords configuring the announcements for
413 +an interface.
414 +.IP "\fBhop-limit:\fP \fIinteger\fP"
415 +(default 0)
416 +Set the hop limit for hosts on this network.
417 +If set to 0 or null, then it will not set that information.
418 +.IP "\fBmanaged:\fP \fIboolean\fP"
419 +(default false)
420 +Configures the "Managed address configuration" bit, configuring
421 +if hosts on this network should use DHCPv6 to get an address.
422 +(Hosts ignore this if the "Other" bit is set)
423 +.IP "\fBother:\fP \fIboolean\fP"
424 +(default false)
425 +Configures the "Other configuration" bit.
426 +This tells the hosts on this network that there is more configuration available
427 +via DHCPv6.
428 +(Hosts ignore this if the "managed" bit is set)
429 +.IP "\fBlifetime:\fP \fIduration\fP"
430 +(default 0s if there is no default route or if the default route points back
431 +out the same interface, 1h otherwise)
432 +This configures the "Router Lifetime".
433 +This configures how long this host should be considered a default router.
434 +Setting this to 0 means that the erbium host is not a default router.
435 +.IP "\fBreachable:\fP \fIduration\fP"
436 +(default 0ms)
437 +This configures the "Reachable Time" for hosts on the network.
438 +This is how long a host on the local network should consider a host reachable
439 +after having confirmation of reachability.
440 +Setting this to 0 means that this is not specified by this router.
441 +.IP "\fBretransmit:\fP \fIduration\fP"
442 +(default 0ms)
443 +This configures the "Retrans Timer" for hosts on the network.
444 +The time between retransmitted Neighbor Solicitation messages.
445 +Setting this to 0 means that this is not specified by this router.
446 +.IP "\fBmtu:\fP \fImtu\fP"
447 +(defaults to the MTU of the interface)
448 +This configures the MTU of the link.
449 +This can be set to \fBnull\fP so that this router will not specify this.
450 +.IP "\fBcaptive-portal:\fP \fIurl\fP"
451 +(defaults to \fBcaptive-portal\fP in the top level configuration)
452 +This configures a URL to the captive portal (RFC7710).
453 +This can be set to \fBnull\fP so that this router will not specify this.
454 +.IP "\fBdns-servers:\fP"
455 +(defaults based on \fBdns-servers\fP in the top level configuration)
456 +hash configuring the recusive DNS servers,
457 +.RS
458 +.IP "\fBaddresses:\fP \fIlist-of-ipv6-addresses\fP"
459 +(defaults to the IPv6 addresses listed in the \fBdns-servers\fP top level
460 +configuration)
461 +This sets the IPv6 addresses for the router addresses.
462 +It is possible to use $self6 here to refer to the local interface address.
463 +.IP "\fBlifetime:\fP \fIduration\fP"
464 +(defaults to the setting of the interface lifetime)
465 +This sets the amount of time that the recursive DNS servers addresses are
466 +valid.
467 +.RE
468 +.\"
469 +.IP "\fBdns-search:\fP"
470 +(hash configuring the DNS search list)
471 +.RS
472 +.IP "\fBdomains:\fP \fIlist-of-domain-suffixes\fP"
473 +(defaults to the domains listed in the top level \fBdns-search\fI
474 +configuration)
475 +This sets the ordered list of domain suffixes that should be tried.
476 +.IP "\fBlifetime:\fP \fIduration\fP"
477 +(defaults to the setting of the interface lifetime)
478 +This sets the amount of time that the DNS search list domain suffixes are
479 +valid.
480 +.RE
481 +.\"
482 +.IP "\fBpref64:\fP"
483 +(a hash configuring the NAT64 prefix range used by this network)
484 +.RS
485 +.IP "\fBprefix:\fP \fIip6-prefix\fP"
486 +(defaults to none)
487 +This configures the NAT64 prefix used by this network.
488 +.IP "\fBlifetime:\fP \fIduration\fP"
489 +(defaults to 10 minutes)
490 +This configures how long the NAT64 prefix is valid for.
491 +.RE
492 +.\"
493 +.IP "\fBprefixes:\fP"
494 +(list of hash configuring addresses)
495 +.RS
496 +.IP "\fBprefix:\fP \fIcidr6-prefix/len\fP"
497 +(defaults to no prefix)
498 +This configures a prefix to be announced in router advertisement.
499 +.IP "\fBon-link:\fP \fIboolean\fP"
500 +(defaults to true)
501 +This configures if all addresses in this prefix are considered "on link".
502 +.IP "\fBautonomous:\fP \fIboolean\fP"
503 +(defaults to true)
504 +This configures if hosts should autonomously configure one or more addresses
505 +from this prefix.
506 +.IP "\fBvalid:\fP \fIduration\fP"
507 +(defaults to 30 days)
508 +This configures how long this prefix is considered valid and usable.
509 +.IP "\fBpreferred:\fP \fIduration\fP"
510 +(defaults to 7 days)
511 +The duration that addresses generated from the prefix via stateless address
512 +autoconfiguration remain preferred, and should be used for new connections.
513 +.RE
514 +.SH DNS Configuration
515 +.IP "\fBdns\-listeners:\fP \fIlist-of-socket-addresses\fP"
516 +(defaults to [::]:53 if default-listen-style is bind-unspecified, otherwise the interface addresses listed in addresses)
517 +This configures which addresses the DNS server will listen on.
518 +.IP "\fBdns\-routes:\fP \fIlist-of-dns-routes\fP"
519 +(defaults to the empty list)
520 +This is a list of DNS routes.
521 +.RS
522 +.IP "\fBdomain\-suffixes:\fP \fIlist-of-domain-suffixes\fP"
523 +(defaults to the empty list)
524 +This is the list of domain suffixes that this route should apply to.
525 +This will match this domain, and all sub\-domains.
526 +For example "example.com" matches "foo.example.com" and "example.com" but not "example.net".
527 +The longest suffix match wins.
528 +Use the empty string "" to use this as a default match.
529 +.IP "\fBtype:\fP \fIforward\fP|\fIforge-nxdomain\fP"
530 +(defaults to forward)
531 +This configures what to do with domain names that end in this suffix.
532 +.RS
533 +.IP forward
534 +This is used to forward queries that desire recursion to another set of nameservers.
535 +.IP forge-nxdomain
536 +This will forge a NXDOMAIN reply for this, and all subdomains.
537 +.RE
538 +.IP "\fBdns-servers:\fP \fIlist-of-socket-addresses\fP"
539 +(defaults to the empty list)
540 +Only used by type "forward".
541 +This specifies the nameservers that the queries should be forwarded to.
542 +.RE
543 +.SH ACLs (Access Control Lists)
544 +To change which clients can do what, erbium has a customisable ACL system.
545 +ACLs are defined under the heading "acls:" at the top level, and are an ordered list of rules of which clients this
546 +particular ACL applies to, and what access this client has.
547 +ACLs are applied in a strict first-match basis.
548 +Any client that does not match any ACL will not be granted any access.
549 +
550 +.IP "\fBmatch-subnets:\fP \fIarray-of-subnets\fP"
551 +If specified, this requires that the access granted by this ACL applies only to clients that have a source
552 +address that matches one of subnets provided.
553 +If not specified, then the source address is not matched.
554 +.IP "\fBmatch-unix:\fP \fIboolean\fP"
555 +If specified, this requires that the access granted by this ACL applies only to clients over a unix domain socket (if
556 +true), otherwise must not be a unix domain socket (if false).
557 +If not specified, then if the client arrives over a unix domain socket is not matched.
558 +.IP "\fBapply-access:\fP \fIarray-of-access-strings\fP"
559 +(default: empty list)
560 +This specifies which accesses the matched clients are permitted.
561 +.RS
562 +.IP "\fBdhcp-client\fP"
563 +Permissions required for DHCP clients with default settings.
564 +This is used to support future versions that may add additional protocols for DHCP clients.
565 +Currently an alias for "dns-recursion".
566 +.IP "\fBdns-recursion\fP"
567 +Allows DNS recursion.
568 +.IP "\fBhttp\fP"
569 +Allows access to the non-API parts of the HTTP server.
570 +.IP "\fBhttp-metrics\fP"
571 +Allows access to the /metrics endpoint of the HTTP server.
572 +.IP "\fBhttp-leases\fP"
573 +Allows access to the list of active leases over HTTP.
574 +.IP "\fBhttp-ro\fP"
575 +An alias for "http-metrics" and "http-leases".
576 +This is used to support future versions that may add additional read only HTTP end points that users can use
577 +to collect information.
578 +By using "http-ro" instead of "http-metrics" and "http-leases" independently, as new accesses are added then
579 +this configuration will include them.
580 +.RE
581 +
582 +If you specify any ACLs then all the defaults are overridden and need to be specified.
583 +The defaults for ACLs are as follows:
584 +.EX
585 +acls:
586 + # Allow DHCP clients to perform DNS queries, and talk to the HTTP API server (if enabled)
587 + - match-subnets: [\fIthe-contents-of-the-top-level-addresses-field\fP]
588 + apply-access: ["dns-recursion", "http-ro"]
589 + # Allow localhost to perform DNS queries, any talk to the HTTP API server (if enabled)
590 + - match-subnets: [127.0.0.0/8, ::1/128]
591 + apply-access: ["dns-recursion", "http-ro"]
592 + # Allow all users via Unix domain sockets to talk to the HTTP API server (if enabled)
593 + - match-unix: true
594 + apply-access: ["http-ro"]
595 +.EE
596 +
597 +.SH EXAMPLE
598 +.EX
599 +dns-servers: [$self4, $self6, 8.8.8.8, 2001:4860:4860::8888]
600 +dns-search: [example.com, example.org]
601 +addresses: [192.0.2.0/24, 2001:db8::/64]
602 +dhcp-policies:
603 + - apply-ntp-servers: [192.0.2.123]
604 +
605 + policies:
606 + - match-subnet: 198.51.100.0/24
607 + apply-range:
608 + start: 198.51.100.100
609 + end: 198.51.100.199
610 + apply-routes:
611 + - prefix: 203.0.113.0/24
612 + next-hop: $self4
613 + policies:
614 + - { match-hardware-address: 00:00:5E:00:53:01, apply-address: 198.51.100.110, apply-dns-servers: null }
615 + - { match-hardware-address: 00:00:5E:00:53:02, apply-address: 198.51.100.111, apply-dns-servers: [8.8.8.8] }
616 +
617 + - apply-subnet: 203.0.113.0/24
618 + policies:
619 + - { match-hardware-address: 00:00:5E:00:53:F0 }
620 + - { match-hardware-address: 00:00:5E:00:53:F1 }
621 +
622 +router-advertisements:
623 + eth1:
624 + lifetime: 30m
625 + prefixes:
626 + - prefix: 2001:db8:0:1::/64
627 + dns-servers:
628 + addresses: [2001:db8::53]
629 +
630 +dns-routes:
631 + - domain-suffixes: [""]
632 + type: forward
633 + dns-servers: [2001:4860:4860::8888]
634 +.EE
635 +.PP
636 +Imagine a router with 3 interfaces.
637 +.IP eth0
638 +This has the addresses 192.0.2.254/24, and 2001:db8::1/64.
639 +.IP eth1
640 +This has the addresses 198.51.100.254/24, and 2001:db8:0:1::1/64.
641 +.IP eth2
642 +This has the address 203.0.113.254/24.
643 +.PP
644 +A client on eth0 will be assigned an IP out of the range 192.0.2.1 to 192.0.2.253
645 +(192.0.2.0 being the network address, 192.0.2.254 being in use by the local
646 +interface, and 192.0.2.255 being the broadcast address, all are excluded).
647 +.PP
648 +A client on eth1 with the mac address 00:00:5E:00:53:01 on eth1 will
649 +get given the IP address 198.51.100.110 (and no other).
650 +It will not be given any DNS servers (overriding the top level configuration),
651 +.PP
652 +A client on eth1 with the mac address 00:00:5E:00:53:02 on will get given the
653 +IP address 198.51.100.111.
654 +It will get assigned only 8.8.8.8 as the DNS server address.
655 +.PP
656 +Other clients on eth1 will get assigned an IPv4 address between 198.51.100.100
657 +and 198.51.100.200, but not 198.51.100.110 or 198.51.100.111, as these are
658 +reserved in a subpolicy.
659 +Other clients will get 192.0.2.254 and 8.8.8.8 as IPv4 DNS servers (Inherited
660 +from the top level configuration, IPv6 addresses filtered out).
661 +.PP
662 +On eth2, only the two hosts 00:00:5E:00:53:F0 and 00:00:5E:00:53:F1 will be
663 +allocated addresses between 203.0.113.1 and 203.0.113.254 (as the default
664 +allocated addresses is calculated from the match-address directive).
665 +.PP
666 +All IPv4 clients on all interfaces will get assigned the NTP server
667 +192.0.2.123.
668 +.PP
669 +Despite there being no explicit router configuration section for eth0, clients
670 +with IPv6 on eth0 will allocate themselves an address in 2001:db8::/64, due to
671 +addresses matching this interface being configured at the top level.
672 +They will have 2001:db8::1 and 2001:4860:4860::8888 as their DNS servers (again
673 +inherited from the top level), and a dns search path of example.com and example.org.
674 +.PP
675 +Clients with IPv6 on eth1 will allocate themselves an address in 2001:db8:0:1:/64, and
676 +will use the DNS server 2001:db8::53.
677 +.SH FILES
678 +erbium.conf
679 +.SH BUGS
680 +erbium is currently under active development, and many important features and protocols are not yet complete, or even
681 +implemented yet.
682 +.SH SEE ALSO
683 +.BR erbium.conf (5),
684 +.BR erbium-dns (8),
685 +.BR erbium-dhcp (8),
686 +.BR erbium-conftest (8)
687 +
688 Index: erbium-core/src/test_man_configs.rs
689 ===================================================================
690 --- erbium-core.orig/src/test_man_configs.rs
691 +++ erbium-core/src/test_man_configs.rs
692 @@ -5,7 +5,7 @@ use tokio;
693 * run the config parser over them to make sure they're valid.
694 */
695 async fn man_page_example_configs() {
696 - let contents = include_str!("../../../man/erbium.conf.5");
697 + let contents = include_str!("../man/erbium.conf.5");
698 let mut example: String = Default::default();
699 let mut in_example = false;
700 let mut examples = 0;
701 @@ -33,7 +33,7 @@ async fn man_page_example_configs() {
702
703 #[tokio::test]
704 async fn validate_example_config() {
705 - let mut contents = include_str!("../../../erbium.conf.example").to_string();
706 + let mut contents = include_str!("../erbium.conf.example").to_string();
707 // If the line is indented, replace the "#" with a " ", keeping the indentation.
708 contents = contents.replace("\n# ", "\n ");
709 // If the line is not indented, then strip the leading "# "