Provided by: dnssec-trigger_0.13~svn685-4_amd64 bug

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-control  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 insecurely.

       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,  /etc/dnssec-trigger/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
              /run/dnssec-triggerd.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 pathname.  With a space after the command arguments can  be
              configured 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 interfering.  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 registry 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.  Communication 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: "sensible-browser"
              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 intercept 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 commandline argument.

       server-key-file: "/etc/dnssec-trigger/dnssec_trigger_server.key"

       server-cert-file: "/etc/dnssec-trigger/dnssec_trigger_server.pem"

       control-key-file: "/etc/dnssec-trigger/dnssec_trigger_control.key"

       control-cert-file: "/etc/dnssec-trigger/dnssec_trigger_control.pem"
              The files used for SSL secured communication with dnssec-triggerd.  These files can
              be created with dnssec-trigger-control-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 systems 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 prefixed 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 simultaneously.   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.

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

       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 existing private keys.  With -d dir the  files
       are placed in the given directory.

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

       /etc/dnssec-trigger/dnssec-trigger.conf
              The default configuration file.

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

       /run/dnssec-triggerd.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.