Last updated on 5 April 2025
Macvlan
Drop the compose below into your Project YAML section.
services:
pihole:
image: pihole/pihole:latest
container_name: pihole-macvlan
cap_add:
- CAP_NET_RAW
- CAP_NET_BIND_SERVICE
- CAP_CHOWN
# - CAP_NET_ADMIN #uncomment if you want to use DHCP
- CAP_SYS_NICE
- CAP_SYS_TIME
environment:
- PIHOLE_UID=1234 #CHANGE_TO_YOUR_UID
- PIHOLE_GID=65432 #CHANGE_TO_YOUR_GID
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- FTLCONF_webserver_api_password=YOURPASSWORD
- DNSMASQ_USER=pihole
volumes:
- /volume1/docker/pihole:/etc/pihole
networks:
macvlan:
ipv4_address: 192.168.0.129
labels:
- com.centurylinklabs.watchtower.enable=false
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"
Settings Amendments for the Macvlan
OK we now need to make some further edits to the compose and sort out DNS for DSM
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 |
FTLCONF_webserver_ api_password= | Change this to the password you would like to use for the Web UI |
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

Now you can make some edits to the compose information before moving on
Section | Explanation |
---|---|
ipv4_address: 192.168.0.129 | 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. |
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 |
You can now jump ahead to Page 5 for the final configuration.
how can we update the FTLCONF_webserver_
api_password ?
Hey check out the official docs for full sets of variables, but this is set exactly as you put
– FTLCONF_webserver_api_password=’THIS IS MY PASSWORD’
https://docs.pi-hole.net/docker/configuration/#environment-variables
Does this automatically install Unbound? I used 127.0.0.1#5335 as my Custom DNS Server, but I get a connection error:
CONNECTION_ERROR Connection error (127.0.0.1#5335): TCP connection failed (Connection refused)
I’m also getting this:
DNSMASQ_WARN dnsmasq warning:
Maximum number of concurrent DNS queries reached (max: 150)
Hey Rod – I just realised my left menu still say Unbound in the link – I actually removed the Unbound element from the guide as it was causing my trouble than its worth. So you need to set it up independently
Were you still planning to add Unbound to the guide later? Was keeping this page bookmarked out of interest for that. Your guides were very helpful when I first started into self-hosting. Thank you so much for sharing your expertise!
I am not sure why, but it seemed to cause lots of random issues for people. I just hunted back through our Pi-hole megathread on Discord as Muiz had a working compose it includes Redis for local caching of queries. You need to place the config files in the right folders
https://paste.drfrankenstein.co.uk/?2dab3f135acedfd0#6k2P2epCToLQB1Hn6fpeFRKEc3MKBJYVaqVoupD6e57A
https://drfrankenstein.co.uk/wp-content/uploads/2025/02/unbound.conf /docker/unbound/data
https://drfrankenstein.co.uk/wp-content/uploads/2025/06/cachedb.conf /docker/unbound/
Just my 2c…
After a lot of testing myself I found out that the only stable and solid solution to use PiHole as a recursive DNS server using docker is by concentrating on the following docker image:
https://github.com/mpgirro/docker-pihole-unbound/blob/main/README.md
So I would suggest to try this one and provide a guide for this image. Really a good and stable solution, much better than using different PiHole and Unbound images in the same project.
OK good to know – will add to the reading list 🙂