Create a Custom firewalld ICMP Type Without Guessing the XML

Firewalld ships plenty of ICMP types, but the one your monitoring tool wants is never quite there, so you end up hand-writing an ICMP type definition. You will create a local one, restrict it to the IP family you actually need, load it into the permanent configuration and verify the result with firewall-cmd. Allow about 15 minutes, including a cautious reload and a rollback copy.

• You need: a Linux host with firewalld installed, an account that can write to /etc/firewalld/icmptypes, and a name for the new type. The examples use corp-echo-check.
• Replace that name consistently. The XML file name and the ICMP type name must refer to the same object.

Before you start

This guide follows firewalld 2.1.1, the version installed on the reference machine. Check your own version before relying on details:

$ firewall-cmd --version
firewalld 2.1.1

The command output can differ on another host. If firewalld is not running, read-only commands that talk to the daemon will report that fact; do not start a production firewall merely to make a documentation example pass.

1. Check whether the name already exists

Use the runtime listing before choosing a name. This avoids accidentally colliding with a predefined type or an existing local definition:

$ firewall-cmd --get-icmptypes | tr ' ' '\n' | grep -Fx 'corp-echo-check' || echo 'name is available'

For a stopped daemon, use the files as a second check:

$ test ! -e /etc/firewalld/icmptypes/corp-echo-check.xml && echo 'no local file'
$ test ! -e /usr/lib/firewalld/icmptypes/corp-echo-check.xml && echo 'no packaged file'

A name must be made from letters and digits, with underscores and hyphens also allowed when using the corresponding firewall-cmd management operation. Keep it simple and lower-case so it is easy to use in zone rules and scripts.

2. Write one valid XML definition

Local administrator-owned definitions belong under /etc/firewalld/icmptypes. The file has one mandatory icmptype element. The readable name and description are optional. The version attribute is metadata, not a firewalld package version.

The destination is the key safety setting. If the element is omitted, the documented default is both IPv4 and IPv6. This example opts into IPv4 only:

$ sudo install -d -m 0755 /etc/firewalld/icmptypes
$ sudo tee /etc/firewalld/icmptypes/corp-echo-check.xml >/dev/null <<'XML'
<?xml version="1.0" encoding="utf-8"?>
<icmptype version="1">
  <short>Corporate Echo Check</short>
  <description>An organisation-specific ICMP type used for an IPv4 health check.</description>
  <destination ipv4="yes" ipv6="no"/>
</icmptype>
XML

• Use ipv4="no" and ipv6="yes" for an IPv6-only type, or set both to yes when both families are intentional.
• Keep destination as one element. The man page describes it as an optional empty element that can be used once; put both family attributes on that one element.

$ sudo sed -n '1,20p' /etc/firewalld/icmptypes/corp-echo-check.xml
$ sudo test "$(grep -c '<destination ' /etc/firewalld/icmptypes/corp-echo-check.xml)" -eq 1 && echo 'one destination element'

3. Validate the permanent configuration

Run the built-in configuration check. This reads configuration and reports syntax or structural problems without adding a firewall rule:

$ sudo firewall-cmd --check-config
success

If it fails, stop here. Check the XML closing tags, the spelling of ipv4 and ipv6, and whether the file is readable by the daemon. A file named correctly but containing malformed XML is still a broken configuration.

On the reference machine the daemon was stopped, so the check returned FirewallD is not running with status 252. That is a host-state result, not evidence that the XML is valid. Run this step on the host where firewalld is managed.

4. Reload and inspect the type

$ sudo firewall-cmd --reload
success
$ firewall-cmd --info-icmptype=corp-echo-check
corp-echo-check
  destination: ipv4

The exact information output is version-dependent, but it should identify the type and show only the destination family you selected. If the type is not found, check the file name, directory and reload result before changing any zone rules.

5. Use the type in a rule only after verification

Defining an ICMP type does not itself allow or block traffic. It makes a named type available to firewalld rules. For example, to add a permanent ICMP block to the active zone, first identify that zone and understand the impact:

$ firewall-cmd --get-active-zones
$ sudo firewall-cmd --permanent --zone=public --add-icmp-block=corp-echo-check
$ sudo firewall-cmd --reload
$ firewall-cmd --zone=public --query-icmp-block=corp-echo-check
yes

To undo that specific change, remove the permanent block and reload:

$ sudo firewall-cmd --permanent --zone=public --remove-icmp-block=corp-echo-check
$ sudo firewall-cmd --reload

When you only need the definition for later work, stop after inspecting --info-icmptype. Keep the definition separate from the rule so its family restriction is reviewable.

6. Recover cleanly or remove the definition

After removing any rules that use the type, delete the local file and reload. This is a state-changing operation; make a backup first if the definition may be needed again:

$ sudo cp --preserve=all /etc/firewalld/icmptypes/corp-echo-check.xml /tmp/corp-echo-check.xml.backup
$ sudo rm /etc/firewalld/icmptypes/corp-echo-check.xml
$ sudo firewall-cmd --check-config
$ sudo firewall-cmd --reload

The copy in /tmp is a recovery aid, not a permanent configuration location. Restore it to the original path, check the configuration and reload if you need to bring the type back.