1dnssec-trigger(8) dnssec-trigger 0.17 dnssec-trigger(8)
2
6 dnssec-trigger, dnssec-triggerd, dnssec-trigger-panel, dnssec-trigger-
7 control, dnssec-trigger-control-setup, dnssec-trigger.conf - check DNS
8 servers for DNSSEC support and adjust to compensate.
9
11 dnssec-triggerd [-d] [-v] [-u] [-c file]
12 dnssec-trigger-control [-c file] [-s ip[@port] ] command [arguments]
14 dnssec-trigger-panel [-d] [-c file]
16
18 The dnssec-trigger programs steer unbound(8) towards DNSSEC capable DNS
19 servers. A DHCP hook installed on the system calls dnssec-trigger-con‐
20 trol that contacts the daemon dnssec-triggerd that probes the list of
21 servers. The daemon then adjusts a running unbound through
22 unbound-control(8) and notifies the user applet dnssec-trigger-panel
23 for GUI display.
24 The dnssec-trigger-panel runs after user login, displays notifications
26 and status to the user. It may popup a warning if no DNSSEC capable
27 servers are available, with options to disconnect or to connect inse‐
28 curely.
29 The dnssec-trigger-control tool is used in the background by scripts to
31 notify the daemon of new (DHCP) DNS servers. It can be used to test
32 the system by providing a (fake) list of DNS server IP addresses.
33 The dnssec-trigger-control-setup tool is used to setup the SSL keys
35 that the daemon and user panel use to communicate securely. It must be
36 run once after installation.
37
39 Thus the dnssec-triggerd daemon runs continually, and is started after
40 boot. It receives a list of IP addresses, probes them, and adjusts
41 unbound and resolv.conf. Unbound acts as the validating local
42 resolver, running on 127.0.0.1. And resolv.conf is modified to point
43 to 127.0.0.1.
44 -c cfgfile
46 Set the config file with settings for the dnssec-triggerd to
47 read instead of reading the file at the default location,
48 /etc/dnssec-trigger/dnssec-trigger.conf. The syntax is described
49 below.
50 -d Debug flag, do not fork into the background, but stay attached
52 to the console.
53 -u uninstall dns override: makes resolv.conf mutable again, or
55 other OS action.
56 -v Increase verbosity. If given multiple times, more information is
58 logged. This is in addition to the verbosity (if any) from the
59 config file.
60
62 The config file contains options. It is fairly simple, key: value.
63 You can make comments with '#' and have empty lines. The parser is
64 simple and expects one statement per line.
65 verbosity: <num>
67 Amount of logging, 1 is default. 0 is only errors, 2 is more
68 detail, 4 for debug.
69 pidfile: "<file>"
71 The filename where the pid of the dnssec-triggerd is stored.
72 Default is /run/dnssec-triggerd.pid.
73 logfile: "<file>"
75 Log to a file instead of syslog, default is to syslog.
76 use-syslog: <yes or no>
78 Log to syslog, default is yes. Set to no logs to stderr (if no
79 logfile) or the configured logfile.
80 unbound-control: "<command>"
82 The string gives the command to execute. It can be
83 "unbound-control" to search the runtime PATH, or a full path‐
84 name. With a space after the command arguments can be config‐
85 ured to the command, i.e. "/usr/local/bin/unbound-control -c
86 my.conf".
87 resolvconf: "/etc/resolv.conf"
89 The resolv.conf file to edit (on posix systems). The daemon
90 keeps the file readonly and only make it writable shortly to
91 change it itself. This is to keep other software from interfer‐
92 ing. On OSX (if compiled in) also the DNS settings are changed
93 in the network configuration machinery (visible in the network
94 settings control panel). On Windows (if compiled), it sets reg‐
95 istry settings for network configuration (may be visible in the
96 control panel tab for network devices) and does not write a
97 resolv.conf file.
98 domain: "example.com"
100 The domain to set in resolv.conf. See resolv.conf(5). Picked
101 up once during installation, and not from DHCP since it allows
102 directing traffic elsewhere.
103 search: "example.com"
105 The domain name search path to set in resolv.conf. See
106 resolv.conf(5). Picked up once during installation, and not
107 from DHCP since it allows directing traffic elsewhere.
108 noaction: <yes or no>
110 Default is no. If yes, no action is taken to change
111 unbound-control or resolv.conf. The software can be tested with
112 this, probe results are available.
113 port: <8955>
115 Port number to use for communication with dnssec-triggerd. Com‐
116 munication uses 127.0.0.1 (the loopback interface). SSL is used
117 to secure it, and the keys are stored on the disk (see below).
118 The other tools read this config file to find the port number
119 and key locations.
120 login-command: ""
122 The command that is run when the user clicks Login on the no web
123 access dialog. That is supposedly a web browser, that is aimed
124 to open some url so that the hot-spot network login can inter‐
125 cept and show its login page. The default is a detected generic
126 web browser. The "" empty string turns off this feature and no
127 command gets run.
128 login-location: "http://www.nlnetlabs.nl/projects/dnssec-trigger"
130 The url that is opened with the web browser. Used as command‐
131 line argument.
132 server-key-file: "/etc/dnssec-trigger/dnssec_trigger_server.key"
134 server-cert-file: "/etc/dnssec-trigger/dnssec_trigger_server.pem"
136 control-key-file: "/etc/dnssec-trigger/dnssec_trigger_control.key"
138 control-cert-file: "/etc/dnssec-trigger/dnssec_trigger_control.pem"
140 The files used for SSL secured communication with dnssec-trig‐
141 gerd. These files can be created with dnssec-trigger-con‐
142 trol-setup (run as root).
143 check-updates: <yes or no>
145 Check for software updates, if there are, download them and
146 present the user with a dialog that allows them to run the in‐
147 staller to upgrade the software. It checks a SHA256 checksum on
148 the download, the checksum is signed with DNSSEC (from a TXT
149 record). On windows and osx the default is yes. On other sys‐
150 tems the default is no (it'll download the source tarball if
151 enabled).
152 url: "http://example.com OK"
154 This command adds an url to probe via HTTP (port 80). The first
155 word, before the space is the url to resolve. The remainder is
156 the string that is expected as page contents (that may be pre‐
157 fixed or suffixed with whitespace). The url is resolved, a HTTP
158 1.1 query is sent. The reply must be type 2xx and contain the
159 page contents. If this is not true, dnssec-trigger knows that
160 there is a 'hot spot' of some sort interfering with traffic. If
161 you do not configure any urls, then no probes are done. If you
162 configure multiple urls then it probes a random selection of 3
163 urls, all of their IP addresses in turn, with IP4 and IP6 simul‐
164 taneously. At most 5 of the DHCP DNS servers are used to
165 resolve (in parallel). If an answer is gotten and it fails the
166 probe stop, the probing continues if there is no connection or
167 response 404.
168 tcp80: <ip>
170 Add an IP4 or IP6 address to the list of fallback open DNSSEC
171 resolvers that are used on TCP port 80. These relay traffic
172 from port 80 to regular DNS.
173 tcp443: <ip>
175 Add an IP4 or IP6 address to the list of fallback open DNSSEC
176 resolvers that are used on TCP port 443. These relay traffic
177 from port 443 to regular DNS.
178 tcp443: <ip> or <ip> { <hash>}
180 Add an IP4 of IP6 address to the list of fallback SSL open
181 DNSSEC resolvers. They serve plain-DNS(tcp-style) over port
182 443, encapsulated in SSL. The SSL certificate online is checked
183 with the fingerprint (if configured here). You may configure
184 multiple hashes (one space between), if one matches its OK, so
185 that pre-publish rollover of the certificates is possible.
186 use-vpn-forwarders: <yes or no>
188 Use DNS servers from VPN for all hosts, default is no. Only
189 domains configured for this connection are forwarded to VPN
190 resolvers. If set yes, all DNS queries are resolved on servers
191 supplied by VPN.
192 use-private-addresses: <yes or no>
194 Forward reverse zones of RFC 1918 private addresses to global
195 forwarders, default is yes. If set no, private addresses are
196 resolved only on this host. Addresses not configured locally
197 will return NXDOMAIN.
198
200 The dnssec-trigger-panel is an applet that runs in the tray. It shows
201 the DNSSEC status. It can be invoked with -d to test in the build
202 directory. The -c cfgfile option can set the config file away from the
203 default. The applet keeps an SSL connection to the daemon and displays
204 the status, and can show the user dialogs.
205 The applet has a small menu. The menu item Reprobe causes the daemon
207 to probe the last seen DHCP DNS servers again, which may now work after
208 a hotspot signon. The menu item Hotspot Signon goes into insecure mode
209 for hotspots where this must be used to sign on to the hot spot: use
210 reprobe when done to resume dnssec protection efforts. The Probe
211 Result menu item shows the results of the previous probe to the user,
212 for technical help with network difficulties.
213
215 The dnssec-trigger-control tool can be used to test. It is also used
216 inside DHCP scripts (platform specific). It can send commands to the
217 daemon.
218 Options:
220 -c cfgfile
222 Set the config file to use away from the default.
223 -s ip[@port]
225 Default connects to 127.0.0.1 with the port from config file,
226 but this options overrides that with an IPv4 or IPv6 address and
227 optional a port.
228 -v increase verbosity of dnssec-trigger-control.
230 Commands:
232 submit <ips>
234 Submit a list of space separated IP addresses (from DHCP) that
235 are the DNS servers that the daemon will probe. IPv4 and IPv6
236 addresses can be used.
237 unsafe Test command that probes some 127/8 addresses in a way that
239 makes the daemon conclude that no DNSSEC works. Presents user
240 with 'Insecure?' dialog.
241 status Shows the last probe results.
243 reprobe
245 Probe the last probe again. It also cancels forced insecure
246 state from hotspot signon, causing probes for dnssec to resume.
247 This command acts as the menu item with the same name.
248 skip_http
250 Skip the http probe step. Setup DNSSEC, as possible, without
251 taking the result of the http probe into account. Once http
252 works again, it'll stop skipping the http results. Useful, if
253 you want to have DNSSEC on a network where web access is not
254 possible.
255 hotspot_signon
257 This command acts as the menu item with the same name. Use it
258 to force insecure mode, where you can then interact with (weird)
259 hotspot set ups. When you are done, do the reprobe command to
260 resume DNSSEC protection efforts.
261 results
263 continuous feed of probe results.
264 cmdtray
266 Continuous input feed, used by the tray icon to send commands to
267 the daemon.
268 stoppanels
270 Makes connected tray icons quit. Useful for installers that
271 need to update their executable.
272 stop stops the daemon.
274
276 This tool aids setup of files. Without arguments it creates the key
277 files. If key files already exist, it resigns certificates with exist‐
278 ing private keys. With -d dir the files are placed in the given direc‐
279 tory.
280 With -i the tool changes configuration files. It tests if unbound has
282 remote-control: control-enable: yes and if not appends lines to
283 unbound.conf that enable unbound-control, and it runs unbound-con‐
284 trol-setup to generate the keys for unbound-control. It tests if
285 unbound has a trust anchor, if not it enables the root.key as
286 auto-trust-anchor-file and runs unbound-anchor(8) to initialize the
287 key. It picks up the domain and search from resolv.conf and configures
288 the dnssec-trigger.conf to use that.
289 Note the tool trusts the domain and search path at install time. You
291 should review them or perform configuration manually.
292 With -u it removes the options it enabled in unbound.conf(5).
294
296 /etc/dnssec-trigger/dnssec-trigger.conf
297 The default configuration file.
298 /etc/dnssec-trigger
300 Directory with keys used for SSL connections to dnssec-triggerd.
301 /run/dnssec-triggerd.pid
303 Default pidfile with the pid of the running dnssec-triggerd.
304
306 unbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).
307
309 This program was developed by Wouter Wijngaards at NLnet Labs.
310NLnet Labs 2018-06-25 dnssec-trigger(8)