In this tutorial, we are going to look at how to set up Pi-hole on a Synology NAS. Before we get started, I want to be clear that this process changed drastically after DSM 7.2 was released in May of 2023. Now, Container Manager is used as opposed to Docker and the UI is entirely different.
If you’d like to know how to set up Pi-hole on a Synology NAS using a version of DSM prior to v7.2, please watch the video below!
Prerequisites for Pi-hole on a Synology NAS
Before we look at how to set up Pi-hole on a Synology NAS, it is incredibly important to note that having redundant DNS servers is very important. Losing DNS resolution has similar consequences to losing internet from your ISP – you might think the internet is down, but you really just lost DNS resolution.
I highly suggest that you purchase a cheap Raspberry Pi and configure Pi-hole on it so that you have two Pi-hole DNS servers. This will ensure that when your NAS is rebooted, your clients do not lose DNS resolution services.
How to Set Up Pi-hole on a Synology NAS
Before we configure the Pi-hole container itself, we need to create a few folders that we’ll mount the container volumes to.
1. Install Container Manager from Synology’s Package Center. This will automatically create a docker shared folder on your NAS.
2. There are two folders that we will map our Docker image to that we need to create. Inside of the docker folder, we are going to create a folder named pihole.
Inside that folder, we are going to create two subfolders. Create one folder named pihole and another folder named dnsmasq.d. From a navigational perspective, the paths will look like this:
docker > pihole > pihole
docker > pihole > dnsmasq.d

Configuring the Macvlan Network Interface
As mentioned above, we’re configuring a macvlan network interface so that our Pi-hole container will have an entirely separate IP address and ports.
There are port conflicts if you use the host network interface, and this will bypass all of them. You’ll also access Pi-hole on a separate IP address than your NAS has.
1. Ensure you can SSH into your Synology NAS. Open Control Panel, select Terminal & SNMP, and Enable SSH service. If you are using Synology’s Firewall, ensure that you allow port 22 traffic.

2. SSH into your Synology NAS using your favorite SSH tool. The first thing that we need to do is create a docker macvlan network interface. First, we need to determine what network interfaces currently exist (on your Synology NAS) and note down the adapter name.
To do this, run the command below and note down the network interface name that has your Synology NAS’s IP address (in this example, mine is eth0).
ifconfig

3. Next, you need to run the command below while substituting the correct subnet (most are 192.168.1.0/24 by default). You also need to pick an IP address that you’d like to use that’s not currently in use. I will be using 192.168.1.198.
NOTE: ph_network will be the name of the network (you can substitute this as you’d like). The values in red might have to be altered
sudo docker network create -d macvlan -o parent=eth0 --subnet=192.168.1.0/24 --gateway=192.168.1.1 --ip-range=192.168.1.198/32 ph_network

Our network is now created. We can then exit our SSH session and disable it in DSM (if you won’t be using it). If you are disabling it and you created a firewall rule for it, you should inactivate the firewall rule as well.
Setting up Pi-hole with Docker Compose and Container Manager
Thanks to DSM 7.2 and the addition of Docker Compose, the steps below will be significantly easier than they were in prior versions.
1. Open Container Manager, select Project, then Create.

2. Enter pihole as the Project Name, then select the pihole folder and select Create docker-compose.yml.

3. There are a few changes you might have to make to the docker-compose file before creating it. I have highlighted in red what might need to be updated, but in general, you’ll potentially change the volume number, timezone, and most importantly, password.
- WEBPASSWORD: password that you’d like to access the admin portal with.
- TZ: Current timezone.
version: "3"
# Instructions: https://www.wundertech.net/how-to-setup-pi-hole-on-a-synology-nas-two-methods/
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
ports:
- "53:53/tcp"
- "53:53/udp"
- "67:67/udp" # Only required if you are using Pi-hole as your DHCP server
- "80:80/tcp"
networks:
- ph_network
environment:
TZ: 'America/Chicago'
WEBPASSWORD: 'password'
# Volumes store your data between container upgrades
volumes:
- '/volume1/docker/pihole/pihole:/etc/pihole'
- '/volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d'
cap_add:
- NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
restart: unless-stopped
networks:
ph_network:
name: ph_network
external: true
4. Add the Docker Compose file above with your changes to the editor, and select Next.

5. Select Next until you can view the summary, then select Done to create the container.

6. The container is now created and Pi-hole is running!

Configuring the Pi-hole Application
Pi-hole is now installed on your NAS and can be accessed by following the IP address of your macvlan network interface and signing in with the password specified above!
http://[ph_network_IP_ADDRESS]/admin

