How to install nxfilter and pihole with docker


Feature request: NxFilter for NethServer

This howto is for testing the DNS webfilters. Do not use in production.
Maybe we could improve it together. Please test and give feedback…


Get docker repo and install and enable nethserver-docker:

cd ~
wget -O /etc/yum.repos.d/docker-ce.repo
yum -y install
config setprop docker status enabled
signal-event nethserver-docker-update


For testing purposes I decided to open the docker network by policy. In a production environment you should leave this step and set firewall rules.

mkdir -p /etc/e-smith/templates-custom/etc/shorewall/policy
cp /etc/e-smith/templates/etc/shorewall/policy/35aqua /etc/e-smith/templates-custom/etc/shorewall/policy/
cat << 'EOF' > /etc/e-smith/templates-custom/etc/shorewall/policy/35aqua
# 35aqua -- the Docker network policy
aqua net ACCEPT
loc aqua ACCEPT
signal-event firewall-adjust

Download and start containers

Install nxfilter and/or pihole to test them.
Edit TZ=Europe/Vienna to match your timezone:


docker run -d --name nxfilter -v nxfilter-conf:/nxfilter/conf -v nxfilter-log:/nxfilter/log -v nxfilter-db:/nxfilter/db -e TZ=Europe/Vienna --net=aqua --restart=unless-stopped packetworks/nxfilter-base:latest


docker run -d --name pihole -e TZ="Europe/Vienna" -e WEBPASSWORD="admin" -v "$(pwd)/etc-pihole/:/etc/pihole/" -v "$(pwd)/etc-dnsmasq.d/:/etc/dnsmasq.d/" --cap-add NET_ADMIN --net=aqua --restart=unless-stopped pihole/pihole:latest


Browse to https://YOURNETH:980/portainer, setup admin username/password and select Local.
Now you can manage the containers via web UI.

Check the IPs of your machines, if you installed in a different order they may differ. In this howto is the nxfilter, is the pihole.

General rules for adding more docker containers

  • don’t publish ports
  • put the containers to aqua network
  • set restart to policy to unless-stopped



Browse to and login with admin, password: admin

You may need to set upstream DNS:


NxFilter supports LDAP/AD and much more…


Browse to and login with password: admin

You may need to set upstream DNS:

Client access

You may use a static route on the internet gateway for the aqua network to go to the docker machine. This way all clients should be able to access it.


Clients use filter DNS

The clients use the DNS server of a webfilter. They may get the DNS server to use from Nethserver DHCP.
This webfilter uses the Nethserver as upstream DNS.
The Nethserver uses an outside upstream DNS like (google).
This way the filter gets the client IP and you can see it in the logs. Nxfilter for instance can map the IP to AD/LDAP users.

Nethserver uses webfilter as upstream DNS

In this case the filter only gets the IP of the Nethserver and has no information who is surfing but blocks ads and more.

Clients use Nethserver proxy

You need to set the Nethserver upstream DNS to one of the filters. Now when clients use the proxy the DNS filter is involved.


You may use more filters for testing. One filter uses the next one as upstream DNS. The last filter uses Nethserver as upstream DNS.


  • Testing
  • More secure firewall
  • Using rootless podman containers - I already tried but no success

Bring to this man a medal! And a beer, of course.


Good afternoon,

I was playing around with Guacamole and ran into problems trying to deploy nethserver-docker on a fresh NS demo. Installng the nethserver-docker via yum install --enablerepo=nethforge-testing nethserver-docker resulted in the following error:


[root@nethdemo ~]# yum install --enablerepo=nethforge-testing nethserver-docker
Loaded plugins: changelog, fastestmirror, nethserver_events
Loading mirror speeds from cached hostfile

I also noted that yum install of results in a failed connection. Am i missing something?

Sorry, I was testing. It should work now again, please try.
Alternatively you may download my new repo located on another server where I do no testing:

yum -y install

Very nice howto ! I’m planning to migrate my pihole currently performing very nicely on a pi to my NS gateway.

Question : how do I access that network from the green LAN ?? Sorry if it sounds obvious :wink:

1 Like

Thanks, it’s missing in the howto, I am going to add it…done.
Just add a static route on your gateway for routing to the aqua network via your docker machine. This way all clients should be able to reach it.

