Docs 1

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

README.md

@@ -1,36 +1,39 @@
-# 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:
 
   - whitelists (names that must not be blocked)
   - 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):
 

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