Provided by: dnssec-trigger_0.13~svn685-4_i386 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.