nftfw logo

nftfw-config (5)

% NFTFW-CONFIG(5) | Nftfw documentation


nftfw-config - configuration file for the nftfw system


A standard 'ini' file configures the nftfw(1) system, it's stored in /etc/nftfw/config.ini or /usr/local/etc/nftfw/config.ini. The file uses the standard conventions for commenting and makes use of several sections. Empty values can be specified by just using a keyword.

The program starts with a built-in version of the settings, then reads the config.ini file. As distributed, the installed file has all variables commented out using semi-colons.

Values for the main nftfw script can be overridden by using the -o option. The -i option prints keys and values.

There are several sections in the file.


The locations section defines the paths to files and directories used by the system. The program looks in /etc and then /usr/local/etc for the nftfw directory determining the 'root' key and that forms the basis for all paths.

sysetc, sysvar These two variables contain the control and working files for the system:

  sysetc = ${root}/etc/nftfw
  sysvar = ${root}/var/lib/nftfw

nftables_conf nftfw needs to know where the system writes nftables.conf file that provides input to nftables on system reboot. On installation, the file is written into /etc/nftfw for safety. The variable needs changing to /etc/nftables.conf when the system is live.

  nftables_conf = ${sysetc}/etc/nftables.conf

nftfw_init The location for the initial nft setup file containing the framework used by the firewall.

  nftfw_init = ${sysetc}/nftfw_init.nft


This section provides tailoring of the default rules used in the five processing sections of the program when rules are not explicitly given.

  incoming = accept
  outgoing = reject
  whitelist = accept
  blacklist = reject
  blacknets = drop

The key on the left is a program section name and the value is the name of a rule. A possible choice for 'reject' is the 'drop' rule which simply throws inbound packets away. The 'reject' rule jumps to a table in the initialisation script that actively rejects the packet.


logfmt Set the format of log statements (see the Python logging documentation for possible formats)

  logfmt = nftfw[%(process)d]: %(message)s

loglevel Sets the level are we logging at, this value needs to be a level name not a value. Choose one of CRITICAL, ERROR, WARNING, INFO, DEBUG. nftfw uses the -v flag to the set this value to INFO. On installation, the log level is set to INFO and can be changed to ERROR to reduce information written into the logs.

  loglevel = INFO

logfacility The logging facility are we using, it needs to be a facility name not a value.

  logfacility = daemon

logprint Control printing of logged information. Set to False to inhibit log printing at the console. This value is initially set to False when the program is not talking to a terminal. nftfw uses the -q flag to the set this value to False and the option will suppress printing to the terminal.

  logprint = True

logsyslog Set to False to inhibit syslog use.

  logsyslog = True


This section affects the nftables statements generated by the rules.

Do we want counters on the statements?

  incoming_counter = True
  outgoing_counter = True
  blacklist_counter = True
  whitelist_counter = True
  blacknets_counter = True

Do we want nftables logging? By adding a different prefix for each of the tables, it's possible to scan the syslog for events and get feedback from the firewall. To stop logging, just use the name.

  blacklist_logging = Blacklist

The three variables below control the type of sets automatically generated for blacklist, blacknets and whitelist tables. When true, nftfw uses auto_merged, interval sets for the sets it makes. This type automatically creates entries containing an address range for adjacent IP addresses. The feature is desirable because it reduces the number of matches.

However, the auto-merged, interval sets can cause the loading of nftables rules to fail, flagging an error. A load can succeed when a full install is performed but partial loads of sets can fail. The bug was reported to the nftables development team, based on problems with the Buster release and a fix was generated. The fix is now widely deployed.

nftfw works around this bug, automatically generating a full install when an attempt at a set reload fails. However, it seems a good idea to provide a way of turning this feature on and default to not using the feature.

It seems likely that this problem has been fixed for the Bullseye Debian release. It's recommended to enable this feature, but monitor logs to check that updates are not failing and nftfw is managing to do installs of sets without reporting errors.

  blacklist_set_auto_merge = False
  whitelist_set_auto_merge = False
  blacknets_set_auto_merge = False


wtmp_file The whitelist command scans the wtmp file, and this variable is normally empty to use the system default. Set wtmp_file=utmp to use the system utmp file, otherwise set a filename in the variable.


whitelist_expiry Whitelist entries in _/etc/nftfw/whitelist.d`` are automatically expired by the number of days in this variable. Nftfw computes the delay as the difference between 'now' and the time on the file.

  whitelist_expiry = 10


Constants to manage blacklisting depend on the number of matches found in log files for the specific IP address - the matchcount. The nftfwls(1) program shows the currently active blacklist and all the information associated with each IP.

block_after When the matchcount goes over this level, nftfw blocks the ip using the ports in the rule (Symbiosis used 2).

  block_after = 10

block_all_after When the matchcount goes over this level, nftfw blocks the ip using all ports.

  block_all_after = 100

expire_after nftfw removes blocked IPs from the blacklist.d directory after the number of days in this value have passed since the last incident. Bad guys keep coming back, and sometimes re-appear several months after expiry. It's useful to have feedback from the firewall to keep them in play while they batter at the firewall door. The system allows for this, see nftfw_files(5) for information on patterns that support feedback.

  expire_after = 10

Symbiosis used 2 for this value.

clean_before nftfw blacklist will remove ip from the database where there has been no error posted for more than these number of day, the intention is to keep the database from growing to huge proportions. A zero value will inhibit this action.

 clean_before = 90

sync_check nftfw blacklist will check whether the IP addresses in the database that should be active are actually present in the blacklist directory blacklist.d. 'Should be active' means that the addresses have not been automatically expired. nftfw is largely event driven, but events get missed. So on the basis that if stuff can happen, it will, this code will recover the correct state of the blacklist directory. It seems overkill to call this every time the blacklist scanner runs, so it is executed when number of runs of the scanner is greater than the value of this variable. The default is to run the blacklist scanner 96 times a day, so 50 seems are reasonable way to run the recovery code once a day. Set this to zero to turn this feature off.

 sync_check = 50


nft_select Allow selection of the method used to load/unload nftables. Permissable values are: shell using the original interface which calls /usr/sbin/nft, and python uses python nftables library to load and read nftables. python is the default. This option may go away in future, it's there in case the python code appears to cause problems.

  nft_select = python


date_fmt Allows change of date format for nftfwls. The default is DD-MM-YYYY HH:MM.

  date_fmt = %d-%m-%Y %H:%M

pattern_split Replaces any commas in the pattern listing column by a newline and a space, reducing output width on the terminal output. Can be overridden by -p option to nftfwls.

  pattern_split = No


The nftfwedit print function can lookup the IP supplied as an argument in various DNS blocklists. The function is not enabled until entries are supplied in this section of the config file. The Python 3 package python3_dnspython must also be installed. I also suggest that your system runs a caching nameserver.

Sample entries are supplied in the distributed file, and require un-commenting by removing the initial semi-colon. The entry is Name=domainname, where the domainname is used to access the list in the DNS lookup.



Files can be located in /usr/local rather than under_/_.


: Location of control files


: Location of build, install, lock file and sqlite3 databases storing file positions and blacklist information


See GitHub Issues:


Peter Collinson (huge credit to the ideas from Patrick Cherry's work for the firewall for the Symbiosis hosting system).


nft(1), nftfw(1), nftfwls(1), nftfwedit(1), nftfwadm(1), nftfw-files(5)