Getting the Packages

Debian-based

Prerequisites

Make sure you have all the build requirements installed:

apt install git make golang build-essential

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:

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 respecive repos:

Enable the repositories in your package manager:

dnf

dnf copr enable @dnstapir/edge-testing

zypper

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

dnf install dnstapir-pop dnstapir-cli dnstapir-edm

zypper

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.

Generating Configuration Without Enrolling

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

sudo -g dnstapir dnstapir-cli --standalone enroll -L path/to/response -c path/to-credentials

This will use information in a local copy of a response 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.

Edge services

In addition to a recursive resolver, an Edge installation consists of three services.

`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. It receives observations about domain names over MQTT and, based on a locally configured policy, produces an RPZ zone which it transfers to a recursive resolver.

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

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

Start the services

sudo systemctl start dnstapir-pop
sudo systemctl start dnstapir-edm
sudo systemctl start dnstapir-renew

Enable the services

sudo systemctl enable dnstapir-pop
sudo systemctl enable dnstapir-edm
sudo systemctl enable dnstapir-renew

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.

DNS TAPIR Technical Documentation

Getting the Packages

Debian-based

Prerequisites

Building the Package

RPM-based

dnf

zypper

dnf

zypper

Building an RPM Package Locally

Managing permissions

Enrolling with the DNS TAPIR Node Manager

Generating Configuration Without Enrolling

Edits to the Configuration Boilerplate

pop-outputs.yaml

dnstapir-pop.yaml

dnstapir-edm.toml

Edge services

`dnstapir-pop`

`dnstapir-renew`

`dnstapir-edm`

Installation footprint

Users and Groups

Files and Folders

Start the services

Enable the services

Sample Config for Resolvers

Unbound

Post-installation

Keyboard shortcuts

DNS TAPIR Technical Documentation