Skip to content

Pi-hole in Container Manager on a Synology NAS

Last updated on 16 November 2024

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.
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 one01/08/2024
Removed two uneeded capabilites from the bridge version of the docker compose as they are not required.16/11/2024
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.

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.

Folders
/docker/projects/pihole-compose
/docker/pihole
/docker/pihole/dnsmasq.d
/docker/pihole/pihole

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:

SectionSetting
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.

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

YAML
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

YAML
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

YAML
services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole-bridge
    cap_add:
      - 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.

SectionExplanation
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

Now you can make some edits to the compose information before moving on

SectionExplanation
ipv4_address: 192.168.0.122Change 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: “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.

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

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.

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?

PortProtocolUsed For
53TCP/UDPDNS
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

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.

Published inAd-Blocking / DNS 7.2DockerSynology

140 Comments

  1. Kael Kael

    Many thanks for these guides – they’re truly useful!
    One problem I encounter is when using the host network, if I change the Synology IP, through getting a new router or whatever, the container breaks and I have to recreate it. Is that to be expected? Can it be modified instead?
    Updating the FTLCONF_LOCAL_IPV4= to the new address doesn’t fix it.

    Finally, any tips for which adlists in Pihole to subscribe to?

    • Dr_Frankenstein Dr_Frankenstein

      Hey, you should set a manual IP for DSM in the Control Panel > Networks or tell your router to assign the same IP (DHCP Reservation) so it doesn’t change at all. Keep in mind that when you update the address it will take a while for each device to receive the new IP. They will generally be on a 24-hour lease time before asking to renew the details from the router.

      Oh, and list wise this site tends to do an annual update of where to get the best lists. Just don’t go crazy with them!

      https://avoidthehack.com/best-pihole-blocklists

  2. Muiz Muiz

    The bridge version : [✗] DNS resolution is currently unavailable

    The host version : /bin/bash: line 1: 477 Real-time signal 0 /usr/bin/pihole-FTL no-daemon > /dev/null 2>&1
    Stopping pihole-FTL
    pihole-FTL: no process found

    Remove the FTL no-daemon fixes the error, but pihole doesnt show Queries

    The host version after redo the ip nrs : [✗] DNS resolution is currently unavailable and doesnt eben come up

    cap_add: : only neded if you use Pihole as DHCP

    And :
    For Synology :
    DNSMASQ_USER:root
    FTLCONF_LOCAL_IPV4=0.0.0.0

    So its time to redo this guide. Its A or incorrect or incorect cause of out of date.

    • Dr_Frankenstein Dr_Frankenstein

      Hi

      I will remove the two lines below from the Bridge version of the YAML as you are correct that won’t support DHCP due to the lack of ports being exposed so it won’t need the extra caps. However, the other two could be used for that purpose so will leave them in place as well as the chown.

      – CAP_NET_RAW
      – CAP_NET_BIND_SERVICE

      You should be able to use a non-root user for DNSMASQ successfully. It has been in the guide that way since pre DSM7 as we are granting the user permissions via the UID/GID of our dockerlimited user not the default Pi-hole internal user permissions of 999:1000. I know there were reports of issues back in 2022, but they seem to have been resolved avoiding the need for root. Double-check the folders have the dockerlimited user as owner or has read/write permissions.

      The guides go through regular amendments and testing so no ‘redo’ is required to be sure I just spun up all 3 versions on my DSM VM which is purely for the guides, and this exact same versions are in use on my live server.

      Happy to check your full logs to see what else must be going on.

      https://paste.drfrankenstein.co.uk

      Cheers

  3. Dave Dave

    Thanks for the great guide!

    Up until this morning I was running pi hole on a raspberry pi, and I powered it off to do something and it wouldn’t boot again when I powered it back on, so time to run it on the NAS!

    Now that it’s in docker, what’s the equivalent to the pihole -up command? Stop the container, then Action>Build the project and it will pull the latest files, rebuild, and restart?

  4. Dominic Dominic

    Hey Dr_Frankenstein,

    I am a new visitor and must say, you created some great Guides here.
    First I followed your „Initial Setup“ Guides and I want to use the Bridge Mode. Not sure if that is important for my question.
    I followed this Guide and the Container is starting perfectly fine in the first place. However, in the logs I can see a lot of messages like this:
    „pihole-FTL: no process found“

    Do you have an idea what could cause this issue?
    Or did miss something?

    Thank you in advance.
    Best regards,
    Dominic

    • Dr_Frankenstein Dr_Frankenstein

      Hey

      Just catching up on some comments, did you get this going? You may want to stop the container. delete the contents of each folder and start up the project again. See if that then allows FTL to start up.

      • Dominic Dominic

        Hi,

        sadly I still have the same issue after deleting folder contents and restarting the project. However, I noticed the following error messages:
        – „Failed to set capabilities on file /usr/bin/pihole-FTL (Operation not supported)“
        – „The value of the capability Argument is not permitted for a file. Or the file is not a regular (non-symlink) file
        – ERROR: Unable to set cababilities for pihole-FTL. Cannot run as non-root

        Thank you for your Support.
        Best Regards,
        Dominic

        • Dr_Frankenstein Dr_Frankenstein

          OK I suspect this is permissions related, First check the PIHOLE_UID and GID are correct if they are can you jump back to the User and Group guide, towards the bottom there are a couple of commands to run…. Adjust the paths mentioned to just /volume1/docker/pihole and then start the container up again.

          • Dominic Dominic

            drwxrwxr-x 4 docker dockergroup 4096 Jun 2 21:13 .
            drwxrwxr-x 6 docker dockergroup 4096 May 31 12:39 ..
            drwxrwxr-x 2 docker dockergroup 4096 Jun 2 21:13 dnsmasq.d
            drwxrwxr-x 2 docker dockergroup 4096 Jun 3 21:26 pihole

            Permissions should be fine.
            My Docker User already was present before. Maybe I just try to recreate it once again tomorrow.
            I will let you know if it worked.

  5. Mike Scott Mike Scott

    Hey Doc, hope you’re doing well. Question: with host mode, do I still need to update my DNS servers/DHCP settings? I recently had an issue with my router where everything on my network stopped working due to those settings so I had to put them back to 8.8.8.8 to get them running again. I’m just trying to figure out the best way to get this going. Thanks!

    • Dr_Frankenstein Dr_Frankenstein

      Hey – So yes in Host Mode you still need to update the IP be given out by your DHCP server otherwise your devices won’t be using the NAS for DNS requests. Keep in mind if the Pi-hole is ever off you will lose internet access.

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.

drfrankenstein.co.uk – writing Synology Docker Guides since 2016 – Join My Discord!