How to Set Up Pi-Hole on OpenMediaVault!

Today we are going to install Pi-hole on OpenMediaVault using Docker and Portainer.

Fortunately, OpenMediaVault makes it very easy to install Docker and Portainer. We will be installing Pi-hole on Portainer and using a macvlan network interface so that we don’t have any port conflicts with our OpenMediaVault instance. If you haven’t installed OpenMediaVault yet, you can learn how to do that here.

Before we get started, it is incredibly important to note that having redundant DNS servers is very important. I highly suggest that you purchase a cheap Raspberry Pi Zero and configure Pi-hole on it so that you have two Pi-hole DNS servers. This will ensure that when your NAS is rebooted, your clients do not lose DNS resolution services.

Instructions – Pi-Hole OpenMediaVault

1. Login to OpenMediaVault and select OMV-Extras on the left-hand side. If you don’t have OMV-Extras, you will need to install it from the Plugins section.

openmediavault pi-hole - settings in openmediavault

2. Select the Docker tab, then click the Docker drop-down and select Install. Docker will now install.

openmediavault pi-hole - installing docker in openmediavault

3. Select the Portainer drop-down and select Install. We will be using Portainer to install Pi-hole.

4. When Portainer finishes, restart your Raspberry Pi and when it comes back up, Open Portainer.

how to open portainer

5. Set up your username and password for Portainer.

openmediavault pi-hole - creating the administrator user

6. Select Docker and then Connect.

openmediavault pi-hole - docker settings in portainer

7. Select Local. Leave this up in the background and we will get back to it in a few steps.

local docker container in portainer

8. Now that Portainer is set up, we need to create a docker macvlan network interface. SSH into your Raspberry Pi the same way you did when you initially set up OpenMediaVault. We need to determine what network interfaces currently exist (on your Raspberry Pi) and note down the adapter name. To do this, run the command below and note down the network interface name that has your Raspberry Pi’s IP address (in this example, mine is enxb827eb03ae0e).

viewing the ip addresses in terminal for the raspberry pi

9. Next, you need to run the command below while substituting the correct subnet (most are by default) and network interface ID (mine is enxb827eb03ae0e). You also need to pick an IP address that you’d like to use that’s not currently in use. I will be using NOTE: ph_network will be the name of the network (you can substitute this as you’d like). The items listed below in pink might need to be updated when you run this command.

sudo docker network create -d macvlan -o parent=enxb827eb03ae0e --subnet= --gateway= --ip-range= ph_network

10. The network interface is now setup. Go back to Portainer and select Volumes.

11. Select Add Volume and add two total volumes. One with the name etc-pihole and one with the name etc-dnsmasq.d.

openmediavault pi-hole - creating volumes in portainer

12. Select Containers and then Add Container.

openmediavault pi-hole - portainer containers
adding a container in portainer

13. Give the container a Name and then in the Image section, enter pihole/pihole:latest.

openmediavault pi-hole container name

14. Select Publish a new network port five total times and match the ports as the screenshot below shows. NOTE: Ensure that you have the two top ports (53, 67) set as UDP ports.

openmediavault pi-hole - port settings for pi-hole

15. Select Volumes and select map additional volume twice. Enter the first container as /etc/pihole and select the /etc/pihole volume. Enter the second container as /etc/dnsmasq.d and select the /etc/dnsmasq.d volume.

openmediavault pi-hole - volume settings for pi-hole

16. In the Network tab, select the macvlan network we created earlier.

adding the pi-hole network created

17. In the Env section, enter the two variables in the screenshot below. Ensure that you replace WEBPASSWORD value with the password that you’d like to use to access Pi-Hole. Also, change the ServerIP value to match the IP address you created for your macvlan network interface.

adding pi-hole environment variables

18. In the Restart Policy, change this to Always. This will force Pi-Hole to always start when Docker starts.

changing the restart policy of the container

19. Finally, in the Capabilities, turn on NET_ADMIN.

modifying the capabilities of the docker container

20. Select Deploy the container. The container will take a few minutes to fully download and install, but when it’s done and reporting running, you will be able to access the Pi-Hole web admin interface using the ServerIP address you assigned!


DNS Configuration

Now that the setup of Pi-hole is complete, we need to determine a way to point our clients to our DNS server. There are two main ways to do this:

  • Point your router’s DNS server to your Pi-hole server IP address. This will ensure that any device connected will use Pi-hole as its DNS server.
  • Point each client to your DNS server. This is beneficial if you only want certain clients to use Pi-hole as a DNS server.

I point my routers DNS servers to my Pi-hole server as I want to ensure every device connects to it.

dns server settings for the router


Setting up Pi-Hole on OpenMediaVault isn’t too bad thanks to Portainer. Technically, this tutorial will work for any Docker instance where Portainer is installed if OpenMediaVault isn’t something that you have installed!

Thank you for reading the tutorial! As always, if you have any questions, please leave them in the comments!

Please share if this helped you!

You are currently viewing How to Set Up Pi-Hole on OpenMediaVault!

