Skip to content

Pi-hole in Container Manager on a Synology NAS

Important or Recent Updates
Historic UpdatesDate
Updated guide for Container Manager and using Macvlan14/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 mode12/08/2023
Added additional security option to the compose to restrict the container from gaining new privileges25/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.
Historic Updates

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.

Macvlan or Bridge Mode?

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 This won’t impact ad blocking, but it will mean you can apply device specific rules etc.


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 you ad blocking with Tailscale.

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 and Bridge Network 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.


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.

In the next screen we will set up our General Settings, enter the following:

Project Name:pihole
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.

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.


    image: pihole/pihole:latest
    container_name: pihole
      - CAP_NET_RAW
      - CAP_CHOWN
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - WEB_PORT=8000
      - DNSMASQ_USER=pihole
      - /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
      - /volume1/docker/pihole/pihole:/etc/pihole
    restart: always

    name: macvlan
    driver: macvlan
      parent: eth0
        - subnet: ""
          ip_range: ""
          gateway: ""

Bridge Mode

    image: pihole/pihole:latest
    container_name: pihole
      - CAP_NET_RAW
      - CAP_CHOWN
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - WEB_PORT=8000
      - DNSMASQ_USER=pihole
      - /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
      - /volume1/docker/pihole/pihole:/etc/pihole
      - 53:53/udp
      - 8000:8000
    network_mode: synobridge
    restart: unless-stopped

We are now changing some settings this applies to both Macvlan and Bridge versions.

These UIDs are the ones 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.
As per the above these two lines 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
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 22 when you do that part below.

If you are setting up the Bridge version 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 in order for it to work on your Network.

I have broken down the edits needed in this table it includes the line numbers and an explanation of what to edit.

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 and Cloudflare1.1.1.1

ipv4_address: 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: eth0This 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: “”We need to change this in line with your networks’ subnet – in the example I have used 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: “”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: “”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.

On the final screen click ‘Done’ which will begin the download of the container images and once downloaded they will be launched!

The image will now be downloaded and extracted. You should see ‘Code 0’ when it has finished.

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


Bridge = Your NAS IP followed by the port :8000/admin/login.php

You can access the UI with the password you specified in the compose.

Now you need to add the appropriate IP address to your router depending on which method you used to set up Pi-hole

Bridge = 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!


What ports does Pi-hole use?

PortProtocolUsed For
67IPv4 UDPDHCP – Only used when the ipv4 DHCP server is enabled.
547IPv6 UDPDHCP – Only used when the ipv6 DHCP server is enabled.
8000TCPFor the WebUI

Buy Me a Coffee or Throw me some Sats

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 get the odd beverage. Plus 10% goes to the devs of the apps I do guides for every year.

Published inAd-Blocking / DNS 7.2DockerSynology


  1. James James

    Which ip address am I adding to my router’s DNS settings to point it to the pi-hole? The same as the IP I use to access the web ui? 192.168.xx.xx? Or the and

  2. Cody Cody

    Hello! Amazing resource as always, thanks so much. I’ve setup my macvlan network as described (my router is
    – subnet: “”
    ip_range: “”
    gateway: “”
    However when I build I get the error “failed to create network macvlan: Error response from daemon: failed to allocate gateway ( Address already in use”.
    Any ideas what could be causing this?

    • Dr_Frankenstein Dr_Frankenstein

      Do you already have a MACVLAN set up within Container Manager > Networks as this can clash. You will need to remove it if so and then define any containers you want on a MACVLAN within this same project.

  3. Iwan Iwan


    Thank you for your clear tutorials they have helped me resolve some errors in the passed.
    I have no IT background whatsoever. I just like trying new things with my Synology NAS.
    Recently I started using Container Manager. However with Pi-hole I run into an error which I dont understand:

    Error,2023/11/07 01:08:08,Iwan,Start container pihole failed: {“message”:”driver failed programming external connectivity on endpoint pihole (7c99c89137c466356bb4ceedd5030e……………………): Error starting userland proxy: listen tcp4 bind: address already in use”}.

    It looks like to me like a conflict with a previous installation, where i did manage to open Pi-hole but than the DNS was not working/starting.

    Is there anyway to solve this?

    Thank you!

    • Dr_Frankenstein Dr_Frankenstein

      Hey, thanks for the feedback. I would double check you have completely removed the other container and also make sure you don’t have anything else on port 8000. Sometimes a reboot can clear things up if a port has not been released. Doesn’t happen often but worth a shot.

  4. Erik Hagemeijer Erik Hagemeijer

    In the query log I only see address, is it possible to see the ip addresses of the clients that do the lookup?

    • Dr_Frankenstein Dr_Frankenstein

      You would need to run the container in MACVLAN mode in order for it to act independently of the Docker Bridge which is handling the routing.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed. – writing Synology Docker Guides since 2016 – Join My Discord!