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

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

Run the following command to create a network outside of docker-compose.yml

sudo ./syno_pihole.sh create

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
`version`	Shows host and Pi-hole versions
`create`	Create docker network outside of docker-compose.yml

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.

Access Task Scheduler via Control Panel ➡ Task Scheduler in DSM.
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.
Schedule the task in the tab Schedule, for example running it at 00:00 daily.
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
```

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.

Access Task Scheduler via Control Panel ➡ Task Scheduler in DSM.
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.
In the same screen, select root as user and Boot-up as event.
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
```

Configuration

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).

Contributing

Clone the repository and create a new branch

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

Make and test the changes
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)

afreisinger/synology-pihole