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 |
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.
Host vs Macvlan vs Bridge Network Modes
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.
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.
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.
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 two initial guides 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/pihole/dnsmasq.d
/docker/pihole/pihole
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/10/image-97.png)
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’.
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/05/image-37.png)
In the next screen we will set up our General Settings.
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 |
Next we are going to drop in our docker compose configuration. You now need to decide if you are going to go with Macvlan or Bridge Mode and copy the appropriate compose from below and paste it into line ‘1’ just like the screenshot.
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/10/image-98.png)
What on earth is a Docker Compose? Docker Compose allows us to define how Docker should set up one or more containers within a single configuration file. This file is yaml formatted and Container Manager uses the Projects feature to manage them.
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.
Host
services:
pihole:
image: pihole/pihole:latest
container_name: pihole-host
cap_add:
- CAP_NET_RAW
- CAP_NET_BIND_SERVICE
- CAP_CHOWN
environment:
- PIHOLE_UID=1234 #CHANGE_TO_YOUR_UID
- PIHOLE_GID=65432 #CHANGE_TO_YOUR_GID
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- WEBPASSWORD=YOURPASSWORD
- DNSMASQ_LISTENING=local
- WEB_PORT=8000
- DNSMASQ_USER=pihole
- FTLCONF_LOCAL_IPV4=YOURIPV4ADDRESS
volumes:
- /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
- /volume1/docker/pihole/pihole:/etc/pihole
network_mode: host
restart: unless-stopped
Macvlan
services:
pihole:
image: pihole/pihole:latest
container_name: pihole-macvlan
cap_add:
- CAP_NET_RAW
- CAP_NET_BIND_SERVICE
- CAP_CHOWN
environment:
- PIHOLE_UID=1234 #CHANGE_TO_YOUR_UID
- PIHOLE_GID=65432 #CHANGE_TO_YOUR_GID
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- WEBPASSWORD=YOURPASSWORD
- DNSMASQ_LISTENING=local
- WEB_PORT=8000
- DNSMASQ_USER=pihole
- FTLCONF_LOCAL_IPV4=YOURIPV4ADDRESS
volumes:
- /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
- /volume1/docker/pihole/pihole:/etc/pihole
networks:
macvlan:
ipv4_address: 192.168.0.129
restart: always
networks:
macvlan:
name: macvlan
driver: macvlan
driver_opts:
parent: eth0
ipam:
config:
- subnet: "192.168.0.0/24"
ip_range: "192.168.0.254/24"
gateway: "192.168.0.1"
Bridge Mode
services:
pihole:
image: pihole/pihole:latest
container_name: pihole-bridge
cap_add:
- CAP_NET_RAW
- CAP_NET_BIND_SERVICE
- CAP_CHOWN
environment:
- PIHOLE_UID=1234 #CHANGE_TO_YOUR_UID
- PIHOLE_GID=65432 #CHANGE_TO_YOUR_GID
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- WEBPASSWORD=YOURPASSWORD
- DNSMASQ_LISTENING=local
- WEB_PORT=8000
- DNSMASQ_USER=pihole
- FTLCONF_LOCAL_IPV4=YOURIPV4ADDRESS
volumes:
- /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
- /volume1/docker/pihole/pihole:/etc/pihole
ports:
- 53:53/udp
- 8000:8000/tcp
restart: unless-stopped
We are now changing some settings this applies to all versions of the YAML above.
Section | Explanation |
---|---|
PIHOLE_UID= | This UID is the one you obtained when setting up your dockerlimited user in the earlier guide at the start of the page. This tells Pi-hole to run under this user rather than root and gives it access to the folders we created. |
PIHOLE_GID= | As per the above this line will be the GID you obtained earlier. |
TZ= | You will need to change this line to your own timezone code – you can find the correct list of ones to use on wikipedia.org/wiki/List_of_tz_database_time_zones |
WEBPASSWORD= | Change this to the password you would like to use for the Web UI |
FTLCONF_LOCAL_IPV4= | If you are using the Bridge Mode this line will be the IP address of your NAS If you are using MACVLAN Mode this line will be the same as line 25 when you do that part below. |
If you are setting up the Bridge or Host versions you can now press next and jump ahead in the guide to Web portal settings for MACVLAN continue on below.
Settings Amendments for the Macvlan
OK we now need to make some further edits to the compose and sort out DNS for DSM
External DNS for DSM
Containers on a Macvlan cannot be accessed by the host they reside on (without network changes under the hood), this mean DSM cannot use Pi-hole for its own DNS requests. It’s better to put DSM on an external DNS provider to avoid it having any issues connecting to the Internet if your Pi-hole is down.
Go into the DSM Control Panel > Network and then in the ‘Manually configure DNS server’ set two good quality DNS providers such as Quad9 9.9.9.9
and Cloudflare1.1.1.1
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/06/image.png)
Now you can make some edits to the compose information before moving on
Section | Explanation |
---|---|
ipv4_address: 192.168.0.122 | Change to the IP address you want to use for the container. Make sure this is available and not in use by another device on your network. Don’t forget to go back up and change line 15. |
parent: eth0 | This defines the network interface the container should use, I have used eth0 which will be the first Ethernet port on your NAS. If you want to use a different port change it accordingly. Note! If you have Virtual Machine Manager installed change this to ovs_eth0 |
subnet: “192.168.0.0/24” | We need to change this in line with your networks’ subnet – in the example I have used 192.168.0.0/24. The super quick way to work out what to use is just take the IP of your NAS and change the final digit before the /24 to 0 |
ip_range: “192.168.0.254/24” | This has to be changed to the highest available IP address within the range of your subnet. Again if your network is in the 192 range the final number used from the subnet above can be changed to 254 and added to this section. |
gateway: “192.168.0.1” | This will be the IP address of your Router/Gateway/DHCP Server |
Once you have made the edits you can click ‘Next’
Web portal settings
You do not need to enable anything on the ‘Web portal settings’ screen click ‘Next’ again.
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/05/image-41.png)
On the final screen click ‘Done’ which will begin the download of the container images and once downloaded they will be launched!
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/10/image-99.png)
The image will now be downloaded and extracted. You should see ‘Code 0’ when it has finished.
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/05/image-49.png)
You will now see your Pi-hole running and should have a green status on the left-hand side.
The web interface will now be available via the below.
Macvlan = the IP you specified in the compose followed by the port :8000/admin/login.php
OR
Bridge or Host = Your NAS IP followed by the port :8000/admin/login.php
You can access the UI with the password you specified in the compose.
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/05/image-50.png)
![](https://drfrankenstein.co.uk/wp-content/uploads/2023/05/image-51-1024x777.png)
Update your Router DNS
Now you need to add the appropriate IP address to your router depending on which method you used to set up Pi-hole
Bridge or Host = NAS IP
MACVLAN=The address you chose for the container on the line ‘ipv4_address:’
It can take some time for all of your devices to move over the new DNS settings so be patient, and you will gradually start to see your stats begin to start.
Also note as we are not using Pi-hole as the DHCP server you will not be able to see the names of the devices in the statistics just their IP addresses.
That’s it!
FAQ:
What ports does Pi-hole use?
Port | Protocol | Used For |
---|---|---|
53 | TCP/UDP | DNS |
67 | IPv4 UDP | DHCP – Only used when the ipv4 DHCP server is enabled. |
547 | IPv6 UDP | DHCP – Only used when the ipv6 DHCP server is enabled. |
8000 | TCP | For the WebUI |
Looking for some help, join our Discord community
If you are struggling with any steps in the guides or looking to branch out into other containers join our Discord community!
Buy me a beverage!
If you have found my site useful please consider pinging me a tip as it helps cover the cost of running things or just lets me stay hydrated. Plus 10% goes to the devs of the apps I do guides for every year.
hi, just discovered your site, it is amazing !
I ‘m using talescale with my synology, and I have the following message :
Code d’erreur : PR_END_OF_FILE_ERROR
I connect to : tailscaleIPAdress:8000/admin/login.php
Hey thanks 🙂
The machine you are on is it connected to Tailscale – Do you have subnetting enabled as you can then just use the NAS IP instead of the tailscale one
Have you tried using this with Unbound? Do you have one in the works that combines Pihole with Unbound?
I did have unbound running a few years ago on my original PiZero install – Let me check what it entails for Docker.
Thank you for this guide. I have followed the whole guide and when I click “done” I get the error “Start container pihole failed: {“message”: “driver failed programming external connectivity on endpoint pihole: error starting useland proxy: listen tcp4 0.0.0.0:53: bind: address already in use”}
I tried a “netstat” and it does not indicate any other open processes on port 53
Can you help me.
Thank you
Hey – can you try changing the network mode to host – you will need to review the ‘ports’ section.network_mode: host
Try changing the ports section to include ‘udp’
– 53:53/udp
Hello. It works!
Thank you Dr.
Hi, thanks for this guide.
I want to see the device names in the Pihole statistics. Your last sentence states “Also note as we are not using Pi-hole as the DHCP server you will not be able to see the names of the devices in the statistics just their IP addresses.”
Can you advise.
So there is an option within the UI Settings > DNS > Conditional Forwarding, you will need to set the IPs as described in the info, I never managed to get this to function on my own network.
Local network in CIDR notation = Basically take your NAS IP and change the last number to 0 (e.g 192.168.0.101 would be 192.168.0.0)
IP address of your DHCP server (router) = Your Router IP
Hello there, thanks for putting this together! The pihole container image downloads, it gets created with all my settings, but I can not load the pihole login page.
When I check the log (container manager>container>log), I see the following repeating error message:
lighttpd: no process found
Stopping lighttpd
pihole-FTL: no process found
Stopping pihole-FTL
(repeat, repeat, repeat)
I followed steps 1,2,3 from your “initial setup” pages before I created the container… not sure what I missed. I will try again later this week but I wonder if these error messages immediately show that I missed a specific step?
Check to make sure your PUID/PGID (UID/GID)are correct in case it is struggling to write the config into /docker/pihole
Hi Doctor, thanks for the fast response! I think my GUI and UID are correctly set (see below). I did a bunch of Googling of similar issues, and here’s what I changed in the YAML file to get it to work.
(change #1) I changed DNSMASQ user from pihole to root:
DNSMASQ_USER=root
(change #2) I commented out the 4 lines requiring UID/GID:
# – PIHOLE_UID=1033
# – PIHOLE_GID=100
# – WEB_UID=1033
# – WEB_GID=100
I don’t know what’s going on under the hood, but this is what worked for me. Do you think I’m doing something particularly stupid/insecure with these changes?
I suspect it’s a permission issue as removing those lines and changing to root means all the files are owned by the root user in the container. So has exclusive permissions to the mounted folder.
Hey Max,
I have run into this exact same issue. Were you able to fix the permissions issue at all? If so, are you able to share the resolution steps?
Thanks