Firewall bouncer for CrowdSec
=============================

Initial configuration
---------------------

The upstream configuration is shipped directly under /etc and registered via
conffiles, and an override file is deployed alongside upon first installation.
The main file can be updated for new upstream releases by answering the usual
dpkg prompt, while the override file is left untouched.

 - upstream: /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
 - override: /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local

More about overriding values:
  https://docs.crowdsec.net/docs/configuration/crowdsec_configuration/#overriding-values

The override file is created automatically during the first installation, with
two settings:

 - the detected firewall backend, which the admin might need to adjust if the
   firewall is switched to a different set of packages (see below);
 - an API key (optional).

By default, this bouncer package pulls the `crowdsec` package (via Recommends)
and the postinst registers the bouncer automatically. If the admin decided not
to install the `crowdsec` package, they are responsible for registering the
bouncer manually and setting up the required parameters in the override file
(`api_url` and `api_key`).

When the autoregistration happens, the bouncer identifier is stored alongside,
so that the bouncer can unregister itself automatically upon purge:

 - identifier: /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.id


Modifying configuration
-----------------------

Admins might want to adjust the firewall backend that was detected during the
first installation, and maybe override some parameters stored in the upstream
configuration file. This can be done by editing the override file, and
restarting the systemd unit afterwards:

    editor /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local
    systemctl restart crowdsec-firewall-bouncer


Firewall backends: nftables or iptables+ipset
---------------------------------------------

Let's look at the relationships between the following packages:

 - nftables
 - iptables
 - ipset

In Bullseye, and in Bookworm as of December 2022, nftables is installed by
default, since it's Priority: important. It can be installed together with
iptables, which even recommends it (so that admins can prepare the switch
from iptables to nftables). Additionally, iptables installs a set of
alternatives, which can be configured either as iptables-nft (the default)
or as iptables-legacy. Finally, ipset is another package that can be added
to the mix.

This CrowdSec bouncer can work with either nftables alone or with iptables
and ipset together. That cannot really be expressed via package-level
dependencies (and alternatives must be taken into account anyway), so the
postinst script uses the following rules:

 - To match the trend towards nftables, the bouncer is configured to use
   nftables as the firewall backend by default.
 - If iptables is installed, and if its set of alternatives is configured
   as iptables-legacy, then the iptables backend is configured instead. A
   warning is displayed if ipset is not installed; in that case the
   postinst doesn't error out but the systemd unit is expected to fail to
   start. Installing ipset and restart the unit should be sufficient.