dnssec-trigger(8)

dnssec-trigger 💖 — the manual, but make it make sense

okay bestie, gather round 🫶 this is the manpage for dnssec-trigger, version 0.17, and it's a whole little family of programs. Let's go.

---

✨ NAME ✨

So the whole squad is: dnssec-trigger, dnssec-triggerd, dnssec-trigger-panel, dnssec-trigger-control, dnssec-trigger-control-setup, and the config file dnssec-trigger.conf.

And what do they all do? They check DNS servers for DNSSEC support and adjust to compensate. That's the whole vibe. 💅

---

✨ SYNOPSIS ✨

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

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

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

no cap, that's literally it. three commands, three vibes. 🦋

---

✨ DESCRIPTION ✨

So here's the tea ☕ — the dnssec-trigger programs steer unbound(8) towards DNS servers that actually do DNSSEC. Like, they gently nudge it. "bestie, this way, these servers are the real ones." 🧚

Here's the whole pipeline, and it's honestly iconic:

• A DHCP hook installed on the system calls dnssec-trigger-control
• which contacts the daemon dnssec-triggerd
• which probes the list of servers 🔍
• and then the daemon adjusts a running unbound through unbound-control(8)
• and notifies the user applet dnssec-trigger-panel so it can show you GUI stuff ✨

It's giving relay race, honestly. Everyone passing the baton. 🏃♀️💨

dnssec-trigger-panel runs after user login, and it 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. (Yeah, that second one is the "fine, whatever, I guess" button. Choose wisely 😭)

dnssec-trigger-control is the tool that scripts use in the background to notify the daemon about new (DHCP) DNS servers. You can also use it to test the system by handing it a (fake) list of DNS server IP addresses. Fake it till you make it 💅

dnssec-trigger-control-setup sets up the SSL keys that the daemon and the user panel use to talk to each other securely. It must be run once after installation. Once! Don't skip it! 🎀

---

✨ THE DNSSEC-TRIGGERD DAEMON ✨

So the dnssec-triggerd daemon runs continually, and it gets started after boot. It's the main character here, honestly 👑

What it does, step by step:

• it receives a list of IP addresses 📋
• it probes them 🔍
• it adjusts unbound and resolv.conf 🛠️

Unbound acts as the validating local resolver, running on 127.0.0.1. And resolv.conf gets modified to point to 127.0.0.1. Local loopback supremacy, fr fr 🌈

Options

• -c cfgfile — sets 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, bestie 👇
• -d — debug flag 🐛. Does not fork into the background; instead it stays attached to the console. It's giving "I'm right here, watch me work."
• -u — uninstall dns override: makes resolv.conf mutable again, or does another OS action. Basically "put it back how you found it" 🙈
• -v — increase verbosity 📢. If you give it multiple times, more information gets logged. This is in addition to the verbosity (if any) from the config file. Stack it up, bestie ✨

---

✨ THE DNSSEC-TRIGGER.CONF FILE ✨

This file contains options. It's fairly simple: key: value. You can make comments with # and you can have empty lines. The parser is simple and expects one statement per line — so don't get cute and write a novel on one line, she won't read it 📖💀

• verbosity: <num> — the amount of logging. 1 is the default. 0 is only errors, 2 is more detail, 4 is for debug. Pick your volume 🎚️
• 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. The default is to syslog. 🗂️
• use-syslog: <yes or no> — log to syslog, default is yes. Set to no and it logs to stderr (if there's no logfile) or to 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 makes it writable shortly to change it itself. Why? To keep other software from interfering. Gatekeeping, but make it security 💅. On OSX (if compiled in) the DNS settings are also 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. (Sneaky. We don't do sneaky. 🙅♀️)
• 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. Same energy as above, different key 🔍
• noaction: <yes or no> — default is no. If yes, no action is taken to change unbound-control or resolv.conf. You can test the software with this — probe results are available. It's the "look, don't touch" mode 👀
• port: <8955> — the 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 gets run when the user clicks Login on the no-web-access dialog. That's supposedly a web browser, aimed at opening some url so the hot-spot network login can intercept it 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 gets opened with the web browser. Used as a 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" — these are the files used for SSL secured communication with dnssec-triggerd. They can be created with dnssec-trigger-control-setup (run as root). 🔑✨
• check-updates: <yes or no> — check for software updates. If there are any, 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, and 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 a 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, an 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 stops; 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), and if one matches it's 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 ✨

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, and every item is doing something, bestie:

