kieren / synology-pihole

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

synology-pihole

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

About

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.

Built With

The project uses the following core software components:

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

Prerequisites

Synology-pihole runs on a Synology NAS with DSM 6. The script has been tested with a DS918+ running DSM 6.2.3-25426 Update 2. 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

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

Usage

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

Commands

Synology-pihole supports the following commands.

Command	Description
install	Installs Pi-hole as Docker container
network	Creates or recreates virtual network
update	Updates an existing Pi-hole Docker container

In addition, the following options are available.

Option	Alias	Parameter	Description
-f	--force		Bypass checks to force the installation / update
-l	--log	LOG FILE	Redirect output to LOG FILE

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.

Variable	Parameter	Required	Example	Description
PIHOLE_IP	-i, --ip	Yes	192.168.0.250	Static IP address of Pi-hole, ensure this IP address is available
INTERFACE	-n, --interface	No	eth0	Host network interface to the subnet, auto-detected if omitted
SUBNET	-s, --subnet	No	192.168.0.0/24	CIDR notated subnet the Pi-Hole will join, auto-detected if omitted
GATEWAY	-g, --gateway	No	192.168.0.1	Subnet gateway router address (see --subnet), auto-detected if omitted
HOST_IP	--host-ip	No	192.168.0.3	New host address for communicating with Pi-hole via macvlan bridge interface. By default the lowest address starting at the first (not the Pi-hole address) of the Docker network range (see --range) is used
IP_RANGE	-r, --range	No	192.168.0.250/30	CIDR notated address range for Docker to assign to containers attached to the created 'Docker macvlan Network', defaults to PIHOLE_IP/32
VLAN_NAME	-v, --vlan	No	macvlan0	Name assigned to the generated macvlan interface on the host to enable container <-> host communication (defaults to macvlan0)
MAC_ADDRESS	-m, --mac	No	70:d9:5a:70:99:cd	Unicast MAC to assign Pi-hole, randomized if omitted
DOMAIN_NAME	-d, --domain	No	example.com	Fully qualified domain of the subnet
PIHOLE_HOSTNAME	-H, --host	No	pihole	Hostname of Pi-hole, defaults to pihole
TIMEZONE	-t, --timezone	No	Europe/Amsterdam	Local Timezone (see Wikipedia for an overview, auto-detected if omitted)
DNS1	--DNS1	No	1.1.1.1	Primary DNS provider to be used by Pi-hole (see this list for typical providers)
DNS2	--DNS2	No	1.0.0.1	Alternative DNS provider to be used by Pi-hole
DATA_PATH	--path	No	./data	Host data location path for Pi-hole, defaults to ./data
WEBPASSWORD	-p, --password	No	password	Password for the Pi-hole administrative web interface (prompted for when omitted)

Scheduled Tasks

Updating Pi-Hole to the Latest Version

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 -l /var/log/syno_pihole.log copies all messages to a log file.

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

Ensuring the Host <-> Container Bridge Interface is Available After Reboot

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 -l /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

Configuration

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

Contributing

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

Credits

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)

Donate

License

Copyright © Mark Dumay

synology-pihole's Issues

PARAM_IP_RANGE validation doesn't check for network address

Validation checks the subnet broadcast address is not in the range defined by PARAM_IP_RANGE in syno_pihole.sh but not the network address.

--log command line option is positional

If the --log option is used with syno_pihole.sh and a log file is not specified then this option must be specified last after all other commands, parameters and options. Otherwise a parsing error occurs when the next command line argument is blindly assumed to be the name of the log file.

For example: syno_pihole.sh -l update will fail with a 'no command' error and error messages logged to ./update