include rule desc as "comment" in actual rule
templates/nftables.conf: conditionally add ruleset flushing
Fix loop_control / loop_var re-use warning from ansible


browse  log 



You can also use your local clone with git send-email.

#Forked from https://code.vandalsweb.com/ansible-roles/nftables.git

With the following changes/fixes:

  • Add support for Alpine Linux
  • Simply nftables install task
  • Fixed loop_control / loop_var re-use warning from ansible
  • Conditionally add ruleset flushing

Conventional Commits Semantic Versioning Pipelines

#Ansible role - Nftables

This Ansible role install and configure a Linux Netfilter Nftables server and its rules.

#Project management

To provide an easy way to manage the project, there are some make targets to run the most common tasks:

  • To download dependencies, requirements, etc: make deps.
  • To run tests suites: make tests.
  • To generate the CHANGELOG based in the git history: make changelog.
  • To clean the temporary files, built artifacts and clean the project directory: make clean.


You only need Python (v3, of course!). The rest of the packages or dependencies required to run the project are downloaded with the make deps command, but as in the resto of projects based on Python, it's a good recommendation to use a Virtualenv before download dependencies, just like this:

$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ make deps

#Role Variables

Almost every options have a default value (you can check these values in defaults/main.yml file), but you can override as much as you want (from command-line param, in your own vars.yml file, etc).

  • General settings

    • nftables_remove_other_firewalls: Set to true to remove other firewalls installed (if exists) like firewalld or iptables, false otherwise (default: true).
    • nftables_config_path: Path of the config file with the firewall rules (default: /etc/nftables.conf).
  • Firewall rules

    • nftables_ruleset: Definition of the firewall ruleset (see below).

#Ruleset definition

To define the firewall rules you have to use the nftables_ruleset parameter. This parameter could contain a list of tables. Each of these tables could contain a list of chains. Each of these chains could contain a list of rules.

A very useful documentation about ruleset configuration is the official Nftables wiki: https://wiki.nftables.org/wiki-nftables/index.php/Quick_reference-nftables_in_10_minutes

The parameters of a list of tables are:

  • name: A name for the filtering table (for example firewall or nat).
  • family: Refers to a one of the following table types: ip, arp, ip6, bridge, inet, netdev.
  • chains: A list of chains for the current table.

The parameters of a list of chains are:

  • name: A name for the chain (for example incoming or input).
  • type: Refers to the kind of chain to be created. Possible types are:
    • filter: Supported by arp, bridge, ip, ip6 and inet table families.
    • route: Mark packets (like mangle for the output hook, for other hooks use the type filter instead), supported by ip and ip6.
    • nat: In order to perform Network Address Translation, supported by ip and ip6.
  • hook: Refers to a specific stage of the packet while it's being processed through the kernel. Possible hooks are:
    • The hooks for ip, ip6 and inet families are: prerouting, input, forward, output, postrouting.
    • The hooks for arp family are: input, output.
    • The bridge family handles ethernet packets traversing bridge devices.
    • The hook for netdev is: ingress.
  • priority: Refers to a number used to order the chains or to set them between some Netfilter operations. Possible values are (default: 0):
    • -300: NF_IP_PRI_RAW
    • -150: NF_IP_PRI_MANGLE
    • -100: NF_IP_PRI_NAT_DST
    • 100: NF_IP_PRI_NAT_SRC
  • default_policy: This is the default verdict statement to control the flow in the chain. Possible values are: accept, drop, queue, continue or return (default: drop).
  • rules: A list of rules for the current chain.

The parameters of a list of rules are:

  • desc: A small description to add information about the purpose of the rule.
  • matches: A list of clues used to access to certain packet information and create filters according to them (check more information about matches here: https://wiki.nftables.org/wiki-nftables/index.php/Quick_reference-nftables_in_10_minutes#Matches).
  • statement: The action performed when the packet match the rule. It could be terminal and non-terminal. The valid verdict statements are:
    • accept: Accept the packet and stop the remain rules evaluation.
    • drop: Drop the packet and stop the remain rules evaluation.
    • queue: Queue the packet to userspace and stop the remain rules evaluation.
    • continue: Continue the ruleset evaluation with the next rule.
    • return: Return from the current chain and continue at the next rule of the last chain. In a base chain it is equivalent to accept
    • jump : Continue at the first rule of . It will continue at the next rule after a return statement is issued
    • goto : Similar to jump, but after the new chain the evaluation will continue at the last chain instead of the one containing the goto statement

#Example Playbook

A basic playbook example to allow established connections from everywhere, ping requests from everywhere, http and https connections from everywhere, SSH connections from everywhere except and enabling the NAT in eth1 interface could be:

- hosts: all
      - name: firewall
        family: ip
          - name: incoming
            type: filter
            hook: input
            priority: 0
            default_policy: drop
              - desc: Allow established/related connections
                  - ct state established,related
                statement: accept
              - desc: Allow localhost traffic
                  - meta iif lo
                statement: accept
              - desc: Allow PING
                  - icmp type echo-request
                statement: accept
              - desc: Allow SSH from everywhere except honeypot
                  - ip saddr !=
                  - tcp dport 22
                statement: accept
              - desc: Allow web traffic
                  - tcp dport {80, 443}
                statement: accept
      - name: nat
        family: ip
          - name: postrouting
            type: nat
            hook: postrouting
            priority: 100
              - desc: NAT rules
                  - oifname "eth0"
                  - ip saddr
                statement: counter masquerade
    - "nftables"


Tools, external libraries, useful references and other third-part software used in the project:

  • Semantic Versioning (semver): A simple set of rules and requirements that dictate how version numbers are assigned and incremented.
  • Conventional Commits: A specification for adding human and machine readable meaning to commit messages.
  • Git-hooks: Hook manager.
  • Git-chglog: CHANGELOG generator.
  • Ansible: Ansible is an open-source software provisioning, configuration management, and application-deployment tool enabling infrastructure as code.
  • Molecule: Molecule project is designed to aid in the development and testing of Ansible roles.
  • Linux Netfilter Nftables: This software provides a new in-kernel packet classification framework that is based on a network-specific Virtual Machine (VM) and a new nft userspace command line tool.


This project is licensed under MIT License. See LICENSE for more details.


This project is just another amazing idea of BhEaN, created on 2020.