Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction Edge Services

In addition to a recursive resolver, an Edge installation consists of three services as described below. This document guides you through the installation of these three services. Additionally it gives you an example of configuration options for unbound at the end.

dnstapir-pop

The dnstapir-pop service is provided by the dnstapir-pop package. It consists of a daemon process that communicates with a DNS TAPIR Core instance over MQTT and with a recursive resolver using zone transfers.

dnstapir-pop in itself is actually a DNS server that receives its observations from DNS TAPIR Core as described above and, based on a locally configured policy, produces an RPZ and initiates a zone transfer to your selected recursive resolver using DNS NOTIFY messages.

dnstapir-renew

The dnstapir-renew service is installed by the dnstapir-cli package. It automates the process of renewing mTLS certificates (used to secure the MQTT connection) by issuing dnstapir-cli commands on a systemd timer.

dnstapir-edm

The dnstapir-edm service is installed by the dnstapir-edm package. It consists of a daemon process that communicates with a recursive resolver using DNSTAP and a DNS TAPIR Core instance over MQTT and HTTPS. It receives DNSTAP data from the resolver, which it anonymizes and sends to the Core instance in aggregates using HTTPS. Certain events, such as domain names being encountered for the first time, is sent over MQTT to the same Core instance.

dnstapir-reloader

The dnstapir-reloader service is also installed by the dnstapir-edm package. It is a small workaround that makes sure that dnstapir-edm gets a SIGHUP after certificates have been renewed to trigger a reload.

Installation footprint

A typical DNS TAPIR Edge installation will have the following footprint.

Users and Groups

Users:

  • dnstapir-pop, systemd service user
  • dnstapir-edm, systemd service user
  • dnstapir-renew, systemd service user

Groups:

  • dnstapir, common group for service users and sysadmin account

Files and Folders

Files:

  • /usr/bin/dnstapir-pop, executable for DNS TAPIR POP
  • /usr/bin/dnstapir-edm, executable for DNS TAPIR EDM
  • /usr/bin/dnstapir-cli, executable for POP management and certificate renewal service
  • /usr/lib/systemd/system/dnstapir-pop.service, service unit for DNS TAPIR POP
  • /usr/lib/systemd/system/dnstapir-edm.service, service unit for DNS TAPIR EDM
  • /usr/lib/systemd/system/dnstapir-reloader.service, service unit for triggering a cert and config reload in DNSTAPIR EDM
  • /usr/lib/systemd/system/dnstapir-renew.service, service unit for certificate renewal
  • /usr/lib/systemd/system/dnstapir-renew.timer, timer unit for certificate renewal

Folders:

  • /etc/dnstapir, for configuration
  • /var/log/dnstapir, for DNS TAPIR POP logging
  • /var/lib/dnstapir/edm, for DNS TAPIR EDM runtime state

Getting the Packages

Debian-based

Prerequisites

Make sure you have all the build requirements installed:

sudo apt install git make golang build-essential

Building the Package

We currently do not provide any official debian builds. However, it is possible to build debian packages from a cloned repo. To build debian packages for an edge installation, start by cloning these repositories:

git clone https://github.com/dnstapir/pop
git clone https://github.com/dnstapir/cli
git clone https://github.com/dnstapir/edm

For each cloned repo, build the corresponding package by issuing:

make deb

Then install it with:

sudo dpkg -i path/to/package

RPM-based

DNS TAPIR provides three rpm packages for an Edge installation: dnstapir-pop, dnstapir-edm and dnstapir-cli. They are built using Fedora's public Copr instance with the @dnstapir group. Currently, packages are being built for EPEL 10, EPEL 9, Fedora 42,43 and OpenSUSE Leap 15.6.

Packages in the @dnstapir/edge-testing repo are signed with this PGP key:

07FC 9787 0134 6ED4 522A 17E7 2C4D 4FAC 02CF 0AC2

Packaging code lives side-by-side with the source code in the respective repos:

Enable the repositories in your package manager:

dnf

sudo dnf copr enable @dnstapir/edge-testing

zypper

sudo zypper ar https://copr.fedorainfracloud.org/coprs/g/dnstapir/edge-testing/repo/opensuse-leap-15.6/group_dnstapir-edge-testing-opensuse-leap-15.6.repo

And install them:

dnf

sudo dnf install dnstapir-pop dnstapir-cli dnstapir-edm

zypper

sudo zypper in dnstapir-pop dnstapir-cli dnstapir-edm

Building an RPM Package Locally

It is also possible to build and RPM package locally. This requires make, golang, rpmbuild and git. To build it, start by cloning the desired repo. This example will use pop

git clone https://github.com/dnstapir/pop

Then, change into the newly cloned repo and issue

make rpm

This will build an RPM package that can then be installed with your preferred package manager.

Managing permissions

Three system users, dnstapir-pop, dnstapir-edm and dnstapir-renew, and a group, dnstapir, will have been created. Add your administrator user to this group for easier bootstrapping and maintenance:

