diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..1206e5b --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,66 @@ +# TAPIR-POP INSTALLATION + +TAPIR-POP is most commonly installed as a Docker container, but it can also be run as a separate binary. +This document focuses on the latter alternative. + +## Building TAPIR-POP + +Two DNS TAPIR github repositories are relevant to the installation of TAPIR-POP: + +* [tapir-pop](https://github.com/dnstapir/tapir-pop) - contains the TAPIR-POP server + +TAPIR-POP relies heavily on code from the [tapir](https://github.com/dnstapir/tapir) repository. + +Commands to build the TAPIR-POP service are: + +``` +git clone https://github.com/dnstapir/tapir-pop +cd tapir-pop +go mod tidy +make +[examine and edit the Makefile to set the INSTALL_DIR to something other than /usr/local/libexec] +make install +``` + +## Configuring TAPIR-POP + +By default, TAPIR-POP will look for a configuration files in the directory `/etc/dnstapir`. The primary configuration file is `/etc/dnstapir/tapir-pop.yaml`. If the file is not found, the program will terminate with an error. + +In addition to the main configuration file, TAPIR-POP will look for a three more configuration files: + +* `/etc/dnstapir/pop-sources.yaml` - contains the configuration for the sources of data that TAPIR-POP will use for policy decisions. +* `/etc/dnstapir/pop-policy.yaml` - contains the local policy configuration for TAPIR-POP. This is instructions for what conditions must be met for a domain name to be filtered. +* `/etc/dnstapir/pop-outputs.yaml` - contains the configuration for various outputs that TAPIR-POP will use. The primary output is always a DNS RPZ zone that is sent to a "downstream" DNS resolver. Additional outputs may be configured, such as more RPZ targets and a local MQTT reflector (to enable local monitoring of the observations that arrive from TAPIR-CORE). + +The configuration files are described in their own README files. + +## Connecting TAPIR-POP to TAPIR-CORE + +The primary requisite is a client certificate and key for the TAPIR-POP server issued by the TAPIR-CORE CA. To obtain these, run the script +`generate-csr.sh` and follow the instructions. The script is only a few lines long and is easy to follow. It takes one parameter, which is a TAPIR "instance id". This is needed to ensure that the CSR is unique. + +The result is a file named `tapir-instance-id.csr` and a file named `tapir-instance-id.key`. The CSR file is sent manually to the TAPIR-CORE for signing and in return the TAPIR-CORE will return a signed certificate in a file named `tapir-instance-id.crt`. We recommend that both the `.crt` and `.key` files are stored in the `/etc/dnstapir/certs` directory, and that this directory has restricted access. + +Once the certificate and key are in place, the exact location of these files must be specified in the `/etc/dnstapir/tapir-pop.yaml` configuration file +under the keys `tapir.mqtt.clientcert` and `tapir.mqtt.clientkey`. + +*** TODO: add stuff on creation of the signingkey + +## Running TAPIR-POP + +Before starting TAPIR-POP, ensure that the TAPIR-CLI utility is built and installed: + +* [tapir-cli](https://github.com/dnstapir/tapir-cli) - contains the TAPIR-CLI utility that is used to interact with the TAPIR-POP service. + +TAPIR-CLI is described in its own README and installation instructions. + +When the TAPIR-CLI utility is installed, the TAPIR-POP service can be started with the following command: + +``` +tapir-pop -v & +``` + +## Examining the TAPIR-POP logs + +By default several log files are created in the `/var/log/dnstapir` directory. The log files are named `tapir-pop.log`, `pop-policy.log`, +`pop-dnsengine.log` and `pop-mqtt.log`. \ No newline at end of file diff --git a/README.md b/README.md index 5183e18..dc24de4 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,31 @@ -# tem: DNS TAPIR Edge Manager +# tapir-pop: DNS TAPIR Policy Processor -The *DNS TAPIR Edge manager*, TEM, is the connection between the core and the +The *DNS TAPIR Policy Processor*, TAPIR-POP, is the component that processes the intelligence data from the TAPIR-CORE +(and possibly other sources) and applies local policy to reach a filtering decision. + +It is the connection between the core and the edge platform. It manages local configurations and gets updates from the core with alerts and config changes. -TEM is responsible for the task of integrating all intelligence sources +TAPIR-POP is responsible for the task of integrating all intelligence sources into a single Response Policy Zone (RPZ) that is as compact as possible. The RPZ file is used by the DNS resolver to implement blocklists and other policy-related functions. ## A unified single RPZ zone instead of multiple sources -TEM presents a single output with all conflicts resolved, +TAPIR-POP presents a single output with all conflicts resolved, rather than feeding the resolver multiple sources of data from which to look for policy guidance, where sources can even be conflicting (eg. a domainname may be flagged by one source but whitelisted by another). The result is smaller, as no whitelisting information is needed for the resolver. -## TEM supports a local policy configuration +## TAPIR-POP supports a local policy configuration -TEM is able to apply further policy to the intelligence data, +TAPIR-POP is able to apply further policy to the intelligence data, based on a local policy configuration. To enable the resolver operator to -design a suitable threat policy TEM uses a number of concepts: +design a suitable threat policy TAPIR-POP uses a number of concepts: - __lists__: there are three types of lists of domain names: @@ -30,7 +33,7 @@ design a suitable threat policy TEM uses a number of concepts: - blacklists (names that must be blocked) - greylists (names that should perhaps be blocked) -- __tags__: these are attributes of a suspicious domain name. In reality +- __observations__: these are attributes of a suspicious domain name. In reality whether a particular domain name should be blocked or not is not an absolute, it is a question of propabilities. Therefore, rather than a binary directive, "this name must be blocked", some intelligence @@ -51,13 +54,13 @@ design a suitable threat policy TEM uses a number of concepts: - __CSV Files__: Text files on local disk, either with just domain names, or in CSV format are supported. - __HTTPS__: To bootstrap an intelligence feed that only distributes deltas - (like DNS TAPIR, over MQTT), TEM can bootstrap the current state of the - complete feed via HTTPS. [NYI] + (like DNS TAPIR, over MQTT), TAPIR-POP can bootstrap the current state of the + complete feed via HTTPS. -- __outputs__: TEM outputs RPZ zones to one or several recipients. Both AXFR and IXFR - is supported +- __outputs__: TAPIR-POP outputs RPZ zones to one or several recipients. Both AXFR and IXFR + is supported. -## Overview of the TEM policy +## Overview of the TAPIR-POP policy The resulting policy has the following structure (in order of precedence): diff --git a/generate-csr.sh b/generate-csr.sh index c58657f..3b749f4 100755 --- a/generate-csr.sh +++ b/generate-csr.sh @@ -2,14 +2,13 @@ if [ $# != 1 ]; then echo Usage: $0 instance-id - echo \"instance-id\" is a string that you choose yourself that will identify this DNS TAPIR Edge instance. - echo A domain name is usually a good idea. + echo \"instance-id\" is a string that you receive from TAPIR Core that will identify this DNS TAPIR Edge instance. exit 1 fi id=$1 -echo Your chosen DNS TAPIR Edge Id is \"$id\". +echo Your DNS TAPIR Edge Id is \"$id\". /bin/echo -n "Proceed [yes]: " default_ans="yes" read answer