Inspect and Safely Plan IPsec State with ip xfrm

You will identify the installed ip xfrm implementation, inspect its Security Association Database and Security Policy Database, and prepare a narrowly scoped state or policy change without flushing a live host. Allow about 15 minutes for inspection. Applying an IPsec configuration needs a maintenance window and a tested peer configuration.

1. Check the local tool and package

The commands below are ordinary, unprivileged checks. This guide was written against iproute2 6.1.0-1ubuntu6.4. Syntax and available algorithms can differ between releases, so record the version before copying a configuration between hosts.

$ command -v ip
/usr/sbin/ip
$ ip -V
ip utility, iproute2-6.1.0, libbpf 1.3.0
$ dpkg-query -W -f='${Package} ${Version}\n' iproute2
iproute2 6.1.0-1ubuntu6.4

Checkpoint: if command -v ip finds a different binary, or the package is managed by another distribution, use that host's manual page and version as the authority.

2. Understand what xfrm controls

XFRM is the kernel framework used for packet transformations such as IPsec. Its state object represents entries in the Security Association Database. Its policy object represents entries in the Security Policy Database. A state describes how a matching transform is performed; a policy selects traffic and can refer to a transform template.

Selectors can match source and destination addresses, a device, and an upper-layer protocol. For TCP, UDP, SCTP and DCCP, the selector can also include source and destination ports. Policies have an in, out or fwd direction. The policy defaults documented by this installed manual are type main, action allow, and priority 0; a template level defaults to required.

Do not confuse an XFRM policy with a firewall rule. A policy controls whether traffic requires a transform or is allowed by the XFRM policy database. Firewall filtering remains a separate concern.

3. Inspect state and policy first

Listing does not intentionally add or remove an entry, but it still asks the kernel for security-sensitive information. Run it as your normal account first. The nokeys option omits key material from state output when you only need identifiers and modes.

$ ip xfrm state list nokeys
$ ip xfrm policy list
$ ip xfrm state count
$ ip xfrm policy count

On a host without the required network-admin capability, the kernel can reject these requests with RTNETLINK answers: Operation not permitted. That is a privilege boundary, not proof that the databases are empty. If your operational role permits it, repeat the read-only commands with sudo and record the output before making changes:

$ sudo ip xfrm state list nokeys
$ sudo ip xfrm policy list

Checkpoint: save a before snapshot somewhere access-controlled. Avoid putting full state output into tickets or shell history if it contains key material.

4. Watch changes while troubleshooting

ip xfrm monitor listens for XFRM events such as state, policy, acquire, expire, aevent and report messages. Start it in one terminal while a controlled test runs in another:

$ sudo ip xfrm monitor all
<wait for an XFRM event>
<press Ctrl-C when the test is complete>

The output is event-driven, so an idle terminal is normal. The all-nsid option also listens for network namespaces that have an assigned namespace ID. Use it only when namespace scope matters; otherwise it can make the output harder to attribute.

5. Plan a state entry without guessing

A state ID is built from some combination of source address, destination address, transform protocol and SPI. The installed syntax supports esp, ah, comp, route2 and hao. IPsec commonly uses ESP in transport or tunnel mode. The state also needs algorithm and keying details agreed with the peer.

Before writing anything, ask the local binary for the accepted grammar. This is a safe syntax check and does not install a state:

$ ip xfrm state add help
Usage: ip xfrm state { add | update } ID [ ALGO-LIST ] ...
$ ip xfrm policy add help
Usage: ip xfrm policy { add | update } SELECTOR dir DIR ...

The exact help text can vary with the build. Do not invent an algorithm name or key length from an example on another system. Use the peer's negotiated specification and confirm that the corresponding kernel support exists. Never paste real key material into a public guide, ticket or shared terminal transcript.

6. Plan a policy and its rollback

A policy can select traffic directly and can include one or more tmpl entries. A template identifies the transform protocol and can specify mode, request ID and level. A policy change can interrupt connectivity immediately, particularly when it changes outbound traffic from allowed plaintext to required transformed traffic.

Write down the exact selector, direction, priority, mark and template before using elevated privileges. Use a narrow selector such as the intended peer addresses and protocol rather than a broad catch-all while testing. Keep the existing policy listing as your rollback record.

$ sudo ip xfrm policy get \
    src PEER_NETWORK \
    dst LOCAL_NETWORK \
    dir out
$ sudo ip xfrm policy list

Replace the uppercase values with addresses and selectors valid for your deployment. If the command reports that no matching policy exists, do not treat that as permission to add a guessed rule. Reconcile the selector with the peer and the service's actual traffic first.

Warning: state flush removes all state, and policy flush removes policies. The manual also provides deleteall operations. These are service-disrupting operations, not cleanup shortcuts. Prefer deleting one precisely identified entry, and retain a tested recovery command or configuration-management revision before doing so.

7. Verify after a controlled change

When a change has been approved, apply it in a maintenance window with monitoring running. Then inspect the resulting objects and test only the intended traffic:

$ sudo ip xfrm state list nokeys
$ sudo ip xfrm policy list
$ sudo ip xfrm state count
$ sudo ip xfrm policy count
$ sudo ip xfrm monitor

Compare the post-change listing with the before snapshot. Confirm the expected source, destination, protocol, SPI, mode, direction and template. A successful netlink command only means that the kernel accepted the request; it does not prove that the peer can authenticate, that routing is correct, or that application traffic is protected.

To undo a precisely identified entry, use the matching state delete or policy delete form from the installed manual, then restore the known-good configuration. Do not use a flush as a rollback unless you have explicitly approved removing every XFRM object on the host.