Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Nftfw - Nftables firewall builder for Debian

The nftfw package builds firewalls for nftables. The system creates a simple and easy-to-use configuration model for firewall management. The model was created for the iptables based firewall package supplied as part of Bytemark's Symbiosis hosting package and also for Sympl, a fork of Symbiosis. The firewall is controlled using files in a directory structure that maps onto the parts of the firewall. To add a rule, you just add a file. To block an IP address with a specific set of ports, you just add a file.

nftfw doesn't need Sympl or Symbiosis, it's stand-alone and will run on any Debian Buster system or later. It should work on other Linux distributions. The package is written in Python 3 and needs at least the 3.6 release.

nftfw can be installed from a Debian binary package, there is a zip file called in the package directory containing the most recent version. For safety, nftfw needs some configuration after installation. See the installation document Install nftfw from Debian package for a how-to guide.

New in current release

For update information see the Changelog.

Main changes:

  • Fix for the getgeocountry script in cidrlists, the format of the downloaded MaxMind zip file has changed.

  • Changes to nftfwedit to provide full editing of the active blacklist.d directory and the nftfw database.

  • Configure fail2ban to drive nftfw - see Using fail2ban with nftfw.

  • Use Python interface to directly load the nftables statements into the system.


  • Easy-to-use firewall admin. Five directories control the firewall. Placing files in the directories create firewall rules configured from the file names. Two directories, incoming.d and outgoing.d, supply rules allowing access to ports for incoming and outgoing connections. These files are usually empty, but can contain IP addresses to make the rule more specific. Two more directories, blacklist.d and whitelist.d, contain IP addresses, blocking or allowing access for named addresses. These files can contain ports, modifying the action of the rule. The final directory, blacknets.d can contain files with lists of IP address ranges and makes rules that block access to all the addresses. Changing the firewall is simply a matter of making or removing a file in one of these directories. The directory contents are described in detail in the User's Guide, while the How do I... or Quick Users' Guide gives a more task oriented description.

  • Automatic blacklisting. The system contains a log file scanner that uses regular expressions to detect unwanted access and then creates files in the blacklist.d directory to block access to any matched IP address. Files to scan, the relevant ports to block for the file and the regular expressions for matching are all contained in a set of files in patterns.d. Pattern files are small text files, easy to add and edit, and the system contains a method of testing them. The nftfw configuration file controls the number of matched lines needed for blocking and how long to wait before removing the IP address from the blacklist.

  • Blacklisting by address range. The system may be supplied with lists of IP address ranges used to block all the addresses in the ranges. This can be used to block access to specific countries, or unwanted access from organisations.

  • Firewall feedback. The blacklist scanner can be told how to scan the syslog file looking for log entries from nftables and updates the blacklist database when a blocked IP address returns, keeping it in the firewall until it stops being active.

  • Automatic whitelisting. The whitelist scanner looks in the system's wtmp file for logins from users and automatically whitelists their IP address.

  • Full use of nftables sets. Blacklist and whitelist rules use nftables sets, and nftfw tries not to perform a full firewall reload until it's needed. If just the blacklist or whitelist sets alter, then only the changed sets are reloaded.

  • Configurable nftables template. A user editable template provides the framework for nftables. nftfw uses the template on every firewall build, using 'includes' to pull in its own rules. The use of a template allows for local changes, perhaps to support internal LAN interfaces on a gateway machine. A sample version of the template file used on my gateway machine is supplied in the source distribution.

  • Editable nftables commands. Rules in incoming.d and outgoing.d use small action files that are shell scripts to create commands for nftables rules. The scripts are called with a defined set of environment variables and generate output using echo. The idea is that local tailoring should be possible and easy.

  • Blacklist monitoring. The system provides a tool listing the current blacklist status. For each live entry it shows: the IP address and optionally the country of origin, the blocked ports, the date and time of the first and last access and the difference between the two times. HTML output can be generated so the data can be seen from the web. A sample PHP webpage is provided.

  • Admin editing. A database editor allows admins to add and delete entries from the blacklist database.

  • Initial configuration. The system comes with a fully configured set of firewall rules and is supplied with some working pattern files that are in use now keeping the bad guys out.

Other documents

All documents can be found on the web from the nftfw website.

See documents in the docs directory:

Request for help

I wanted to do this because I like the simplicity and ease of controlling the firewall. The control system lacks danger, messing with complex tables isn't needed to add or remove a rule, you just create or delete a file. Controlling things using the file system is very much part of the UNIX ethos that I embraced willingly many years ago. The user interface to this system is entirely down to the efforts of Patrick Cherry who ran Bytemark, a hosting company in the UK who I used for many years.

Most of what I understand about firewalls has been picked up over the years, largely from folklore. Mine seem to work. However, there may be glaring errors in what this system delivers, helpful suggestions are always welcomed.