NxFilter

Fork

This is a fork of Deepwoods' NxFilter-docker⁠. The only changes involve tagging in Docker Hub.

While Deepwoods puts all updates under the "latest" tag (Deepwoods's Docker Hub), I want each image tagged with the NxFilter version number.

My links to: Docker Hub and GitHub⁠

About

NxFilter⁠ is a scalable and reliable DNS filtering server software by Jahastech.

Container image is based off of Ubuntu:latest minimal with the most current DEB package for NxFilter from NxFilter⁠.

Usage

Interactive container for testing:

docker run -it --name nxfilter \
   -p 53:53/udp \
   -p 19004:19004/udp \
   -p 80:80 \
   -p 443:443 \
   -p 19002-19004:19002-19004 \
   zorbatherainy/nxfilter:latest

Detached container with persistent data volumes:

docker run -dt --name nxfilter \
  -e TZ=America/Chicago \
  -v nxfconf:/nxfilter/conf \
  -v nxfdb:/nxfilter/db \
  -v nxflog:/nxfilter/log \
  -p 53:53/udp \
  -p 19004:19004/udp \
  -p 80:80 \
  -p 443:443 \
  -p 19002-19004:19002-19004 \
  zorbatherainy/nxfilter:latest

Configuration

• The admin GUI URL is http://[DOCKER_HOST_SERVER_IP]/admin
• The default Block Redirection IP under System -> Setup needs to match your [DOCKER_HOST_SERVER_IP] unless you're bridging your docker network to your local LAN or using MACVLAN.
• TZ of the container defaults to UTC unless overridden by setting the environment variable to your locale. see List of tz time zones⁠

Docker-compose example

version: '3.5'

services:
  nxfilter:
    image: zorbatherainy/nxfilter:latest
    container_name: nxfilter
    hostname: nxfilter
    restart: unless-stopped
    environment:
      TZ: "America/Chicago"
    volumes:
      - nxfconf:/nxfilter/conf
      - nxflog:/nxfilter/log
      - nxfdb:/nxfilter/db
    ports:
      - 53:53/udp
      - 19004:19004/udp
      - 80:80
      - 443:443
      - 19002-19004:19002-19004
volumes:
  nxfconf:
  nxfdb:
  nxflog:

Troubleshooting

I noticed that with recent versions of NxFilter, if you use emptybind mounts instead of volumes (i.e., there is nothing in the mount's directories, a clean start), NxFilter tends to fail with an NullPointer exception (see your container logs).

The way I fixed this was to either (a) copy the config from another instance (if you're migrating), or (b) start up with a volume (to create the initial config) and then copy the volume's contents to the bind mount, or (c) just use volumes, don't use bind mounts.

Example of option B

# Run a container with the source volume mounted
docker run -d --name=source_container -v source_volume:/source busybox

# Copy files from container to bind mount
docker cp source_container:/source/. /tmp/target_dir

Useful Commands

docker-compose to start and detach container: docker-compose up -d

Stop and remove container: docker-compose down

Restart a service: docker-compose restart nxfilter

View logs: docker-compose logs

Open a bash shell on running container name: docker exec -it nxfilter /bin/bash

Updating

1. Pull the latest container. docker pull zorbatherainy/nxfilter:latest
2. Stop and remove the current container. docker stop nxfilter && docker rm nxfilter

1. Run the new container with the same command from above. Detached container

1. Make sure that the container is running. docker ps
2. Check the container logs if unable to access the GUI for some reason. docker logs nxfilter