Install DNS Relay using Docker

Minetta Gould Community Team

DNSFilter Staff

October 16, 2024 13:13
Edited

Installing the DNSFilter Relay with Docker is quick and easy. Follow this post to complete the install.

The recommended specs for this deployment are 64-bit 2-core CPU; 2GB of RAM.

Install Docker and Docker Compose on your device
Create a new folder and add these two files:
1. The relay.conf file
  1. From the DNSFilter dashboard, populate the generated or manual relay.conf file following the standard method. Select the Docker Container for the download
2. The docker-compose.yml file
```
version: '3'

services:
  relay:
    image: dnsfilter/relay:latest
    network_mode: host
    volumes:
      - ./relay.conf:/go/bin/relay.conf
      - ./relay.reg:/go/bin/relay.reg
    restart: unless-stopped
```
Create an empty file named relay.reg

🚨 Important: Once the container runs, it will populate this file with the registration information for the Relay, so that it persists. Without this file, every time you start and stop the Relay, it would create a new copy in the DNSFilter dashboard.
Open a Terminal window in the same folder as the files
Start the Relay container:
```
docker-compose up -d && docker-compose logs -f
```
The container will start up and you will see log output.
If applicable, set the IP address of the device running this container as the DNS for another device on your network. The queries from that device should immediately be visible in the log output

The DNS Relay is now operating and filtering DNS traffic. Confirm by navigating to the DNS Query Log and checking for logged traffic (traffic can take up to 5 minutes to populate).

Run this command to shut down the container:

docker-compose down

Notes on the Docker Container

This file defines that Docker should:

Download the dnsfilter/relay:latest image from Docker Hub
Bind to the networks of the host machine
Use the relay.conf file in the folder, and restart if stopped

Comments

7 comments

Jeremy Felpel

October 15, 2024 22:41
Can you provide a standard docker-compose.yaml file?
Does the Docker image support any ENV variables?
0
Bailey Taylor Community Manager DNSFilter Staff

October 16, 2024 13:22
Jeremy Felpel Thank you for bringing this to our attention; our docker install instructions have been updated to include the docker-compose.yaml file!
1
Jeremy Felpel

October 16, 2024 15:43
Bailey Taylor Thank you! I'll try it out shortly!

If it works well, DNSFilter may well be the newest edition to the stack I roll out to my customers!!!
0
Eric Nix

November 30, 2024 19:44
Will this work with Synology's new Container Manager?
Can you provide a sample setup where VLANs query separate policies (via NAT – hopefully via DoT)?
0
Bailey Taylor Community Manager DNSFilter Staff

December 02, 2024 21:52

Edited
Eric Nix It should work, but I suggest reviewing this Docker on Synology NAS video for more details. If you run into any issues, Synology might be your best source to get answers on their capabilities!
Docker on Synology NAS
As an example of VLANs I've shared the following

1. Overview
- DNS-over-TLS Hostnames:
  
  dns1.dnsfilter.com (Primary)
  
  dns2.dnsfilter.com (Secondary)
- DNS Ports:
  DoT communicates over port 853.
- Policy Separation: VLANs route DNS requests to DNSFilter using NAT, and DNSFilter applies policies based on the source IP address of the requests.
2. VLAN Setup
- VLAN 10 (Office):
  
  Subnet: 192.168.10.0/24
  
  Gateway: 192.168.10.1
  
  DNS Policy: Strict Filtering (Policy A).
- VLAN 20 (Guest):
  
  Subnet: 192.168.20.0/24
  
  Gateway: 192.168.20.1
  
  DNS Policy: General Filtering (Policy B).
3. Router/Firewall Configuration
Firewall Rules
1. Allow DoT Traffic:
  Permit DNS traffic (port 853) from the VLAN subnets to dns1.dnsfilter.com and dns2.dnsfilter.com.
2. Block Direct DNS Traffic:
  Deny DNS traffic (port 53) from the VLAN subnets to external DNS servers to enforce policy.
NAT Rules
Create NAT rules to redirect all DNS requests from VLANs to the DoT hostnames:
- VLAN 10: NAT DNS traffic to dns1.dnsfilter.com.
- VLAN 20: NAT DNS traffic to dns2.dnsfilter.com.
4. Configure DNS Forwarder (Optional)
If your router supports a local DNS forwarder, configure it to forward DNS queries securely to DNSFilter’s DoT endpoints.
Configuration Example
```
server:
  interface: 0.0.0.0
  access-control: 192.168.10.0/24 allow
  access-control: 192.168.20.0/24 allow
  tls-cert-bundle: "/etc/ssl/certs/ca-certificates.crt"

forward-zone:
  name: "."
  forward-tls-upstream: yes
  forward-addr: dns1.dnsfilter.com@853  # VLAN 10 (Strict Filtering)
  forward-addr: dns2.dnsfilter.com@853  # VLAN 20 (General Filtering)
```
This configuration sends DNS requests securely via TLS and ensures policy separation based on the source IP.
5. Testing
DNS Query Test
- From a device in VLAN 10:
  
  Run: dig @dns1.dnsfilter.com example.com or nslookup example.com.
  
  Verify requests resolve via Policy A.
- From a device in VLAN 20:
  Run the same test, verifying requests resolve via Policy B.
DNSFilter Logs
- Check the DNSFilter dashboard to confirm:
  
  VLAN 10 IP range is mapped to Policy A.
  
  VLAN 20 IP range is mapped to Policy B.
Packet Capture (Optional)
- Use packet capture tools (e.g., Wireshark) to confirm DNS queries are sent over port 853 and are encrypted.
This configuration ensures that VLAN-specific DNS policies are enforced using DNSFilter and all DNS traffic is securely tunneled via DoT.
0
Eric Nix

December 03, 2024 00:22
Bailey Taylor Thank you for that detailed post!!
I know how to assign NATs to different policies, but how do you assign different DoT policies? i.e., dns1 primary, first NAT dns2, etc.? How many can you have?
Thanks again!
0
Bailey Taylor Community Manager DNSFilter Staff

December 03, 2024 15:09
Eric Nix If you're looking to assign different policies based on where the devices are located (e.g., in specific VLANs), a good approach would be to set up a separate container for each VLAN. Each container can serve DNS requests for its respective VLAN and be configured with a unique client ID. You can then assign a different DNSFilter policy to each client ID, ensuring that devices in each VLAN follow the appropriate policy.
Also, we do not maintain a specific limit on the number of Relays you can deploy within your network!
0