Fix #1228 - Separate DNS docs and add notes on MX, FCrDNS/SPF/DKIM/DM…

…ARC (#1298) (cherry picked from commit 5c40de0)
internetstandards · Mar 26, 2024 · 34b6182 · 34b6182
1 parent 8c503ec
commit 34b6182
Show file tree

Hide file tree

Showing 4 changed files with 87 additions and 51 deletions.
diff --git a/docker/webserver/certbot.sh b/docker/webserver/certbot.sh
@@ -15,9 +15,9 @@ else
 fi
 
 domain=$INTERNETNL_DOMAINNAME
-subdomains="nl.$domain,en.$domain,ipv6.$domain,nl.ipv6.$domain,en.ipv6.$domain"
+subdomains="nl.$domain,en.$domain,www.$domain,ipv6.$domain,nl.ipv6.$domain,en.ipv6.$domain"
 if [ "$ENABLE_BATCH" != True ]; then
-  subdomains="$subdomains,www.$domain,conn.$domain,en.conn.$domain,nl.conn.$domain,www.conn.$domain,conn.ipv6.$domain,en.conn.ipv6.$domain,nl.conn.ipv6.$domain,www.conn.ipv6.$domain"
+  subdomains="$subdomains,conn.$domain,en.conn.$domain,nl.conn.$domain,conn.ipv6.$domain,en.conn.ipv6.$domain,nl.conn.ipv6.$domain,www.conn.ipv6.$domain"
 fi
 if [ ! -z $REDIRECT_DOMAINS ];then
   subdomains="$subdomains,$REDIRECT_DOMAINS"

diff --git a/documentation/Docker-DNS.md b/documentation/Docker-DNS.md
@@ -0,0 +1,80 @@
+# Docker DNS setup
+
+There are several DNS components. First, there are the following three Docker containers:
+
+1. A non-validating resolver, used for DNS resolving by almost all tests. As we have our own DNSSEC validation test, we want to see bogus responses as well.
+2. A validating resolver, used to validate DANE records through ldns-dane.
+3. An authoritative name server for the connection test zone.
+
+Besides, an authoritative name server that should be hosted elsewhere, is needed for the DNS records in the zone for `INTERNETNL_DOMAINNAME`. 
+
+The resolvers (1 and 2) do not require any specific configuration.
+In this document, `INTERNETNL_DOMAINNAME` is `example.com`. Furthermore, example IP addresses are used.
+
+## Common parts
+
+Note that typically, you would use `$ORIGIN example.com.` in your zone, allowing for these suffixes to be removed.
+
+For accessing the absolute minimum basic functionality of the application the following DNS records must be configured:
+
+    example.com.                    A      192.0.2.1
+                                    AAAA   2001:db8:1::1
+    www.example.com.                CNAME  example.com.
+    nl.example.com.                 CNAME  example.com.
+    en.example.com.                 CNAME  example.com.
+    ipv6.example.com.               AAAA   2001:db8:1::1
+    nl.ipv6.example.com.            CNAME  ipv6.example.com.
+    en.ipv6.example.com.            CNAME  ipv6.example.com.
+
+The hostname (`INTERNETNL_DOMAINNAME`) should have SPF, DKIM and DMARC,
+as some mail servers may filter on this, and it could affect mail tests.
+For a domain that does not otherwise send email, use:
+
+    example.com.		               TXT	"v=spf1 a -all"	; The "a" mechanism is needed for the mail test (see rfc7208, section-2.3).
+    *._domainkey.example.com.	     TXT	"v=DKIM1; p="	; empty DKIM, also to score 100% for this non-sending subdomain that does have SPF "a" mechanism which is needed for mail test.
+    _dmarc.example.com.	           TXT	"v=DMARC1; p=reject; sp=reject;"
+
+    ; optionally set an CAA record to Let's Encrypt or any other used ACME supporting certificate authority (note that if CAA is used, the correct certificate authority must be present)
+    ; example.com.                 CAA 0 issue "letsencrypt.org;"
+
+The `INTERNETNL_DOMAINNAME` host should also have a working MX and correct FCrDNS.
+DANE records are recommended, but not required.
+
+## Specific settings for batch mode
+
+For batch, the connection test is not used, and the authoritative name server should not be publicly available.
+Set `IPV4_IP_PUBLIC=127.0.0.1` and `IPV6_IP_PUBLIC=::1` in `docker/host.env`.
+
+## Specific settings for connection test in single test mode
+
+For the connection test the following records are also required (i.e., not needed for batch mode):
+
+    conn.example.com.               CNAME  example.com.
+    en.conn.example.com.            CNAME  example.com.
+    nl.conn.example.com.            CNAME  example.com.
+
+    conn.ipv6.example.com.          CNAME  ipv6.example.com.
+    nl.conn.ipv6.example.com.       CNAME  ipv6.example.com.
+    en.conn.ipv6.example.com.       CNAME  ipv6.example.com.
+
+    test-ns-signed.example.com.     NS     example.com.
+    test-ns6-signed.example.com.    NS     ipv6.example.com.
+
+The Docker image will create two DNS zones, served by the authoritative name server for the connection test zone.
+These are signed, and therefore also require the correct `DS` records.
+
+Obtain the `DS` records by inspecting the logs of the `unbound` service and
+finding the 2 lines beneath `Please add the following DS records for domain`:
+
+    $ docker logs internetnl-prod-unbound-1 2>&1 | grep -A2 "Please add the following DS records for domain"
+    Please add the following DS records for domain example.com:
+    test-ns-signed.example.com.   IN  DS  55295 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    test-ns6-signed.example.com.  IN  DS  33292 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+
+Then, configure those two DS records in their parent zone.
+
+You can verify DNSSEC using:
+
+  - https://dnsviz.net/d/test.a.conn.test-ns-signed.example.com/dnssec/
+  - https://dnsviz.net/d/test.aaaa.conn.test-ns-signed.example.com/dnssec/
+
diff --git a/documentation/Docker-deployment-batch.md b/documentation/Docker-deployment-batch.md
@@ -129,6 +129,10 @@ Create database indexes:
 
     docker compose --project-name=internetnl-prodexec app ./manage.py api_create_db_indexes
 
+## DNS setup
+
+See the [Docker DNS setup](Docker-DNS.md).
+
 ## Managing users
 
 To manage users, call the `/opt/Internet.nl/docker/batch_user.sh` script. This takes two arguments: an operation

diff --git a/documentation/Docker-deployment.md b/documentation/Docker-deployment.md
@@ -119,55 +119,7 @@ This command will take a long time (up to 30 minutes) due to RPKI data that need
 
 ## DNS setup
 
-For accessing the absolute minimum basic functionality of the application the following DNS records must be configured:
-
-    example.com                    A      192.0.2.1
-                                   AAAA   2001:db8:1::1
-
-The following extra records must be configured for language switching and IPv6 only hostname:
-
-    www.example.com                CNAME  example.com
-    nl.example.com                 CNAME  example.com
-    en.example.com                 CNAME  example.com
-
-    ipv6.example.com               AAAA   2001:db8:1::1
-    www.ipv6.example.com           CNAME  ipv6.example.com
-    nl.ipv6.example.com            CNAME  ipv6.example.com
-    en.ipv6.example.com            CNAME  ipv6.example.com
-
-For the "Test your connection" test the following records are required:
-
-    conn.example.com               CNAME  example.com
-    en.conn.example.com            CNAME  example.com
-    nl.conn.example.com            CNAME  example.com
-    www.conn.example.com           CNAME  example.com
-
-    conn.ipv6.example.com          CNAME  ipv6.example.com
-    nl.conn.ipv6.example.com       CNAME  ipv6.example.com
-    en.conn.ipv6.example.com       CNAME  ipv6.example.com
-    www.conn.ipv6.example.com      CNAME  ipv6.example.com
-
-    test-ns-signed.example.com     NS     example.com
-    test-ns6-signed.example.com    NS     ipv6.example.com
-
-For connectin test two signed DNS zones are created and served by the application using Unbound. For this to work properly the delegating zone must also serve the correct `DS` records.
-
-Obtain the `DS` records by inspecting the logs of the `unbound` service and finding the 2 lines beneath `Please add the following DS records for domain`:
-
-    $ docker logs internetnl-prod-unbound-1 2>&1 | grep -A2 "Please add the following DS records for domain"
-    Please add the following DS records for domain example.com:
-    test-ns-signed.example.com.   IN  DS  55295 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-    test-ns6-signed.example.com.  IN  DS  33292 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-
-Configure these two DS records:
-
-    test-ns-signed.example.com.   IN  DS  55295 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-    test-ns6-signed.example.com.  IN  DS  33292 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-
-You can verify DNSSEC using:
-
-  - https://dnsviz.net/d/test.a.conn.test-ns-signed.example.com/dnssec/
-  - https://dnsviz.net/d/test.aaaa.conn.test-ns-signed.example.com/dnssec/
+See the [Docker DNS setup](Docker-DNS.md).
 
 ## Testing your installation