1dnssec-trigger(8) dnssec-trigger 0.15 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 /var/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
188 The dnssec-trigger-panel is an applet that runs in the tray. It shows
189 the DNSSEC status. It can be invoked with -d to test in the build
190 directory. The -c cfgfile option can set the config file away from the
191 default. The applet keeps an SSL connection to the daemon and displays
192 the status, and can show the user dialogs.
193 The applet has a small menu. The menu item Reprobe causes the daemon
195 to probe the last seen DHCP DNS servers again, which may now work after
196 a hotspot signon. The menu item Hotspot Signon goes into insecure mode
197 for hotspots where this must be used to sign on to the hot spot: use
198 reprobe when done to resume dnssec protection efforts. The Probe
199 Result menu item shows the results of the previous probe to the user,
200 for technical help with network difficulties.
201
203 The dnssec-trigger-control tool can be used to test. It is also used
204 inside DHCP scripts (platform specific). It can send commands to the
205 daemon.
206 Options:
208 -c cfgfile
210 Set the config file to use away from the default.
211 -s ip[@port]
213 Default connects to 127.0.0.1 with the port from config file,
214 but this options overrides that with an IPv4 or IPv6 address and
215 optional a port.
216 -v increase verbosity of dnssec-trigger-control.
218 Commands:
220 submit <ips>
222 Submit a list of space separated IP addresses (from DHCP) that
223 are the DNS servers that the daemon will probe. IPv4 and IPv6
224 addresses can be used.
225 unsafe Test command that probes some 127/8 addresses in a way that
227 makes the daemon conclude that no DNSSEC works. Presents user
228 with 'Insecure?' dialog.
229 status Shows the last probe results.
231 reprobe
233 Probe the last probe again. It also cancels forced insecure
234 state from hotspot signon, causing probes for dnssec to resume.
235 This command acts as the menu item with the same name.
236 skip_http
238 Skip the http probe step. Setup DNSSEC, as possible, without
239 taking the result of the http probe into account. Once http
240 works again, it'll stop skipping the http results. Useful, if
241 you want to have DNSSEC on a network where web access is not
242 possible.
243 hotspot_signon
245 This command acts as the menu item with the same name. Use it
246 to force insecure mode, where you can then interact with (weird)
247 hotspot set ups. When you are done, do the reprobe command to
248 resume DNSSEC protection efforts.
249 results
251 continuous feed of probe results.
252 cmdtray
254 Continuous input feed, used by the tray icon to send commands to
255 the daemon.
256 stoppanels
258 Makes connected tray icons quit. Useful for installers that
259 need to update their executable.
260 stop stops the daemon.
262
264 This tool aids setup of files. Without arguments it creates the key
265 files. If key files already exist, it resigns certificates with exist‐
266 ing private keys. With -d dir the files are placed in the given direc‐
267 tory.
268 With -i the tool changes configuration files. It tests if unbound has
270 remote-control: control-enable: yes and if not appends lines to
271 unbound.conf that enable unbound-control, and it runs unbound-con‐
272 trol-setup to generate the keys for unbound-control. It tests if
273 unbound has a trust anchor, if not it enables the root.key as
274 auto-trust-anchor-file and runs unbound-anchor(8) to initialize the
275 key. It picks up the domain and search from resolv.conf and configures
276 the dnssec-trigger.conf to use that.
277 Note the tool trusts the domain and search path at install time. You
279 should review them or perform configuration manually.
280 With -u it removes the options it enabled in unbound.conf(5).
282
284 /etc/dnssec-trigger/dnssec-trigger.conf
285 The default configuration file.
286 /etc/dnssec-trigger
288 Directory with keys used for SSL connections to dnssec-triggerd.
289 /var/run/dnssec-triggerd.pid
291 Default pidfile with the pid of the running dnssec-triggerd.
292
294 unbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).
295
297 This program was developed by Wouter Wijngaards at NLnet Labs.
298NLnet Labs 2017-10-11 dnssec-trigger(8)