dnssec-trigger(8)             dnssec-trigger 0.13            dnssec-trigger(8)



NAME
       dnssec-trigger,  dnssec-triggerd, dnssec-trigger-panel, dnssec-trigger-
       control, dnssec-trigger-control-setup, dnssec-trigger.conf - check  DNS
       servers for DNSSEC support and adjust to compensate.

SYNOPSIS
       dnssec-triggerd [-d] [-v] [-u] [-c file]

       dnssec-trigger-control [-c file] [-s ip[@port] ] command [arguments]

       dnssec-trigger-panel [-d] [-c file]

DESCRIPTION
       The dnssec-trigger programs steer unbound(8) towards DNSSEC capable DNS
       servers.  A DHCP hook installed on the system calls dnssec-trigger-con-
       trol  that  contacts the daemon dnssec-triggerd that probes the list of
       servers.   The  daemon  then  adjusts   a   running   unbound   through
       unbound-control(8)  and  notifies  the user applet dnssec-trigger-panel
       for GUI display.

       The dnssec-trigger-panel runs after user login, displays  notifications
       and  status  to  the user.  It may popup a warning if no DNSSEC capable
       servers are available, with options to disconnect or to  connect  inse-
       curely.

       The dnssec-trigger-control tool is used in the background by scripts to
       notify the daemon of new (DHCP) DNS servers.  It can be  used  to  test
       the system by providing a (fake) list of DNS server IP addresses.

       The  dnssec-trigger-control-setup  tool  is  used to setup the SSL keys
       that the daemon and user panel use to communicate securely.  It must be
       run once after installation.

THE DNSSEC-TRIGGERD DAEMON
       Thus  the dnssec-triggerd daemon runs continually, and is started after
       boot.  It receives a list of IP addresses,  probes  them,  and  adjusts
       unbound   and  resolv.conf.   Unbound  acts  as  the  validating  local
       resolver, running on 127.0.0.1.  And resolv.conf is modified  to  point
       to 127.0.0.1.

       -c cfgfile
              Set  the  config  file  with settings for the dnssec-triggerd to
              read instead of  reading  the  file  at  the  default  location,
              /usr/local/etc/dnssec-trigger.conf.   The  syntax  is  described
              below.

       -d     Debug flag, do not fork into the background, but  stay  attached
              to the console.

       -u     uninstall  dns  override:  makes  resolv.conf  mutable again, or
              other OS action.

       -v     Increase verbosity. If given multiple times, more information is
              logged.   This is in addition to the verbosity (if any) from the
              config file.

