nftfw logo

nftfw-config (5)

% NFTFW-CONFIG(1) | 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 stores the main nftables.conf file. If installing a new system into root (/) you may wish to change this value to prevent nftfw from overwriting an extant file. Conversely, if installing a new system into /usr/local/etc, you will need to change this value when things are working to make sure that nftfw writes its settings in the correct place.

  nftables_conf = $(root}/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

nftfw_base nftfw expects to find the five working directories, incoming.d, outgoing.d, blacklist.d, whitelist.d and patterns.d under this directory. It you want to run the system from the Symbiosis control directory, then the nftfw_base option needs to be changed from the default to /etc/symbiosis/firewall. You'll need to create a blacknets.d directory. Nftfw expects to find its rule.d directory in its own sysetc directory. Symbiosis files in firewall/local.d are not supported by this system. To provide local changes, edit /etc/nftfw_init.nft.

  nftfw_base = ${sysetc}


owner, group The owner variable needs to be set to the username of the owner of the files in ${sysetc}/nftfw. The intention is to allow a user to have easy non-root access to control the firewall. If the group variable is empty, the group will be set to the main group of the owner, but can be set to another group if this assists. The blacklist and whitelist scanners will make files owned by the user in their control directories. The default is to use the root user.



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.

  loglevel = ERROR

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

  logfacility = daemon

logprint Control printing of logged informaion. 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

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

However, at present, the auto-merged, interval sets can cause the nft program to fail in some circumstances, flagging an error. There is a bug causing nft to succeed in loading the set when a full install is performed but failing when attempting a reload.

The bug has been reported to the nftables development team, but no fix has been generated as of the current releases. nftfw will work 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.

  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


date_fmt Allows change of date format for nftfwls. The default is DD-MM-YYYY HH:MM:SS. I'm using a two digit year number.

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

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 / rather than /usr/local.


: 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)