Load Linux OS Fingerprints for iptables OSF Matching

You will load an OS fingerprint file into the kernel with nfnl_osf, check the command status, and remove the same signatures when they are no longer needed. The examples use nfnl_osf from the Ubuntu iptables package version 1.8.10-3ubuntu2.

Allow about fifteen minutes. You need a root shell or sudo, the iptables package, and a fingerprint file in the format expected by the installed utility. Loading signatures changes kernel state, so test this on the host that will use the osf match and record the exact file path. This guide does not add or activate an iptables rule.

1. Confirm the installed utility

First check which executable and package version you have. These are read-only commands and do not need elevated privileges:

$ command -v nfnl_osf
/usr/sbin/nfnl_osf
$ dpkg-query -W -f='${Package} ${Version}\n' iptables
iptables 1.8.10-3ubuntu2

Ask the command to show its usage as well:

$ nfnl_osf
... Missing fingerprints file argument.

The diagnostic wording can vary with the build. The useful result is that -f is required: the command does not choose a default fingerprint file.

2. Obtain and inspect a fingerprint file

The manual points to OpenBSD's pf.os as a source for an up-to-date set of OS signatures. The old CVS web address in this installed manual now returns an error, so use the read-only mirror of the official OpenBSD source repository:

$ curl --fail --location --output /tmp/pf.os \
    https://raw.githubusercontent.com/openbsd/src/master/etc/pf.os
$ test -s /tmp/pf.os && echo 'fingerprint file is non-empty'
fingerprint file is non-empty

Inspect the downloaded file before loading it. A download error, HTML error page or unexpected format should be treated as a stop condition:

$ file /tmp/pf.os
$ sed -n '1,12p' /tmp/pf.os

The URL is an upstream source, not a promise that every future file revision will suit every kernel. Keep a copy of the exact file used for a deployment. Do not load a file merely because it has the right name.

3. Load the signatures into the kernel

Loading is a privileged, state-changing operation. Review the path one more time, then run:

$ sudo nfnl_osf -f /tmp/pf.os
$ printf 'nfnl_osf exit status: %s\n' "$?"
nfnl_osf exit status: 0

The utility reads signatures from the file and adds them to the kernel for later matching by iptables' osf match. A successful exit status is the primary verification supplied by this command. It may print no success message. A non-zero result means loading did not complete; do not proceed as if the signatures were available.

Checkpoint: if you are working in a script, test the status immediately rather than relying on text output:

if sudo nfnl_osf -f /tmp/pf.os; then
    echo 'OS fingerprints loaded'
else
    status=$?
    printf 'nfnl_osf failed with status %s\n' "$status" >&2
    exit "$status"
fi

4. Keep matching separate from loading

nfnl_osf only loads or removes signatures. It does not create an iptables policy. The related osf match is configured separately, in a rule that has been reviewed for your firewall's traffic path and default policy. Do not paste a guessed rule into a production firewall just to test whether loading worked.

Likewise, loading fingerprints is not proof that a packet will be identified. Matching depends on the traffic reaching the rule and on the signatures available to the kernel. Test the complete rule in a maintenance window, with a rollback for the rule itself.

5. Remove the same signatures

When you need to undo this change, use the same fingerprint file with -d. This is also privileged and changes kernel state:

$ sudo nfnl_osf -d -f /tmp/pf.os
$ printf 'nfnl_osf exit status: %s\n' "$?"
nfnl_osf exit status: 0

Keep the file until removal succeeds. Using a different revision may not describe exactly the signatures that were loaded, so do not discard the original file after a successful load. If removal fails, retain the file and its error output, then investigate before rebooting or loading another set.

This workflow does not write a persistent configuration file. If your system needs the signatures after boot, establish that persistence through the distribution's documented firewall or service mechanism, and make sure its startup ordering is understood. Do not assume that a successful one-off load survives a reboot.

6. Diagnose failures without guessing

The manual distinguishes several useful failure classes. A missing -f argument is an argument error. An unreadable file or failed netlink communication is reported as an error. An invalid fingerprint format or netlink handle initialisation failure is another class. The numeric error displayed by one shell or wrapper is less useful than the command's diagnostic and non-zero status, so preserve both.

$ sudo nfnl_osf -f /path/that/does/not/exist
... fingerprints file not readable ...
$ printf 'nfnl_osf exit status: %s\n' "$?"
nfnl_osf exit status: 255

The exact text and negative return-code representation can differ between the utility and the shell. Check the file without changing anything:

$ ls -l /path/to/fingerprints
$ test -r /path/to/fingerprints && echo readable
$ file /path/to/fingerprints

Do not fix a format or netlink error by repeatedly loading the file. Stop, preserve the file, and compare it with the installed manual and the kernel support on that host.