sudo usermod -a -G dnstapir <USERNAME>

Log out and back in and make sure the new group membership is in effect before proceeding.

Enrolling with the DNS TAPIR Node Manager

To connect with DNS TAPIR Core, an Edge node needs to be enrolled. You should have received enrollments credentials from a DNS TAPIR representative on a trusted out-of-band channel. They will look something like the following:

{
    "name":"enroll-example.test.dnstapir.se",
    "key":{
        "kty":"OKP",
        "kid":"123456789012345678901234",
        "alg":"EdDSA",
        "crv":"Ed25519",
        "x":"ABCD_EFGHIJKLMNO_PQRSTUVW_XYZ123456789_12345",
        "d":"abcdefghijklmno_pqrstuvwxyz_123456789012345"
    },
    "nodeman_url":"https://nodeman.test.dnstapir.se/"
}

Store the credentials in a file on the node that is to be enrolled. Then run:

sudo -g dnstapir dnstapir-cli --standalone enroll --enroll-credentials <PATH TO ENROLL CREDS>

The reason for running with sudo -g dnstapir is that, apart from exchanging cryptographic material with DNS TAPIR Core, the above enrollment command also generates a number of config files under /etc/dnstapir (by default). They need to have dnstapir as the group owner so that they can be used by the three system users mentioned before.

Upon success this command will generate a file of the form nodeman-resp-[UNIX TIME].json in the current working directory. If you in the future would like to re-generate the configuration boilerplate without enrolling, as described in the following section, you need to save this file.

Regenerating Configuration Without Enrolling

Sometimes it might be desirable to re-generate the configuration boilerplate without actually enrolling. This can be done by issuing:

sudo -g dnstapir dnstapir-cli --standalone enroll --enroll-credentials <PATH TO ENROLL CREDS> --local-response <PATH TO ENROLLMENT RESPONSE>

or shortly:

sudo -g dnstapir dnstapir-cli --standalone enroll -c <PATH TO ENROLL CREDS> -L <PATH TO ENROLLMENT RESPONSE>

Where <PATH TO ENROLL CREDS> is the same credentials file as above, and <PATH TO ENROLLMENT RESPONSE> is the file that the above command generates with a name of the form nodeman-resp-[UNIX TIME].json. This will in other words use the locally stored information from a previous enrollment to generate the configuration boilerplate.

Edits to the Configuration Boilerplate

The configuration generated in the enrollment step contains sensible defaults for most deployments. However, some final touches need to be made before it can be properly integrated with a recursive resolver and with DNS TAPIR Core. By default, these files will be generated under /etc/dnstapir. This guide uses the default.

pop-outputs.yaml

Edit this file where annotated (1 location) with the destination to which POP will be sending DNS NOTIFY messages about changes to the RPZ zone it has generated based on the observations from Core and on the local policies.

dnstapir-pop.yaml

Edit this file where annotated (1 location) with the interface on which POP will listen to incoming zone transfer requests for the RPZ zone it has generated.

dnstapir-edm.toml

Edit this file where annotated (2 locations) with a strong secret/password and a DNSTAP interface. The secret is used when pseudonymizing the recursive traffic with Crypto-PAn. The DNSTAP interface is the IP + port where EDM listens for DNSTAP traffic from the recursive resolver.

Start the services

sudo systemctl start dnstapir-pop.service
sudo systemctl start dnstapir-edm.service
sudo systemctl start dnstapir-renew.timer

Enable the services

sudo systemctl enable dnstapir-pop.service
sudo systemctl enable dnstapir-edm.service
sudo systemctl enable dnstapir-reload.service
sudo systemctl enable dnstapir-renew.timer

dnstapir-renew is not a daemon that keeps running, it's a program that terminates, but which needs to be run on a regular basis. Hence the .timer suffix.

dnstapir-reload is triggered whenever dnstapir-renew.service finishes and only needs to be enabled, not started.

Sample Config for Resolvers

Unbound

Note that for unbound to support DNSTAP, the flag --enable-dnstap must be passed at compile time. Make sure your unbound package is doing this. After doing so, edit unbound.conf to contain the following:

rpz:
  name:         dnstapir
  primary:      <IP>@<PORT> # Must match config in dnstapir-pop.yaml
  zonefile: 	"/var/run/unbound/dnstapir.zone"
  rpz-log:      yes
  rpz-log-name: dnstapir

dnstap:
  dnstap-enable: yes
  dnstap-ip: <IP>@<PORT> # Must match config in dnstapir-edm.yaml
  dnstap-tls: no
  dnstap-log-client-query-messages: yes
  dnstap-log-client-response-messages: yes
  dnstap-send-identity: yes
  dnstap-send-version: yes

server:
    module-config: "respip validator iterator" # "respip" module needed for RPZ

Post-installation

Check out the post-installation docs for info on how to to basic connectivity checks and verify that your Edge is running as intended.