Check and Migrate firewalld Config with firewall-offline-cmd

Run firewall-offline-cmd against a live firewall and you are editing files under a daemon that is not listening to you. This guide gives you a repeatable way to inspect, validate and migrate firewalld configuration with the offline client, while keeping it away from a running firewall. The examples match firewalld 2.1.1, the version installed on the reference system, and take about 20 minutes plus time to review the resulting rules.

• You need firewalld installed, root access for the command itself, a maintenance window if you will change the system configuration, and a tested recovery path.
• Offline means offline. The manpage says to use this client only when the firewalld service is not running.
• It is not a safer firewall-cmd. Do not use it as one on a live host.

1. Confirm the installed command

Check the package version and binary as an ordinary user. These commands only read local metadata:

$ command -v firewall-offline-cmd
/usr/bin/firewall-offline-cmd
$ dpkg-query -W -f='${Package} ${Version}\n' firewalld
firewalld 2.1.1-1
$ firewall-offline-cmd --help
You need to be root to run /usr/bin/firewall-offline-cmd.

The last message is an access check from this installation. Run the client with sudo only after you have confirmed that firewalld is stopped and that you have a backup or rollback plan.

2. Make the service boundary explicit

Before using a state-changing option, check the service state:

$ systemctl is-active firewalld
inactive

Anything other than inactive needs investigation before you continue. Stopping a firewall service can remove live protection and may interrupt connections, so schedule that action rather than hiding it in a longer command:

# sudo systemctl stop firewalld
# sudo systemctl is-active firewalld
inactive

When you have finished, restore the service deliberately, if that is how the host is meant to operate:

# sudo systemctl start firewalld
# sudo systemctl is-active firewalld
active

If the service must stay active, stop here and use the online client or a separate offline configuration tree instead.

3. Validate without migrating legacy input

--check-config checks the permanent default and system configuration, including XML validity and semantics. It is the best first operation after stopping the service:

# sudo firewall-offline-cmd --check-config

A clean run may produce no output and return status 0. Make the status visible when you are recording a change:

# sudo firewall-offline-cmd --check-config
# printf 'exit status: %s\n' "$?"
exit status: 0

A non-zero status means the configuration needs attention. Read the complete diagnostic before trying another option.

If you maintain handwritten files away from the standard location, pair --check-config with --system-config pointing at that directory. Correct the source files before you copy anything into /etc/firewalld. The option changes where the system configuration is read; it does not make malformed XML safe.

# sudo firewall-offline-cmd \
    --system-config /srv/firewalld-staging \
    --check-config

4. Migrate a legacy system-config-firewall file

For a specific legacy file, use --migrate-system-config-firewall. Supply an explicit path so there is no doubt which input is being converted:

# sudo firewall-offline-cmd \
    --migrate-system-config-firewall=/srv/backup/system-config-firewall

The conversion is incomplete by design.

• Ignored input. The tool can warn about or ignore custom rule files and module settings.
• Translation limits. The compatibility options cover services, ports, forwarding, ICMP blocks, trusted interfaces and masquerading, but those translations have boundaries. For example, the --masq interface argument is ignored and the resulting masquerading is IPv4-only.
• Warnings are work. Treat them as review items, not harmless noise.

A successful exit does not prove that the resulting policy matches the old firewall. The manpage describes special handling for repeated options: an already-enabled item, an item that was not enabled, or an already-set zone can count as success. If one item succeeds while another has a parsing warning, the overall status can still be zero. Read all the output and inspect the saved configuration afterwards.

5. Apply a small, explicit offline change

The compatibility options can add a service or port to the default zone. Use a known firewalld service name, and query the available names before you pick one:

# sudo firewall-offline-cmd --get-services
cockpit dhcp dhcpv6 dhcpv6-client dns freeipa-ldap freeipa-ldaps ...
# sudo firewall-offline-cmd --service=ssh

The list is host-specific, so the abbreviated line above is illustrative rather than literal output. To add a raw port, use a single port or range followed by a colon and one of tcp, udp, sctp or dccp:

# sudo firewall-offline-cmd --port=8443:tcp
# sudo firewall-offline-cmd --port=50000-50010:udp

These examples change persistent firewall configuration. They do not mean that a running daemon has safely reloaded the new policy, which is another reason to keep the service stopped during the offline workflow. After each change, rerun --check-config and inspect the relevant zone or service files through your normal review process.

Removing a service is also a persistent change:

# sudo firewall-offline-cmd --remove-service=ssh

6. Avoid compatibility traps

Several legacy-looking options do not carry their old meaning cleanly:

• --addmodule, --removemodule and --custom-rules produce warnings and are ignored.
• --trust, --masq and --forward-port produce warnings because their conversion has limitations.
• A quiet migration proves nothing. Check the generated configuration rather than assuming it reproduced every netfilter detail.

Direct rules are deprecated in this firewalld release and are intended only as a last resort. The manpage also warns that their behaviour depends on the firewall backend. Prefer services, zones, rich rules or policies where they express the requirement. Do not paste direct arguments from an old script without reviewing the table, chain, priority, address family and backend.