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 un‐
22 bound-control(8) and notifies the user applet dnssec-trigger-panel for
23 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 un‐
41 bound and resolv.conf. Unbound acts as the validating local resolver,
42 running on 127.0.0.1. And resolv.conf is modified to point to
43 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 de‐
68 tail, 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 "un‐
83 bound-control" to search the runtime PATH, or a full pathname.
84 With a space after the command arguments can be configured to
85 the command, i.e. "/usr/local/bin/unbound-control -c my.conf".
86 resolvconf: "/etc/resolv.conf"
88 The resolv.conf file to edit (on posix systems). The daemon
89 keeps the file readonly and only make it writable shortly to
90 change it itself. This is to keep other software from interfer‐
91 ing. On OSX (if compiled in) also the DNS settings are changed
92 in the network configuration machinery (visible in the network
93 settings control panel). On Windows (if compiled), it sets reg‐
94 istry settings for network configuration (may be visible in the
95 control panel tab for network devices) and does not write a re‐
96 solv.conf file.
97 domain: "example.com"
99 The domain to set in resolv.conf. See resolv.conf(5). Picked
100 up once during installation, and not from DHCP since it allows
101 directing traffic elsewhere.
102 search: "example.com"
104 The domain name search path to set in resolv.conf. See re‐
105 solv.conf(5). Picked up once during installation, and not from
106 DHCP since it allows directing traffic elsewhere.
107 noaction: <yes or no>
109 Default is no. If yes, no action is taken to change un‐
110 bound-control or resolv.conf. The software can be tested with
111 this, probe results are available.
112 port: <8955>
114 Port number to use for communication with dnssec-triggerd. Com‐
115 munication uses 127.0.0.1 (the loopback interface). SSL is used
116 to secure it, and the keys are stored on the disk (see below).
117 The other tools read this config file to find the port number
118 and key locations.
119 login-command: "/usr/bin/xdg-open"
121 The command that is run when the user clicks Login on the no web
122 access dialog. That is supposedly a web browser, that is aimed
123 to open some url so that the hot-spot network login can inter‐
124 cept and show its login page. The default is a detected generic
125 web browser. The "" empty string turns off this feature and no
126 command gets run.
127 login-location: "http://hotspot-nocache.fedoraproject.org/"
129 The url that is opened with the web browser. Used as command‐
130 line argument.
131 server-key-file: "/etc/dnssec-trigger/dnssec_trigger_server.key"
133 server-cert-file: "/etc/dnssec-trigger/dnssec_trigger_server.pem"
135 control-key-file: "/etc/dnssec-trigger/dnssec_trigger_control.key"
137 control-cert-file: "/etc/dnssec-trigger/dnssec_trigger_control.pem"
139 The files used for SSL secured communication with dnssec-trig‐
140 gerd. These files can be created with dnssec-trigger-con‐
141 trol-setup (run as root).
142 check-updates: <yes or no>
144 Check for software updates, if there are, download them and
145 present the user with a dialog that allows them to run the in‐
146 staller to upgrade the software. It checks a SHA256 checksum on
147 the download, the checksum is signed with DNSSEC (from a TXT
148 record). On windows and osx the default is yes. On other sys‐
149 tems the default is no (it'll download the source tarball if en‐
150 abled).
151 url: "http://example.com OK"
153 This command adds an url to probe via HTTP (port 80). The first
154 word, before the space is the url to resolve. The remainder is
155 the string that is expected as page contents (that may be pre‐
156 fixed or suffixed with whitespace). The url is resolved, a HTTP
157 1.1 query is sent. The reply must be type 2xx and contain the
158 page contents. If this is not true, dnssec-trigger knows that
159 there is a 'hot spot' of some sort interfering with traffic. If
160 you do not configure any urls, then no probes are done. If you
161 configure multiple urls then it probes a random selection of 3
162 urls, all of their IP addresses in turn, with IP4 and IP6 simul‐
163 taneously. At most 5 of the DHCP DNS servers are used to re‐
164 solve (in parallel). If an answer is gotten and it fails the
165 probe stop, the probing continues if there is no connection or
166 response 404.
167 tcp80: <ip>
169 Add an IP4 or IP6 address to the list of fallback open DNSSEC
170 resolvers that are used on TCP port 80. These relay traffic
171 from port 80 to regular DNS.
172 tcp443: <ip>
174 Add an IP4 or IP6 address to the list of fallback open DNSSEC
175 resolvers that are used on TCP port 443. These relay traffic
176 from port 443 to regular DNS.
177 tcp443: <ip> or <ip> { <hash>}
179 Add an IP4 of IP6 address to the list of fallback SSL open
180 DNSSEC resolvers. They serve plain-DNS(tcp-style) over port
181 443, encapsulated in SSL. The SSL certificate online is checked
182 with the fingerprint (if configured here). You may configure
183 multiple hashes (one space between), if one matches its OK, so
184 that pre-publish rollover of the certificates is possible.
185 use-vpn-forwarders: <yes or no>
187 Use DNS servers from VPN for all hosts, default is no. Only do‐
188 mains configured for this connection are forwarded to VPN re‐
189 solvers. If set yes, all DNS queries are resolved on servers
190 supplied by VPN.
191 use-private-addresses: <yes or no>
193 Forward reverse zones of RFC 1918 private addresses to global
194 forwarders, default is yes. If set no, private addresses are
195 resolved only on this host. Addresses not configured locally
196 will return NXDOMAIN.
197
199 The dnssec-trigger-panel is an applet that runs in the tray. It shows
200 the DNSSEC status. It can be invoked with -d to test in the build di‐
201 rectory. The -c cfgfile option can set the config file away from the
202 default. The applet keeps an SSL connection to the daemon and displays
203 the status, and can show the user dialogs.
204 The applet has a small menu. The menu item Reprobe causes the daemon
206 to probe the last seen DHCP DNS servers again, which may now work after
207 a hotspot signon. The menu item Hotspot Signon goes into insecure mode
208 for hotspots where this must be used to sign on to the hot spot: use
209 reprobe when done to resume dnssec protection efforts. The Probe Re‐
210 sult menu item shows the results of the previous probe to the user, for
211 technical help with network difficulties.
212
214 The dnssec-trigger-control tool can be used to test. It is also used
215 inside DHCP scripts (platform specific). It can send commands to the
216 daemon.
217 Options:
219 -c cfgfile
221 Set the config file to use away from the default.
222 -s ip[@port]
224 Default connects to 127.0.0.1 with the port from config file,
225 but this options overrides that with an IPv4 or IPv6 address and
226 optional a port.
227 -v increase verbosity of dnssec-trigger-control.
229 Commands:
231 submit <ips>
233 Submit a list of space separated IP addresses (from DHCP) that
234 are the DNS servers that the daemon will probe. IPv4 and IPv6
235 addresses can be used.
236 unsafe Test command that probes some 127/8 addresses in a way that
238 makes the daemon conclude that no DNSSEC works. Presents user
239 with 'Insecure?' dialog.
240 status Shows the last probe results.
242 reprobe
244 Probe the last probe again. It also cancels forced insecure
245 state from hotspot signon, causing probes for dnssec to resume.
246 This command acts as the menu item with the same name.
247 skip_http
249 Skip the http probe step. Setup DNSSEC, as possible, without
250 taking the result of the http probe into account. Once http
251 works again, it'll stop skipping the http results. Useful, if
252 you want to have DNSSEC on a network where web access is not
253 possible.
254 hotspot_signon
256 This command acts as the menu item with the same name. Use it
257 to force insecure mode, where you can then interact with (weird)
258 hotspot set ups. When you are done, do the reprobe command to
259 resume DNSSEC protection efforts.
260 results
262 continuous feed of probe results.
263 cmdtray
265 Continuous input feed, used by the tray icon to send commands to
266 the daemon.
267 stoppanels
269 Makes connected tray icons quit. Useful for installers that
270 need to update their executable.
271 stop stops the daemon.
273
275 This tool aids setup of files. Without arguments it creates the key
276 files. If key files already exist, it resigns certificates with exist‐
277 ing private keys. With -d dir the files are placed in the given direc‐
278 tory.
279 With -i the tool changes configuration files. It tests if unbound has
281 remote-control: control-enable: yes and if not appends lines to un‐
282 bound.conf that enable unbound-control, and it runs unbound-con‐
283 trol-setup to generate the keys for unbound-control. It tests if un‐
284 bound has a trust anchor, if not it enables the root.key as
285 auto-trust-anchor-file and runs unbound-anchor(8) to initialize the
286 key. It picks up the domain and search from resolv.conf and configures
287 the dnssec-trigger.conf to use that.
288 Note the tool trusts the domain and search path at install time. You
290 should review them or perform configuration manually.
291 With -u it removes the options it enabled in unbound.conf(5).
293
295 /etc/dnssec-trigger/dnssec-trigger.conf
296 The default configuration file.
297 /etc/dnssec-trigger
299 Directory with keys used for SSL connections to dnssec-triggerd.
300 /run/dnssec-triggerd.pid
302 Default pidfile with the pid of the running dnssec-triggerd.
303
305 unbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).
306
308 This program was developed by Wouter Wijngaards at NLnet Labs.
309NLnet Labs 2018-06-25 dnssec-trigger(8)