Installing PiHole on a Raspberry Pi for SplitDNS

Introduction

3CX PBX requires either Hairpin NAT or Split-Brain DNS to function correctly. This guide is intended to cover the set up and installation of PiHole, a DNS Server that can satisfy the Split-Brain DNS requirement, on a Raspberry Pi. In this guide, we assume the 3CX Server has an internal IP address of 192.168.3.155 and PiHole has an internal IP address of 192.168.3.154. We also use a public IP address of 1.2.3.4 and an FQDN of “service.tigunia.com” in the validation screenshots (Step 8).

Step 1: Get the correct Raspberry Pi

  • Any Raspberry Pi that supports Raspberry Pi OS (formerly Raspbian). Both Buster and Bullseye are supported at the time of this article’s publication. You need at least 512mb of RAM.
  • A 4+GB Micro SDHC
  • A Raspberry Pi-compatible 2.5 Amp Micro USB power supply
  • Ensure the device has a good casing that allows for maximum cooling

Step 2: Prepare the SD card with Raspbian

1. Download the Raspbian image from https://www.raspberrypi.com/software/ to a computer with an SD card reader. Put the SD card you'll use with your Raspberry Pi into the reader and run Raspberry Pi Imager.

Step 3: Install Raspbian and configure options

1.    Insert the SD card in the Raspberry Pi memory card slot and connect the power cord.

2.    Wait for the boot process to complete and login with the default user “pi” and password “raspberry”.

3.    Run the Raspbian configuration utility with the command: sudo raspi-config

4.    Select “1. System Options” and press the <Enter> key.

5.    Select “S4 Hostname”, press the <Enter> key and then “OK” on the warning dialog.

6.    Enter the Pi's hostname using only alphanumeric characters and dashes (“-”).

7.    Set any other options as desired, including a secure password or enabling SSH.

8.    Select <Finish> and then <Yes> to reboot and apply the configuration.

Step 4: Set a Static IP

1.      Edit the “/etc/dhcpcd.conf” file to configure the ethernet interface “eth0” with the nano editor: sudo nano /etc/dhcpcd.conf

2.    Scroll to the end of the file and add the following lines, making sure to replace the values for “interface”, “ip_address”, “routers” (gateway) and “domain_name_servers” based on your LAN settings:

#Ethernet static IP configuration

interface eth0

static ip_address=192.168.3.154/24

static routers=192.168.3.1

static domain_name_servers= 8.8.8.8

Note: LAN installs are supported on properly configured RFC 1918 private networks, i.e. 172.16.0.0 /10.0.0.0/192.168.0.0 IP range.

3.    Press the “Ctrl” + “x” key combination, then “y” and <Enter> to confirm writing changes to the file.

4.    Reboot the Pi using: sudo reboot

5.    When the Pi boots again, login with “pi” user and verify “eth0” IP address with the command: ip a

Step 5: Install PiHole

1.    Log in to the Pi and execute the following command to install PiHole: curl -sSL https://install.pi-hole.net | bash

2.    Follow the setup wizard to complete the install:

  1. You can choose Google as the upstream DNS Provider
  2. You do not need to include any blacklists
  3. You do want to install the Admin Interface
  4. You do not need to enable query logging

3. At the end of the install, PiHole will provide the IP and Password. Note these down for the next step. If you forget the password, you can reset it to “piholeguide” with the following command: pihole -a -p piholeguide

Step 6: Configure PiHole

1.    Connect in to the PiHole web admin interface (https://192.168.3.154/admin) and select login


2.    Navigate to the “Local DNS” section on the left and add a custom record. Enter your 3CX FQDN in the Domain field and your internal IP of your 3CX server in the IP Address field.


Step 7: Set PiHole as your DNS Server

You need to direct queries from your 3CX endpoints (such as IP Phones, Webclients, and softphones) to PiHole in order to get correct DNS resolution inside your network. This can be accomplished a few ways, including setting static DNS servers on these endpoints, updating your DHCP server options to set PiHole as the DNS server when it issues a lease, or configuring PiHole to be the upstream DNS resolver for your existing DNS server. PiHole can even act as your DHCP server if required, although that configuration is beyond the scope of this guide. As many different DHCP and DNS servers exist, this guide will not be able to show you the direct steps for each one. Please consult your DHCP or DNS server manual for more information.

Step 8: Validating Your Setup

To validate your Split Brain DNS setup, you can use the nslookup tool (inside the network / behind your PiHole DNS Server) to validate how DNS is resolved. Simply type “nslookup <fqdn> <dns-server>” where <fqdn> is your 3CX FQDN and <dns-server> is the IP of the DNS server you wish to query. When querying an external DNS server you should see your WAN IP returned and when querying your internal PiHole DNS Resolver you should see the internal IP address of the 3CX Phone System returned.

1.    The below example shows checking the external IP resolution of FQDN “service.tigunia.com” against Google’s public DNS servers (8.8.8.8):


2.    The below example shows checking the internal IP resolution of FQDN “service.tigunia.com” against your internal PiHole Resolver (192.168.3.154):

Special thanks to 3CX Gold Partner, Tigunia, and Martin Twerski for this guide.

Last Updated

This document was last updated 23 October 2023

https://www.3cx.com/docs/raspberry-pi-split-dns