In this article

This article describes how to install and configure the DNS Relay on a Raspberry Pi.

Running the DNS Relay on a Raspberry Pi provides a lightweight, low-cost option for deploying DNSFilter protection in small offices, branch locations, or test environments. 

The Raspberry Pi’s compact form factor and low resource requirements make it well-suited for environments where a dedicated server is unnecessary but reliable DNS filtering is still required.

Prerequisites

• Recommended hardware: 64-bit 2-core CPU, 2 GB RAM
• Storage: 10 GB HDD

Installation Steps

1. Generate Required Files

Follow the DNS Relay deployment guide to create and download:

• relay.config
• Linux arm64 binary (relay-linux-arm64)

2. Enable SSH on Raspberry Pi

To transfer files over SCP, enable SSH by following the Raspberry Pi SSH guide.

3. Install WinSCP

Download and install WinSCP for file transfer.

4. Connect to Raspberry Pi via WinSCP

1. Open WinSCP
2. Set File protocol to SCP
3. Enter the Raspberry Pi IP address, username, and password
4. Select Advanced → SCP/Shell and set shell to sudo su
5. Click OK, then Login
6. Upon login, the Raspberry Pi root directory displays

5. Create Relay Directory

1. Navigate to /etc
2. Right-click whitespace → New → Directory
3. Name the directory relay
4. Set permissions and confirm with OK

6. Transfer Relay Files

Copy the following into /etc/relay:

• relay.config
• Relay binary (relay-linux-arm64)

Drag and drop the files into the folder using WinSCP.

7. Run Relay Manually

Update permissions and start the relay:

sudo chmod +x /etc/relay/relay-linux-arm64
sudo /etc/relay/relay-linux-arm64

If successful, output confirms the appliance is running and listening.

Relay can also be started directly from the Raspberry Pi terminal or over SSH using PowerShell.

8. Test the Connection

Follow the testing section of the DNS Relay deployment guide to confirm successful relay operation.

9. Configure Auto-Start on Boot

Follow the Auto-start Relay guide.

Update the ExecStart path in the dnsfrelay.service file to reflect the relay binary location. For example:

[Unit]
Description=DNSFilter Relay Service
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=root
ExecStart=/etc/relay/relay-linux-arm64

[Install]
WantedBy=multi-user.target

The DNS Relay runs on the Raspberry Pi and automatically starts on reboot, providing continuous DNS protection.