1dnssec-trigger(8) dnssec-trigger 0.11 dnssec-trigger(8)
2
3
4
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
13 dnssec-trigger-control [-c file] [-s ip[@port] ] command [arguments]
14
15 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
25 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
30 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
34 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
45 -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
51 -d Debug flag, do not fork into the background, but stay attached
52 to the console.
53
54 -u uninstall dns override: makes resolv.conf mutable again, or
55 other OS action.
56
57 -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
66 verbosity: <num>
67 Amount of logging, 1 is default. 0 is only errors, 2 is more
68 detail, 4 for debug.
69
70 pidfile: "<file>"
71 The filename where the pid of the dnssec-triggerd is stored.
72 Default is /var/run/dnssec-trigger.pid.
73
74 logfile: "<file>"
75 Log to a file instead of syslog, default is to syslog.
76
77 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
81 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
88 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
99 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
104 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
109 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
114 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
121 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
129 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
133 server-key-file: "/etc/dnssec-trigger/dnssec_trigger_server.key"
134
135 server-cert-file: "/etc/dnssec-trigger/dnssec_trigger_server.pem"
136
137 control-key-file: "/etc/dnssec-trigger/dnssec_trigger_control.key"
138
139 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
144 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
153 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
169 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.
172
173 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.
176
177 tcp443: <ip> or <ip> { <hash>}
178 Add an IP4 of IP6 address to the list of fallback SSL open
179 DNSSEC resolvers. They serve plain-DNS(tcp-style) over port
180 443, encapsulated in SSL. The SSL certificate online is checked
181 with the fingerprint (if configured here). You may configure
182 multiple hashes (one space between), if one matches its OK, so
183 that pre-publish rollover of the certificates is possible.
184
186 The dnssec-trigger-panel is an applet that runs in the tray. It shows
187 the DNSSEC status. It can be invoked with -d to test in the build
188 directory. The -c cfgfile option can set the config file away from the
189 default. The applet keeps an SSL connection to the daemon and displays
190 the status, and can show the user dialogs.
191
192 The applet has a small menu. The menu item Reprobe causes the daemon
193 to probe the last seen DHCP DNS servers again, which may now work after
194 a hotspot signon. The menu item Hotspot Signon goes into insecure mode
195 for hotspots where this must be used to sign on to the hot spot: use
196 reprobe when done to resume dnssec protection efforts. The Probe
197 Result menu item shows the results of the previous probe to the user,
198 for technical help with network difficulties.
199
201 The dnssec-trigger-control tool can be used to test. It is also used
202 inside DHCP scripts (platform specific). It can send commands to the
203 daemon.
204
205 Options:
206
207 -c cfgfile
208 Set the config file to use away from the default.
209
210 -s ip[@port]
211 Default connects to 127.0.0.1 with the port from config file,
212 but this options overrides that with an IPv4 or IPv6 address and
213 optional a port.
214
215 -v increase verbosity of dnssec-trigger-control.
216
217 Commands:
218
219 submit <ips>
220 Submit a list of space separated IP addresses (from DHCP) that
221 are the DNS servers that the daemon will probe. IPv4 and IPv6
222 addresses can be used.
223
224 unsafe Test command that probes some 127/8 addresses in a way that
225 makes the daemon conclude that no DNSSEC works. Presents user
226 with 'Insecure?' dialog.
227
228 status Shows the last probe results.
229
230 reprobe
231 Probe the last probe again. It also cancels forced insecure
232 state from hotspot signon, causing probes for dnssec to resume.
233 This command acts as the menu item with the same name.
234
235 skip_http
236 Skip the http probe step. Setup DNSSEC, as possible, without
237 taking the result of the http probe into account. Once http
238 works again, it'll stop skipping the http results. Useful, if
239 you want to have DNSSEC on a network where web access is not
240 possible.
241
242 hotspot_signon
243 This command acts as the menu item with the same name. Use it
244 to force insecure mode, where you can then interact with (weird)
245 hotspot set ups. When you are done, do the reprobe command to
246 resume DNSSEC protection efforts.
247
248 results
249 continuous feed of probe results.
250
251 cmdtray
252 Continuous input feed, used by the tray icon to send commands to
253 the daemon.
254
255 stoppanels
256 Makes connected tray icons quit. Useful for installers that
257 need to update their executable.
258
259 stop stops the daemon.
260
262 This tool aids setup of files. Without arguments it creates the key
263 files. If key files already exist, it resigns certificates with exist‐
264 ing private keys. With -d dir the files are placed in the given direc‐
265 tory.
266
267 With -i the tool changes configuration files. It tests if unbound has
268 remote-control: control-enable: yes and if not appends lines to
269 unbound.conf that enable unbound-control, and it runs unbound-con‐
270 trol-setup to generate the keys for unbound-control. It tests if
271 unbound has a trust anchor, if not it enables the root.key as
272 auto-trust-anchor-file and runs unbound-anchor(8) to initialize the
273 key. It picks up the domain and search from resolv.conf and configures
274 the dnssec-trigger.conf to use that.
275
276 Note the tool trusts the domain and search path at install time. You
277 should review them or perform configuration manually.
278
279 With -u it removes the options it enabled in unbound.conf(5).
280
282 /etc/dnssec-trigger/dnssec-trigger.conf
283 The default configuration file.
284
285 /etc/dnssec-trigger
286 Directory with keys used for SSL connections to dnssec-triggerd.
287
288 /var/run/dnssec-trigger.pid
289 Default pidfile with the pid of the running dnssec-triggerd.
290
292 unbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).
293
295 This program was developed by Wouter Wijngaards at NLnet Labs.
296
297
298
299NLnet Labs 2012-06-07 dnssec-trigger(8)