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: true4. 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: trueConclusion: 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!
Thank you for this great guide, especialy for macvlan method. Everything works great in this scenario, but I have a setup which is a bit different. I use LAN1 with address in 10.69.109.0/24 and LAN2 in 192.168.69.0/24 subnet. When using computers which are on that 10.69.109.0/24 subnet I can use pihole DNS (which is on 192.168.69.12 and Synology DS718+ is on 192.168.69.11) just fine. However, if I use computer from any other subnet, ie. 10.69.110.0/24, it can’t reach it. I can ping and open DSM on 192.168.69.11. It was the same problem when I used simple method and pihole was on same 192.168.69.11 address. Then I could even open pihole web interface but could not use DNS. Synology FW is off.
When you are on the 192.168.69 subnet, can you piing the 10.69.109 subnet (and vice-versa) regularly? If not, you might have to set up a static route so that the different subnets can communicate.
Thank you for the guide used the 2nd method because method one was a crash/restart party :-).
I did however need to add a static route on the synology to be able to ping the ip and browse to the admin page. Which looked something like this (to be honoust no clue what it says exactly, google … ;op but it worked after that.
ip link add foobar link bond0 type macvlan mode bridge
ip addr add 192.168.1.2/32 dev foobar
ip link set foobar up
ip route add 192.168.1.4/32 dev foobar
bond0 is my network interface (bonded instead of eth0 for me)
192.168.1.2 is my nas IP
192.168.1.4 is the IP i assigned to my pi-hole
These entries are not permanent and gone after a reboot.
So i created an rc.sh in /etc and put it into a scheduled task (task scheduler – triggered task)
with run command: bash /etc/rc.shon dsm.
However it seems to fire of a bit to quickly after reboot so i added a pause in the rc.sh for about 30 seconds.
After that it worked fine.
rc.sh contents:
sleep 30
ip link add foobar link bond0 type macvlan mode bridge
ip addr add 192.168.1.2/32 dev foobar
ip link set foobar up
route add 192.168.1.4/32 dev foobar
I read you could create a rc.local and put the entries there but for the live of me i couldn’t get it to work.
I have no clue if this is just an issue to me specific but figured to put it here, perhaps it will help someone.
Also use at your own risk 🙂 no expert.
I haven’t seen anyone need to do that, but either way, thanks so much for sharing in case someone else has the same problem!
Tad bit of a novice here, but followed your instructions and got this working perfectly.
Since then i’ve moved my synology to a new house which has a different setup, separate modem and using my own router which has a different subnet. I updated my synology ip to be on the same subnet as i did the router and all is well with dsm but the pihole docker doesn’t seem to work. I cannot connect to the pihole page so i deleted the pihole container and then the two new PH networks i created.
After doing this i cannot download any docker images, so not able to start from scratch with pihole. I’m thinking its because of the vlan’s but i have no idea how to remove these, which i created with your command.
Thought id ask before i completely remove docker/or reset my nas and start from scratch.
I suspect that it’s DNS related. You definitely did the right thing in deleting the PH networks because those networks were using the old routers gateway and I am assuming it changed. As for the container not downloading, did you set a static IP address anywhere on your NAS? If you did, can you confirm that the gateway and DNS servers are both pointing to the right location?
Similar issues to a few others here – with a twist though! Use method 2 using the macvlan. NAS main eth addr is 192.168.67.1.210, set up the pihole outside visible addr to be .220. DNS requests go through to the container via .220 fine but the http page is only accessible via .210 ?!?!? got me scratching my head as to why the .80 port isn’t translated over
That is definitely a little weird. One thing to confirm – you removed the default “bridge” network in the Docker container, right? The ph_bridge network should stay, but the “bridge” network should be removed.
Yes, deleted the default bridge. I just blew it away and rebuilt it as per the above instructions, and same thing – DNS port 53 can be accessed on .220, if I try to map port 80 to port 80 in the port settings tab it complains about port 80 being used already (I am running a webserver on .210:80) to keep it happy I’ve mapped 89:80 for the pi-hole admin page.
I’m honestly not entirely sure why it works using Portainer and not Synology’s GUI. Ultimately, they’re the same (just a skin for Docker), so it shouldn’t have a different effect. As for port 89, that shouldn’t be a problem either if you’re not using the macvlan network interface for anything else. I wish I had better feedback, but I feel like it’s not fully using the macvlan network interface like it should be.
Further to my previous reply…. I followed this guide (https://servicemax.com.au/tips/pi-hole-in-docker-on-synology-the-best-way/ ) using portainer to do the network part of the config and the way it configures it up passes port 80 through to .220. I don’t know what the differences are in the configuration settings/methodology, but it now works. Curious to hear your thoughts. Thanks!
Hi Frank, thanks very much for the tutorial. I used method #2 and it kind of works, my pihole runs on it’s own IP (192.168.178.210) and my home devices start using it, but I have some questions. Why can’t you use synology’s existing docker bridge (172.17.0…) network for the bridge network? Why do you have to create a new one (your example: 192.168.10…)? Next, in fact no matter which bridge network I use, “your’s” or the 172…. one, when I am on my Synology NAS or any other container (e.g. grafana) I cannot reach my pihole at 192.168.178.210. I can reach it at the IP address of the bridge I am using (the 172.17. oder 192.168.10. one – doesn’t matter) – but not at 192.168.178.210. Ray posted a solution on May 6th in this page and I also found a (German) video which does the same thing (https://youtu.be/21CTUWn4JSI?t=419) – but what’s happening here? Could you perhaps explain it? By the way – I am using portainer to assign or un-assign the networks to the pihole container – could that be a problem?
When you say that you can’t access it on the IP address you specify, from which device are you trying to access it from? It makes sense that anything on the NAS will have to use the bridge, but the outside devices should be forced to use the regular IP address.
As for the docker bridge, it might function the exact same way, but I find it easier this way since we specify a static IP address (using /32), so the IP address for the bridge will ALWAYS be what we specify. If the docker bridges IP address won’t change, you might be able to use it for the same functionality!
Hey. Came here from your video. When trying to set up the macvlan i get the response of “Errror response from daemon: operation no supported”. Any ideas where i am going wrong. Cheers
What device are you trying to set this up on? I know some Synology models have issues with the macvlan network interfaces.
Hi!
Just wanted to add that when installing Virtual Machine Manager, vSwitch gets turned on and for some reason Dockers macvlan network causes a conflict. This results in DSM disappearing from network. The fix is to create the macvlan network with parent “ovs_eth0” instead of “eth0” as such:
docker network create -d macvlan –subnet=192.168.1.0/24 –gateway=192.168.1.1 –ip-range=192.168.1.0/29 -o parent=ovs_eth0 my-macvlan
(DSM 6.2.4)
Awesome input, thank you so much for sharing!
Hi Frank, never heard of Pi_Hole before but after seeing this How-To it now leaves me wondering if and why I need it.
Can you please explain in layman’s terms what the benefit of it is please for my Synology that runs Plex for family members as well as security camera recording?
How does it benefit me browsing the net on my iMac & iPhones if at all?
Thank you and keep up the great work 🙂
Thanks! In it’s simplest form, Pi-hole is used to block ads on your local network. When you navigate to a website that has ads (even this one), those ads will automatically be blocked and you won’t see any of them. It’s done by blocking certain DNS requests, which is why Pi-hole is a DNS server. In summary, if you would like to block ads, it’s a great option, but it’s more complex than something like a browser ad-blocker.
Hello,
Thank you for your guide, I tried following it but had the following two errors when configuring Pi-Hole after step 4. I get these when trying to 1) add a blocklist: [✗] DNS resolution is currently unavailable
[✗] DNS resolution is not available
and 2) update the blocklists:
Error, something went wrong!
While executing: attempt to write a readonly database
Some google searches imply changing the root access to Pi-Hole, would you have any advice? One thing I did differently, was open a notepad file to create the resolv.conf file, and moved that to the pi-hole folder in the Synology. I also installed version 5.3.1, and used option 2, installed through macvlan. Thanks in advance.
The conf file has the correct extension, right? meaning it’s resolv.conf and not resolv.conf.txt? That error is almost certainly resolv.conf related (caused me a ton of heartache when I first set mine up). You shouldn’t have to provide admin access, so I’m not sure I would take that route. If you can, double check that everything is right in the resolv.conf file.
Yes, the file is saved as resolv.conf. I’ll try the vi editor method you mentioned if the resolv.conf file is the culprit. FYI it seems the link to the vi editor on your page is broken, and new the link may be https://staff.washington.edu/rells/R110/.
Thanks for replying, I’ll update if successful.
unfortunately the vi editor method didn’t solve the issue either. I’ll see if I can see if I can solve the problem and add the solution here for any others. to summarize, not only can I not add blocklists or update gravity, but any devices added to the DNS server of the pi-hole will then not be able to access websites.
yes, the file has the correct extension. I also tried using the vi editor method which didn’t solve the issue either. Also, any device that has the DNS linked to the pi-hole cannot access any websites unfortunately
by doing a command:
sudo chmod g+w etc-pihole
fixed the 1st issue of being able to add blocklists.
however i’m still stuck on DNS resolutation currently unavailable. google searches suggest the same solution you did, which was have the nameserver 127.0.0.1 on the resolv.conf file, however that’s not working for me just yet unfortunately. I’ll try again, and update if I find a solution
Sorry for not getting to your other messages in time. This is a frustrating one because I dealt with it for a long time at first (which is actually why I created this tutorial, as the resolv.conf situation was a little confusing). When you created that file, did you map it immediately or did you go in at a later time (after the container was created) and try and map it then?
No problem, thank you for your help. I apologize as there is a heavy knowledge gap with me.
I may have done both. So I tried reinstalling Pi-Hole following your steps with resolv.conf mapping it immediately with the latest version and it still gave the same 2 errors of not being able to write, and DNS being unavailable.
some changes I noted from your version:
-your eth0 inet addr: points to 192.168.1.220
-mine is 192.168.0.—
so I set my pihole to an unused 192.168.0.— address.
I kept the same ph_bridge and settings you set though
I tried installing version 5.1 per your guide, and I’m unable to access Pi-hole’s GUI, and in the log it reported: DNS resolution is currently unavailable
So when you installed v5.1, did you receive the exact same DNS resolution error or is this a different error? As for not being able to get to the web admin page, is it giving you any type of error or can it simply not find the page?
Different error in the sense that it shows up in the log of the docker container and stops there rather than show up as an error in pihole’s GUI. After, I am unable to access pihole at all through the ip address.
That’s actually a good sign because that’s where I was receiving my errors (and was able to fix). Have you tried to install Pi-Hole v5.1 without the resolv.conf file?
Just reinstalled without resolv.conf, and received these errors in the docker container log:
WARNING Misconfigured DNS in /etc/resolv.conf: Two DNS servers are recommended, 127.0.0.1 and any backup server
WARNING Misconfigured DNS in /etc/resolv.conf: Primary DNS should be 127.0.0.1 (found 127.0.0.11
I then added resolv.conf with the settings you set, and received this error in the docker container log:
[✗] DNS resolution is currently unavailable
I looked at your adguard guide, perhaps I’ll try that to see if anything changes. One question, should any ports be allowed through for pihole? you mention so in the adguard guide. Thanks again.
I feel bad because I know my input has been unhelpful, but I just don’t know what it could be if it the resolv.conf issue doesn’t fix it. I had this issue for a few days when I first tried to implement Pi-hole on my NAS, but the resolv.conf file (at initial creation) fixed it and fixes it moving forward for every container I try and create.
One side question – are you using Synology’s firewall? If you are, can you allow traffic on port 53 (DNS port)?
I was using Synology’s firewall and port 53 was allowed but still received those errors. But luckily, I was finally able to get it to work by following https://github.com/piwi3910/techtalk/tree/master/Docker_series/07
One google search did mention having to set the time zone, but not sure if that was enough to hamper the entire thing. I’m not sure what particular setting in this code worked, but it ended up working. Thanks for your help throughout this process, I’m following your guides one by one and will move on to the next one now.
Glad that you were able to get it working!