Skip to content

Commit 699cb1d

Browse files
mxsashamxsasha
committed
Fix #1228 - Separate DNS docs and add notes on MX, FCrDNS/SPF/DKIM/DMARC
1 parent b3c8713 commit 699cb1d

File tree

3 files changed

+91
-49
lines changed

3 files changed

+91
-49
lines changed

‎documentation/Docker-DNS.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Docker DNS setup
2+
3+
There are several DNS components in the Docker setup:
4+
5+
* A non-validating resolver, used for DNS resolving by almost all tests.
6+
As we have our own DNSSEC validation test, we want to see bogus responses as well.
7+
* A validating resolver, used to validate DANE records through ldns-dane.
8+
* An authoritative server for the connection test zone.
9+
* The DNS records in the zone for `INTERNETNL_DOMAINNAME`.
10+
These are hosted elsewhere, but have certain requirements for the instance to work.
11+
12+
The resolvers do not require any specific configuration.
13+
In this document, `INTERNETNL_DOMAINNAME` is `example.com`.
14+
15+
## Common parts
16+
17+
For accessing the absolute minimum basic functionality of the application the following DNS records must be configured:
18+
19+
example.com. A 192.0.2.1
20+
AAAA 2001:db8:1::1
21+
22+
The following extra records must be configured for language switching:
23+
24+
www.example.com. CNAME example.com.
25+
nl.example.com. CNAME example.com.
26+
en.example.com. CNAME example.com.
27+
28+
The hostname (`INTERNETNL_DOMAINNAME`) should have SPF, DKIM and DMARC,
29+
as some mail servers may filter on this, and it could affect mail tests.
30+
For a domain that does not otherwise send email, use:
31+
32+
example.com. TXT "v=spf1 a -all" ; The "a" mechanism is needed for the mail test (see rfc7208, section-2.3).
33+
_domainkey.example.com. TXT "v=DKIM1; p=" ; empty DKIM to score 100% for this non-sending subdomain that does have SPF "a" mechanism which is needed for mail test.
34+
_dmarc.example.com. TXT "v=DMARC1; p=reject; sp=reject;"
35+
36+
The `INTERNETNL_DOMAINNAME` host should also have a working MX and correct FCrDNS.
37+
38+
39+
## Specific settings for batch mode
40+
41+
For batch, the connection test is not used, and the authoritative server should not be publicly available.
42+
Set `IPV4_IP_PUBLIC=127.0.0.1` and `IPV6_IP_PUBLIC=::1` in `docker/host.env`.
43+
44+
45+
## Specific settings for single test mode
46+
47+
The single test instance also has an IPv6-only host:
48+
49+
ipv6.example.com. AAAA 2001:db8:1::1
50+
www.ipv6.example.com. CNAME ipv6.example.com.
51+
nl.ipv6.example.com. CNAME ipv6.example.com.
52+
en.ipv6.example.com. CNAME ipv6.example.com.
53+
54+
For the connection test the following records are also required:
55+
56+
conn.example.com. CNAME example.com.
57+
en.conn.example.com. CNAME example.com.
58+
nl.conn.example.com. CNAME example.com.
59+
www.conn.example.com. CNAME example.com.
60+
61+
conn.ipv6.example.com. CNAME ipv6.example.com.
62+
nl.conn.ipv6.example.com. CNAME ipv6.example.com.
63+
en.conn.ipv6.example.com. CNAME ipv6.example.com.
64+
www.conn.ipv6.example.com. CNAME ipv6.example.com.
65+
66+
test-ns-signed.example.com. NS example.com.
67+
test-ns6-signed.example.com. NS ipv6.example.com.
68+
69+
The Docker image will create two DNS zones, served by the authoritative server.
70+
These are signed, and therefore also require the correct `DS` records.
71+
72+
Obtain the `DS` records by inspecting the logs of the `unbound` service and
73+
finding the 2 lines beneath `Please add the following DS records for domain`:
74+
75+
$ docker logs internetnl-prod-unbound-1 2>&1 | grep -A2 "Please add the following DS records for domain"
76+
Please add the following DS records for domain example.com:
77+
test-ns-signed.example.com. IN DS 55295 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
78+
test-ns6-signed.example.com. IN DS 33292 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
79+
80+
Then, configure those two DS records in their parent zone.
81+
82+
You can verify DNSSEC using:
83+
84+
- https://dnsviz.net/d/test.a.conn.test-ns-signed.example.com/dnssec/
85+
- https://dnsviz.net/d/test.aaaa.conn.test-ns-signed.example.com/dnssec/
86+

‎documentation/Docker-deployment-batch.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,10 @@ Create database indexes:
127127

128128
docker compose --project-name=internetnl-prod exec app ./manage.py api_create_db_indexes
129129

130+
## DNS setup
131+
132+
See the [Docker DNS setup](Docker-DNS.md).
133+
130134
## Managing users
131135

132136
To manage users, call the `/opt/Internet.nl/docker/batch_user.sh` script. This takes two arguments: an operation

‎documentation/Docker-deployment.md

Lines changed: 1 addition & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -119,55 +119,7 @@ This command will take a long time (up to 30 minutes) due to RPKI data that need
119119

120120
## DNS setup
121121

122-
For accessing the absolute minimum basic functionality of the application the following DNS records must be configured:
123-
124-
example.com A 192.0.2.1
125-
AAAA 2001:db8:1::1
126-
127-
The following extra records must be configured for language switching and IPv6 only hostname:
128-
129-
www.example.com CNAME example.com
130-
nl.example.com CNAME example.com
131-
en.example.com CNAME example.com
132-
133-
ipv6.example.com AAAA 2001:db8:1::1
134-
www.ipv6.example.com CNAME ipv6.example.com
135-
nl.ipv6.example.com CNAME ipv6.example.com
136-
en.ipv6.example.com CNAME ipv6.example.com
137-
138-
For the "Test your connection" test the following records are required:
139-
140-
conn.example.com CNAME example.com
141-
en.conn.example.com CNAME example.com
142-
nl.conn.example.com CNAME example.com
143-
www.conn.example.com CNAME example.com
144-
145-
conn.ipv6.example.com CNAME ipv6.example.com
146-
nl.conn.ipv6.example.com CNAME ipv6.example.com
147-
en.conn.ipv6.example.com CNAME ipv6.example.com
148-
www.conn.ipv6.example.com CNAME ipv6.example.com
149-
150-
test-ns-signed.example.com NS example.com
151-
test-ns6-signed.example.com NS ipv6.example.com
152-
153-
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.
154-
155-
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`:
156-
157-
$ docker logs internetnl-prod-unbound-1 2>&1 | grep -A2 "Please add the following DS records for domain"
158-
Please add the following DS records for domain example.com:
159-
test-ns-signed.example.com. IN DS 55295 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
160-
test-ns6-signed.example.com. IN DS 33292 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
161-
162-
Configure these two DS records:
163-
164-
test-ns-signed.example.com. IN DS 55295 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
165-
test-ns6-signed.example.com. IN DS 33292 8 2 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
166-
167-
You can verify DNSSEC using:
168-
169-
- https://dnsviz.net/d/test.a.conn.test-ns-signed.example.com/dnssec/
170-
- https://dnsviz.net/d/test.aaaa.conn.test-ns-signed.example.com/dnssec/
122+
See the [Docker DNS setup](Docker-DNS.md).
171123

172124
## Testing your installation
173125

0 commit comments

Comments
 (0)