Write a firewalld Lockdown Whitelist Without Locking Yourself Out

Switch on firewalld lockdown with a half-checked whitelist and your own admin commands get refused, at the worst possible moment. This guide gets you a checked lockdown-whitelist.xml that permits only the clients you choose. It is written for firewalld 2.1.1, and a small whitelist takes about 10 minutes, plus time to test from the account that will use it.

What lockdown does. It limits firewall changes made through firewalld's D-Bus interface to applications in the whitelist.
What it does not do. It does not decide which packets are allowed. Zones, services and rich rules still do that.
The default. firewalld.conf ships with Lockdown=no, so a whitelist does nothing until you enable lockdown.

1. Check firewalld is running

You need root privileges and a working firewalld installation. Check the version and state first:

firewall-cmd --version
sudo firewall-cmd --state

On this installation the first command reports 2.1.1. If the second does not report running, stop: do not use reload or lockdown commands yet. A stopped service cannot apply the file.

2. Inspect the existing file

The installed 2.1.1 manpage names the permanent file /etc/firewalld/lockdown-whitelist.xml. Singular. Do not create the plural lockdown-whitelists.xml that some newer online documentation shows, unless the manpage on your machine says otherwise.

sudo install -D -m 0644 /dev/null /tmp/lockdown-whitelist.xml
sudo cp -a /etc/firewalld/lockdown-whitelist.xml /tmp/lockdown-whitelist.xml.backup 2>/dev/null || true
sudo test -f /etc/firewalld/lockdown-whitelist.xml && \
  sudo sed -n '1,160p' /etc/firewalld/lockdown-whitelist.xml || \
  echo 'No existing whitelist file'

The backup is only a convenience for this session. If the file exists and you want a durable rollback, make a separate dated copy before editing.

Checkpoint: you either see the current whitelist or the line No existing whitelist file, and a backup exists if there was a file to copy.

3. Choose the narrowest entry

There are three useful entry types:

Command. Matches a complete command line, including its absolute path and arguments. A trailing asterisk turns it into a prefix match.
User. Permits a user by name or numeric ID.
SELinux context. Permits a security context, which can cover more than one process.

Then pick with these rules:

Prefer an exact command when one maintenance action needs permission.
Use a user entry only when every firewalld client run by that account should be allowed.
Check a context before you use it. An unconfined context can open access more broadly than the intended application.

Find the real executable path and, if you use SELinux, the context of the running process. Run these as the target user where PATH differences matter:

command -v firewall-cmd
ps -e --context | grep '[f]irewall-cmd'

The command path can differ for root and other users, because firewalld evaluates the path supplied through the environment. Do not copy a path from another host without checking it here.

4. Write a minimal XML file

The root element appears once. Each child is an empty element with exactly the attribute described by the manpage. This example allows one exact command line and one named automation account.

<?xml version="1.0" encoding="utf-8"?>
<whitelist>
  <command name="/usr/bin/firewall-cmd --reload"/>
  <user name="firewall-automation"/>
</whitelist>

Warning: replace both placeholder values with ones you have verified. Do not leave the example values in production.

Write the file with an elevated editor, or stage it outside /etc and install it after reviewing it:

cat > /tmp/lockdown-whitelist.xml <<'XML'
<?xml version="1.0" encoding="utf-8"?>
<whitelist>
  <command name="/usr/bin/firewall-cmd --reload"/>
  <user name="firewall-automation"/>
</whitelist>
XML
sudo install -o root -g root -m 0644 /tmp/lockdown-whitelist.xml \
  /etc/firewalld/lockdown-whitelist.xml

Tip: for a prefix rule, put the asterisk inside the XML attribute, such as name="/usr/bin/firewall-cmd --zone=public --add-service=*". That is deliberately broad: it matches every command line beginning with that text. An exact rule does not match a different argument order or an omitted argument.

5. Validate and apply

Ask firewalld to check its permanent configuration before reloading. This does not enable lockdown:

sudo firewall-cmd --check-config
sudo firewall-cmd --reload
sudo firewall-cmd --list-lockdown-whitelist-commands
sudo firewall-cmd --list-lockdown-whitelist-users
sudo firewall-cmd --query-lockdown

Checkpoint: the check succeeds, the listings include the entries you chose, and the final query still says no. The context and UID listings are available with --list-lockdown-whitelist-contexts and --list-lockdown-whitelist-uids.

6. Enable lockdown carefully

Warning: enabling lockdown is security-sensitive and can disrupt administration immediately. Keep a root shell open and confirm that your actual management command is covered before you run this.

sudo firewall-cmd --lockdown-on
sudo firewall-cmd --query-lockdown

Do not test this first over your only remote session. If your intended client is rejected, disable lockdown from the open root shell:

sudo firewall-cmd --lockdown-off

Common traps

Valid XML, wrong permission. A missing absolute path, a different argument order, or a command launched with another PATH will prevent an exact command match.
Too broad. A trailing asterisk or an unconfined SELinux context can grant more than you expected.
The fix. Recheck the live lists and compare them with the command as actually executed.

If the file fails validation or reload, restore the copy you made before editing and check again:

sudo install -o root -g root -m 0644 /tmp/lockdown-whitelist.xml.backup \
  /etc/firewalld/lockdown-whitelist.xml
sudo firewall-cmd --check-config
sudo firewall-cmd --reload

Recovery: the restore command overwrites the current whitelist file. If the backup does not exist, edit the file back to its last known good contents instead. --lockdown-off is the immediate recovery for an administrative lockout, but it does not undo edits to the XML.

Done means

The file is in place. It is at /etc/firewalld/lockdown-whitelist.xml and has one <whitelist> root.
Entries are narrow. Every command, context and user entry is narrower than the access it replaces.
Validation passes. sudo firewall-cmd --check-config succeeds after the change.
Listings match. The list commands show the intended entries.
Lockdown came last. You enabled it only after a recovery shell and a real client test were ready.