Yeah that’s what I was going to do. I’m really new to docker, I never really used it. Why not bridging i.e the green interface to docker’s ? After all, from the user point of view, what we want is a service like another ?

1 Like

I never tried it with a bridged network to green.
I think it’s because of security (not bridge all containers to green by default) and to get the possibility of firewalling/routing or use local reverse proxy to containers without opening them completely to the local network.

1 Like

I’m trying PiHole on docker. Take care : the IP address given by docker can change upon restart. This is really weird, though expected. Clients will obviously not get DNS resolution anymore if that IP changes. is giving some clues how to circumvent this but I’m afraid my knowledge of docker is not good enough to fully grasp the real fix.

What do you think @mrmarkuz ?

I couldn’t reproduce this issue. The IP only changed if I removed the container or the network from the container.

You may define an IP address with the --ip option:

docker run -d --name nxfilter -v nxfilter-conf:/nxfilter/conf -v nxfilter-log:/nxfilter/log -v nxfilter-db:/nxfilter/db -e TZ=Europe/Vienna --net=aqua --ip= --restart=unless-stopped packetworks/nxfilter-base:latest

1 Like

I had installed other docker images after PiHole. Could be the reason. All the IPs were mixed up. Thanks for the tip.

so the current portainer version has been updated right?

Absolutely @oneitonitram.

Question: does pihole and nxfilter support static ip address?
If docker is bridged to Green, can dhcp server be used for a reservation?

Just wanted to report that it happened again. Looks absolutely mandatory to either expose ports or fix the IP rather than relying on docker’s way of assigning IP adresses.

@pike I had the same question, and this helped me :

Is it reproducable? I still get same IPs on restart/reboot.

I tested the Experimental Docker Libnetwork DHCP Driver but it didn’t work. It seems an unsolved problem and the compiled docker version is old.

[root@testserver ~]# home/brent/go/src/ network create -d macvlan --ipam-driver=dhcp --subnet= -o parent=ens33 --ipam-opt dhcp_interface=ens33 testnet
Error response from daemon: plugin "dhcp" not found

Yes, the docker-net-dhcp plugin worked perfectly.
BTW, I tested with the nxfilter image first and noticed the latest nxfilter image does not start, there’s an open issue.

Install the plugin:

docker plugin install devplayer0/net-dhcp

You need a bridge to connect to (could be created in UI, if you use NSDC you already have one).

Create the docker network testnet with bridge br0:

docker network create -d devplayer0/net-dhcp:latest --ipam-driver null -o bridge=br0 testnet

We need to set the new created network and a fixed unique MAC address else the containers get random ones on restart and that breaks DHCP reservations.
Run the docker run command, like in this example for pihole:

docker run -d --name pihole -e TZ="Europe/Vienna" -e WEBPASSWORD="admin" -v "$(pwd)/etc-pihole/:/etc/pihole/" -v "$(pwd)/etc-dnsmasq.d/:/etc/dnsmasq.d/" --cap-add NET_ADMIN --net=testnet --mac-address=0e:6f:47:f7:26:1a --restart=unless-stopped pihole/pihole:latest

I needed to set the “Interface listening behavior” to “Listen on all interfaces” in pihole network settings as pihole defaults to not existing eth0 (the virtual adapter for testnet is named like br00@ifXX)

This way we get a separate docker network to use for bridging docker containers to the local network like we do in other virtualization environments without dealing with firewalls or virtual NAT and IPs can be managed with Nethserver DHCP.

Pihole does not as it uses DHCP only and nxfilter does as it uses the IP set in OS.

As regards the docker implementation you can just define the IP for the container:


Not sure I understood the question, but DHCP server is not mandatory at all in pihole. It can even query the local DNS server (nethserver’s) to get the FQDN of the clients when it is not serving addresses itself.

Therefore I believe that fixed IP, wether for pihole itself (which is mandatory anyway) or machines on the network are not an issue.

This looks really great ! Let’s try :blush:


@mrmarkuz, why would you use both NxFilter and Pi-Hole? I thought their purpose is pretty much similar, or not?

Yes, you’re right, it was intended just for testing:

1 Like