Ubuntu Manpage: dnssec-trigger, dnssec-triggerd, dnssec-trigger-panel, dnssec-trigger-control, dnssec-trigger-control-

Provided by: dnssec-trigger_0.17+repack-5build1_amd64

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

use-vpn-forwarders: <yes or no>
Use DNS servers from VPN for all hosts, default is no. Only domains configured for this connection
are forwarded to VPN resolvers. If set yes, all DNS queries are resolved on servers supplied by
VPN.

use-private-addresses: <yes or no>
Forward reverse zones of RFC 1918 private addresses to global forwarders, default is yes. If set
no, private addresses are resolved only on this host. Addresses not configured locally will return
NXDOMAIN.

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.

AUTHORS

       This program was developed by Wouter Wijngaards at NLnet Labs.

NLnet Labs                                         2018-06-25                                  dnssec-trigger(8)