The ferm debian package
=======================

ferm is commonly referred to as "your friendly iptables macro assembler",
allowing one to write iptables rulesets in a more structured way. The ferm
syntax is similar to what the more modern nft toolchain reads, and it is
adviseable to use nft for new deployments.


abandoned upstream
------------------

Unfortunately, ferm is officially abandoned upstream. Upstream is no longer
reacting to bug reports or e-mails. This package is still being kept barely
alive in Debian to ease the transition to nft which should have been done
years ago. Do not expect bugreports about improvements in the actual code to
be acted upon. The Debian maintainers of ferm will liberally spread the
"upstream", "help" and "wontfix" tags after commenting on the bug report. We
will no longer forward Debian bugs upstream to avoid pestering the dead upstream project with debian bug reports. If you want to report your wishes upstream as well, please go ahead and do that work yourself.


contributions appreciated
-------------------------

We will consider code patches for inclusion in the Debian package. Please
submit them as Merge Requests in our Salsa repo, see Vcs-Browser in
debian/control. We expect you to write test cases for your changes, will
verify whether they fail before applying your patch and succeed after applying
your patch, and we also expect you to update the docs.


iptables tool choice
--------------------

Since 2017, upstream ferm has unconditionally used the -legacy/xtables version
of the iptables tools, even if the distribution was configured to use the
nftables versions instead. With the upcoming deprecation and removal of
xtables from Debian, this had to change.

Upstream had simply declared ferm incompatible with the nftables versions of
the tools, and sadly there is no information available at this time as to the
extent of the incompatibility.

ferm 2.7-5+exp1 is the first version in Debian to default to use whatever
version of the iptables tools have been selected with Debian's alternatives
mechanism, which defaults to the nftables version of the tools.

If you encounter any issues with the current default, please report that in a
bug report against Debian's ferm package and consider using
update-alternatives iptables to change back to the legacy version of iptables.
Be advised that the kernel and iptables maintainers plan to remove the -legacy
version of the tools and the corresponding kernel framework as it has been
deprecated for a long time now. The Debian maintainers of ferm do not plan to
make code changes on their own to increase ferm's compatibility with
nftables-based iptables, but we intend to build a list of incompatibilities to
allow people to develop and share workaround. Report any experience you might
have in the Debian Wiki on https://wiki.debian.org/ferm.


two-step initialization and rule set
------------------------------------

ferm comes up in two steps. The first step, configured from
/etc/ferm/ferm-early.conf and /etc/ferm/ferm-early.d, is established early in
system start, before any networking is initialized. This ruleset does basic
protection of the local host, allowing only the basic services for incoming
connection, allows all outgoing connections and disallows all forwarding. This
rule set MUST NOT depend on interface names, DNS or anything else that needs
an operational network.

After the network is fully operational, the final ruleset is established from
/etc/ferm/ferm.conf and /etc/ferm/ferm.d. This ruleset can do everything you
want.

THe final ruleset that gets established after the network is fully
operationalis configured from /etc/ferm/ferm.conf. The directory
/etc/ferm/ferm.d is included by this default ruleset. Feel free to add your
own rules there.

When developing firewall rules on remote machines, interactive mode (ferm
--interactive) is recommended. In this mode, ferm applies the new firewall
rules and asks for confirmation. If you don't confirm within 30 seconds, ferm
automatically reverts to the previous rule set.


https://systemd.io/NETWORK_ONLINE/ was used as advice about how to specify the
dependencies of the systemd units. This probably depends on proper
configuration of network-online.target which is your responsibility.

systemd
-------

This package invokes ferm by means of a systemd unit and a wrapper,
/usr/libexec/ferm/ferm-systemd, that handles caching and fast/slow mode as the
init script did. The wrapper can either be configured via the
/etc/default/ferm file or by overriding the Environment lines of the unit with
a /etc/systemd/system/ferm.service.d/override.conf file. What is set in
/etc/default/ferm takes precedence.

A simpler systemd unit is included as /usr/share/doc/ferm/ferm-simple.service.
To use this, copy it to /etc/systemd/system/ferm.service, overriding the more
complex systemd unit.

Please let ferm@packages.debian.org know whether you are using SLOW and/or
CACHE. I might make the simple systemd unit the default and move the more
complex code to an examples directory in a future version if no one speaks up.

The cache ("CACHE=yes", disabled by default) speeds things up, too, because
ferm will only be run when you modify its configuration, but this also means
that ferm's rollback-on-error isn't assisting you. The wrapper rebuilds the
cache when any file in /etc/ferm is newer than the cache. If you move your
ruleset from /etc/ferm to another directory, this mechanism becomes
ineffective.


Upstream info
-------------

More information about ferm can be obtained from the github ferm page,
https://github.com/MaxKellermann/ferm, or on the project page,
http://ferm.foo-projects.org/. Please note that ferm.foo-projects.org does not
properly support https and the https version of that URL currently (2026-01)
ends up in an "under construction" page. Many modern browsers use https
without explicitly being told to, moving you to the "under construction" page.
Both page haven't been updated in years.


Authors
-------

This README.Debian file was originally written in by Max Kellermann
<max@duempel.org> 2013 and has been updated and rewritten since then by Marc
Haber <mh+debian-packages@zugschlus.de> up to 2026.