THE DNSSEC-TRIGGER.CONF FILE
       The config file contains options.  It is  fairly  simple,  key:  value.
       You  can  make  comments  with '#' and have empty lines.  The parser is
       simple and expects one statement per line.

       verbosity: <num>
              Amount of logging, 1 is default. 0 is only  errors,  2  is  more
              detail, 4 for debug.

       pidfile: "<file>"
              The  filename  where  the  pid of the dnssec-triggerd is stored.
              Default is /var/run/dnssec-trigger.pid.

       logfile: "<file>"
              Log to a file instead of syslog, default is to syslog.

       use-syslog: <yes or no>
              Log to syslog, default is yes.  Set to no logs to stderr (if  no
              logfile) or the configured logfile.

       unbound-control: "<command>"
              The   string   gives   the   command  to  execute.   It  can  be
              "unbound-control" to search the runtime PATH, or  a  full  path-
              name.   With  a space after the command arguments can be config-
              ured to the  command,  i.e.  "/usr/local/bin/unbound-control  -c
              my.conf".

       resolvconf: "/etc/resolv.conf"
              The  resolv.conf  file  to  edit (on posix systems).  The daemon
              keeps the file readonly and only make  it  writable  shortly  to
              change it itself.  This is to keep other software from interfer-
              ing.  On OSX (if compiled in) also the DNS settings are  changed
              in  the  network configuration machinery (visible in the network
              settings control panel).  On Windows (if compiled), it sets reg-
              istry  settings for network configuration (may be visible in the
              control panel tab for network devices)  and  does  not  write  a
              resolv.conf file.

       domain: "example.com"
              The  domain  to set in resolv.conf.  See resolv.conf(5).  Picked
              up once during installation, and not from DHCP since  it  allows
              directing traffic elsewhere.

       search: "example.com"
              The  domain  name  search  path  to  set  in  resolv.conf.   See
              resolv.conf(5).  Picked up once  during  installation,  and  not
              from DHCP since it allows directing traffic elsewhere.

       noaction: <yes or no>
              Default   is   no.   If  yes,  no  action  is  taken  to  change
              unbound-control or resolv.conf.  The software can be tested with
              this, probe results are available.

       port: <8955>
              Port number to use for communication with dnssec-triggerd.  Com-
              munication uses 127.0.0.1 (the loopback interface).  SSL is used
              to  secure  it, and the keys are stored on the disk (see below).
              The other tools read this config file to find  the  port  number
              and key locations.

       login-command: "xdg-open"
              The command that is run when the user clicks Login on the no web
              access dialog.  That is supposedly a web browser, that is  aimed
              to  open  some url so that the hot-spot network login can inter-
              cept and show its login page.  The default is a detected generic
              web  browser.  The "" empty string turns off this feature and no
              command gets run.

       login-location: "http://www.nlnetlabs.nl/projects/dnssec-trigger"
              The url that is opened with the web browser.  Used  as  command-
              line argument.

       server-key-file: "/usr/local/etc/dnssec_trigger_server.key"

       server-cert-file: "/usr/local/etc/dnssec_trigger_server.pem"

       control-key-file: "/usr/local/etc/dnssec_trigger_control.key"

       control-cert-file: "/usr/local/etc/dnssec_trigger_control.pem"
              The  files  used for SSL secured communication with dnssec-trig-
              gerd.  These  files  can  be  created  with  dnssec-trigger-con-
              trol-setup (run as root).

       check-updates: <yes or no>
              Check  for  software  updates,  if  there are, download them and
              present the user with a dialog that  allows   them  to  run  the
              installer  to upgrade the software.  It checks a SHA256 checksum
              on the download, the checksum is signed with DNSSEC (from a  TXT
              record).   On windows and osx the default is yes.  On other sys-
              tems the default is no (it'll download  the  source  tarball  if
              enabled).

       url: "http://example.com OK"
              This  command adds an url to probe via HTTP (port 80). The first
              word, before the space is the url to resolve.  The remainder  is
              the  string  that is expected as page contents (that may be pre-
              fixed or suffixed with whitespace).  The url is resolved, a HTTP
              1.1  query  is sent.  The reply must be type 2xx and contain the
              page contents.  If this is not true, dnssec-trigger  knows  that
              there is a 'hot spot' of some sort interfering with traffic.  If
              you do not configure any urls, then no probes are done.  If  you
              configure  multiple  urls then it probes a random selection of 3
              urls, all of their IP addresses in turn, with IP4 and IP6 simul-
              taneously.   At  most  5  of  the  DHCP  DNS servers are used to
              resolve (in parallel).  If an answer is gotten and it fails  the
              probe  stop,  the probing continues if there is no connection or
              response 404.

       tcp80: <ip>
              Add an IP4 or IP6 address to the list of  fallback  open  DNSSEC
              resolvers  that  are  used  on TCP port 80.  These relay traffic
              from port 80 to regular DNS.

       tcp443: <ip>
              Add an IP4 or IP6 address to the list of  fallback  open  DNSSEC
              resolvers  that  are  used on TCP port 443.  These relay traffic
              from port 443 to regular DNS.

       tcp443: <ip> or <ip> { <hash>}
              Add an IP4 of IP6 address to  the  list  of  fallback  SSL  open
              DNSSEC  resolvers.   They  serve  plain-DNS(tcp-style) over port
              443, encapsulated in SSL.  The SSL certificate online is checked
              with  the  fingerprint  (if configured here).  You may configure
              multiple hashes (one space between), if one matches its  OK,  so
              that pre-publish rollover of the certificates is possible.

