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
Hi,
great guides.
I wonder if anyone has a guide to enable IPV6 Support ?
regards,
Tim
Thanks for the excellent guide. I don’t suppose that you have any pointers for adding Unbound to the pi-hole configuration?
Have had a few requests for this, let me see what I can cook up as would need to set it up here in order to then support.
Excellent tutorial! I am preparing to install pi-hole in bridge mode (once all configured, I will be setting up Tailscale as per your Tailscale tutorial). I have Cloudflare DNS nameservers configured in Synology and router. At the end of your tutorial you say “Now you need to add the appropriate IP address to your router depending on which method you used to set up Pi-hole”. I will be in Bridge mode and understand its the NAS IP but where and why am I adding the IP address in router settings? (Sorry for the basic question and thank you in advance).
Hey, the ip in the router is so all devices on your network then use pihole for their dns lookups, you would then use based on your preferences put the Cloudflare dns into pihole for its upstream lookups. I would keep the NAS on external dns just to ensure it always has Internet access for if the PiHole is down for updates etc
Thanks! I’ve pointed Primary DNS on router to NAS IP and Secondary DNS to Cloudflare. Left DNS on NAS as Cloudflare and switched to Cloudflare in PiHole. All seems good now. Onto, Tailscale now!
has anyone have pihole working with DoT on synology?
what i want to achieve is setting the private dns in android to my own pihole.
i found this post
https://blog.svarun.dev/configure-pi-hole-with-dns-over-tls-private-dns
but changing the nginx on synology bascily get overriden everytime.
any ideas?
I know this is not DOT, but you can use DNS over HTTPS (DOH) using the quad9 address of https://dns.quad9.net/dns-query
https://quad9.net/news/blog/doh-with-quad9-dns-servers/
I am trying to set this up so that I can use Pi-hole set up via the Macvlan guide here with my VPN, so I can get Pi-hole working externally. When I connect to my NAS with OpenVPN, it doesn’t use the Pi-hole. Furthermore, I’m trying to link to the assigned IP address of the webpage with a reverse proxy, but it is unable to resolve the link. I know next to nothing about Macvlan, so could you provide some insight into why this may be occurring, if possible? Thanks you!
It sounds like you are trying to access the PiHole services from the NAS with a macvlan the service is not accessible from the host machine. So you would have to run pihole in normal bridge mode and then the NAS can use it for vpn / proxy etc.
Moving to bridge mode did indeed fix it! I’m sad I’ll lose the individual clients but configuring it through my router is more convenient anyways.
I have been trying to get a bridge between the container and nas working that doesn’t involve getting into ssh and editing things, if I even get it working I will be updating the guide. I have found that once pihole is working you will rarely touch it again.
For what it’s worth, this guide might be worth reviewing. I’ve got my setup finally working with all devices, so I’m not going to try touching this quite yet haha. But if this were to work in a way such that I could use pi-hole and also enable DHCP through pi-hole, I’d pursue it!
https://tonylawrence.com/posts/unix/synology/free-your-synology-ports/
On MACVLAN you can enable DHCP but just be aware that you will need to always make sure the NAS is set at a manual IP address as it won’t be able to access the DHCP server on PiHole. (due to aforementioned isolation)