From here, you can configure Local DNS Records, and add or change various blocklists! Pi-hole is now functional, but there are still DNS changes that must be made.
DNS Configuration: How to Set up Pi-hole on a Synology NAS
Now that we looked at how to set up Pi-hole on a Synology NAS and that section is complete, we need to determine a way to point our clients to our DNS server. There are two main ways to do this:
- Point your router’s DNS server to your Pi-hole server IP address. This will ensure that any device connected will use Pi-hole as its DNS server.
- Point each client to your DNS server. This is beneficial if you only want certain clients to use Pi-hole as a DNS server.
I point my router’s DNS servers to my Pi-hole server as I want to ensure every device connects to it. This is different for every router, so you might have to look up where exactly it is on your device.

Now, all devices on my local network will automatically use these DNS servers and Pi-hole adblocking will work for all devices!
Troubleshooting Steps: Pi-hole on a Synology NAS
In prior versions of DSM and the Pi-hole container, I had DNS issues with the container itself. In situations like this, I found that manually specifying the DNS servers was necessary. Follow the steps below if you’re having issues with the container starting.
1. SSH into your Synology NAS and run these commands, but substitute your volume.
cd /[VOLUME_#]/docker/pihole sudo vi resolv.conf

If you aren’t sure what volume you’re using, open the Control Panel, select Shared Folder, then look at what’s listed for docker folder and use that number:

2. In the file that is created, enter the two lines below and save the file. If you aren’t sure how to use the vi editor, you can learn how to use it here.
In summary, from the editor, press i (for insert mode), add the nameservers listed below, then press the ESC key (to exit editing), then type :wq, then enter to write the changes and exit.
NOTE: If you have trouble with this, just create a local file named resolv.conf with the two lines below and upload it to your pihole folder in DSM.
nameserver 127.0.0.1 nameserver 8.8.8.8

After the file is created, you should see it (resolv.conf) in the pihole folder in DSM.

3. Recreate the container using the Docker Compose file below which will utilize this file. I have highlighted in red what might be updated, but in general, you’ll potentially change the volume number, timezone, and most importantly, password.
- WEBPASSWORD: password that you’d like to access the admin portal with.
- TZ: Current timezone.
version: "3"
# Instructions: https://www.wundertech.net/how-to-setup-pi-hole-on-a-synology-nas-two-methods/
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
ports:
- "53:53/tcp"
- "53:53/udp"
- "67:67/udp" # Only required if you are using Pi-hole as your DHCP server
- "80:80/tcp"
networks:
- ph_network
environment:
TZ: 'America/Chicago'
WEBPASSWORD: 'password'
# Volumes store your data between container upgrades
volumes:
- '/volume1/docker/pihole/pihole:/etc/pihole'
- '/volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d'
- '/volume1/docker/pihole/resolv.conf:/etc/resolv.conf'
cap_add:
- NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
restart: unless-stopped
networks:
ph_network:
name: ph_network
external: true
Conclusion: How to Set up Pi-hole on a Synology NAS
This tutorial explained how to set up Pi-hole on a Synology NAS. The process on how to set up Pi-hole on a Synology NAS isn’t too bad and Pi-hole is awesome! I’ve been using it for a while and while I run into the occasional issue where it blocks something I need, finding it and whitelisting it is a fairly easy process.
Once again, I will point out the importance of redundant Pi-hole servers. There are so many benefits to having a second DNS server, and with Raspberry Pi Zero kits being as cheap as $25, it’s worth it for redundancy purposes.
Thanks for checking out the tutorial on how to set up Pi-hole on a Synology NAS. If you have any questions on how to set up Pi-hole on a Synology NAS, please leave them in the comments!
Hi. Great guide, thank you 🙂
I have a question on the last part of the guide, regarding opening the ports in the firewall; method 1, Step 12/13.
I’m not sure if Source-IP should be left “All”, or what that should be. And I assume the rules should be “Allow”.
It would be great if you could show a screenshot with the overview of the two rules, just to confirm that I did it correctly.
Since you aren’t opening the port on your router, you can leave it as all. I am super busy so I’m not sure when I will get time for a screenshot, but please feel free to email me at [email protected] with the screenshot of how yours is set up and I’m happy to confirm it’s correct.
Perhaps stupid question, about changing the DNS IP in my router.
Could my primary DNS be my Pi-Hole, and the secondary by for example Googles DNS server?
So in case my NAS or Pi-Hole fails, then all devices in the house will use the secondary DNS instead, and we can still surf the web.
Would that work?
Absolutely! Just know that if any DNS requests go to Google, you will not have ad-blocking.
Hi,
Thanks for the amazing tutorials. Discovered your channel 2 weeks back and enjoying going back in time to discover what I’ve missed.
I’ve setup 2 PiHole like you mentioned, one on my Synology, another on one of my server (VM on Ubuntu ). And set them both at router level.
Is that enough to ensure load balancing and optimal performance? Would you have a tutorial/guide I might have missed that explain how to do that ? For now it seems like all my clients are hitting the first DNS while the second one seems pretty bored with nothing to do 🙂
Thanks for the help and thanks again for the great work !
Everything you did is perfect! If the main Pi-hole instance is overloaded, requests will automatically be sent to the second Pi-hole instance. You also will have the benefit of redundancy now. Great job!
Apologies for the 2 posts. I didn’t know if my first message went through or not.
Thanks for the advice. Despite setting my Synology as my first dns the second one (the NUC11) seems to be doing all the work. Do you know what are the mechanics behind that ? That’s definitely out of scope for this tutorial though 🙂
I don’t believe that it matters which one you set (though I could be wrong) as the device will simply go to whichever one it deems available. I think that the terms “primary” and “secondary” are used relatively loosely as I experienced similar behavior.
Hi,
I’ve absolutely enjoyed your tutorials so far. I’ve discovered your channel 2 weeks ago and been going back in time to look at all the videos one by one, and found some very useful tips in them. Thanks for the time spent in helping us.
I’ve setup 2 pihole on my local machines : one in a VM inside a small Intel NUC that I have, and one in my Synology NAS in order to have redundancy setup, following this guide. In another video you mention how critical and important it is to have two pihole setup, and you also mention that you naturally got “load balancing” out of this setup.
Both mine are working (nslookup from my lan to any ip resolves correctly), and both are set on my router (Google wifi) to ensure everyone gets it lan-wide. However, after a day or two, I observe that the load balancing didn’t come to me naturally. One gets more than 95% of the requests, the second one almost none.
Did you have to go through something specific to load balance ?
Thanks again for the help.
Just replied to your other comment – sorry, I have to approve the comments due to tons of spam. If you have any other questions, please let me know!
How can I add a private upstream DNS server like unbound? (On Synology)
I haven’t set it up myself so I can’t validate exactly how it will work, but I believe you’ll have to spin up a new container.
Hi, great tutorial!
Short question/situation:
I have synology router (192.168.1.1) as DHCP and DNS the same (asks cloudflare 1.1.1.1).
Domain on the router is home48
– when I ping from windows1 windows2 it reply with windows2.home48
I have now set up pihole in docker (method1) and manually set 192.168.1.2 (Synology NAS) as DNS just for windows1.
All is great, adds are blocked but:
when I ping windows2 = could not find host windows2
Basically, no more LAN devices hostname resolution.
Any clues ?
Thank you!
Yes, that’s how it’s supposed to work (strangely). On your router, there’s a local DNS section where it knows the device name and it’s used as a DNS lookup. If you’d like this to work in Pi-hole, go under “local DNS records” and create a record for the specific local IP address. It should then work as you’re expecting it to.
So even no Synology DNS server package is installed on the router, the router knows the hostnames. Maybe a way to make Pihole forward local “.home48” requests to the Synology Router? Adding a hostname/reservation on the router and than having to add the same record on the pihole is not the nicest thing 🙂
Also, since I see a lot of questions about it:
Synology router (and other routers I believe) has built-in Cloudflare DoH support.
Maybe a tutorial “add-on” on how to also make DNS queries private too using Pihole?
Thanks!
I will look into if it can be synced any way, but generally, it’s a pretty easy one-time setup for the local DNS servers. As for Cloudflare DoH, check out Unbound (I have a tutorial for it, though not on a Synology NAS – I will add it to my list). This is most likely what you’re looking for!
Hi, about DoH, I found a simple way to do it (don’t want to mess with macVlan or editing to much stuff not because it is hard, but because Synology updates might break stuff … like it happened with USB support in DSM7 and etc.)
Basically, you install a simple cloudflared container (https://hub.docker.com/r/visibilityspots/cloudflared), and in PiHole use that container on port #5054 as the only upstream DNS.
After, 1.1.1.1/help should see connection as DoH.
But still, your videos are much more nice than written stuff so you could include it like a 2min ‘add-on’.
PS: and maybe add the setup part for DHCP on pihole too.
Great input, thank you! Will definitely take a look into this!
Error response from daemon: failed to create the macvlan port: device or (i assume it says busy but it cuts off)
Error 1
I followed your guide to the letter and managed to do the script thing to install the macvlan etc but i get the error message above. Any hints on where i should start looking to resolve this?
Are you using the correct network interface name? Also, you don’t have any other macvlan network interfaces, right?
Can you also make a version / tutorial with Pi-hole + unbound on Synology with container manager?
I’ll add it to my list!
This tutorial is great!
Container is up and running. But I did run into an issue. I am getting this error “FTL failed to start due to failed to create listening socket for port 53: Permission denied”
Any idea?
Thanks! Did you configure the macvlan network interface properly and using the exact same name (ph_network)?