THE DNSSEC-TRIGGER-PANEL
       The  dnssec-trigger-panel is an applet that runs in the tray.  It shows
       the DNSSEC status.  It can be invoked with -d  to  test  in  the  build
       directory.  The -c cfgfile option can set the config file away from the
       default.  The applet keeps an SSL connection to the daemon and displays
       the status, and can show the user dialogs.

       The  applet  has a small menu.  The menu item Reprobe causes the daemon
       to probe the last seen DHCP DNS servers again, which may now work after
       a hotspot signon.  The menu item Hotspot Signon goes into insecure mode
       for hotspots where this must be used to sign on to the  hot  spot:  use
       reprobe  when  done  to  resume  dnssec  protection efforts.  The Probe
       Result menu item shows the results of the previous probe to  the  user,
       for technical help with network difficulties.

THE DNSSEC-TRIGGER-CONTROL TOOL
       The  dnssec-trigger-control  tool can be used to test.  It is also used
       inside DHCP scripts (platform specific).  It can send commands  to  the
       daemon.

       Options:

       -c cfgfile
              Set the config file to use away from the default.

       -s ip[@port]
              Default  connects  to  127.0.0.1 with the port from config file,
              but this options overrides that with an IPv4 or IPv6 address and
              optional a port.

       -v     increase verbosity of dnssec-trigger-control.

       Commands:

       submit <ips>
              Submit  a  list of space separated IP addresses (from DHCP) that
              are the DNS servers that the daemon will probe.  IPv4  and  IPv6
              addresses can be used.

       unsafe Test  command  that  probes  some  127/8 addresses in a way that
              makes the daemon conclude that no DNSSEC works.   Presents  user
              with 'Insecure?' dialog.

       status Shows the last probe results.

       reprobe
              Probe  the  last  probe  again.  It also cancels forced insecure
              state from hotspot signon, causing probes for dnssec to  resume.
              This command acts as the menu item with the same name.

       skip_http
              Skip  the  http  probe step.  Setup DNSSEC, as possible, without
              taking the result of the http probe  into  account.   Once  http
              works  again,  it'll stop skipping the http results.  Useful, if
              you want to have DNSSEC on a network where  web  access  is  not
              possible.

       hotspot_signon
              This  command  acts as the menu item with the same name.  Use it
              to force insecure mode, where you can then interact with (weird)
              hotspot  set  ups.  When you are done, do the reprobe command to
              resume DNSSEC protection efforts.

       results
              continuous feed of probe results.

       cmdtray
              Continuous input feed, used by the tray icon to send commands to
              the daemon.

       stoppanels
              Makes  connected  tray  icons  quit.  Useful for installers that
              need to update their executable.

       stop   stops the daemon.

THE DNSSEC-TRIGGER-CONTROL-SETUP TOOL
       This tool aids setup of files.  Without arguments it  creates  the  key
       files.  If key files already exist, it resigns certificates with exist-
       ing private keys.  With -d dir the files are placed in the given direc-
       tory.

       With  -i the tool changes configuration files.  It tests if unbound has
       remote-control:  control-enable:  yes  and  if  not  appends  lines  to
       unbound.conf  that  enable  unbound-control,  and  it runs unbound-con-
       trol-setup to generate the  keys  for  unbound-control.   It  tests  if
       unbound  has  a  trust  anchor,  if  not  it  enables  the  root.key as
       auto-trust-anchor-file and runs  unbound-anchor(8)  to  initialize  the
       key.  It picks up the domain and search from resolv.conf and configures
       the dnssec-trigger.conf to use that.

       Note the tool trusts the domain and search path at install  time.   You
       should review them or perform configuration manually.

       With -u it removes the options it enabled in unbound.conf(5).

FILES
       /usr/local/etc/dnssec-trigger.conf
              The default configuration file.

       /usr/local/etc
              Directory with keys used for SSL connections to dnssec-triggerd.

       /var/run/dnssec-trigger.pid
              Default pidfile with the pid of the running dnssec-triggerd.

SEE ALSO
       unbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).

AUTHORS
       This program was developed by Wouter Wijngaards at NLnet Labs.



NLnet Labs                         20161215                  dnssec-trigger(8)

Wed Sep 25 2013

© Stichting NLnet Labs

Science Park 400, 1098 XH Amsterdam, The Netherlands

labs@nlnetlabs.nl, subsidised by NLnet and SIDN.