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.

This version of ferm has been patched 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.

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.

If you don't want to change iptables' defaults, you can also override ferm's
choice of iptables executables by defining ferm variables path_TOOL, for
example path_(6)iptables, path_ip(6)tables_save and path_ip(6)tables_restore in
your ruleset. You need to enter full paths here, the path is not searched if
you decide to override.

This is only tested with iptables IPv4 and IPv6 rule sets. If you're using
ebtables, arptables etc, please do your own testing and submit test cases to
be included in ferm's autopkgtest suite to help with package QA.


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
operational is 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.