• Reprobe — causes the daemon to probe the last seen DHCP DNS servers again, which may now work after a hotspot signon. Second chances! 🔄
• 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. So: dip into insecure mode, do the thing, then get right back to safety 🏃♀️💨
• Probe Result — shows the results of the previous probe to the user, for technical help with network difficulties. Receipts! 🧾

---

💖 THE DNSSEC-TRIGGER-CONTROL TOOL 💖

Okay bestie, meet dnssec-trigger-control — the lil tool that can be used to test stuff. It's also used inside DHCP scripts (the platform-specific ones, iykyk). Basically it can send commands to the daemon. It's giving messenger. It's giving ✨ middle management ✨.

🌸 Options 🌸

• -c cfgfile — use a different config file than the default one, because sometimes you wanna be ✨different✨.
• -s ip[@port] — by default it connects to 127.0.0.1 with the port from the config file, but this option overrides that with an IPv4 or IPv6 address, and optionally a port. So you can point it wherever, no cap.
• -v — crank up the verbosity of dnssec-trigger-control. More words. More chaos. More knowing.

🦋 Commands 🦋

• submit <ips> — submit a list of space-separated IP addresses (these come from DHCP, okay?) that are the DNS servers the daemon will probe. IPv4 and IPv6 addresses both welcome, come one come all 💅.
• unsafe — a test command that probes some 127/8 addresses in a way that makes the daemon conclude that no DNSSEC works. It presents the user with an 'Insecure?' dialog. It's a lil drama queen, on purpose.
• status — shows the last probe results. Receipts, basically.
• reprobe — probes the last probe all over again. It also cancels the forced insecure state from hotspot signon, which means probes for dnssec get to resume. This command acts as the menu item with the same name. She's the same girl, just in command-line form 🫶.
• skip_http — skip the http probe step. Set up DNSSEC as much as possible without taking the result of the http probe into account. Once http works again, it'll stop skipping the http results. Super useful if you want DNSSEC on a network where web access is not possible. Iconic for airplane-mode girlies ✈️.
• 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're done, do the reprobe command to resume DNSSEC protection efforts. Girl's gotta lower her shields to deal with the captive portal, then put them right back up 😤.
• results — a continuous feed of probe results. Just vibes streaming in, forever.
• cmdtray — continuous input feed, used by the tray icon to send commands to the daemon. Little tray icon, big responsibilities 🎀.
• stoppanels — makes connected tray icons quit. Useful for installers that need to update their executable. Eviction notice, but make it cute 🧚.
• stop — stops the daemon. Periodt. That's it, that's the whole command.

---

🌈 THE DNSSEC-TRIGGER-CONTROL-SETUP TOOL 🌈

Hiii, this one aids setup of files 💖.

With no arguments at all, it creates the key files. And if the key files already exist? Then it resigns certificates with the existing private keys. No wasted effort, we reuse, we recycle 💅.

Add -d dir and the files get placed in the directory you gave it. Choose your own adventure, choose your own folder.

With -i the tool changes configuration files. Here's the whole rundown, bestie, don't skip:

• It tests if unbound has remote-control: control-enable: yes, and if not, it 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, and 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 just do the configuration manually. Do not blindly trust, bestie. Do your own vibe check 🙈.

With -u it removes the options it enabled in unbound.conf(5). Undo button, but make it terminal ✨.

---

🎀 FILES 🎀

• /etc/dnssec-trigger/dnssec-trigger.conf — the default configuration file. The main character config, the one everyone's looking for 👑.
• /etc/dnssec-trigger — the directory with keys used for SSL connections to dnssec-triggerd. Secret little key stash 🔐.
• /run/dnssec-triggerd.pid — the default pidfile with the pid of the running dnssec-triggerd. Her birth certificate, basically 💀.

---

⭐ SEE ALSO ⭐

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

Go read those too, bestie, they're the supporting cast and they ate 🍓.

---

💜 AUTHORS 💜

This program was developed by Wouter Wijngaards at NLnet Labs. Legend behaviour, honestly. Give them their flowers 💐.

---

And that's a wrap on this page 🦋 — brought to you by NLnet Labs, version-dated 2018-06-25, living in the dnssec-trigger(8) section of the manual. Now go forth and DNSSEC responsibly, my love. No cap 💅✨