This Post Has 102 Comments

  1. Marcel

    Hi and thanks for the great tutorial!
    I follow your steps, but i get one Error: I can`t accsess with my password to pi-hole.
    When I click on the container, I see the password I assigned under Webpassword. But when I enter it on the start page of Pi-Hole, I always get the message that it is wrong. What can I do here? (My container is on healty state)

    1. WunderTech

      Just to confirm, you have “WEBPASSWORD” in all caps, right? Not sure if that’s a requirement. Also, if it is, did you set it before the container was created? The container has to be created with the environment variable (cannot be added after).

  2. Hemant

    Good Day

    worked like a charm. thanks

    i have disabled the query logging thru web interface however need your help to increase the log database interval.


  3. caio

    Hello I followed your tutorial with raspberry pi 4 and omv 5 successfully, but in volumes I indicated to the share folder of my external hd config, and no pihole file is created, I remember that when I used it in the past, files were created in this folder, you know why does this occur?

    1. WunderTech

      I am not entirely sure why it wouldn’t be there. Have you considered running Pi-hole in Docker?

  4. Cody

    Works great. How do I add unbound to this pihole container? I am struggling to find a way to run pihole and unbound in the same container.

    1. WunderTech

      Using Docker is slightly tricky. I’m assuming you installed Unbound on the host and then Pi-hole inside of Docker? Did you use a macvlan network interface/bridge network interface? If so, I believe you can use the bridge IP address and it should function properly.

  5. Dominik


    i face several issues which might hav one root cause.

    1. when i try to update gravity it runs in a timeout:
    [X] DNS resolution is currently unavailable
    [X] DNS resolution is not available

    2. from the Docker Console i cannot ping my Gateway..

    Here are my IPs:

    (old PiHole already shutted down and deleted from several configs):
    PiHole (Docker):

    i’ve added the env “DNS1=” and “DNS2=” but this didn’t work

    i also cannot change the /etc/resolv.conf from the Docker Console because wether nano nor vi is installed. Since i cannot reach my GW i cannot install one of those editors.

    The Output from “cat /etc/resolv.conf” is:

    options ndots:0

    i did step by step from your tutorial. I hope you have an idea.

    1. WunderTech

      I have run into that issue on my Synology NAS, but not on OMV. Can you create a file somewhere on your system called “resolv.conf”, add two different lines with:


      Then map a file volume to the location of that resolv.conf file, with the mount path as “/etc/resolv.conf”. I suspect this should fix it.

      It’s in these Synology NAS instructions, it’s just a different GUI – should be the same steps though:

  6. Martin

    Great guide, It works for me without issue.

    but I have a question regarding the Volumes you setup.
    /etc/pihole & /etc/dnsmasq.d

    Why is this needed? What if I skip that step?

    1. WunderTech

      Thanks! Those locations are mapped to a volume so that you can move your personal data (from Pi-hole) to a different system/container if you’d like.

  7. Tiiara

    Hi there. I followed your guide to the best of my knowledge but I’cant seem to access the pihole admin page. I always get a network timeout. My router (Fritzbox) does find the device, but I cannot connect at all.
    In portainer the pi-hole container is running as healty.
    I used this command in SSH $ sudo docker network create -d macvlan -o parent=eth0 –subnet= –gateway= –ip-range= ph_network
    Any ideas? Any information you need for troubleshooting?

    1. WunderTech

      If the router finds it, then it’s most likely there. Are you using the correct port? This will generally be 80, but if you changed it to something different, you will have to use that.

      1. Tiiara

        No, I didn’t change any ports.I also tried deleting everything and going trough the setup again but still nothing. I did spot something interesting. The router only found the IP during or shortly after the initial setup. I tried restarting OMV and after that the IP shows as offline in the routers webadmin, but it is still running in portainer and showing as healthy.

      2. Tiiara

        I tried pinging my router via the terminal in Containers > Pi-Hole > Console and THIS works. But it does not work the other way around. Maybe some kind of security feature or setting I’m unaware of?

        1. WunderTech

          If the container isn’t getting an IP address, then there’s a problem at that point. Just for testing, can you try creating a container without the macvlan and see if you can access it? Map the port 80 to something different (8080 for example).

          1. Tiiara

            Just to make sure I don’t brick my OMV: You want me to try following your guide, skipping the first step with the mcvlan network and create the container just as in the guide, but change the manual network port publishing from host 80 > container 80 to host 8080 > container 80. Also, in the Advanced container settings under “Network” I leave “Network” as “bridge” and the “environment variable” “ServerIP” should now be the same as the one used for OMV , right?

          2. WunderTech

            That is correct, but I would suggest that you ensure you have proper backups if you plan on playing around. I don’t really think this will have any impact on OMV, but I always suggest having a rollback plan.

  8. Tiiara

    Hey there, great guide. Really easy to follow.
    Everything seems to work fine, portainer works, pi-Hole container shows healthy but I can’t connect to the web admin. Browser shows connection timeout. Any ideas?

  9. Philippe

    Hi, great support, 1st run 1st success, try other tips found on the web, most simple, run in 1 shoot.
    Just needed to rename the “hostname” but tips is given is the discussion.
    I suppose when new pi-hole version will release jus need to type again pihole/pihole:latest in the “” and run “create”

    1. WunderTech

      That is correct! Glad that it helped!

Comments are closed.