Skip to main content


📚 Documentation 💠 Hub 💬 Discourse

CrowdSec bouncer written in golang for firewalls.

crowdsec-firewall-bouncer will fetch new and old decisions from a CrowdSec API and add them to a blocklist used by supported firewalls.

Supported firewalls:

  • iptables (IPv4 ✔️ / IPv6 ✔️ )
  • nftables (IPv4 ✔️ / IPv6 ✔️ )
  • ipset only (IPv4 ✔️ / IPv6 ✔️ )
  • pf (IPV4 ✔️ / IPV6 ✔️ )


Packages for crowdsec-firewall-bouncer are available on our repositories. You need to pick the package according to your firewall system :


sudo apt install crowdsec-firewall-bouncer-iptables


sudo apt install crowdsec-firewall-bouncer-nftables


sudo pkg install crowdsec-firewall-bouncer

See as well Manual Installation documentation below


There are two primary ways to use the firewall bouncer:

  • managed (default): cs-firewall-bouncer will create ipset/nft sets, insert the associated firewall rules and manage the set contents
  • set only: you already have a (complex) firewall setup, cs-firewall-bouncer will only manage the content of existing specified sets

Managed mode : Iptables/ipset or Nftables

This is the default behaviour

In "managed" mode (mode nftables or iptables), bouncer creates all the needed elements (rules, sets) and insert the appropriate rules in nftables or iptables.


IPSet (when using iptables mode) does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds.

Set Only : Iptables/Ipset table

In iptable set-only mode (mode ipset), the bouncer only handles the contents of sets that are specified by blacklists_ipv4 and blacklists_ipv6. These sets must be created before starting the bouncer, and it is the user's responsibility to create the associated iptables rules.


IPSet does not support a timeout greater than 2147483 seconds (about 596 hours). If crowdsec is configured to take decisions longer than that, the bouncer will cap the duration to 2147482 seconds.

Set Only : nftables

In nftables set only mode (mode nftables with nftables.{ipv4,ipv6}.set-only set to true), the bouncer only manages the contents of the sets. It's the user's responsibility to create the associated chains and sets :

table ip crowdsec {
set crowdsec-blacklists {
type ipv4_addr
flags timeout

chain crowdsec-chain {
type filter hook input priority filter; policy accept;
ip saddr @crowdsec-blacklists drop
table ip6 crowdsec6 {
set crowdsec6-blacklists {
type ipv6_addr
flags timeout

chain crowdsec6-chain {
type filter hook input priority filter; policy accept;
ip6 saddr @crowdsec6-blacklists drop

Configuration directives

  • mode : can be set to iptables, nftables , ipset or pf
  • pid_dir : directory to drop pid file
  • update_frequency controls how often the bouncer is going to query the local API
  • daemonize : for systemd unit
  • log_mode : can be file or stdout
  • log_dir : log directory
  • log_level : can be trace, debug, info, or error
  • log_compression : compress logs on rotation, true or false
  • log_max_size : maximum file size before rotation
  • log_max_backups : how many backup log files to keep
  • log_max_age : oldest backup log file before deletion
  • api_url and api_key control local API parameters.
  • insecure_skip_verify : allow self-signed certificates for LAPI, false or true
  • disable_ipv6 : disable ipv6 support, defaults to false
  • deny_action : firewall action to apply, defaults to DROP, but can be REJECT
  • deny_log : if set to true, enables logging of dropped packets (ie. -j LOG)
  • deny_log_prefix : if logging is true, this sets the log prefix, defaults to "crowdsec: "

Iptables/Ipset specific directives

  • iptables_chains : specify a list of chains to insert rules (only relevant in iptables mode) :
  • blacklists_ipv4 and blacklists_ipv6 : names of ipv4 and ipv6 sets
  • ipset_size: maximum number of entries in the ipset (default: 131072)
  • ipset_type: type to use for the set (default: nethash)

The default for ipset_size has been raised in v0.0.28 (from 65536) to allow for larger blocklists.

Nftables specific directives

Nftables mode has its own nftables section, with sub-section of ipv4 and ipv6 :

## nftables
enabled: true
set-only: false
table: crowdsec
chain: crowdsec-chain
enabled: true
set-only: false
table: crowdsec6
chain: crowdsec6-chain

if set-only is set to true, the bouncer will only manage the set contents.

Manual installation


First, download the latest crowdsec-firewall-bouncer release.

$ tar xzvf crowdsec-firewall-bouncer.tgz
$ sudo ./

From source

Run the following commands:

git clone
cd cs-firewall-bouncer/
make release
tar xzvf crowdsec-firewall-bouncer.tgz
cd crowdsec-firewall-bouncer-v*/
sudo ./


If you already have crowdsec-firewall-bouncer installed, please download the latest release and run the following commands:

tar xzvf crowdsec-firewall-bouncer.tgz
cd crowdsec-firewall-bouncer-v*/
sudo ./

Configuration for manual installation

To be functional, the crowdsec-firewall-bouncer service must be able to authenticate with the local API. The script will take care of it (it will call cscli bouncers add on your behalf). If it was not the case, the default configuration is in /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.

You can then start the service:

sudo systemctl start crowdsec-firewall-bouncer

If you need to make changes to the configuration file and be sure they will never be modified or reverted by package upgrades, starting from v0.0.25 you can write them in a crowdsec-firewall-bouncer.yaml.local file as described in Overriding values. Package upgrades may have good reasons to modify the configuration, so be careful if you use a .local file.


logs can be found in /var/log/crowdsec-firewall-bouncer.log


  • mode nftables relies on to create table, chain and set.
  • mode iptables relies on iptables and ipset commands to insert match-set directives and maintain associated ipsets
  • mode ipset relies on ipset and only manage contents of the sets (they need to exist at startup and will be flushed rather than created)
  • mode pf relies on pfctl command to alter the tables. You are required to create the following tables on your pf.conf configuration:
 # create crowdsec ipv4 table
table <crowdsec-blacklists> persist

# create crowdsec ipv6 table
table <crowdsec6-blacklists> persist

You can refer to the step-by-step instructions of the user tutorial on FreeBSD to setup crowdsec-firewall-bouncer with pf.


ipset lists have to exist before crowdsec-firewall-bouncer starts. You can create them and add them to your iptables like this:

ipset create crowdsec-blacklists hash:ip timeout 0 maxelem 150000
ipset create crowdsec6-blacklists hash:ip timeout 0 family inet6 maxelem 150000
iptables -I INPUT 1 -m set --match-set crowdsec-blacklists src -j DROP
ip6tables -I INPUT 1 -m set --match-set crowdsec6-blacklists src -j DROP