Skip to content

Pi-hole & Unbound in Container Manager on a Synology NAS

Last updated on 27 February 2025

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 unneeded capabilities from the bridge version of the docker compose as they are not required.16/11/2024
Guide updated for the all new v6 of Pi-hole (Note if you upgrade from v5 you effectively have to change all the compose settings in line with the new guide so might be worth just scrapping and starting fresh unless you really need stats etc

Please note as recommended by the Pi-hole dev team I have added a Watchtower exclusion label to the compose so you can do manual updates. Automated ones could result in you losing internet access if a bad update takes place.

Edited again today as I left in a variable that is not required in Host and Macvlan mode “DNSMASQ_LISTENING” sorry.
20/02/2025
Had a rethink of the Guide, and it has been rewritten to include an overdue request of including Unbound!24/02/2025
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.

Pi-hole GitHub

What is Unbound (Optional)

Unbound is a validating, recursive, caching DNS resolver. Rather than using an upstream DNS provider such as Google or Cloudflare who will look up the IP addresses for domain names you visit Unbound does this for you. It queries root servers for the address for a website. For example when you visited this site its actually on the server 213.186.33.50. This adds a layer of privacy in your web browsing as you are not relying on a third party with this information.

Unbound GitHub

Host vs Bridge vs Macvlan Network Modes

You need to decide which mode of Networking you want to use, I have outlined the key points below in general order of preference. (Unbound will be on a bridge which has no impact on your choice)

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.

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.

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.

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.

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 initial guide 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/unbound #Optional

Unbound Configuration (Optional)

We need to make a config file for Unbound to define its network settings.

Download the file below and put it into the “unbound” folder we created earlier

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, enter the following:

SectionSetting
Project Name:pihole
Path:/docker/projects/pihole-compose
Source:Create docker-compose.yml

The code section of the below will be blank until we move to the next step.

Next we are going to drop in our docker compose configuration. You now need to decide if you are going to go with Host, Bridge Mode or Macvlan. Jump to the appropriate page to follow the setup.

Host – Page 2
Bridge – Page 3
Macvlan – Page 4

Pages: 1 2 3 4 5

Published inAd-Blocking / DNS 7.2DockerSynology

167 Comments

  1. Howler Howler

    Have you got an extension to this that uses a “cloudflared” container to use DNS-over-HTTPS ?

    • Dr_Frankenstein Dr_Frankenstein

      Hey Howler – Unfortunately it’s not something I have set up – I am extremely limited in time currently so pausing new guides currently as the existing ones plus discord eat a lot of support time.

  2. billy billy

    hi there when i click create project i get the error “failed to create macvlan port: device or resource busy”. nothing shows up in the logs besides that same error

    • Dr_Frankenstein Dr_Frankenstein

      Hi billy – It may be you already have the MACVLAN created – In the Networks section of Container Manager delete any existing MACVLAN (assuming its not in use)

  3. Johannes Johannes

    Thank you for your documentation. It works great. But is there a way to enable ipv6 with this setup? It is disabled by default on the NAS. And everything i tried failed.

    • Dr_Frankenstein Dr_Frankenstein

      I am going to be completely honest – I have nothing IPv6 across my network stack or from my ISP so it’s not something I have even tried.

      My basic understanding is that if you have IPv6 enabled on your router so it is giving out DHCP v6 addresses then enable ipv6 on the NAS and you should then be able to do v6 DNS.

  4. Michael Michael

    Greetings.

    I spun up a piHole following your guid using the macvlan configuration but none of the clients are coming in as their own IPs, they all seem to be coming in under the routers IP and its been a few hours now.

    Also, Is there any additional configurations that are required for multiple subnets? For example, if someone has a “guest” and “Iot” subnet for example?

    Thanks!

  5. jano jano

    thank you very much for this manual.
    I did check my config more times but not able to find solution to my problem.
    After I restart container {or synology restart because update} pihole is starting as from begining {I need to configure Interface settings to “Permit all origins” after each restart} and another problem is that I dont see any long term statistics.

    this is my volume config in docker compose
    /volume1/docker/pihole:/etc/pihole

    I did check persmisions and are ok,.
    Changes made in web in settings -> dns are saved to /volume1/docker/pihole/setupVars.conf and /volume1/docker/pihole/pihole-FTL.conf without problem

    any idea ? thanks

    • Dr_Frankenstein Dr_Frankenstein

      Hey Jano

      This must be a permissions issue, try running the following commands via SSH, you wont see any output but it grants the docker user full permissions to the required folder (I assume this is on volume1)

      sudo chown -R dockerlimited:dockergroup /volume1/docker/pihole

      sudo chmod -R a=,a+rX,u+w,g+w /volume1/docker/pihole

      • jano jano

        I did check that several times, anyway, I did stop container, run your command, remove pihole-FTL.db {because it has cca 22K} and started container.

        same problem, I had to correct settings for interface, otherwise it will not resolve for another vlans. AND again db is small and there are plenty errors in log “SQLite3 message: no such table: network_addresses in “SELECT interface FROM network JOIN network_addresses ON network_addresses.network_id = network.id WHERE network_addresses.ip = ? AND interface != ‘N/A’ AND interface IS NOT (1)”

        [/SNIP]

        • Dr_Frankenstein Dr_Frankenstein

          Its odd that you are still getting permission issues – Can you stop the project, then completely delete the whole /docker/pihole folder. Create it again using File Station and then right click on the /pihole folder and change it to the dockerlimited user as the owner.. Then start the project again.

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!