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
Many thanks for these guides – they’re truly useful!
One problem I encounter is when using the host network, if I change the Synology IP, through getting a new router or whatever, the container breaks and I have to recreate it. Is that to be expected? Can it be modified instead?
Updating the FTLCONF_LOCAL_IPV4= to the new address doesn’t fix it.
Finally, any tips for which adlists in Pihole to subscribe to?
Hey, you should set a manual IP for DSM in the Control Panel > Networks or tell your router to assign the same IP (DHCP Reservation) so it doesn’t change at all. Keep in mind that when you update the address it will take a while for each device to receive the new IP. They will generally be on a 24-hour lease time before asking to renew the details from the router.
Oh, and list wise this site tends to do an annual update of where to get the best lists. Just don’t go crazy with them!
https://avoidthehack.com/best-pihole-blocklists
The bridge version : [✗] DNS resolution is currently unavailable
The host version : /bin/bash: line 1: 477 Real-time signal 0 /usr/bin/pihole-FTL no-daemon > /dev/null 2>&1
Stopping pihole-FTL
pihole-FTL: no process found
Remove the FTL no-daemon fixes the error, but pihole doesnt show Queries
The host version after redo the ip nrs : [✗] DNS resolution is currently unavailable and doesnt eben come up
cap_add: : only neded if you use Pihole as DHCP
And :
For Synology :
DNSMASQ_USER:root
FTLCONF_LOCAL_IPV4=0.0.0.0
So its time to redo this guide. Its A or incorrect or incorect cause of out of date.
Hi
I will remove the two lines below from the Bridge version of the YAML as you are correct that won’t support DHCP due to the lack of ports being exposed so it won’t need the extra caps. However, the other two could be used for that purpose so will leave them in place as well as the chown.
– CAP_NET_RAW
– CAP_NET_BIND_SERVICE
You should be able to use a non-root user for DNSMASQ successfully. It has been in the guide that way since pre DSM7 as we are granting the user permissions via the UID/GID of our dockerlimited user not the default Pi-hole internal user permissions of 999:1000. I know there were reports of issues back in 2022, but they seem to have been resolved avoiding the need for root. Double-check the folders have the dockerlimited user as owner or has read/write permissions.
The guides go through regular amendments and testing so no ‘redo’ is required to be sure I just spun up all 3 versions on my DSM VM which is purely for the guides, and this exact same versions are in use on my live server.
Happy to check your full logs to see what else must be going on.
https://paste.drfrankenstein.co.uk
Cheers
Thanks for the great guide!
Up until this morning I was running pi hole on a raspberry pi, and I powered it off to do something and it wouldn’t boot again when I powered it back on, so time to run it on the NAS!
Now that it’s in docker, what’s the equivalent to the pihole -up command? Stop the container, then Action>Build the project and it will pull the latest files, rebuild, and restart?
Hey – Have a look at the container update guide on the left menu 🙂
Hey Dr_Frankenstein,
I am a new visitor and must say, you created some great Guides here.
First I followed your „Initial Setup“ Guides and I want to use the Bridge Mode. Not sure if that is important for my question.
I followed this Guide and the Container is starting perfectly fine in the first place. However, in the logs I can see a lot of messages like this:
„pihole-FTL: no process found“
Do you have an idea what could cause this issue?
Or did miss something?
Thank you in advance.
Best regards,
Dominic
Hey
Just catching up on some comments, did you get this going? You may want to stop the container. delete the contents of each folder and start up the project again. See if that then allows FTL to start up.
Hi,
sadly I still have the same issue after deleting folder contents and restarting the project. However, I noticed the following error messages:
– „Failed to set capabilities on file /usr/bin/pihole-FTL (Operation not supported)“
– „The value of the capability Argument is not permitted for a file. Or the file is not a regular (non-symlink) file
– ERROR: Unable to set cababilities for pihole-FTL. Cannot run as non-root
Thank you for your Support.
Best Regards,
Dominic
OK I suspect this is permissions related, First check the PIHOLE_UID and GID are correct if they are can you jump back to the User and Group guide, towards the bottom there are a couple of commands to run…. Adjust the paths mentioned to just /volume1/docker/pihole and then start the container up again.
drwxrwxr-x 4 docker dockergroup 4096 Jun 2 21:13 .
drwxrwxr-x 6 docker dockergroup 4096 May 31 12:39 ..
drwxrwxr-x 2 docker dockergroup 4096 Jun 2 21:13 dnsmasq.d
drwxrwxr-x 2 docker dockergroup 4096 Jun 3 21:26 pihole
Permissions should be fine.
My Docker User already was present before. Maybe I just try to recreate it once again tomorrow.
I will let you know if it worked.
Hi,
I got it to work, but only with a compromise on my Synology NAS (DS723+):
DNSMASQ_USER:root
However, this seems to be a Knowledge issue:
– https://github.com/pi-hole/docker-pi-hole?tab=readme-ov-file#experimental-variables
– https://github.com/pi-hole/docker-pi-hole/issues/963
Maybe in future there will be another Solution.
Its weird as I have never had this issue as well as others, it must be related to permissions, can you try doing the permissions fix mentioned in the User and Group guide, adjust the paths it mention to purely do /volume1/docker/pihole and then see if it works with the pihole user not root.
Hey Doc, hope you’re doing well. Question: with host mode, do I still need to update my DNS servers/DHCP settings? I recently had an issue with my router where everything on my network stopped working due to those settings so I had to put them back to 8.8.8.8 to get them running again. I’m just trying to figure out the best way to get this going. Thanks!
Hey – So yes in Host Mode you still need to update the IP be given out by your DHCP server otherwise your devices won’t be using the NAS for DNS requests. Keep in mind if the Pi-hole is ever off you will lose internet access.