dnssec-trigger(8)dnssec-trigger 0.11 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,
/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 /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: ""
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: "/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-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 in‐
staller 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.
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 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
/etc/dnssec-trigger/dnssec-trigger.conf
The default configuration file.
/etc/dnssec-trigger
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 ALSOunbound(8), unbound-control(8), unbound.conf(5), resolv.conf(5).
AUTHORS
This program was developed by Wouter Wijngaards at NLnet Labs.
NLnet Labs 2012-06-07 dnssec-trigger(8)
