Last updated on 27 February 2025
Important or Recent Updates
| Historic Updates | Date |
|---|---|
| Updated guide for Container Manager and using Macvlan | 14/05/2023 |
| Added a new section to ensure DSM continues having network access. | 02/06/2023 |
| Guide updated so you can choose between Macvlan or Bridge mode | 12/08/2023 |
| Added additional security option to the compose to restrict the container from gaining new privileges | 25/10/2023 |
| Fixed issues I introduced with the recent changes in my mission to make things more secure. It was so secure I broke it! Added the appropriate permissions/capabilities at start up for the container. | 29/10/2023 |
| Removed the requirement for the synobridge as this container can just use its own bridge, and added the Host network mode, so all three are a choice. | 28/01/2024 |
| Removed the WEB_UID and WEB_GID from the config to avoid issues with ID’s conflicting inside the container. I will update again once I have some time to work around this. | 03/04/2024 |
| Some minor amends to sync up the information across this guide and the AdGuard one | 01/08/2024 |
| Removed two unneeded capabilities from the bridge version of the docker compose as they are not required. | 16/11/2024 |
| Guide updated for the all new v6 of Pi-hole (Note if you upgrade from v5 you effectively have to change all the compose settings in line with the new guide so might be worth just scrapping and starting fresh unless you really need stats etc Please note as recommended by the Pi-hole dev team I have added a Watchtower exclusion label to the compose so you can do manual updates. Automated ones could result in you losing internet access if a bad update takes place. Edited again today as I left in a variable that is not required in Host and Macvlan mode “DNSMASQ_LISTENING” sorry. | 20/02/2025 |
| Had a rethink of the Guide, and it has been rewritten to include an overdue request of including Unbound! | 24/02/2025 |
What is Pi-hole?
If you are looking to get advertising and tracking blocked across all the devices on your network a Pi-hole will have you covered. It’s a locally hosted Domain Name Server and uses block lists to stop adverts.
This guide will get you set up with Pi-hole and cover some basic initial settings, I recommend checking out the documentation for all the various features available.
What is Unbound (Optional)
Unbound is a validating, recursive, caching DNS resolver. Rather than using an upstream DNS provider such as Google or Cloudflare who will look up the IP addresses for domain names you visit Unbound does this for you. It queries root servers for the address for a website. For example when you visited this site its actually on the server 213.186.33.50. This adds a layer of privacy in your web browsing as you are not relying on a third party with this information.
Host vs Bridge vs Macvlan Network Modes
You need to decide which mode of Networking you want to use, I have outlined the key points below in general order of preference. (Unbound will be on a bridge which has no impact on your choice)
Host:
Host mode uses your NAS underlying network to run the containers network services, so it will be reliant on the NAS not using any of the required ports for the container. However, this makes it easy to set up, but you need to make sure no other service is using the required ports. All your clients will appear correctly as independent devices and stats.
Bridge Mode:
The main benefit of Bridge Mode will be the ease of setup however you will find that all clients on your network will appear under the same IP as the Bridge 172.20.0.1. This won’t impact ad blocking, but it will mean you can apply device specific rules etc.
Macvlan:
This gives you the benefit of Pi-hole having its own IP address on your network, all clients appear with their real IP addresses allowing you to assign specific rules and give you some nicer stats. However, one downside is that your NAS will not be able to use Pi-hole for DNS, due to the additional security features of Macvlan and its communication with its host. This is generally not an issue unless you wanted to use your Ad blocking with Tailscale.
Please note you will not be able to use Macvlan with a Bonded network connection e.g. ‘Bond0’. You will need to remove the bond in order to use this method.
Let’s Begin
In order for you to successfully use this guide you will need to check that your Router allows you to change your network DNS servers, this is usually found in the DHCP settings.
Please follow the initial guide below to get a restricted Docker user set up, then come back here.
Folder Setup
Let’s start by getting some folders set up for the container to use. Open up File Station create the following.
/docker/projects/pihole-compose
/docker/pihole
/docker/unbound #Optional
Unbound Configuration (Optional)
We need to make a config file for Unbound to define its network settings.
Download the file below and put it into the “unbound” folder we created earlier
Container Manager
Next we are going to set up a ‘Project’ in Container Manager. Open up Container Manager and click on Project then on the right-hand side click ‘Create’.
In the next screen we will set up our General Settings, enter the following:
| Section | Setting |
|---|---|
| Project Name: | pihole |
| Path: | /docker/projects/pihole-compose |
| Source: | Create docker-compose.yml |
The code section of the below will be blank until we move to the next step.
Next we are going to drop in our docker compose configuration. You now need to decide if you are going to go with Host, Bridge Mode or Macvlan. Jump to the appropriate page to follow the setup.
Host – Page 2
Bridge – Page 3
Macvlan – Page 4
Hey, I’m new to the Synology world and having recently purchased a DS224+ I’ve followed several of your guides… thank you!
I’d been attempting to setup Pi-Hole using the Host method. However, once running I could access and login to the GUI but the dashboards would fail to load and I would get an amber warning message in Container Manager. Pi-Hole also noted FTL failing to load and the following error message “PHP error fsockopen(): unable to connect to 127.0.0.1:4711” .
I tried all sorts to get this to work and finally found that adding NET_ADMIN to cal_add, resolved the issues. I stumbled upon this setting while reading about using Pi-Hole for DHCP. With this setting enabled all is now stable and I’ve also progressed to using DHCP.
Just thought I would share this, I may not be alone!
Current YML:
services:
pihole:
image: pihole/pihole:latest
container_name: pihole
cap_add:
– CAP_NET_RAW
– CAP_NET_BIND_SERVICE
– CAP_CHOWN
– NET_ADMIN
environment:
– PIHOLE_UID=**** #CHANGE_TO_YOUR_UID
– PIHOLE_GID=***** #CHANGE_TO_YOUR_GID
– WEB_UID=**** #CHANGE_TO_YOUR_UID
– WEB_GID=***** #CHANGE_TO_YOUR_GID
– TZ=Europe/London #CHANGE_TO_YOUR_TZ
– WEBPASSWORD=*********
– DNSMASQ_LISTENING=local
– WEB_PORT=8000
– DNSMASQ_USER=pihole
– FTLCONF_LOCAL_IPV4=192.168.0.10
volumes:
– /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
– /volume1/docker/pihole/pihole:/etc/pihole
network_mode: host
Hey, I will have another read of the documentation and see if I need to add this specifically for someone wanting to use the DHCP functions
I followed this guide and i cannot access to the web UI, in the register tab of the container i see these two messages repeatedly:
Stopping lighttpd
lighttpd: no process found
No matter what mode i use (host, macvlan or bridge mode), the same error occurs..
looking in forums, it seems the pihole user the user pihole does not even start the container… however the root user does
Maybe this problem is related with port conflicts?
I use last version of dsm and i have a synology ds224plus
Thanks
I would jump back to the user and group guide an apply the permission fix command to see if it clears up a permission issue as the guide should work fine
https://drfrankenstein.co.uk/step-2-setting-up-a-restricted-docker-user-and-obtaining-ids/
But just use the path /volume1/docker/pihole not the two specified in the first command.
I had this problem also, but it was due to me missing the FTLCONF_LOCAL_IPV4= setting.
After a long time a tried again to run pihole+unbound. I found a lot of new info and I managed it at last.
So far I have managed to geti it running as host, bridge and macvlan network modes
What would be the correct way to send those compose files to you, check them and refine them with your experience and may be of any helpl to update the guide?
Hey beat me to it, I will ping you an email via the address you used in your comment 🙂
OK.
Waiting for contact details via this email address…
Hi,
Love all these guides! The Arr’s and watchtower ones worked beautifully.
One of the last things I’m trying do is install a pihole on my synology (DS220+, running DSM 7.2.1-69057 Update 3).
I’m running into the “pihole-FTL:no process found” issue.
I’ve been following the latest version of your guides (and the general setup ones) and tried both the bridge and the MACVLAN versions. Both gave me the same issues.
Additionally, the Pihole Web UI isn’t even loading. But the project does build and starts up properly.
Stuff I’ve tried:
-change the user from pihole to root
This fixed the FTL thing, but now it can’t find the “lighttp process”. Web UI still doesn’t work.
– Use an older version of Pihole per your comments. This did nothing.
– Fixed the user and user group permissions with the terminal commands in your general setup guide. (the latest ones since I’m trying to set this up in the last week). Also didn’t fixed the issue.
I’m out of stuff to try besides giving up on pihole and going to your adguard guide. Any idea on what I’m doing wrong?
Alvast bedankt!/Thanks in advance!
YAML for both versions:
Bridge mode
services:
pihole:
image: pihole/pihole:latest
container_name: pihole
cap_add:
– CAP_NET_RAW
– CAP_NET_BIND_SERVICE
– CAP_CHOWN
environment:
– PIHOLE_UID=1028
– PIHOLE_GID=65537
– WEB_UID=1028
– WEB_GID=65537
– TZ=America/Los_Angeles
– WEBPASSWORD=###########
– DNSMASQ_LISTENING=local
– WEB_PORT=8000
– DNSMASQ_USER=pihole
– FTLCONF_LOCAL_IPV4=192.168.1.148
volumes:
– /volume2/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
– /volume2/docker/pihole/pihole:/etc/pihole
ports:
– 53:53/udp
– 8000:8000
network_mode: bridge
restart: unless-stopped
MACVLAN mode
services:
pihole:
image: pihole/pihole:latest
container_name: pihole
cap_add:
– CAP_NET_RAW
– CAP_NET_BIND_SERVICE
– CAP_CHOWN
environment:
– PIHOLE_UID=1028
– PIHOLE_GID=65537
– WEB_UID=1028
– WEB_GID=65537
– TZ=America/Los_Angeles
– WEBPASSWORD=###########
– DNSMASQ_LISTENING=local
– WEB_PORT=8000
– DNSMASQ_USER=pihole
– FTLCONF_LOCAL_IPV4=192.168.1.10
volumes:
– /volume2/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
– /volume2/docker/pihole/pihole:/etc/pihole
networks:
macvlan:
ipv4_address: 192.168.1.10
restart: always
networks:
macvlan:
name: macvlan
driver: macvlan
driver_opts:
parent: eth0
ipam:
config:
– subnet: “192.168.1.0/24”
ip_range: “192.168.1.254/24”
gateway: “192.168.1.1”
It sounds like you have done the correct troubleshooting steps, this should work with DNS mask running as our docker user without issue… Can you try deleting and recreating the folders? Also, I note you are using volume2 did you amend the command as such for the permission fix..
Hi,
Thanks a bunch for helping me troubleshoot!
Nuked the folders as requested, deleted the container and project, even cleaned the recycle bin for good measure. Recreated the folders based on your guide again. Still the exact same behaviour.
I did update all my scripts (YAML and terminal) to reflect the correct paths. (Volume 2 is a hold over from an old RAID setup I used to have running. Can’t get ride of it without starting completely from scratch for some reason.) I had no issues with the arr’s with these paths once inputted correctly. (it yelled at me when I forgot to change the 1 to a 2 🙂 )
I don’t think my network would impact the running of these containers, but are there any synology specific settings I should double check?
For completeness:
I’m running Sab, Sonarr, Radarr, Watchtower and an instance of homebridge concurrently at the moment.
This must be related to permissions as I have successfully spun up each version of the container without issue. Could you ping me an email via the Help Me! page on the menu and we can exchange some screenshots so I can understand what is happening (or not happening)
Once again, thanks for all guides!
Would really appreciate if you could help with Pi-hole+Unbound or Pi-hole+clouflared solutions….
Yup, added onto the list of enhancements, just making some tweaks to things and will be getting to that next 🙂