Install or Update Pi-Hole as Docker Container on a Synology NAS with a Static IP Address

About • Built With • Prerequisites • Deployment • Usage • Contributing • Credits • Donate • License

Pi-hole is an open-source application that blocks advertisements and internet tracking on a private network. By setting up Pi-hole as DNS server on your local router, all devices connected to your network will automatically benefit from this ad-blocking feature. This script simplifies the setup of Pi-hole on a Synology network-attached storage (NAS). It uses Docker to isolate Pi-hole from the NAS. It also assigns a static IP address to the Pi-hole instance using a virtual network (macvlan) to prevent any port conflicts. At the moment, the script only supports IPv4.

The project uses the following core software components:

• Docker - Container platform (including Compose)
• Pi-hole - DNS sinkhole to block unwanted content

Synology-pihole runs on a Synology NAS with DSM 6 or later. The script has been tested with a DS918+ running DSM 7.0-41890. Other prerequisites are:

• SSH admin access is required - synology-pihole runs as a shell script on the terminal. You can enable SSH access in DSM under Control Panel ➡ Terminal & SNMP ➡ Terminal.

• Docker and Docker Compose are required - synology-pihole runs as a Docker container. Install Docker on your NAS in DSM via Package Center ➡ All Packages ➡ Docker and ensure the status is Running.

• A range of at least four local IP addresses needs to be reserved - synology-pihole assigns Pi-hole to a static IP address. To avoid any networking conflicts, a minimum range of four consecutive IP addresses need to be exclusively reserved by your DHCP server. This calculator displays the characteristics for a given IP address and netmask (the script defaults to /30). Please refer to the manual of your modem and/or DHCP server on how to reserve an IP range.

Deployment of synology-pihole is a matter of cloning the GitHub repository. Login to your NAS terminal via SSH first. Assuming you are in the working folder of your choice, clone the repository files. Git automatically creates a new folder synology-pihole and copies the files to this directory. Then change your current folder to simplify the execution of the shell script.

git clone https://github.com/markdumay/synology-pihole.git
cd synology-pihole

Synology-pihole requires sudo rights. Use the following command to invoke synology-pihole from the command line.

sudo ./syno_pihole.sh [OPTIONS] [PARAMETERS] COMMAND

As an example, the following command installs Pi-hole on your NAS at the address 192.168.0.250.

sudo ./syno_pihole.sh --ip 192.168.0.250 install

The virtual network does not persist during a reboot. Invoke the following command to recreate the network.

sudo ./syno_pihole.sh --ip 192.168.0.250 network

Run the following command to update an existing Pi-hole container if a newer version is available.

sudo ./syno_pihole.sh update

Synology-pihole supports the following commands.

In addition, the following options are available.

Synology-pihole supports several advanced settings through either command-line parameters or a .env file. An example sample.env is available in the git repository. The command-line parameters take precedence over settings in the .env file.

It is recommended to schedule a task to ensure Pi-hole uses the latest version available. Follow these steps to do so.

1. Access Task Scheduler via Control Panel ➡ Task Scheduler in DSM.
2. Now click on Create ➡ Scheduled Task ➡ User-defined script to create a custom script. Give the task a familiar name in the tab General, such as Update Pi-hole container, and select root as user.
3. Schedule the task in the tab Schedule, for example running it at 00:00 daily.
4. Finally, enter the following script in the user-defined script section of the Task Settings tab. Be sure to update /path/to/your/script/. The optional instruction --log /var/log/syno_pihole.log copies all messages to a log file.

   /bin/sh /path/to/your/script/syno_pihole.sh update --ip 192.168.0.250 --log /var/log/syno_pihole.log

By default, Docker containers are automatically restarted after a system reboot. However, the macvlan bridge interface setup by synology-pihole is lost after a system reboot and/or update. Similar to the instructions in the previous paragraph, you can setup a task to automatically recreate it during the boot process of your Synology NAS. Follow these steps to do so.

1. Access Task Scheduler via Control Panel ➡ Task Scheduler in DSM.
2. Now click on Create ➡ Triggered Task ➡ User-defined script to create a custom script. Give the task a familiar name in the tab General, such as Recreate Pi-hole Bridge Interface.
3. In the same screen, select root as user and Boot-up as event.
4. Finally, enter the following script in the user-defined script section of the Task Settings tab. Be sure to update /path/to/your/script/. The optional instruction --log /var/log/syno_pihole.log copies all messages to a log file. The option --force is required to avoid the script asking for user confirmation.

   /bin/sh /path/to/your/script/syno_pihole.sh network --ip 192.168.0.250 --log /var/log/syno_pihole.log --force

The Pi-hole FAQ describes various options on how to configure the Pi-hole DNS server. The Pi-hole administrator web interface is available by navigating to http://ip_address/admin/ (replacing ip_address with the correct IP address).

1. Clone the repository and create a new branch

   git checkout https://github.com/markdumay/synology-pihole.git -b name_for_new_branch

2. Make and test the changes
3. Submit a Pull Request with a comprehensive description of the changes

Synology-pihole is inspired by the following code repositories and blog articles:

• Bram van Dartel (xirixiz) - Setup Pi-hole on a virtual LAN
• Tony Lawrence - Free your Synology ports for Docker
• Lars Kellogg-Stedman - Using Docker macvlan networks
• Steven Welsh (beefyfish) - Pi-hole on Synology NAS (Docker Version)

Copyright © Mark Dumay