1dnssec-trigger(8)             dnssec-trigger 0.17            dnssec-trigger(8)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

THE DNSSEC-TRIGGERD DAEMON

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

THE DNSSEC-TRIGGER.CONF FILE

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 /run/dnssec-triggerd.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.  These relay traffic
172              from port 80 to regular DNS.
173
174       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
179       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
187       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
193       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

THE DNSSEC-TRIGGER-PANEL

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
206       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

THE DNSSEC-TRIGGER-CONTROL TOOL

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
219       Options:
220
221       -c cfgfile
222              Set the config file to use away from the default.
223
224       -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
229       -v     increase verbosity of dnssec-trigger-control.
230
231       Commands:
232
233       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
238       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
242       status Shows the last probe results.
243
244       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
249       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
256       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
262       results
263              continuous feed of probe results.
264
265       cmdtray
266              Continuous input feed, used by the tray icon to send commands to
267              the daemon.
268
269       stoppanels
270              Makes  connected  tray  icons  quit.  Useful for installers that
271              need to update their executable.
272
273       stop   stops the daemon.
274

THE DNSSEC-TRIGGER-CONTROL-SETUP TOOL

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
281       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
290       Note the tool trusts the domain and search path at install  time.   You
291       should review them or perform configuration manually.
292
293       With -u it removes the options it enabled in unbound.conf(5).
294

FILES

296       /etc/dnssec-trigger/dnssec-trigger.conf
297              The default configuration file.
298
299       /etc/dnssec-trigger
300              Directory with keys used for SSL connections to dnssec-triggerd.
301
302       /run/dnssec-triggerd.pid
303              Default pidfile with the pid of the running dnssec-triggerd.
304

SEE ALSO

306       unbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).
307

AUTHORS

309       This program was developed by Wouter Wijngaards at NLnet Labs.
310
311
312
313NLnet Labs                        2018-06-25                 dnssec-trigger(8)
Impressum