Native IKEv2 and IPsec
Pre-Alpha. This page describes behavior that may change.
Ze implements native IKEv2 in Go for route-based IPsec VPN tunnels. It does not require strongSwan, libreswan, or another external IKE daemon. The IKE engine, cryptographic primitives, wire codec, and XFRM dataplane integration are all in-tree. The Ze binary negotiates IKE SAs, installs XFRM policies and states, and programs routes through XFRM interfaces from the same YANG config tree as every other subsystem.
Live IPsec demonstration
The recording loads IKE, ESP, peer authentication and selectors, then XFRM
routing into one SSH candidate on a running router. A hidden Ze responder
protects the other host. Kernel SPIs and increasing packets-in after a
protected-host ping distinguish installed forwarding from negotiated state.
The failure changes only ESP to a cipher the responder does not offer.
show vpn ipsec peer name responder can still report established IKE with no
Child SA. show log recent level warn | match NO_PROPOSAL_CHOSEN | last 1 | yaml
shows the latest refusal with notify: NO_PROPOSAL_CHOSEN and peer: responder
in the same entry's structured attributes, without unrelated warnings scrolling
it out of view. Empty dataplane
drift means the expected SA identities are present, not that a tunnel exists
or that every forwarding policy is installed. The repair restores the ESP
group, clears that peer's SAs and proves protected traffic again.
For Junos operators, the equivalent observations are
show security ike security-associations
for IKE and
show security ipsec security-associations
for the installed IPsec SAs and SPIs.
Build and repair a native IPsec tunnel live
Commit IKE, ESP, selectors and XFRM routing over SSH, prove kernel SPIs with protected traffic, diagnose an ESP mismatch, and restore the tunnel.
Read the demonstration transcript
Native IKEv2 and Linux IPsec, configured live
Lab: shown Ze 172.30.0.1 initiates to a hidden Ze responder at 172.30.0.2.
Protected hosts 10.78.1.2 and 10.78.2.2 live behind different routers.
The shown daemon starts with no VPN configuration or XFRM interface.
$ ze-demo card topic-ipsec lab
$ ze-demo card topic-ipsec overview
In one SSH candidate, load topics/ipsec/1-ike.conf, 2-esp.conf, 3-peer.conf,
and 4-xfrm.conf with load file absolute merge. Review show | compare and
commit now. The sections define IKE, ESP, authenticated peer and selectors,
and the route through vpn-xfrm (if-id 42).
$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/ipsec/1-ike.conf
ze# load file absolute merge /src/demos/terminal/topics/ipsec/2-esp.conf
ze# load file absolute merge /src/demos/terminal/topics/ipsec/3-peer.conf
ze# load file absolute merge /src/demos/terminal/topics/ipsec/4-xfrm.conf
ze# show | compare
ze# commit now
ze# exit
ze> exit
$ ze-demo card topic-ipsec proof
$ ze cli -c 'show vpn ipsec status | no-more'
$ ze cli -c 'show vpn ipsec sa | no-more'
$ ze cli -c 'show vpn ipsec dataplane sa | no-more'
$ ze-demo run showcase-lab control vpn ping
$ ze cli -c 'show vpn ipsec sa | no-more'
The kernel SPIs must match the negotiated Child SA. The protected ping
must succeed and the same inbound SA's packets-in must increase.
Failure: load 5-mismatch.conf and commit. It changes only ESP to AES-128;
the far end offers AES-256. IKE can stay established while no Child SA exists.
$ ze-demo card topic-ipsec failure
$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/ipsec/5-mismatch.conf
ze# show | compare
ze# commit now
ze# exit
ze> exit
$ ze-demo card topic-ipsec diagnosis
$ ze cli -c 'show vpn ipsec peer name responder | no-more'
$ ze cli -c 'show log recent level warn | match NO_PROPOSAL_CHOSEN | last 1 | yaml | no-more'
$ ze cli -c 'show vpn ipsec dataplane sa | yaml | no-more'
$ ze cli -c 'show vpn ipsec dataplane drift | yaml | no-more'
The same log entry carries peer responder and notify NO_PROPOSAL_CHOSEN
under attributes beside the message that IKE remains established. An empty
drift result means the engine and kernel agree, not that a tunnel carries traffic.
Load 2-esp.conf, review and commit, then clear vpn ipsec sa peer responder.
Verify the new kernel SPIs, successful protected ping and increasing packets-in.
The shown Ze process is never restarted.
$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/ipsec/2-esp.conf
ze# show | compare
ze# commit now
ze# exit
ze> exit
$ ze cli -c 'clear vpn ipsec sa peer responder | no-more'
$ ze-demo run showcase-lab control vpn ping
$ ze cli -c 'show vpn ipsec sa | no-more'
$ ze cli -c 'show vpn ipsec dataplane sa | no-more'
$ ze-demo card topic-ipsec recap
Vendor mapping: Junos show security ike security-associations reads IKE state;
show security ipsec security-associations reads the IPsec SAs and their SPIs.
https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/show-security-ike-security-associations.html
https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/show-security-ipsec-security-associations.html
https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/statement/security-edit-proposal.html
Architecture
The IPsec stack is split across several packages:
| Package | Role |
|---|---|
internal/component/ike/wire |
IKEv2 wire format codec for RFC 7296 payloads |
internal/component/ike/crypto |
DH groups, PRFs, integrity, encryption, and key derivation |
internal/component/ike/transport |
UDP transport with NAT-T keepalives and port 4500 encapsulation |
internal/core/eap |
EAP-MSCHAPv2, EAP-TLS and EAP MD5-Challenge authentication |
internal/component/ike/engine |
IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA, and INFORMATIONAL state machines for initiator and responder roles, rekeying, and DPD |
internal/component/ike/ipsec |
YANG schema, configuration, and validation |
internal/component/ike/dataplane |
XFRM policy and state programming through netlink |
internal/component/pki |
X.509 certificate and private-key store |
Configuration
IPsec is configured under vpn { ipsec { } }. Named ike-group and esp-group blocks hold the IKE and ESP proposals and lifetimes. Each site-to-site peer references a group pair, sets its authentication, and binds to an XFRM interface for route-based forwarding. A peer's and remote-access's ike-group and esp-group are leafrefs: commit, a SIGHUP reload and ze config validate refuse a name no group declares, naming the groups that exist, and the editor completes the names.
pki {
ca my-ca {
certificate "-----BEGIN CERTIFICATE-----...";
}
certificate my-cert {
certificate "-----BEGIN CERTIFICATE-----...";
private {
key "-----BEGIN PRIVATE KEY-----...";
}
}
}
vpn {
ipsec {
interface eth0;
ike-group site-b-ike {
key-exchange ikev2;
lifetime 28800;
proposal 1 {
encryption aes256gcm;
hash sha256;
dh-group 14;
}
dead-peer-detection { interval 30; timeout 120; }
}
esp-group site-b-esp {
lifetime 3600;
pfs enable;
proposal 1 { encryption aes256gcm; }
}
site-to-site {
peer site-b {
ike-group site-b-ike;
esp-group site-b-esp;
connection-type initiate;
local-address 198.51.100.2;
remote-address 198.51.100.1;
authentication {
mode x509;
certificate my-cert;
ca-certificate my-ca;
}
vti { bind vti0; }
}
}
}
}
Traffic selectors constrain which protected networks a peer negotiates. Route-based forwarding also needs a route through the bound XFRM interface. The generated configuration reference documents the XFRM interface leaves.
In the live demonstration, the route is 10.78.2.0/24 with
next { interface vpn-xfrm {} }. The empty next-hop entry is meaningful:
it selects the XFRM interface without a gateway or another leaf. The editor
records this as an owned entry, not as a side effect of configuring the nearby
interface leaves. It must survive the SSH candidate commit and appear in the
kernel routing table. Established IKE, installed SAs and an up XFRM interface
do not substitute for that route.
If the protected ping receives Destination Net Unreachable from the local
router, inspect the committed route and kernel route lookup before changing
selectors or proposals.
If the routes exist but a protected-host ping still loses every packet, compare
SA counters with the receiving router's /proc/net/xfrm_stat and
show vpn ipsec dataplane policy. Decryption alone is not forwarding. On Linux,
a tunnel needs a fwd PROTECT policy as well as in and out: the fwd policy
uses the inbound protected prefixes, tunnel endpoints, owner and XFRM if-id.
Ze installs and removes these together; this is not another configuration knob.
A receiving SA whose packet count increases while XfrmInNoPols increases
has decrypted packets rejected by a later policy lookup. In the live
demonstration, both routes and both SAs existed, but the receiving router had
only in and out policies at if-id 42. The missing fwd policy caused that
drop. A wildcard bypass at if-id 0 does not satisfy a lookup at if-id 42.
Changing the traffic test to ping the router itself, disabling policy checks,
or adding a bypass would not repair protected-host forwarding.
Which edits restart a tunnel
Committing a change to ANY leaf inside a peer block restarts that peer, and so does a
change to the ike-group or esp-group that peer names. The tunnel drops, Ze re-negotiates
it, and the new configuration is what the new IKE SA and its Child SA carry. There is no
list of leaves that count and leaves that do not: the whole peer configuration and both
resolved groups are compared, so a leaf that Ze gains in a later release restarts the tunnel
from the day it exists.
Rotating a cipher is the case worth naming, because it edits no peer block at all. A peer
holds the NAME of its groups and none of the crypto, so ike-group IKE-1 { proposal 1 { encryption ... restarts every peer that names IKE-1 and no other.
One edit does not restart the tunnel. When a peer's IKE SA is up with no Child SA, because
the two sides could not agree on ESP when it was established, a commit that changes only that
peer's esp-group keeps the IKE SA. Nothing is carrying traffic yet, so nothing runs under
the old settings; the new esp-group applies when the Child SA is created on that IKE SA,
with no reconnect. Change the ike-group or the peer block in the same commit, or make the
edit while a Child SA exists, and the peer restarts as above.
A commit that leaves a peer's block and its two groups unchanged does not touch that peer, whatever else in the configuration moved. Adding a second peer, editing a firewall rule or changing a log level leaves a running tunnel carrying traffic.
Three consequences are worth planning around:
- A tunnel bounce is how a narrowing takes effect. Narrowing a peer's
traffic-selectorlist to stop carrying a prefix works, and it costs the tunnel a re-negotiation. RFC 7296 Section 2.9.2 leaves no other route: a Child SA cannot be narrowed in place. - Batch peer edits into one commit. Three commits touching one peer bounce it three times. One commit carrying all three edits bounces it once.
- A group is shared, so an edit to it bounces every peer that names it. Give a peer its own group when you want to rotate its crypto without touching the others.
A commit is REFUSED when interface cannot supply an address and some peer has no
local-address of its own. The transaction rolls back and every running tunnel keeps
carrying traffic, because applying that configuration would restart each of those peers
into a state that cannot bind. The error names the interface and how many peers depend on
it. Give those peers a local-address, or bring the interface up, then commit again. At
DAEMON START the same configuration is applied and the condition is logged instead: there
is no running tunnel to protect, and the peers that carry their own local-address still
come up.
IKE features
| Feature | Detail |
|---|---|
| IKEv2, RFC 7296 | Full IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA, and INFORMATIONAL exchange support |
| Role | Initiator or responder per peer through connection-type initiate or respond |
| Proposals | AES-CBC and AES-GCM 128/256 for the IKE SA and ESP; AES-CCM 128/256 with an 8, 12 or 16 octet ICV for the IKE SA only (RFC 5282), refused at commit in an esp-group; NULL encryption with an integrity algorithm for ESP only (integrity-only ESP, RFC 4303 Section 1), refused at commit in an ike-group (RFC 7296 Section 5); ESP-only chacha20poly1305 with no hash, and legacy ESP 3des with hash sha1; DH groups 14 (MODP 2048), 19 (ECP 256) and 20 (ECP 384); SHA-256/384/512 PRFs. ChaCha20, 3DES and SHA-1 remain unavailable for the IKE control channel |
| Authentication | Pre-shared key, X.509 certificates, EAP-MSCHAPv2, and EAP-TLS; Ze acts as the EAP authenticator in responder mode |
| NAT-T, RFC 3948 | Automatic NAT detection, UDP encapsulation on port 4500, and keepalives |
| DPD | Dead Peer Detection through INFORMATIONAL exchanges with configurable interval and timeout |
| Rekeying | On-wire CREATE_CHILD_SA rekeying for IKE and Child SAs, make-before-break installation, and collision handling |
| MOBIKE, RFC 4555 | Tunnel-mode endpoint movement as initiator or responder, with authenticated return-routability checks; requires the Linux atomic XFRM state-migration API |
| Denial-of-service | COOKIE challenge before a half-open slot is committed, and the INVALID_KE_PAYLOAD group retry |
| Dataplane read-back | show vpn ipsec dataplane reads the kernel SAD and SPD, and a drift check compares them against the engine |
| Virtual IP pool | A respond peer with virtual-ip-pool is leased a unique inner address from the named remote-access pool in IKE_AUTH (RFC 7296 Section 2.19), and its Child SAs name that address |
Prefer AES-GCM or ChaCha20-Poly1305 for new ESP deployments. 3des and sha1
are explicit legacy interoperability choices, not defaults. ChaCha20-Poly1305
uses a 32-byte key plus a four-byte salt and a 16-byte tag. 3DES uses a 24-byte
key including DES parity; SHA-1 integrity uses a 20-byte key and a 12-byte ICV.
The fixed-size ciphers send no Key Length attribute. Linux XFRM and VPP have
explicit algorithm mappings; an unavailable backend algorithm fails installation,
never falls back to AES. Interoperability proof for both new combinations is
pending the scoped two-role rekey runs.
MOBIKE endpoint movement
IPv4 tunnel peers negotiate MOBIKE automatically when the dataplane can migrate a
live ESP state without resetting its sequence number or replay window. The Linux
backend requires Linux 7.2's XFRM_MSG_MIGRATE_STATE API and CONFIG_XFRM_MIGRATE.
Kernels without that API, other backends and transport-mode peers do not advertise
MOBIKE; their existing IKE and IPsec behavior is unchanged.
The initiator keeps the configured responder address. If its local address disappears, it selects the routed source address and sends an authenticated address update. The responder accepts explicit updates from that initiator. Both roles require a matching COOKIE2 return-routability response before moving the Child SA. The IKE and Child SPIs, keys and inner traffic selectors remain the same. An invalid COOKIE2 closes the IKE SA rather than installing an unverified path.
MOBIKE uses UDP 4500 even without a NAT. This alone does not enable outbound ESP-in-UDP;
the NAT detection result still controls ESP encapsulation. The per-peer
nat-traversal policy defaults to allow, preserving existing NAT tunnels.
Set vpn ipsec site-to-site peer <name> nat-traversal to prohibit to reject
translated paths. This protects the first IKE_AUTH and every address update with
NO_NATS_ALLOWED. A prohibiting peer also refuses an unprotected MOBIKE address
update from its correspondent; configure the corresponding prohibition there.
NAT detection remains active to detect forbidden translation, and UDP 4500
capability does not override the prohibition.
There is no separate MOBIKE enable leaf. An operator configuration edit, including a NAT-policy change, restarts the peer. Mobility handles a live network address change, not a configuration replacement.
IKEv2 responder role
Ze can act as an IKEv2 responder or initiator. A peer with connection-type respond waits for an unsolicited inbound IKE_SA_INIT from its configured remote-address, answers IKE_AUTH, and installs the first Child SA. connection-type initiate, the default, starts the exchange. The UDP transport always listens, so responder mode does not need a separate listen switch.
As responder, Ze authenticates with a pre-shared key, X.509 certificate, or EAP. For EAP it acts as the EAP-MSCHAPv2 or EAP-TLS server for a road-warrior client. It presents its own certificate or PSK first, runs the EAP method, and derives session keys from the EAP MSK.
A new inbound IKE_SA_INIT can proceed while an older established SA for the same peer is still being maintained. Once the replacement authenticates, its INITIAL_CONTACT notification tells the remote endpoint to discard the stale SA. This lets a responder recover immediately after an operator clear or peer restart instead of waiting for Dead Peer Detection.
The replacement takes over only once its Child SA is installed. If Ze refuses that Child SA (no matching ESP proposal, traffic selectors it cannot accept), the new IKE SA is held beside the old one and the old tunnel keeps carrying traffic; the log names the refusal and its fix. The peer can still create the Child SA on the replacement later, and the tunnel then moves onto it; it can also delete the replacement, which leaves the old tunnel as it was. If the old IKE SA then ends while the replacement still has no Child SA, Ze deletes the replacement and the session reconnects.
A gateway can also reauthenticate a tunnel that Ze started (RFC 7296 Section
2.8.3 lets either end create the new IKE SA). An initiate peer accepts a new
IKE_SA_INIT while its IKE SA is established, and only from the address that SA
talks to; with no established SA it still refuses every unsolicited initiation.
The new IKE SA authenticates with the same peer configuration, and Ze moves the
tunnel onto it, new Child SA first, without reconnecting. A peer that
authenticates with EAP refuses it, because RFC 7296 says reauthentication then
has to come from the side that started the original IKE SA: set
reauth_time = 0s on a strongSwan gateway for such a peer. If the gateway's
reauthentication crosses Ze's own IKE SA rekey, or Ze's reconnect after it gave
the old SA up, Ze keeps the IKE SA the gateway started and deletes its own, in
whichever order the two complete, so one tunnel remains.
vpn {
ipsec {
interface eth0;
ike-group IKE-PSK {
key-exchange ikev2;
proposal 1 { encryption aes256gcm; hash sha256; dh-group 14; }
}
esp-group ESP-PSK {
pfs enable;
proposal 1 { encryption aes256gcm; }
}
site-to-site {
peer swan {
ike-group IKE-PSK;
esp-group ESP-PSK;
connection-type respond;
local-address 172.28.0.2;
remote-address 172.28.0.3;
authentication {
mode pre-shared-secret;
local-id "172.28.0.2";
remote-id "172.28.0.3";
pre-shared-secret "$9$encoded";
}
}
}
}
}
For a road-warrior EAP server, set authentication { mode eap-mschapv2 }, eap-tls or eap-md5, then reference a device certificate and ca-certificate from the PKI store. Configure the client as a site-to-site peer. Read the EAP MD5-Challenge section below before you select eap-md5.
A remote-access pool serves the site-to-site peers whose virtual-ip-pool leaf
names it. Such a peer must use connection-type respond and send a CFG_REQUEST in
IKE_AUTH: Ze leases it an inner address no other live peer holds (RFC 3948 Section
5.1), answers with a CFG_REPLY carrying the address and the pool's DNS servers, and
narrows every Child SA the peer asks for to the address. A Child SA Ze asks for on
that IKE SA, a rekey included, proposes only that address for the peer's side, and
an answer naming a wider one is refused. The peer's proposed inner
selector must contain that address, as a strongSwan client's 0.0.0.0/0 does: a
Child SA proposing only other addresses is refused with TS_UNACCEPTABLE, because
the answer may only narrow what the peer proposed. A bound peer that asks for no
address is refused its Child SA with FAILED_CP_REQUIRED, and one Ze cannot serve
with INTERNAL_ADDRESS_FAILURE; both keep the IKE SA. The address returns to the
pool when the IKE SA ends, and the same peer gets it back on reconnect while it is
free. show vpn ipsec sa lists it under virtual-ip. Admission of clients from
unconfigured sources and the eap-user list are not served yet, so an eap-user
authenticates nobody; plan/release/fixes/spec-ipsec-remote-access.md owns that.
A peer bound to no pool keeps the inner source it proposes when its
configuration names no remote traffic selector. Ze still never gives two peers
tunnels that one packet could be sent into (RFC 3948 Section 5.1). When a peer
proposes inner selectors that overlap a live tunnel of another peer, those
selectors are left out of the answer, and when nothing is left the peer gets
TS_UNACCEPTABLE: its IKE SA stays up with no Child SA, and Ze logs a warning that
names both peers, both selector pairs and the fix. The first peer to hold the
address keeps it until its tunnel goes away. The fix is to configure disjoint
remote prefixes (set vpn ipsec site-to-site peer <name> traffic-selector <n> remote prefix <prefix>), to bind the peer to a pool (set vpn ipsec site-to-site peer <name> virtual-ip-pool <pool>), or, for an overlap you
configured on purpose, to give one of the two peers a different priority (set vpn ipsec site-to-site peer <name> policy-priority <n>). A leased address
counts like any other, so keep pool ranges disjoint from other peers' remote
prefixes.
When Ze is the side that asks for the Child SA and the tunnel the responder answers with overlaps another peer's, Ze refuses the answer itself. It deletes the Child SA pair it just negotiated, keeps the IKE SA with no Child SA, and asks again 30 seconds later, doubling the wait after each refusal up to 300 seconds. The warning it logs names the fix, which is the same as above without the pool, since a pool is the responder's to lease.
The same happens when Ze is the side that started the IKE SA and cannot install
or bind the Child SA it negotiated in IKE_AUTH: the kernel refused the install
(a transform it lacks, or a container started without /dev/net/tun for a
Child SA that must receive both ESP forms), the peer's vti binding names no
XFRM interface, or Ze could not build the Child SA at all (its esp-group holds no
proposal Ze can use, or its keys could not be derived). Ze deletes the Child SA pair, keeps the IKE SA with no Child SA,
and asks again 30 seconds later, doubling the wait after each refusal up to 300
seconds. The warning repeats only at each retry, and it carries the fix the
refusal names, such as --device /dev/net/tun for the missing device. The first
attempt after the cause is gone installs the Child SA with no restart.
show doctor reports each peer whose Child SA this node refused after the peer
accepted it, under doctor-ipsec-child-install-refused (check
ipsec-child-install): the peer, when, the cause, the next attempt and the fix.
The row clears once a Child SA installs, whichever exchange installs it.
A tunnel keeps its selectors until its kernel policies are gone, not only until
the tunnel ends. If Ze cannot remove a policy when a tunnel ends, after a
transient netlink error for example, the policy can still send packets into the
old tunnel, so its selectors stay reserved and a peer proposing an overlapping
tunnel is refused. The warning lists, for each policy left, the command that
removes it in the dataplane's own tool: ip xfrm policy delete ... on the Linux
kernel, vppctl ipsec policy del ... on VPP. IKE cannot drive the VPP dataplane
yet: the VPP backend refuses a policy that names no interface, and IKE names
none, so the VPP command and the retry below apply once that support lands
(plan/post-release/features/spec-ipsec-vpp-policy-interface.md). Ze tries the removal again each time a peer proposes a tunnel
and each time a configuration is committed, and releases the selectors as soon
as the policies are gone. Running the listed commands lets the next proposal
succeed, and restarting Ze is the last resort. The refusal names no
configuration of the peer that held the tunnel, which may no longer exist.
Remote prefixes that you configure on two peers, and that each peer negotiates
exactly as written, may overlap only when the two peers have different
policy-priority values: you ordered them, and the lower value decides which
tunnel a packet takes (RFC 4301 Section 4.4.1). At one value, the default 2000
on both for example, nothing orders them, so the second peer to establish is
refused like an unconfigured one. An overlap a peer chose by narrowing inside a
configured selector, to a smaller prefix, one protocol or one port, is refused at
any priority. Route-based peers on distinct XFRM interfaces never conflict.
The same rule covers a peer in transport mode. Its connection is held from its
own address to Ze's, so a tunnel that another peer negotiates around that
address, for example an unbound peer proposing 198.18.0.9/32 to 0.0.0.0/0
while a transport-mode peer runs from 198.18.0.9, is refused, and so is a
transport-mode connection inside a tunnel another peer already holds, whichever
of the two comes first. The warning names both peers, and the fix is on the
tunnel peer: remote prefixes that leave out the transport-mode peer's address,
or a pool. Where the overlap is on purpose, different policy-priority values
order the two, exactly as for two tunnels, when the tunnel is exactly a traffic
selector you configured on the tunnel peer, both sides, and the transport-mode
connection runs exactly from that peer's remote-address to its local-address,
for every protocol and port. A transport-mode peer that narrows its proposal to
one protocol or one port, on its own address or on Ze's (198.18.0.9/32 to
192.0.2.1/32 TCP port 80 for example), chose that itself, and is refused at any
priority. The refusal names the traffic selector that would order the connection,
both prefixes at the connection's own addresses, /32 for IPv4 and /128 for IPv6. A host-to-host
transport-mode peer at 198.18.0.9 beside a full-tunnel peer configured with
0.0.0.0/0 on both sides is therefore served at two different priorities, and
refused at one. A transport-mode peer whose remote-address or local-address
is a DNS hostname is ordered only by a traffic selector you configured on it. Two
transport-mode peers that overlap, two clients behind one NAT for example, are
refused by the dataplane instead (RFC 3948 Section 5.2).
strongSwan protects the same case differently: its default remote_ts is
dynamic, the peer's observed address, so a client behind a NAT that proposes
its private address gets no tunnel at all without a pool. Ze serves every
client whose inner address is free, and refuses only the one that would share
an address with another peer.
Every EAP mode and X.509 needs a ca-certificate. The daemon refuses a remote
certificate it cannot chain to that anchor. A certificate with no trust anchor
authenticates nobody: any self-signed certificate that carries a valid signature
would pass. RFC 7296 Section 2.16 requires EAP to run with a public-key
authentication of the responder, and the anchor is what makes that signature
attributable.
ca-certificate holds one anchor, not a path. A two-level authority therefore
needs the peer to send its intermediate certificates. RFC 7296 Section 3.6 puts
the peer certificate first, and Ze reads every later CERT payload as a link
toward the anchor. Ze sends its own chain the same way: the certificate entry
first, then the intermediate that PKI entry carries. A refusal names the anchor
and the number of intermediate certificates the peer supplied.
The signature method follows the peer. Ze announces RFC 7427 signature
authentication in every IKE_SA_INIT, and a peer that announces it too gets an
RFC 7427 Digital Signature (method 14). A peer that does not, such as strongSwan
with charon.signature_authentication = no, gets the method that fits Ze's
certificate key: RSA Digital Signature (method 1, SHA-1) for an RSA key, and
ECDSA-256, ECDSA-384 or ECDSA-521 (methods 9, 10, 11) for an ECDSA key on P-256,
P-384 or P-521. An Ed25519 or Ed448 key signs under RFC 7427 only, as RFC 8420
defines it: Ze announces the Identity hash in every IKE_SA_INIT, and when the
peer announces it too (strongSwan does with its openssl plugin, and for Ed25519
with its curve25519 plugin too) Ze signs the AUTH octets whole with pure Ed25519
or pure Ed448. A peer that does not announce Identity, or sends no notify at all,
cannot be signed for with an EdDSA key, and the IKE_AUTH fails with a message
naming the peer: use an ECDSA or RSA certificate for it. Ze verifies all of these
methods from the peer, Ed25519 and Ed448 included. An Ed448 certificate must be
issued by an RSA, ECDSA or Ed25519 CA: Ze cannot check a chain whose CA signs
with Ed448.
A ze started with GODEBUG=fips140=only refuses method 1, because Go refuses
SHA-1 signatures in that mode: enable RFC 7427 on the peer instead.
What a peer certificate must allow
Ze refuses a peer certificate issued for another purpose, as RFC 4945 requires. The rules apply to the peer's own certificate, not to its CAs:
| Extension in the peer certificate | Accepted when |
|---|---|
| ✕ | always |
| extendedKeyUsage | it names id-kp-ipsecIKE (1.3.6.1.5.5.7.3.17) or anyExtendedKeyUsage, beside any other purpose |
| ✕ | always |
| keyUsage | it sets digitalSignature or nonRepudiation |
A certificate whose extendedKeyUsage names only TLS purposes is refused. This
includes a Let's Encrypt certificate (serverAuth, and on older ones
clientAuth), and strongSwan's recipe for Windows clients,
pki --issue --flag serverAuth --flag ikeIntermediate. strongSwan and
libreswan accept such a peer, so a tunnel that worked against them can fail
against Ze. The refusal names the extension found. To fix it, reissue the peer
certificate with no extendedKeyUsage, or add id-kp-ipsecIKE to it. With
openssl, put this line in the extension file given to openssl x509 -req -extfile or openssl ca -extfile:
extendedKeyUsage = 1.3.6.1.5.5.7.3.17
Add serverAuth after a comma when the same certificate also serves a Windows
client. strongSwan's pki --issue cannot write id-kp-ipsecIKE: the extended key
usages its --flag option writes are serverAuth, clientAuth, ikeIntermediate,
ocspSigning and msSmartcardLogon only. Issue that certificate with openssl, or with
strongSwan and no --flag, which writes no extendedKeyUsage.
Revoking a peer certificate
Ze checks a certificate peer against the revocation lists in the PKI store. To
revoke a peer certificate, add the list its CA published to the crl of the
pki ca entry that holds that CA:
pki {
ca corp-root { certificate "<pem>"; crl "<pem>"; }
}
Ze then checks every certificate on the peer's chain, except the trust anchor,
against the lists of each pki ca entry whose certificate is on that chain. A
peer whose certificate is on a list is refused, and the log names the
certificate, its serial number and the CA that revoked it. When the peer's
certificate comes from an intermediate CA that the peer sends in its CERT
payloads, add that intermediate as a pki ca entry with its own crl. It
needs no other reference: Ze finds it on the chain.
Once any ca on the chain holds a list, the check is strict. A certificate
whose issuer has no current list is refused, so publish a fresh list before the
nextUpdate of the one in the config passes. A list with a critical extension
Ze cannot process (a delta CRL, an issuing distribution point) answers nothing
and refuses the same way. When no ca on the chain holds a list, the peer
authenticates and Ze logs a warning that its revocation status was not
checked. Ze fetches no list from a CRL distribution point and asks no OCSP
responder for an IKE peer.
An eap-tls peer whose EAP-TLS client sends its certificate without the
intermediate that issued it can still authenticate. Store that intermediate as a
PKI ca entry and name it in intermediate-certificate, a list. When Ze is the
EAP-TLS authenticator, it builds the client's path from the certificates the
client sent plus this list, anchored at ca-certificate only: an intermediate
completes a path and never ends one. On TLS 1.3 the client certificate's
revocation status must be read, so give the intermediate entry its own crl.
RFC 5216 Section 5.3 asks the authenticator to obtain the intermediates a path
needs. Ze does not fetch them from the Authority Information Access URL, so
that SHOULD is not met; this list is the pre-configuration the same section
names for a server that cannot retrieve them.
pki {
ca corp-root { certificate "<pem>"; crl "<pem>"; }
ca corp-sub { certificate "<pem>"; crl "<pem>"; }
}
vpn ipsec site-to-site peer branch authentication {
mode eap-tls
certificate ze-server
ca-certificate corp-root
intermediate-certificate corp-sub
}
Commit and reload refuse a name that is not a PKI ca entry (as does
ze config validate, because the leaf-list is a ze:reference "pki-ca"), an
entry that holds no CA certificate, and the list on a peer whose mode is not
eap-tls, where nothing would read it.
Ze refuses a config that names no ca-certificate at commit and at reload. It
does NOT refuse it under ze config validate, which reads the schema and does
not run a plugin's config verifier.
Pre-shared secret encoding
pre-shared-secret-encoding reads the secret as ascii, the default, or as hex. RFC
7296 Section 2.15 requires the management interface to accept both. Use hex for a secret
that holds non-printable octets.
The encoding is stated and is never guessed from the value. A secret such as
abcdef0123456789 is valid ASCII and valid hex. A daemon that read the value to decide
would silently reinterpret a deployed secret. A hex value with an odd length or a
non-hexadecimal character is refused at commit rather than read as ASCII.
The at-rest $9$ obfuscation is unwrapped first, so a hex secret can also be stored
obfuscated.
Remote identity
remote-id is the identity Ze expects the remote endpoint to assert. When it is
set, Ze enforces it twice on every authentication.
| Check | What it compares | Refusal |
|---|---|---|
| Policy | The IDi or IDr payload the peer sent against remote-id |
Every authentication mode |
| Certificate | The same asserted identity against the remote certificate | Certificate modes only |
The certificate check is the half that matters when one authority issues to several clients. The chain proves the authority issued the certificate. It does not prove the certificate speaks for this peer, because the peer chooses the identity its signature covers. Without the second check any client of that authority authenticates as any peer.
A subject alternative name binds. The subject common name binds only when the
certificate carries no alternative name extension at all. The two fields do not
carry the same attestation: X.509 name constraints reach the alternative names
and never the subject distinguished name. An authority that permits only
dNSName .branch.example.com leaves the common name free, so a common name read
after a present alternative name would defeat that constraint.
The value you configure picks the field. An address remote-id binds against
the address alternative names alone, never against a domain name that spells the
same address. Certificate authorities issue an address alternative name under a
tighter policy than a name, and this stops the peer from choosing the weaker
field.
Ze compares six identity types: ID_IPV4_ADDR, ID_IPV6_ADDR, ID_FQDN,
ID_RFC822_ADDR, ID_KEY_ID, and ID_DER_ASN1_DN. A domain name and a mail
address compare with the ASCII letters folded. An address compares as an address,
so the encoding does not matter. A distinguished name compares in RFC 4514 string
form, and it binds against the certificate subject octet for octet. A peer that
asserts ID_DER_ASN1_GN is refused, because Ze compares no general name.
A local-id written as a distinguished name is still refused at commit. Ze
derives the type it SENDS from the shape of the value, and that derivation has no
ID_DER_ASN1_DN form.
One peer, or a set of peers
A remote-id can name one peer or a group of them. RFC 4301 Section 4.4.3.1
requires both forms of Peer Authorization Database entry. Write a group with the
hierarchy separator in front. Such an entry admits the identities BELOW it and
never the entry text itself.
| You write | It admits |
|---|---|
vpn.example.com |
that name alone |
.example.com |
vpn.example.com, gw.branch.example.com |
gateway@example.com |
that address alone |
@example.com |
gateway@example.com |
CN=hq,O=Example |
that distinguished name alone |
,ST=MA,C=US |
every distinguished name whose top RDNs are ST=MA,C=US |
10.0.0.1 |
that address alone |
10.0.0.0/24 |
every address in the block |
RFC 4514 renders the most significant RDN last, so a distinguished-name group is
written with the top of the tree at the end and a leading comma in front. An
address group takes the same CIDR prefix a traffic selector takes. ID_KEY_ID
is always compared exactly: an opaque octet string has no hierarchy, so a
leading . or @ in one is content.
Substring matching is not offered. .example.com refuses notexample.com, and
it refuses the bare example.com too. Write the apex exactly when you mean it.
A group never widens what one certificate proves. The certificate check
above still binds the identity the peer ASSERTED, so a peer admitted by
.example.com must hold a certificate that carries its own name. A local-id
that names a group is refused at commit, because Ze asserts exactly one identity
and would send the pattern text verbatim.
RFC 7296 Section 4 requires that you can configure Ze to accept a PKIX peer whose
identity is ID_KEY_ID. An opaque key id matches no certificate field, so Ze
cannot derive that binding and denies it by default. Set remote-id-type key-id
to state that the chain to ca-certificate plus the exact key id IS the binding
you intend.
remote-id-type also pins ONE identity type for the peer. Without it a text
remote-id accepts ID_FQDN, ID_RFC822_ADDR and ID_KEY_ID alike. All three
compare as text. Set remote-id-type rfc822-address when you know the value is a
mail address. Ze then refuses a peer that asserts ID_FQDN with the same text.
The leaf governs what Ze ACCEPTS. The type Ze sends still follows local-id.
An unset remote-id runs neither check. Every certificate the configured
authority issued then authenticates as this peer. Ze logs a warning that names
the peer and the identity it accepted. Set remote-id whenever the authority
issues to more than one client.
Certificate chain length
certificate-count bounds the X.509 chain in both directions. It is the most
certificates Ze sends for the peer, and the most it accepts from it. RFC 7296
Section 3.6 sets that figure at four, and the default is four, so a peer you never
configure gets the conformant behaviour.
A peer that sends more than the bound is REFUSED. Ze does not truncate the chain. A silent trim hides from you that the limit was reached. It also makes the surviving certificates depend on the order the peer chose.
Name the intermediates on the PKI certificate entry, in order from the issuer of
your device certificate toward the trust anchor. Ze refuses at commit a peer whose
certificate-count is smaller than the chain its PKI entry holds.
Hash and URL certificates
hash-and-url replaces the certificate on the wire with a 20-octet SHA-1 hash and
a URL that resolves to it (RFC 7296 Section 3.6). It keeps IKE messages short. Set
certificate-url to the http URL where you publish this device's certificate.
The leaf defaults to false, and that default is a security property. Resolving a URL a peer sends makes an outbound request on behalf of a peer that is NOT yet authenticated. Ze must fetch the certificate before it CAN authenticate the peer. With the leaf false Ze advertises nothing, a conforming peer sends no such payload, and Ze drops one from a peer that sends it anyway.
When you enable it, the lookup is bounded:
| Control | Bound |
|---|---|
| Scheme | http only. Every other scheme is refused before any name resolution |
| Response size | 64 KiB |
| Total timeout | 5 seconds |
| Redirects | None. A redirect is refused |
| Destination | Loopback, private, link-local, multicast and metadata addresses are denied |
| Hash | The SHA-1 is verified BEFORE any parser reads the fetched bytes |
| Cache | Keyed by the hash, never by the URL |
Use certificate-url-allow to permit a destination the deny list refuses. Run
ze doctor to check a configured certificate-url.
The EAP peer validates the authenticator's certificate chain against that trust anchor. EAP-TLS has no server hostname, so the check validates the chain without DNS-name matching.
A second authentication round (RFC 4739)
A site-to-site peer can authenticate twice in each direction: for example a
device certificate first, then a pre-shared key that belongs to a user or to a
third party behind the gateway. The first round is the authentication block
you already have. second-round adds one more round for each direction:
vpn ipsec site-to-site peer branch-1 authentication {
mode x509
local-id ze-device.example.com
remote-id 192.0.2.1
certificate ze-device
ca-certificate site-ca
second-round {
local {
mode pre-shared-secret
pre-shared-secret <secret>
id ze-user.example.com
}
remote {
mode pre-shared-secret
pre-shared-secret <secret>
id gateway-user.example.com
}
}
}
local is the credential Ze proves in its second round, and remote the one
it requires from the peer. Either can be left out. Each round runs in its own
IKE_AUTH exchange and signs over its own identity, and the tunnel comes up only
once every configured round has succeeded. A round is mode pre-shared-secret
or mode x509; an x509 round names its own certificate (local) or
ca-certificate (remote).
| Situation | What Ze does |
|---|---|
The peer asks for a round that second-round remote does not configure |
Refuses with AUTHENTICATION_FAILED |
second-round remote is set and the peer finishes without that round |
Refuses with AUTHENTICATION_FAILED, and the log names the leaf |
| The peer asks for a third round | Refuses with AUTHENTICATION_FAILED. Ze runs at most one extra round each way |
second-round local is set and the peer does not announce RFC 4739 support |
Completes with the first round alone, and logs one warning naming the leaf to remove |
Commit refuses a second round on a peer whose first round is an EAP method, a
round of mode pre-shared-secret with no secret, a local x509 round with no
certificate, and a remote x509 round with no ca-certificate. It also refuses a
local round with no id. The round asserts an identity of its own, and a peer
such as strongSwan picks the round's pre-shared key by that identity, so falling
back to the peer name would make it look up the first round's key.
hash-and-url applies to the first round only. A second-round certificate
always goes out inline, which every peer accepts.
Ze announces MULTIPLE_AUTH_SUPPORTED only to a peer that configures a second
round, so every other peer sees exactly what it saw before. When Ze verifies a
peer's second round it logs ike: second authentication round verified with
the peer and the identity that round proved.
One property comes with the RFC, and Ze does not change it: when the initiator authenticates more than once, the responder reveals its identity before all of the initiator's rounds have completed (RFC 4739 Section 5).
EAP method negotiation
The far end chooses the EAP method, and authentication { mode ... } sets the one
Ze runs. When the far end asks for a different authentication method, Ze answers
with an EAP Nak that names the configured method (RFC 3748 Section 5.3.1) rather
than ending the exchange. A concentrator that also runs that method then offers
it, and the tunnel establishes with no configuration change. A concentrator that
runs no other method ends the exchange, and Ze logs ike: EAP failed. Change
mode to a method both ends run.
The far end can also send an EAP Notification, which is how a concentrator
reports something such as an expiring password. Ze logs it as ike: EAP notification from the authenticator with the message, and the authentication
continues. The message is unauthenticated: it is chosen by whoever sent the
packet, so read it as a claim.
When Ze is the EAP server and the client refuses the offered method, the
ike: EAP authentication failed line names the types the client asked for and
the type Ze offered.
When Ze is the EAP-TLS client on TLS 1.3, it requires the RFC 9190 Section 2.5 protected success result indication before it accepts the EAP-Success. An authenticator that does not send it fails the peering, and the message names the authenticator, the negotiated version and two remedies: an authenticator that follows Section 2.5, or a peering on TLS 1.2, which RFC 5216 governs and where no indication exists. TLS 1.2 peerings are unaffected.
EAP MD5-Challenge
authentication { mode eap-md5 } runs EAP Type 4, the CHAP exchange of RFC 1994
carried inside EAP (RFC 3748 Section 5.4). Both ends read the pre-shared-secret
leaf as the CHAP secret. Ze runs it as the authenticator and as the peer.
It is discouraged, and the daemon says so. RFC 7296 Section 2.16: "EAP methods that do not establish a shared key SHOULD NOT be used, as they are subject to a number of man-in-the-middle attacks". The daemon writes one warning for each peer that carries the mode. It writes it when the configuration is applied, and not for each handshake.
What it costs you, against the two other EAP modes:
| Property | eap-md5 |
eap-mschapv2 and eap-tls |
|---|---|---|
| Key derivation | None. RFC 3748 Section 5.4 records "Key derivation: No" | An MSK of 64 octets |
| IKEv2 AUTH payloads | Keyed by SK_pi and SK_pr, which every party completing IKE_SA_INIT holds | Keyed by the EAP MSK |
| Who is authenticated by EAP | The client only | Both ends, for eap-tls |
| Secret at rest | The CHAP secret, needed in the clear on both ends | The same for eap-mschapv2; a private key for eap-tls |
The responder still authenticates itself with a public-key signature, because
RFC 7296 Section 2.16 requires one whichever EAP method runs. So eap-md5 needs
the same certificate and ca-certificate every other EAP mode needs. Select it
when the client runs no other method, and prefer eap-tls or eap-mschapv2
everywhere else.
EAP-TLS with TLS 1.3
RFC 9190 Section 2.5 requires an encrypted TLS record that carries application data
0x00. The EAP-TLS 1.3 server sends it once it has processed the client Finished and sent
its last handshake message. That record is the protected success result indication. Ze
sends it in the flight that round already carries, so the exchange keeps its round count.
The record is what makes a TLS 1.3 EAP-TLS client work. strongSwan derives no MSK without it, so the AUTH payload of RFC 7296 Section 2.16 cannot be computed and the SA never establishes. A TLS 1.2 exchange concludes with the bare EAP-Success it concluded with before, because the version test reads the negotiated version.
Ze issues a TLS session ticket on every EAP-TLS 1.3 authentication, because RFC 9190
Section 2.1.2 makes that a MUST with no condition on it. The ticket key belongs to the
peering rather than to the session, so a later authentication with the same peer can redeem
it. Whether Ze USES a ticket is the session-resumption leaf, which defaults to true and
covers both roles; with it false every authentication runs a full handshake and the ticket
still goes out. As the authenticator, Ze resumes TLS 1.3 sessions only: a peer that offers a
TLS 1.2 ticket gets a full handshake, because RFC 5216 Section 2.1.2 allows nothing but
change_cipher_spec and finished after a resuming TLS 1.2 server_hello, and the TLS library
adds a new ticket there. So a TLS 1.2 handshake runs with session tickets off: Ze issues no
TLS 1.2 ticket and redeems none, and its full-handshake server_hello carries a session_id Ze
chose rather than an empty one. A resumed authentication re-checks the cached chain against the current
ca-certificate and crl, so a certificate that was revoked or expired since the first
handshake is refused.
Ze caps the TLS version at 1.3 on both EAP-TLS roles. RFC 9190 Section 1 requires that cap, because EAP-TLS couples the TLS state machine to the EAP one and a version nobody integrated into the EAP half breaks the pair. Ze offers no setting that raises the cap. TLS 1.2 stays reachable under it, and an EAP-TLS peer that speaks only TLS 1.2 still authenticates with the RFC 5216 key derivation.
Ze puts the four-octet TLS Message Length only on the first fragment of a message it had to fragment. RFC 9190 Section 2.1.9 forbids the L bit on a message that fits in one EAP-TLS packet, so in a packet capture the TLS data of such a message starts one octet after the EAP Type, not five. Ze accepts an unfragmented message from the far end with the L bit or without it, which the same sentence requires.
Ze does not send local-id as the EAP-TLS identity
RFC 9190 Section 2.1.8 says that "a client supporting TLS 1.3 MUST NOT send its username (or
any other permanent identifiers) in cleartext in the Identity Response". So for
mode eap-tls Ze does not put local-id in the EAP-Response/Identity. It sends an anonymous
Network Access Identifier derived from it:
local-id |
EAP identity Ze sends | Why |
|---|---|---|
alice@example.com |
@example.com |
the username is omitted and the realm is kept, which is the form Section 2.1.8 recommends |
@example.com |
@example.com |
already anonymous |
ze-test-client |
anonymous |
✕ |
alice@localhost |
anonymous |
localhost is not a realm the RFC 7542 Section 2.2 grammar accepts |
The realm survives because it is what routes an EAP exchange to a home domain, and because
RFC 9190 Section 2.1.3 asks for the same realm again when a session resumes. Give local-id
a realm when the exchange has to route: an identity with none tells the far end nothing.
local-id is unchanged everywhere else. It is still IDi in IKE_AUTH, and the EAP-MSCHAPv2
and EAP MD5-Challenge methods still send it as their identity, because RFC 9190 governs
EAP-TLS alone and those methods carry their username inside the method exchange.
EAP-TLS 1.3 needs a certificate revocation list
RFC 9190 Section 5.4 says that "when EAP-TLS is used with TLS 1.3, the revocation status of all the certificates in the certificate chains MUST be checked (except the trust anchor)". Ze checks it on both roles: the authenticator over the client's chain, and the peer over the authenticator's chain.
The revocation lists come from the pki ca the peer validates against, in a crl
leaf-list. Each value is an X509 CRL PEM document or base64-encoded DER, and one CA can
hold several, which is what a segmented CRL or a rollover needs. A list this CA did not
sign is refused at commit, because it cannot answer for the certificates this CA issued.
pki {
ca my-ca {
certificate "-----BEGIN CERTIFICATE-----...";
crl "-----BEGIN X509 CRL-----...";
}
}
A CA with NO list and a list that revokes NOTHING are different answers, and the difference decides whether a session establishes:
| What the CA holds | TLS 1.3 | TLS 1.2 |
|---|---|---|
| A current list, and the chain is not on it | The session establishes | The session establishes |
| A current list naming a certificate on the chain | Ze refuses, naming the certificate, its serial number and the CA that withdrew it | The same |
| ✕ | Ze refuses: nothing can answer the question Section 5.4 makes mandatory | The session establishes |
A list whose nextUpdate has passed |
Ze refuses: an expired list says nothing about the present | The same |
The "no list at all" row is the only one where the two versions differ. TLS 1.2 is governed by RFC 5216 Section 5.4 instead, which asks only that an implementation "MUST support the use of Certificate Revocation Lists (CRLs)". Nothing there obliges a session the operator configured no list for, so a TLS 1.2 peer with no list still authenticates while the same peer on TLS 1.3 does not.
Every other row holds on both versions, because a list that IS configured is checked whatever was negotiated. An expired list is not a usable one, so it refuses on TLS 1.2 too: the operator asked for the check, and the source can no longer perform it.
Publish a fresh list before the nextUpdate of the one in the config passes. An expired
list refuses the same peers a missing one does.
EAP-TLS 1.3 staples the OCSP response you give it
RFC 9190 Section 5.4 says that "EAP-TLS servers supporting TLS 1.3 MUST implement
Certificate Status Requests (OCSP stapling)". Ze answers one with the response configured on
the certificate it presents, in an ocsp-response leaf beside that certificate:
pki {
certificate vpn-server {
certificate "-----BEGIN CERTIFICATE-----...";
ocsp-response "MIIBxAoBAKCB...";
private { key "..."; }
}
}
Fetch the value from the responder your CA publishes, with openssl ocsp -respout. Give it as
base64-encoded DER or as an OCSP RESPONSE PEM document. A response about another certificate
is refused at commit. A certificate with no response answers a Certificate Status Request with
no status, which RFC 6066 Section 8 permits, and the peer then falls back to the crl of the
CA that issued it.
An OCSP response carries a nextUpdate, and a peer that checks the status refuses the
certificate once that time passes. Replace the value before it does, the same discipline a
crl needs.
An EAP-TLS peer can require the stapled status
RFC 9190 Section 5.4 puts a MUST on a peer that uses Certificate Status Requests to check a
chain: "it MUST treat a CertificateEntry (but not the trust anchor) without a valid
CertificateStatus extension as invalid and abort the handshake with an appropriate alert". The
certificate-status-request leaf makes Ze such a peer, and it is false by default:
ipsec {
peer headquarters {
authentication {
mode eap-tls;
certificate-status-request true;
}
}
}
| What the authenticator staples | certificate-status-request true |
certificate-status-request false |
|---|---|---|
| A current response saying the certificate is good | The session establishes | The session establishes |
| Nothing | Ze refuses, naming the missing CertificateStatus | The session establishes |
| A response reporting the certificate revoked or unknown | Ze refuses, naming what the responder said | The session establishes |
A response whose nextUpdate has passed, or one about another certificate |
Ze refuses, naming which | The session establishes |
With the leaf false the chain is still checked against the crl of its CA, which Section 5.4
requires on TLS 1.3 either way.
One deployment limit comes with the leaf. Ze reads the stapled status of the LEAF certificate
and of no other, because Go's TLS stack parses the status extension of the first
CertificateEntry alone. Section 5.4 makes an entry whose status is not valid invalid, and an
entry Ze cannot read the status of is one it cannot call valid, so a chain carrying an
intermediate CA below the trust anchor is refused while the leaf is on. Give the authenticator
a certificate its trust anchor signed directly, or leave the leaf off and check by crl.
An EAP-TLS peer re-checks the server certificate once the tunnel is up
RFC 9190 Section 5.4 asks an EAP-TLS peer to "support checking for certificate revocation after authentication completes and network connectivity is available", and to "use a secure transport" for it. RFC 5216 Section 5.4 asks for the same with no TLS version attached.
Ze runs that check as soon as the Child SA is installed, which is the moment the tunnel it just authenticated gives it a network. It asks the OCSP responder named by the authenticator's own certificate, over https, and it needs no configuration: the responder URL comes from the certificate's authority information access extension.
| What the responder says | What Ze does |
|---|---|
| The certificate is revoked | Closes the SA and logs the revocation. The reconnect that follows runs a fresh authentication, which the same certificate fails inside the handshake |
| The certificate is good | Logs it and leaves the SA up |
| Nothing, because it cannot be reached | Logs a warning and leaves the SA up. A responder outage is not evidence of a revocation |
| Nothing, because the certificate names an http responder or none at all | The same warning. Section 5.4 requires a secure transport, so an http responder is refused before any connection opens |
The check runs once per authentication rather than on a timer, and it never delays the tunnel: the Child SA is up before it starts.
EAP-TLS with TLS 1.2 needs RFC 7627
RFC 5216 Section 2.3 derives the EAP-TLS MSK from a TLS key material export, and Go refuses that export on a TLS 1.2 session that did not negotiate the RFC 7627 extended master secret. Ze cannot authenticate such a peer. It says so rather than failing silently: the log line names the peer, the negotiated version, RFC 7627 and the answers below.
strongSwan 6.1.0, the lab's peer, is such a peer, by default rather than by limitation.
src/libtls/tls.c sets the maximum to TLS 1.2 when charon.tls.version_max is unset,
with the comment "default to TLS 1.2 until 1.3 is stable for use in EAP", and the
generated strongswan.d/charon.conf documents it as # version_max = 1.2. Its libtls
implements no extended master secret: the extension appears only as a name in its
extension table. Set charon.tls.version_max = 1.3 and the same build reaches an
established SA, which is what test/interop-ipsec/scenarios/eap-tls13 runs.
| Answer | What to change |
|---|---|
| Move the peer to TLS 1.3 | RFC 9190 covers EAP-TLS over TLS 1.3, and the export is unconditional there. This is the preferred answer, and on strongSwan it is one line: charon.tls.version_max = 1.3 |
| Add RFC 7627 to the peer's TLS 1.2 stack | The export then works, and ze needs no change |
| Configure another EAP method | EAP-MSCHAPv2 derives its key without a TLS export |
Ze offers no setting that lifts the refusal, and there is nothing to add to the
environment. Go 1.27 removed the tlsunsafeekm GODEBUG setting that once lifted it. A
removed setting carrying its old value is a fatal error that the Go runtime raises before
the daemon starts, so setting it stops ze rather than reaching the peer.
Denial-of-service protection
RFC 7296 Section 2.6 names two attacks on an IKE responder: state and CPU exhaustion from initiation requests with forged source addresses. The answer is a COOKIE. Ze answers an inbound IKE_SA_INIT with a COOKIE notification and commits no state, and the initiator must repeat its request with that cookie as the first payload before Ze creates an SA or takes the peer's half-open handshake slot.
cookie-threshold sets how many half-open IKE SAs Ze tolerates before it challenges.
It defaults to 0, which challenges every inbound initiation. That default costs a
genuine peer one extra round trip and closes a real availability hole: a responder peer
has one half-open slot, held for 30 seconds, so a single spoofed datagram bearing that
peer's source address would otherwise deny it service, and one datagram every 30 seconds
would deny it indefinitely. Raise the value to tolerate that many half-open handshakes
before challenging.
vpn {
ipsec {
cookie-threshold 0;
}
}
The cookie is an HMAC-SHA256 over the initiator's nonce, its source address and its SPI, under a secret Ze generates and rotates every 60 seconds. A cookie minted under the previous secret stays valid for one further interval, so a rotation never breaks an in-flight handshake. A cookie that does not match is ignored rather than rejected, as the RFC requires: the message is processed as though it carried no cookie, which for a pressured responder means issuing a fresh challenge.
Diffie-Hellman group correction
An initiator has to guess which Diffie-Hellman group the responder will pick. When the guess is wrong the responder answers INVALID_KE_PAYLOAD naming the group it accepts, and Ze retries the IKE_SA_INIT under that group. Without this, Ze could never establish with a peer that prefers a different group.
The retry re-offers the whole configured proposal set rather than narrowing it to the suite carrying the responder's group. RFC 7296 Section 1.2 requires that, because the rejection is unauthenticated and a narrowed re-offer would let an attacker who forges one notify choose the cipher. Ze also refuses a group it never proposed, which stops the same attacker choosing the group. Both COOKIE and INVALID_KE_PAYLOAD retries share one budget of three per connection attempt, so two peers can never oscillate between them.
Rekeying
Both Child SAs and IKE SAs are rekeyed with an on-wire CREATE_CHILD_SA exchange. This replaced an earlier local-only key roll that could silently desynchronise a live tunnel. A Child SA rekey carries N(REKEY_SA) with fresh nonces and traffic selectors. An IKE SA rekey performs a fresh Diffie-Hellman exchange and resets the message-ID counters.
Rekeying is make-before-break: the replacement SA is installed before the old one is deleted, so forwarding does not pause. Simultaneous rekeys are resolved by the RFC 7296 nonce rule. Section 2.8.1 states it as a recommendation: if redundant SAs are created, the endpoint that created the SA with the lowest of the four nonces SHOULD close that SA. Ze resolves the collision one step earlier and abandons its own pending exchange when its nonce is the lower one, so the redundant SA is never created and both ends converge on one SA. Ze rekeys at the ESP or IKE soft lifetime and retransmits a lost CREATE_CHILD_SA before tearing the tunnel down. Rekeys are counted by ze_ipsec_rekey_total{peer} and streamed as child-rekey events by monitor vpn ipsec.
Child SA and dataplane
Child SAs define traffic selectors and the ESP proposal. Ze programs XFRM policies and states through netlink. Route-based IPsec uses XFRM interfaces.
| Feature | Detail |
|---|---|
| ESP proposals | AES-GCM-16 128/256 and AES-CBC with HMAC-SHA-256/384/512 |
| Traffic selectors | IPv4 and IPv6 CIDR prefixes, an optional IP protocol, and an optional single port. See Traffic selectors and narrowing below |
| Encapsulation | Tunnel mode by default; mode transport negotiates transport mode per RFC 7296 Section 1.3.1 |
| Connection | connection-type initiate starts the exchange; connection-type respond waits for the peer |
| Replay protection | Anti-replay window, default 64, the size RFC 4303 Section 3.4.3 says SHOULD be the default |
| Lifetime | Time-based rekeying, from the ESP group's lifetime in seconds. Ze carries no byte lifetime, so RFC 4301 Section 4.4.2.1's simultaneous use of both is not met |
| Policy order | policy-priority ranks this peer's SPD entries, lower first. See SPD ordering below |
| DF bit | df-bit copy (default), clear or set: what the tunnel header carries in its DF bit. See DF bit of the tunnel header below |
| Tunnel DSCP | dscp-map copy (default) or a value 0 to 63 for every tunnel header. See DSCP of the tunnel header below |
| ICMP errors | icmp-error-check true (default) or false: whether an ICMP error a Child SA carries has its payload checked. enable and disable are accepted too, and ze config fmt and show print the value that way. See ICMP error messages below |
SPD ordering
RFC 4301 Section 4.4.1 makes the Security Policy Database an ordered database, because entries with range selectors overlap: "Thus, a user or administrator MUST be able to order the entries to express a desired access control policy."
policy-priority under a peer is that order. A LOWER value is searched FIRST,
in Ze and in the Linux kernel. Two peers configured with overlapping remote
prefixes describe the same traffic, so give the one that must win the lower
value. Two tunnels that overlap at one value are not ordered at all, so Ze
refuses the second peer's Child SA rather than let arrival order pick the tunnel
(RFC 3948 Section 5.1, see the inner-address paragraphs above).
The default is 2000, which every peer took before the leaf existed. The range starts at 101 because 100 holds the IKE control-plane bypass. A peer entry at or above that rank matches the IKE datagrams first, which hands the exchange that builds and rekeys the SA to the SA itself, and the tunnel could then never renegotiate. Ze refuses such a value at commit.
ICMP error messages
An ICMP error reports a packet, and its own headers name the router that sent it, not the flow the packet belonged to. RFC 4301 Section 6.2 therefore asks for two things. An error that arrives on a Child SA with headers its selectors do not cover is checked against the header it carries: "the receiver must extract the header of the triggering packet from the ICMP payload, and reverse fields as described above to determine if the packet is consistent with the selectors for the SA via which the ICMP error message was received." And an outbound error that no SA and no SPD entry would carry goes to "the SA that would carry the return traffic associated with the packet that triggered the ICMP error message."
By default Ze does both:
- an ICMP error addressed to Ze that arrives on a Child SA is delivered only when its embedded header, with source and destination addresses and ports reversed, falls inside the selectors of the SA it arrived on. Otherwise it is dropped.
- an ICMP error Ze generates about a packet of a tunnelled flow is sent through the Child SA that carries the return traffic of that packet.
To turn both off for a peer:
set vpn ipsec site-to-site peer branch icmp-error-check false
An ICMP error is then carried only where a traffic selector or a vpn ipsec policy entry covers its own headers, and every other one is dropped unread.
RFC 4301 Section 6.2 allows this as the way to carry ICMP errors without
inspecting their payload, by configuring an entry that explicitly carries
them.
A forwarded ICMP error, one Ze routes between two other hosts, is a different
case on Linux. One that arrives on a Child SA with headers the selectors do not
cover is dropped whatever the leaf says, because the kernel reads its payload
only when no forward policy matches it, and Ze's catch-all always does. One
leaving towards a Child SA is mapped to the return SA under unmatched bypass, and dropped under unmatched discard, where the catch-all blocks it
before the mapping runs. LL-XFRM-ICMP-TRANSIT in
Linux limitations has the kernel
functions.
Linux also maps an error that a bypass entry would carry in clear. Section 6.2
maps an outbound error to the return SA only "if no SPD entry would allow
carriage of this outbound ICMP error message", but the kernel cannot tell a
bypass entry from no entry: whenever the lookup on the error's own headers
finds no Child SA, it sends the error through the SA that carries the return
traffic. So with a vpn ipsec policy bypass entry that covers ICMP errors
towards hosts behind a peer, or with unmatched bypass, an error about a
tunnelled packet would go into the tunnel rather than out in clear.
Commit refuses that pair rather than installing an entry the kernel does not
honour. A peer whose icmp-error-check is true is refused beside
unmatched bypass, and beside a bypass entry that is out or both, has
protocol 0 or the ICMP protocol of its family, has icmp-type any or an ICMP
error type (IPv4 3, 4, 5, 11 and 12; IPv6 1, 2, 3 and 4, the types Linux 7.3
sends through its return-SA lookup, listed with their kernel callers in
icmp_overlap.go), and has a remote prefix that overlaps the peer's remote
traffic selectors. A peer with no traffic selector accepts any selector, so
every such entry overlaps it. The refusal is conservative about the entry's
local prefix and its order, and looks at neither. The kernel picks the address
an error leaves from, so no commit can know it. An entry ranked below the
peer's own policy is overridden for every error whose address falls outside
the peer's local selectors. A protocol 0 entry ranked above it may not be
overridden for every error, but it is overridden for some, so it is refused
too.
A route-based peer (vti bind) is exempt. Its Child SA policies carry the
xfrm interface's if_id, and the kernel's return-SA lookup only looks at
policies whose if_id is 0 (xfrm_lookup in net/xfrm/xfrm_policy.c), so it
never maps an error into that peer's tunnel. ICMP that arrives on the
interface is checked against that if_id too (xfrmi_decode_session), where
no vpn ipsec policy entry applies.
The refusal names the peer and the entry, and one of these fixes it:
set vpn ipsec site-to-site peer branch icmp-error-check false
set vpn ipsec unmatched discard
For an entry, the refusal prints the exact command: set vpn ipsec policy <name> remote prefix <prefix> with a prefix that does not overlap the peer's
remote selectors, which it lists (not offered when a remote selector covers a
whole family, as a peer with no selector does), then
set vpn ipsec policy <name> icmp-type <type> with a type that is not an
error, such as 8, for a protocol 1 or 58 entry, or set vpn ipsec policy <name> protocol <protocol> for a protocol 0 entry.
ze config validate refuses the same configuration, because the check is part
of the IPsec plugin's offline verifier. A configuration the daemon starts with
is not verified, so the same conflict is logged at start at Error level and
reported by ze doctor under config-plugin-verify.
The VPP dataplane performs neither check. VPP is reached only through the test
override ze.test.ike.dataplane, and there commit refuses a peer whose
icmp-error-check is true (the default, which keeps the RFC 4301 Section 6.2
processing on Linux), naming icmp-error-check false as the fix.
DF bit of the tunnel header
RFC 4301 Section 8.1 makes the DF treatment of each tunnel-mode SA
configurable: "set, clear, copy from inner header". df-bit under a peer is
that setting, for the IPv4 tunnel header the peer's outbound Child SAs build.
vpn {
ipsec {
site-to-site {
peer branch {
remote-address 198.51.100.1;
df-bit clear;
}
}
}
}
| Value | Tunnel header DF bit | Linux | VPP |
|---|---|---|---|
copy (default) |
the inner IPv4 header's DF bit | ✓ | ✓ |
clear |
always clear, so a router on the path may fragment the tunnel packet | ✓ | ✓ |
set |
always set | refused at commit | refused at commit |
clear is for a path that drops large tunnel packets and never returns
Fragmentation Needed: the routers fragment instead, and the far end reassembles.
Commit refuses clear or set on a mode transport peer, which builds no
tunnel header, and on a peer whose local-address or remote-address is IPv6,
whose header has no DF bit. set is refused on every dataplane today: the Linux
kernel copies or clears the bit and has no flag that sets it, and VPP's ESP path
ignores its set flag. Changing df-bit restarts the peer.
DSCP of the tunnel header
RFC 4301 Section 5.1.2.1 copies the inner DSCP into the tunnel header, and says
that when the packet "will immediately enter a domain for which the DSCP value
in the outer header is not appropriate, that value MUST be mapped to an
appropriate value for the domain". dscp-map under a peer is that mapping:
copy (the default), or one value 0 to 63 written into every tunnel header.
| Value | Linux | VPP |
|---|---|---|
copy |
✓ | ✓ |
0 |
✓ | ✓ |
1 to 63 |
refused at commit: the kernel can only copy or write 0 | ✓ |
Commit refuses a value on a mode transport peer. Changing dscp-map
restarts the peer.
Path MTU of a tunnel
On Linux the path MTU of a tunnel-mode SA is the path MTU of its outer route. When a router on the way between the tunnel endpoints sends back an ICMP Fragmentation Needed or Packet Too Big about an ESP packet, the kernel finds the SA from the SPI in the quoted packet, lowers the outer route's PMTU, and takes the ESP header, IV, ICV, padding and outer IP header off it to give the inner MTU (RFC 4301 Section 8.2.1). A packet larger than that inner MTU is then handled as Section 8.2.1 says:
| Packet | What happens |
|---|---|
| IPv4 with DF set | dropped, and the sender gets an ICMP Fragmentation Needed carrying the inner MTU |
| IPv4 with DF clear | encrypted, then the ESP packet is fragmented and forwarded; no ICMP |
| IPv6 | dropped, and the sender gets a Packet Too Big carrying the inner MTU |
With the default df-bit copy the tunnel header carries the inner packet's DF
bit, so the routers return Fragmentation Needed and the PMTU is learned. With
df-bit clear an IPv4 tunnel header always carries DF clear, so the routers
fragment the tunnel packets, return nothing, and no PMTU is learned from them.
The SA's PMTU is then the MTU of the outer route: the first-hop link's, or a
PMTU other traffic to the same tunnel endpoint learned, which ages as below.
The table above still holds against that MTU, and a tunnel packet larger than
a link further on is fragmented by that router and reassembled by the far end.
The kernel also clears the DF bit of every IPv4 outbound SA when
net.ipv4.ip_no_pmtu_disc is set, whatever df-bit says, and show vpn ipsec dataplane sa then reads df-bit clear. ze doctor reports it as
doctor-ipsec-no-pmtu-disc, naming each IPv4 df-bit copy peer it affects and
the fix, set sysctl setting net.ipv4.ip_no_pmtu_disc value 0.
A learned PMTU expires: after the aging period the SA's PMTU returns to the MTU of the first-hop link, and the next large packet finds the path MTU again (RFC 4301 Section 8.2.2, the RFC 1191 Section 6.3 reset). The period is the kernel's route PMTU expiry, 600 seconds by default, one value per address family of the tunnel endpoints, set like any other kernel tunable:
sysctl {
setting net.ipv4.route.mtu_expires {
value 300;
}
setting net.ipv6.route.mtu_expires {
value 300;
}
}
Commit refuses a period below 1 second or above 2147483. The period applies to every PMTU the box learns, not only IPsec ones, and a PMTU already learned keeps the period it was learned with.
The VPP dataplane learns no PMTU: VPP takes no action on an ICMP
Fragmentation Needed or Packet Too Big about an ESP packet, and its only path
MTU is a value configured per destination (ip path-mtu), which never ages.
Over VPP the SA's PMTU is the MTU of the outgoing interface.
Security Policy Database entries
RFC 4301 Section 4.4.1 gives the Security Policy Database three dispositions: "PROTECT, BYPASS, or DISCARD". A site-to-site peer produces the PROTECT entries, because a protect entry names an ESP transform and a peer to negotiate keys with. The other two name neither, so no negotiation can produce them and they are written directly:
set vpn ipsec policy drop-guest action discard
set vpn ipsec policy drop-guest local prefix 10.0.0.0/24
set vpn ipsec policy drop-guest remote prefix 192.168.99.0/24
set vpn ipsec policy drop-guest order 800
Section 7.4 makes the discard disposition an obligation: "All implementations MUST support DISCARDing of fragments using the normal SPD packet classification mechanisms." The list above is the management interface Section 4.4.1 requires for it.
| Leaf | Values | Default | Meaning |
|---|---|---|---|
action |
bypass, discard |
none, required | What the entry does with matching traffic |
order |
101 to 2147483647 | 1000 | Rank, lowest searched first |
direction |
out, in, both |
both |
Which half of the database the entry joins |
protocol |
0 to 255 | 0 (any) | Next-layer protocol selector |
local prefix |
CIDR | none, required | Ze's own side of the boundary |
local port |
1 to 65535, or any |
any |
Local port selector |
remote prefix |
CIDR | none, required | The far side of the boundary |
remote port |
1 to 65535, or any |
any |
Remote port selector |
icmp-type |
0 to 255, or any |
any |
ICMP message type, under protocol 1 or 58 |
icmp-code |
0 to 255, start-end, or any |
any |
ICMP code or inclusive code range, under one icmp-type |
both installs a mirrored pair, one entry in each direction: the outbound entry
keeps local and remote as written, and the inbound entry swaps them, because the
local side of a flow is the destination of an inbound packet.
The default order of 1000 sits between the IKE control-plane bypass at 100 and a
peer's default rank of 2000, so an entry written with no order outranks the
tunnels and carves its hole out of them. Raise it above 2000 to let a tunnel
win instead. An order at or below 100 is refused at commit, for the reason
policy-priority states above.
These rules are refused at commit rather than approximated at install time, because a widened selector fails in both directions: a widened bypass passes protected traffic in the clear, and a widened discard black-holes traffic the operator meant to carry.
- Both prefixes are required, and they must share an address family. One kernel policy selector carries one family.
- A port other than
anyneedsprotocolto name a transport that has ports: 6 (TCP), 17 (UDP) or 132 (SCTP). - A port range is not accepted. An entry installs one selector, and the kernel selector carries a port and a mask, which expresses a block aligned on a power of two but not an arbitrary range; Ze does not split one entry into several.
actionhas no default. A bypass written where a discard was meant passes exactly the traffic the entry exists to stop.icmp-typeandicmp-codeneedprotocol1 (ICMP) or 58 (ICMPv6), andicmp-codeneeds anicmp-type. RFC 4301 Section 4.4.1.1 allows "a single type and a range of codes, a single type and ANY code, and ANY type and ANY code", and nothing else.- An
outorbothentry withicmp-type 0and anicmp-codethat includes 0 (any,0, or a range starting at 0) is refused. Linux reads no ICMP type or code from an IP fragment, so the kernel classifies every fragment as type 0 code 0, and it classifies forwarded traffic before reassembling it. The outbound half of such an entry would also pass in the clear, or drop, every forwarded ICMP fragment between its prefixes, whatever message it belongs to: the hazard RFC 4301 Section 7.4 names for a bypass. Write it withdirection in, because traffic for Ze itself is reassembled before it is classified, or with anicmp-coderange that starts at 1.
ICMP type and code selectors
The kernel reads an ICMP message's type into the selector's source port and its
code into the destination port, and matches each under a mask. Ze installs a
type as one exact match, and a code range as the fewest mask-aligned blocks that
cover exactly that range, one kernel policy per block, added and removed
together. RFC 4301 Section 4.4.1.1 requires the test
(T-start*256) + C-start <= (t*256) + c <= (T-end*256) + C-end, and no code
outside the range matches. An ICMP message has one type whichever way it
travels, so a both entry installs the same type and code in each direction.
The same entries are the ICMP controls of RFC 4301 Section 6.1. Section 6.1.1
requires that an administrator can "accept or reject unauthenticated ICMP
traffic", at the granularity of ICMP type. An in entry with discard rejects
one type arriving at Ze, and with bypass accepts it. The Linux kernel checks
every ICMP message delivered to Ze against the inbound policies before it
processes it (icmp_rcv, net/ipv4/icmp.c, and its IPv6 counterpart):
set vpn ipsec policy no-redirect action discard
set vpn ipsec policy no-redirect direction in
set vpn ipsec policy no-redirect protocol 1
set vpn ipsec policy no-redirect icmp-type 5
set vpn ipsec policy no-redirect local prefix 0.0.0.0/0
set vpn ipsec policy no-redirect remote prefix 0.0.0.0/0
Section 6.1.2 asks for controls over ICMP error messages "received on the
protected side of the boundary, and directed to the IPsec implementation". Write
the same kind of in entry with the protected-side subnet as the remote prefix,
for example remote prefix 10.1.0.0/16 and icmp-type 3 to refuse Destination
Unreachable from the hosts behind Ze. Those hosts send in the clear, so the
entry decides every such message.
An ICMP message that arrives on a Child SA is decided by that SA's peer. When
the peer's icmp-error-check is true (the default) and an in discard entry
refuses the message, Linux reads the header the message carries after its ICMP
header, reverses its addresses and ports, and delivers the message when that
header matches the SA it arrived on. The type plays no part: the kernel does not
check that the message is an error, so a message of any type whose following
bytes read as such a header would be admitted, whatever the discard entry
says. With icmp-error-check false on that peer, the entry decides. icmp_rcv
(net/ipv4/icmp.c) and icmpv6_rcv (net/ipv6/icmp.c) make this check when
the last state that decrypted the message carries XFRM_STATE_ICMP, the flag
icmp-error-check true sets; LL-XFRM-ICMP-TRANSIT in
Linux limitations records it.
For an ICMP error forwarded to a protected host, Linux can search the reversed
quoted header before applying the final forwarding disposition. Ze uses the
namespace's XFRM forwarding default for unmatched, rather than a forwarding
catch-all that would hide that lookup. The Child SA's forwarding PROTECT
entries remain in force, including on an XFRM interface. With the check enabled,
a consistent quoted header can select that SA's policy; an inconsistent one is
dropped. Disabling the check requires the error's own headers to be allowed by
the SA's selectors and receive policy. It does not authorize an error outside
them. Ze preserves the namespace's inbound and outbound default dispositions
and restores the previous forwarding default when its SPD is released. Another
XFRM policy manager must coordinate default-policy writes with Ze; an observed
external change refuses a reload or restoration rather than being overwritten.
The diagnostic code doctor-ipsec-forward-default reports a missing host
permission, an unreadable default, a conflicting policy manager, or a restoration
that has not completed. Its finding names the next command. A shutdown failure
also remains in the warning log when the daemon connection has already closed.
So commit refuses a discard entry that is in or both, has protocol 0 or
the ICMP protocol of its family, any icmp-type, and a family the selectors of
a peer with icmp-error-check true can carry. Its prefixes and its order do
not matter, because the kernel's second check reads neither the message's own
source nor the address it arrived at. A peer with vti bind is exempt: ICMP
that arrives on its xfrm interface is checked at the interface's if_id,
where no vpn ipsec policy entry applies. The refusal names the peer and the
entry; set icmp-error-check false on the peer, or delete the entry. The
unmatched discard catch-all is not refused: delivering an error whose
payload matches the SA is the Section 6.2 processing itself.
These entries install inbound and outbound policies only. ICMP that Ze forwards between two other hosts is decided by the Child SA forward policies and the catch-all entry below; an operator entry does not reach it yet.
The VPP dataplane compares ports only for TCP, UDP and SCTP, so an ICMP type entry there would match every ICMP message. Ze refuses such an entry on VPP with a message naming the reason, rather than installing it wider than written.
A tunnel can negotiate an ICMP selector too. IKE carries the type in the high eight bits of the port and the code in the low eight; Ze programs the type and code from the sending side's value in each direction.
On Linux a discard entry is an XFRM policy with action block and a bypass is
allow with no template. On VPP they are IPSEC_API_SPD_ACTION_DISCARD and
IPSEC_API_SPD_ACTION_BYPASS. show vpn ipsec dataplane reports the
disposition of every installed policy, including one another daemon installed.
Ze installs these entries when the configuration is applied and removes them when the entry leaves the configuration or the engine stops. They need no peer, no key and no negotiation, so they are in force whether or not any tunnel is up.
The catch-all entry
RFC 4301 Section 5: "If no policy is found in the SPD that matches a packet (for either inbound or outbound traffic), the packet MUST be discarded." The Linux kernel does the opposite with no matching policy: it passes the packet in the clear. Ze installs last IN and OUT entries for IPv4 and IPv6 at the largest priority the kernel holds, so every entry above is searched first. Forwarding uses the namespace's XFRM default disposition, after ordinary policies and the ICMP quoted-header lookup. Its disposition is one leaf:
set vpn ipsec unmatched discard
| Value | Meaning |
|---|---|
discard (default) |
Traffic no entry matches is dropped, the disposition Section 5 names |
bypass |
Traffic no entry matches crosses the boundary in the clear, which is what the kernel did before the entry existed |
The default is discard, the entry RFC 4301 Section 4.4.1 asks for: "Every
SPD SHOULD have a nominal, final entry that matches anything that is otherwise
unmatched, and discards it." Until 2026-10-18 the default was bypass; the
owner reversed that ruling (R27) to follow the RFC.
The catch-all also drops the router's own traffic wherever it crosses in the clear:
- BGP sessions, SSH and web logins, DNS and NTP.
- ICMP: ping, traceroute, the probes of
show mtu, and the path-MTU errors ("fragmentation needed", "packet too big") that tell the router to send smaller packets. - IPv6 neighbor discovery. It is ICMPv6 (protocol 58), and the catch-all matches every protocol, so with no bypass the router cannot resolve an IPv6 neighbor on a link and sends it nothing.
Only IKE (UDP 500 and 4500, the control-plane bypass at order 100), the
negotiated tunnels and your policy entries stay open. So write a bypass
entry under policy for every flow that must still cross in the clear, for
example a BGP neighbor:
set vpn ipsec policy frr-bgp action bypass
set vpn ipsec policy frr-bgp local prefix 172.28.0.2/32
set vpn ipsec policy frr-bgp remote prefix 172.28.0.4/32
and ICMP for both address families, which keeps ping, traceroute, show mtu,
path-MTU errors and IPv6 neighbor discovery working:
set vpn ipsec policy icmp4 action bypass
set vpn ipsec policy icmp4 protocol 1
set vpn ipsec policy icmp4 order 3000
set vpn ipsec policy icmp4 local prefix 0.0.0.0/0
set vpn ipsec policy icmp4 remote prefix 0.0.0.0/0
set vpn ipsec policy icmp6 action bypass
set vpn ipsec policy icmp6 protocol 58
set vpn ipsec policy icmp6 order 3000
set vpn ipsec policy icmp6 local prefix ::/0
set vpn ipsec policy icmp6 remote prefix ::/0
Order 3000 ranks these entries after a tunnel's default 2000, so ICMP that a
tunnel's traffic selectors cover still goes through the tunnel. These entries
carry ICMP errors in clear, so commit refuses them beside a site-to-site peer
whose icmp-error-check is true and that has no vti bind (see ICMP error
messages above): set icmp-error-check false on each such peer, and the
entries then decide where an error goes. The refusal and the start-up log below print the same ICMP
example.
Or write set vpn ipsec unmatched bypass to pass all of that traffic, with
the same icmp-error-check false on each site-to-site peer that has no
vti bind.
Ze cannot list those flows for you: they live in every other part of the
configuration and in the routing table, and an exemption list that missed one
would cut it with nobody told. Instead, a commit that would turn the discard on
while unmatched is unset is refused, so nobody configuring vpn ipsec over
SSH cuts their own session by default:
ike config: this commit turns on the SPD catch-all DISCARD without saying so: `vpn ipsec unmatched` is not set and its default is discard (RFC 4301 Section 4.4.1). ...
The refusal names what stays open, including how many policy bypass entries
you have, and the two commands that settle it: add the bypass entries, then
set vpn ipsec unmatched discard; or set vpn ipsec unmatched bypass. It
fires only when the commit would turn the discard on: a written unmatched
leaf, either value, always passes, and so does a commit to a box whose catch-all
already discards.
The check runs on commit only. A configuration the daemon starts with is not
verified, and start-up reads unmatched as the file states it: unset means
discard, the default, with the error log below, whichever release saved the
file. Write unmatched bypass into a file to keep passing unmatched traffic,
and unmatched discard to say the discard is meant.
When the daemon starts with the discard in force by default, it logs it at error level, with the same facts and commands as the refusal, so the console says why BGP or SSH went quiet:
ike: the SPD catch-all DISCARD is in force because `vpn ipsec unmatched` is not set and its default is discard (RFC 4301 Section 4.4.1): ... bypass-entries=0 code=doctor-ipsec-implicit-discard
ze doctor reports the same state for as long as it lasts, as the error
doctor-ipsec-implicit-discard with the same text, and names
set vpn ipsec unmatched discard as the fix that confirms the default.
A box with no vpn ipsec block keeps a bypass catch-all: it configured no
IPsec boundary.
The IKE control-plane bypass at order 100 is installed either way, so the
tunnels can still be negotiated. Ze's entries appear together on the first
apply, the catch-all first and the IKE bypass right after it, before any IKE
socket opens. The catch-all is re-asserted on every apply. When the engine
stops, every tunnel is torn down first, then the IKE bypass and your policy
entries are removed, and the catch-all goes last, so no Ze entry is ever in
force without it. If any of those entries cannot be removed, the catch-all
stays installed beneath it, and the daemon logs a warning naming each entry
left as the command that removes it in the dataplane's own tool. On the Linux
kernel that is the exact ip xfrm policy delete command: direction, prefixes,
protocol, ports and if_id, so two entries that differ only by port get two
different commands. On VPP it is the vppctl ipsec policy del command for the
entry VPP holds.
When the entry is not there
A catch-all that is not installed leaves a packet no entry matches meeting no
entry at all, which RFC 4301 Section 5.2 forbids ("If there is no match,
discard the traffic"), so Ze never reports such a configuration as applied,
whichever value unmatched holds. The one exception is the VPP backend:
| Situation | discard |
bypass |
|---|---|---|
| The VPP backend, which holds no entry bound to no interface | Refused at commit. A configuration the daemon starts with is not verified, so a start with unmatched unset (or discard) fails instead: installing the discard entry fails, and the configure step returns that error. Fix: set vpn ipsec unmatched bypass in the configuration file, then start again |
Accepted; no entry is installed, and the traffic crosses in the clear. This is an open RFC 4301 gap on VPP |
| A build off Linux, or a kernel without XFRM | Refused at commit, and a start fails as in the row above | The apply fails: a commit is refused, and at startup the configure step returns the error. Fix: run Ze on a Linux kernel with XFRM (CONFIG_XFRM_USER) |
| ✕ | Refused at commit | The apply fails. Fix: the cause the daemon logged |
The install itself fails when the configuration is applied, which includes a daemon without CAP_NET_ADMIN: it can open the XFRM socket, so the commit check passes, and the kernel refuses the install |
The apply fails with the error, and the configuration is not reported applied: a commit is refused, and at startup the configure step returns the error | Same as discard. Fix: give the daemon CAP_NET_ADMIN |
| Before the first configuration is applied, and after the engine stops | The IPsec engine holds no SPD entry and no SA, so it is not acting as an IPsec implementation and no packet is looked up in an SPD of its own; the kernel passes traffic as it does with no IPsec configured. Two exceptions: an entry the engine could not remove on stop keeps the catch-all beneath it (the warning names both), and OSPFv3 authentication with manual keys installs its own SAs and policies with no catch-all, an open RFC 4301 gap | Same |
The catch-all is installed before the policy entries, the peers and the
cookie threshold of the same configuration, so a refused apply leaves the
previous entries and threshold in place.
That order has a cost with discard. Between the catch-all install and the
install of your bypass entries, traffic those entries are meant to pass
matches only the catch-all and is dropped. This happens on the first apply,
and on every reload that adds or changes a bypass entry, for the flows that
entry covers (a changed entry is removed and installed again). An entry the
reload leaves unchanged stays installed throughout. The window lasts as long as the apply takes to install the policy
entries. When you first turn discard on, commit the bypass entries while
unmatched is still bypass, then set unmatched discard in a later commit:
the entries are then already installed when the catch-all starts dropping. A
bypass entry added or changed once discard is in force always crosses the
window.
Route-based tunnels under discard
The Linux kernel keeps one policy database for each XFRM if_id. The
catch-all lives at if_id 0, and a peer with vti bind installs its Child SA
policies at the if_id of that XFRM interface. A packet routed into the
interface is looked up at if_id 0 first, and only reaches the interface's own
policies once it gets there. Under discard it would meet the catch-all on
the way and be dropped. So for every XFRM interface a peer binds, Ze installs
bypass entries at if_id 0, ranked just above the catch-all and below every
policy entry and every Child SA policy:
| Entry | Matches | Why |
|---|---|---|
| out and fwd, IPv4 and IPv6 | any address, output device the XFRM interface | Forwarded traffic, and the router's own IPv4 traffic, carry the output device into the lookup |
| out, IPv6 | source each IPv6 address the XFRM interface holds, any destination | The router's own IPv6 traffic is looked up before the kernel records the output device |
None of these is installed under unmatched bypass, since the catch-all already
passes the traffic.
Each bound XFRM interface's own database also gets final discard entries in
IN and OUT for IPv4 and IPv6 at the interface's if_id, ranked last, so
the interface's Child SA policies are always searched first. A packet routed
into the interface that no Child SA covers is dropped there and counted by the
kernel's XfrmOutPolBlock counter. This entry discards under both values of
unmatched: an XFRM interface has no path in the clear, because the kernel
drops a packet there that matches no Child SA whatever entry it meets, so a
bypass at the interface would only be listed as one. It goes in before the
if_id 0 entries above hand any packet to the interface, and comes out after
them. Its FWD lookup uses the namespace default after the Child policies and
ICMP quoted-header lookup; a tunnel-mode packet no policy covers is still
rejected even when that default accepts.
The entries follow the interface: Ze reads its index and
addresses and if_id through the interface resolver, and reads them again when an
interface address is added or removed or an interface is created. An address
the interface loses takes its entry with it, and the entries are removed when
no peer binds the interface and when the engine stops; the if_id 0 entries also
leave when unmatched turns to bypass. An interface that reports if_id 0 is
treated as one that cannot be read, because if_id 0 is the node-wide database. If the interface cannot be read, its entries stay as they were and
the daemon logs a warning. If an if_id 0 entry cannot be installed, the daemon
logs an error: the tunnel's traffic is then dropped by the catch-all. If an
interface's own final entry cannot be installed, which includes a daemon without
CAP_NET_ADMIN, the apply fails as it does for the node-wide catch-all: a
commit is refused, at startup the configure step returns the error, and no
if_id 0 entry hands that interface any traffic. Without its final entry the
kernel would still accept an unmatched inbound packet that arrived under a
transport-mode or offloaded state. Fix: give the daemon CAP_NET_ADMIN, then
commit again. An interface address change meets the same failure with no commit
to refuse, so the daemon logs it as an error and the next commit fails until
the entry goes in. On a reload that
turns discard on, the entries go in before the catch-all changes, so a
running tunnel never loses traffic.
The IPv6 source entry is wider than the interface it stands for: an IPv6
packet sourced from the XFRM interface's own address but routed out of another
interface would match it too. Under unmatched discard Ze therefore guards each
such address, and installs its source entry only while the guard holds:
- A rule
from <address>/128looks the packet up in a routing table Ze owns for the interface (tables 3000 to 3999, routes markedze-ipsec-guard). The table holds a route into the interface for every IPv6 remote traffic selector of a Child SA bound to it, and ends inunreachable ::/0. A program that binds the tunnel address as its source is sent into the tunnel, or told the destination is unreachable. - The nft table
ze_ipsec_source_guarddrops, at postrouting, IPv6 from the address leaving through any other interface. This catches the packet whose source the kernel picked after routing it, which no source rule sees.
So traffic from a tunnel address leaves only through its tunnel, and the
operator's own routing table IDs 1000 to 3999 are refused because Ze reserves
them. A peer whose local-address is an address of an interface some peer
binds with vti bind is refused at commit: the guard would send its IKE
traffic into its own tunnel. Set local-address to an address of the WAN
interface instead.
Application overrides
RFC 4301 Section 4.4.1: "However, the system administrator MUST be able to
specify whether or not a user or application can override (default) system
policies." On Linux an application overrides the SPD by setting a per-socket
policy (IP_XFRM_POLICY, IPV6_XFRM_POLICY, and the older IP_IPSEC_POLICY
and IPV6_IPSEC_POLICY). The kernel consults it before any SPD entry, so one
ALLOW socket policy takes that socket past every entry, the discard catch-all
included. Linux asks only for CAP_NET_ADMIN, and a Ze appliance gives that to
every external plugin it starts. One leaf decides:
set vpn ipsec application-override deny
| Value | Meaning |
|---|---|
deny (default) |
Ze attaches a cgroup BPF program to the cgroup2 root that refuses those four options with EPERM to every process in Ze's network namespace except Ze itself. Every other setsockopt passes untouched, and a process in another network namespace (which has its own SPD) is not affected |
allow |
✕ |
A box with no vpn ipsec block attaches nothing: it has no SPD to protect.
Ze's own exception is the ESP form reader's inbound socket policy (see "Both
ESP wire forms"): it is the IPsec implementation's receive path, not an
application, and the listing names it esp-form-socket. The program recognises
Ze by its process id inside Ze's own PID namespace, so the exception holds when
Ze runs in a container.
deny needs CAP_BPF and CAP_NET_ADMIN, a cgroup2 mount (Ze finds it in
/proc/self/mountinfo; gokrazy's init and systemd both mount it at
/sys/fs/cgroup at boot) and a kernel with
CONFIG_CGROUP_BPF, Linux 6.10 or later, both of which Ze's kernel carries. The
version matters on a distribution kernel: the guard names its caller with
bpf_get_ns_current_pid_tgid, which Linux offers to a cgroup program only from
6.10 (bpf_base_func_proto in kernel/bpf/helpers.c; 6.9's
cg_sockopt_func_proto does not offer it), so an older kernel refuses to load the
guard. When any of them is missing the apply fails rather than run without the
guard:
vpn ipsec application-override deny: Ze could not attach its setsockopt guard to the cgroup2 root (<kernel error>). Without it any process holding CAP_NET_ADMIN can exempt its sockets from the IPsec policy. Run ze with CAP_BPF and CAP_NET_ADMIN (under systemd, a ze unit written by an older ze does not grant CAP_BPF: stop ze with `sudo systemctl stop ze`, then rewrite the unit with `sudo ze install systemd --force --start`) on Linux 6.10 or later (an older kernel refuses the guard's bpf_get_ns_current_pid_tgid call), mount cgroup2 at /sys/fs/cgroup, or set `vpn ipsec application-override allow` to accept that risk.
Until an apply succeeds, show doctor reports the same refusal as
doctor-ipsec-override-guard, and so does a ze doctor the running daemon
answers, so a boot that left IPsec down on such a host says why. The check reads
what the IKE engine recorded in the process that answers doctor. It therefore
reports nothing in a ze doctor no daemon answered, and nothing in a daemon that
runs the IKE engine as an external plugin.
A reload moves between the two values with no restart, and removing vpn ipsec
detaches the program after the catch-all leaves.
What the guard cannot do, and what ze doctor reports instead:
| Limit | Why | Doctor |
|---|---|---|
A socket policy set before the guard attached, or while allow held, stays until its socket closes |
The kernel offers no way to delete a socket policy, and its dump names no owning process | doctor-ipsec-socket-policy, a warning per policy that is not Ze's, under deny |
A CAP_NET_ADMIN holder can still write the SPD itself over netlink |
cgroup BPF has no hook on a netlink send, and Linux treats that holder as an administrator | doctor-ipsec-spd-writer, a warning naming each such process and its command; doctor-ipsec-spd-writer-unknown when /proc hides processes from Ze (not mounted, hidepid, no ptrace access), so it cannot tell |
A process holding CAP_SYS_ADMIN or CAP_BPF can detach the program |
It is an ordinary cgroup link | doctor-ipsec-override-guard, an error when the guard is not attached under deny |
show vpn ipsec dataplane policy lists every socket policy with SPD socket,
its direction, and role esp-form-socket or socket-override.
Both ESP wire forms
RFC 7296 Section 2.23 requires a device that supports NAT traversal to receive UDP-encapsulated ESP and bare ESP at any time. One Linux XFRM state serves one form (LL-XFRM-STATE-ONE-ESP-FORM). Ze serves the second form beside the kernel, on a Child SA whose inbound state is UDP-encapsulated: one whose IKE SA runs on port 4500, with or without a NAT. One established Child SA therefore keeps carrying traffic when its peer changes ESP form mid-session, with no rekey and no delete.
Bare ESP for such a Child SA reaches XFRM through one of two paths. On both, the
packet XFRM decrypts arrives on an interface where Linux runs the inbound IPsec
policy check, so the Child SA's traffic selectors and unmatched discard hold
for it as RFC 4301 Section 5.2 requires.
| Path | What it carries | Interface the decrypted packet arrives on |
|---|---|---|
| Fast path, in the kernel | Every whole bare ESP datagram from the SA's peer to its local address, received on a link the program is attached to | The link the datagram arrived on |
| Complete path, in Ze | What the fast path leaves alone: fragmented datagrams (read after the kernel reassembles them), an IPv4 header with options, a frame that carries a VLAN tag (a rule on the VLAN's parent interface can match the tag, and would see UDP where it matches ESP), and a link the program is not attached to. It reads IPv4 only | ze-espform |
On a distribution kernel, the loaded module esp4_offload can consume bare
ESP during Generic Receive Offload (GRO), before either of Ze's paths sees it.
While a dual-form SA is installed, ze doctor reports that module under
doctor-ipsec-esp-form-offload. Its systemd fix is:
sudo systemctl stop ze && sudo modprobe -r esp4_offload && sudo systemctl start ze
Stopping Ze interrupts all its tunnels and removes their SAs, which can hold
references that prevent the module from unloading. Ze does not request
hardware offload for its SAs, so negotiating them again does not autoload this
module. Another IPsec owner can still hold or load it: if unloading fails,
the command leaves Ze stopped. Stop that owner and retry before starting Ze.
If another owner needs the module, disable GRO on the receiving interfaces
through their existing offload { gro false; } configuration instead. Without
systemd, stop and start Ze with the supervisor that runs it, with
sudo modprobe -r esp4_offload between those steps.
An unreadable receiver state or module list is a separate
doctor-ipsec-esp-form-offload-unknown warning, with the command to inspect the
dataplane's warnings or restore missing procfs. A readable module list proves
only whether the module is loaded; it cannot detect an ESP GRO implementation
built into the kernel. Ze's runtime kernel does not enable that feature.
The fast path is a tc ingress program. It adds a UDP header with the IKE ports
to a bare ESP datagram for a watched Child SA, in place, so the kernel receives
the form the state expects on the real link. Ze attaches it to every interface
except lo and ze-espform while any Child SA is served this way, and to an
interface created later. An interface type the program cannot read is logged by
name, and its bare ESP goes to the complete path. When the program cannot load
at all, the complete path carries all bare ESP.
The doctor check ipsec-esp-form-fast-path reports a fast path that could not
load, or that stopped following new interfaces, as a
doctor-ipsec-esp-form-fast-path warning carrying the cause and the fix
(CAP_BPF and CAP_NET_ADMIN, which a unit written by an older ze lacks: stop ze
and rewrite the unit with
sudo systemctl stop ze && sudo ze install systemd --force --start; or a kernel
with TCX), and each interface it does not serve as a doctor-ipsec-esp-form-link
warning naming the interface and the reason. That warning's fix is a step on the
peer, so its message carries it (on strongSwan, set encap = yes in the
connection and run swanctl --load-conns), or routing the traffic over an
interface of a type the fast path serves. Its fix line is the command that shows
the interface, ze show interface name <interface> detail, or ze show interface
when the interface's name cannot be typed as one command word. A fast path
whose state Ze could not read is the same warning, with the command that lists
the warnings naming the cause.
A fast path that loaded and then detached itself is a different warning under
the same code. Ze shuts the program's firewall gate while it checks the
nftables ruleset, and when the kernel refuses that write, Ze removes the program
from every interface rather than let it rewrite bare ESP past a firewall rule
that should see it. All bare ESP then takes the complete path, at its rate
bound, until ze restarts or until no Child SA is served in both ESP forms and
one is installed again. The warning says the gate could not be shut and names
the refused write, and its fix is sudo systemctl restart ze. It names no
capability or kernel step: the program had loaded. Only a fast path that never
loaded gets the CAP_BPF warning above.
Ze picks each inbound SPI at random, so two Child SAs on two different local
addresses can draw the same one. The kernel serves both, but the fast path
serves one SA per SPI, the first one installed, so bare ESP for the second SA
takes the complete path at its rate bound. The same check reports this as a
doctor-ipsec-esp-form-fast-path warning that names the SPI and both local
addresses. Its fix is ze clear vpn ipsec sa peer <name> for the peer that
holds the second SA: Ze has no command that rekeys one Child SA, so the clear
negotiates that peer's SAs again, and the new Child SA draws a new SPI. That
peer's tunnel carries no traffic until its new SAs are up. When Ze cannot name
the peer, for example while a rekey replaces the SA, or when the peer's name
cannot be typed as one command word, the fix is ze show vpn ipsec sa, which
lists each peer with its inbound SPI but not its local address. Clear either
peer whose Child SA carries that SPI: either way the cleared peer's new Child
SA draws a new SPI, the other SA holds the SPI alone, and the fast path serves
it. The warning goes when either SA is removed.
Ze also logs the collision at Warn when the second SA is installed, but only
while the fast path is attached: a fast path that could not load or detached
itself serves no SA, so the collision costs nothing more and that status has
its own warning. The log line's fix is the listing, ze show vpn ipsec sa, and
its message says that clearing either peer whose Child SA carries the SPI, with
ze clear vpn ipsec sa peer <name>, ends the collision. A MOBIKE move that
would put an SA on the local address where another SA with the same inbound SPI
is received is refused before Ze changes anything, and the tunnel stays on its
old address. The refusal's fix is ze show vpn ipsec sa; clear either of the
two peers to end the collision.
A MOBIKE move also needs the complete path. After the move the SA's inbound
state carries the ESP-in-UDP template, so the kernel refuses its bare ESP and
only Ze's receiver, its raw ESP socket and the ze-espform device, serves that
form. When the SA was not served in both forms before the move and those cannot
open, Ze refuses the move with nothing changed, and the tunnel stays on its old
address. The refusal names the SPI and both local addresses, and its fix is the
one the cause names, shown once. Every cause the host can produce names its own
fix:
| Cause | Fix |
|---|---|
| ✕ | sudo systemctl stop ze && sudo ze install systemd --force --start |
A Linux security module (SELinux or AppArmor) refuses the raw ESP socket or its exemption (EACCES); no capability changes that |
sudo journalctl -b --grep 'avc:|apparmor="DENIED"', which lists the denials, then change the policy for ze |
ze reached its limit of open files (EMFILE); the ze unit sets LimitNOFILE=65536 |
sudo systemctl stop ze && sudo ze install systemd --force --start |
The host reached its limit of open files (ENFILE) |
sudo sysctl -w fs.file-max=9223372036854775807, the value systemd sets at boot |
The kernel is short of memory (ENOMEM, ENOBUFS) |
free -m |
The TUN device does not open, or ze-espform cannot be created |
The fix the TUN refusal names, such as ls -l /dev/net/tun or modprobe tun |
| ✕ | sudo systemctl stop ze && sudo ze install systemd --force --start; in Docker, start the container with --cap-add NET_ADMIN |
Another step of the configuration of ze-espform failed, and Ze removed it again |
ze show log recent level warn component ike.dataplane, whose warnings carry the kernel's answer |
An IPv4 setting of ze-espform that Ze could not write, for a reason other than a read-only /proc/sys |
sudo sysctl -w net.ipv4.conf.default.<setting>=<value>, as the refusal names it |
| Any other answer of the socket or its exemption | ze show log recent level warn component ike.dataplane: Ze tries again at the next install, and by itself while such an SA is installed |
The same causes refuse the install of a Child SA that must receive both ESP
forms, with the same fix. Ze records its last failure to open its own receiver
for bare ESP, and the doctor check reports it as a doctor-ipsec-esp-form-tun
error with the cause, the time and the fix, until an open succeeds. When the
TUN outcome the last configuration apply recorded has the same cause, the check
reports this one error alone.
The raw ESP socket can also fail after it opened. The Child SAs it served stay
installed, so Ze opens the receiver again by itself while such an SA is
installed: at once, then further apart, doubling up to 30 seconds. The wait
starts again at once only after a receiver that served for a minute, so a socket
that fails right after each open is not reopened in a tight loop. Ze logs each
stop at Warn and raises it on the report bus as a
doctor-ipsec-esp-form-reader-stopped error event, which ze show errors and
ze show doctor report even when the receiver opened again at once. Until it
opens, bare ESP for those SAs is received only where the fast path rewrites it,
and the next install, or a move onto the ESP-in-UDP form, opens it or is refused
with the cause.
The fast path runs before netfilter, so Ze keeps it off while a firewall rule or
policy on the input path could drop ESP. The check then reports a
doctor-ipsec-esp-form-firewall warning naming the first site that could drop
it. Bare ESP takes the complete path, after the input path, so the firewall
still decides on it. The warning says what that costs: the complete path's rate
bound, the datagrams above it dropped before XFRM sees them, and the input
interface a rule sees, which is ze-espform. To keep the fast path, and only if
that ESP should be accepted, accept protocol esp ahead of that site in its
chain; otherwise leave the firewall as it is. The warning says who writes the
site's table, and its fix depends on that:
-
A table Ze does not own (its kernel name does not start with
ze_) takes the nft command that inserts the accept at the head of the base chain, such assudo nft 'insert rule inet "filter" "input" meta l4proto esp accept'. When the table or chain name holds a quote or a control character, Ze prints no command to paste: the fix issudo nft list ruleset, and the warning says to insert that rule with nft. A table created with the owner flag, whichnft list rulesetmarks# owner, takes that change only from the process that owns it. -
A table of Ze's firewall configuration (its kernel name is
ze_and the table's name in the configuration) is rewritten at each firewall commit, so an nft rule there would be gone after the next one. The fix is three lines to paste intoze config edit, here for tablewanand chaininput:set firewall table wan chain input term accept-esp from protocol esp set firewall table wan chain input term accept-esp then accept commit nowThe editor adds a new term after the chain's existing terms and has no command that moves a term ahead of another, so
accept-espaccepts ESP only where no earlier term of the chain drops it. While an earlier term can drop ESP, that term stays the site and the fast path stays off. -
A table a Ze plugin or component writes (it reserved the table's name) has rules that follow that plugin's state, and Ze rewrites the table whenever the state changes, so neither an nft rule nor the configuration editor changes it for long. The warning names the plugin and what decides its rules, and the fix is the command that shows that state:
show bgp rib best | family ipv4/flowfor the flowspec-firewall plugin'sze_flowspec, orshow firewall ruleset ipsec_source_guardfor the IKE engine's tunnel-source guard. The rule changes only with that state. -
A
ze_table that no plugin reserved and whose table or chain name the configuration cannot hold is neither, and the fix isshow firewall ruleset.
When the fast path started and Ze could not open its nftables reader or join
the monitor that follows the ruleset's changes, or that monitor was closed, the
fast path is off for safety, and the same warning names the cause, with
sudo systemctl restart ze as the fix: nothing reads the ruleset again until
ze restarts, or until no Child SA is served in both ESP forms and one is
installed again. When the reader and the monitor are open but one read of the
ruleset failed, Ze needs no restart: the monitor still runs, so the next commit
to the ruleset, by Ze's firewall or by any other program, makes Ze read it
again, and nothing reads it before then. The warning says so, and its fix,
sudo systemctl restart ze, reads the ruleset at once. When the monitor
fails, Ze needs no restart: it watches the ruleset again by itself, after a wait
that doubles from one second up to thirty seconds, and turns the fast path back
on once a fresh read of the ruleset finds no rule that can drop ESP. While the
fast path is off for that reason, the warning says no restart is needed for the
firewall reading, and its
fix is ze show log recent level warn component ike.dataplane, which names why
the monitor keeps failing, usually a missing CAP_NET_ADMIN.
Ze's own firewall commits hold the fast path off while they land: the IKE engine registers a firewall commit observer that takes the hold before the nftables backend applies a reconcile and releases it once the apply returns. With the IKE engine run as a forked plugin, the daemon's commits take no hold, and Ze learns of them from the nftables monitor alone.
The check reads the state the IKE engine's own process holds, so it is a runtime
check the engine answers: show doctor runs it, and so does ze doctor when the
running daemon answers it. A ze doctor no daemon answered reports
doctor-runtime-not-checked instead.
The same check reports doctor-ipsec-esp-form-tun, an error, when Ze could not
create a usable ze-espform interface for the complete path. For example, Ze
can neither open nor create /dev/net/tun. Or Ze cannot write /proc/sys (it
is read-only, as in a container), and the interface would take from
net.ipv4.conf.default a disable_policy of 1, which skips the inbound policy
check, or a strict rp_filter (the larger of conf.default and conf.all is
1). Every Child SA on UDP port 4500 is then refused at install, because such an
SA must receive bare ESP as well as ESP-in-UDP.
The IKE engine checks this itself on every configuration apply that configures
an IPsec peer on the Linux kernel dataplane, because any IKE SA can move to UDP
port 4500. The apply opens the device as a Child SA install would, so where the
node is missing the apply creates it. It logs a refusal once per apply, at WARN.
The doctor check only reads the outcome that apply recorded, so show doctor
never creates the device node. While the receiver watches a Child SA it holds
the device, and the check reports no finding. The message names the cause, and
the fix is the one the refusal gives, listed below after the complete path. A
refusal that names no fix gets ze show log recent level warn component ike.dataplane.
The complete path is a raw IPPROTO_ESP reader. Linux gives it a copy of the
bare datagram XFRM refused. Ze writes that datagram again with the UDP header
into its own TUN interface ze-espform, which has disable_policy 0, and the
kernel receives it there. The complete path runs in Ze, so it is bounded to 5000
datagrams per second, with a burst of 10000. The fast path has no such bound.
The complete path needs the TUN clone device /dev/net/tun. Where the node is
missing, as in a container started without --device /dev/net/tun, Ze creates
it (c 10 200, mode 0600, in /dev/net) when the kernel allows it: the process
must hold CAP_MKNOD in the initial user namespace, and the device cgroup must
grant the device. A default Docker container meets both. Ze never changes a node
that exists. When Ze can neither open nor create the node, it refuses every
Child SA that must receive both ESP forms, with an error that names the cause and
the fix. Under Docker the fix is --device /dev/net/tun (Compose:
devices: [/dev/net/tun]); on a host it is modprobe tun; a kernel without
CONFIG_TUN needs a new kernel; and creating ze-espform needs CAP_NET_ADMIN.
The refusal is not a configuration error: without the device, Ze cannot receive
bare ESP on the SA and still run the inbound policy check (RFC 4301 Section 5.2).
The kernel gives the new ze-espform interface the values of
net.ipv4.conf.default, and Ze writes disable_policy 0 and rp_filter 2 on it
only where the interface does not already hold them. In a container whose
/proc/sys is read-only, start the container with
--sysctl net.ipv4.conf.default.disable_policy=0 --sysctl net.ipv4.conf.default.rp_filter=2
(Docker accepts net.* sysctls for the container's own network namespace).
Otherwise Ze refuses a Child SA that must accept both ESP forms when the
interface would skip the inbound policy check or use strict reverse-path
filtering.
Setting net.ipv4.conf.all.disable_policy to 1 turns the inbound policy check
off on every interface of the host, ze-espform included, and Ze reports
nothing about it: that is the operator's choice for the whole host, and Ze does
not override it.
Both paths keep the outer TOS octet the bare datagram arrived with, so XFRM copies an ECN congestion mark (CE) from the outer header into the decrypted packet, as RFC 7296 Section 2.24 requires: the fast path never rewrites that octet, and the complete path copies it into the header it builds.
The cost for a firewall rule. A packet the complete path carries arrives on
ze-espform, not on the link it came in on. A firewall rule that matches the
input interface sees ze-espform for that traffic.
The fast path does not take a decision away from the firewall. It adds the UDP
header at tc ingress, and Linux runs tc ingress before the firewall: before the
netdev ingress hook and before prerouting. A datagram it rewrote would reach a
rule on protocol esp as UDP to port 4500. So the fast path rewrites only while
no nftables rule or chain policy on the input path could drop or change the
peer's ESP: a
base chain on the ingress, prerouting or input hook of an inet, ip,
netdev or bridge table. While one could, the fast path leaves bare ESP as it
arrived, and the rule keeps deciding. That holds for a Ze firewall term on
protocol esp and for a rule an operator added with nft alike, because Ze
reads the kernel's ruleset, not its own configuration. A rule Ze cannot read in
full, such as one using an iptables extension or an expression Ze does not know,
counts as one that could drop ESP.
Ze tells a rule that cannot match ESP from one that can only by the match the
rule opens with: meta l4proto equal to a protocol other than ESP, in any
table; the IPv4 protocol field (ip protocol) equal to one, in an inet or ip
table only; or meta nfproto ipv6, in an inet or ip table, as the rule's
first match. In a netdev or bridge table an ip protocol match does not
count, because the packet there need not be IPv4. meta l4proto udp drop cannot match ESP. A rule
whose first match is an address, a port or an interface counts as one that can,
even when a protocol match follows, and so does a rule on meta l4proto != esp.
Ze's own drops open with their protocol for that reason, so the GTSM drops of a
BGP peer with connection ttl max, and an on-host DDoS mitigation against a
protocol other than ESP, keep the fast path on. A DDoS mitigation against ESP
itself, or against a protocol Ze has no name for, keeps it off: the first
opens with ESP, the second with the victim's address, and both can drop ESP
sent to that address.
A rule that can match ESP keeps the fast path on only when all it does is
select, count, log or rate-limit, and it then accepts or goes on to the next
rule. A rule that matches nothing but protocol esp, counts at most and
accepts ends the check of its chain: ESP is accepted there. Any rule that can match ESP and
changes something counts as one that could drop it: a mark or conntrack mark
set, notrack, a DSCP or other header rewrite, a TCP option strip, a set
lookup (ip saddr @trusted, because a set element can carry a connlimit or
quota of its own that the rule does not show), a map lookup, a set update,
dup, a named object, quota or connlimit. The warning and show doctor
name the rule and the reason.
Ze reads the tables, chains and rules itself, through nftables dumps of its own,
so no expression is lost in the reading. One reading is several dumps, so Ze
reads the ruleset's generation number before the first dump and after the last.
Every commit changes that number. When the two differ, a commit landed while Ze
read, so what it read is not one ruleset: Ze turns the fast path off and reads
again. The comparison does not catch every such commit: the kernel changes the
number before it applies a commit's table and chain changes, so a reading that
begins in between sees the new number and the old rules. The notice the kernel
sends once a commit is applied covers that case, because every commit Ze hears
of turns the fast path off until Ze has read the ruleset again. While commits
keep coming faster than Ze can read (fail2ban adding addresses to a set every
few milliseconds, each addition a commit), the fast path stays off, and Ze
waits between readings, 50 ms at first, doubling to one second. A dump the
kernel flags as interrupted (NLM_F_DUMP_INTR, a commit inside one dump) counts
the same way: it is a commit, never a failed read, so it turns the fast path off
and Ze reads again, waiting between readings while such dumps keep coming. The
fast path comes back on once a reading finds the ruleset unchanged and safe, and
no restart is needed.
When the commits keep coming for ten seconds or longer, show doctor reports it
under doctor-ipsec-esp-form-firewall: the nftables ruleset has kept changing
since at least the time it names, so the fast path stays off, and bare ESP takes the
complete path at its rate bound, at most 5000 datagrams per second. The fix line
is sudo nft monitor, which shows each commit as it lands, so you can see which
tool keeps committing. Then make that tool batch its changes, or stop it:
fail2ban, for example, commits each ban on its own. For the firewall reading, no
restart is needed: the fast path comes back on once the commits pause long
enough for one reading, and that reading finds no rule that can drop ESP. The
warning says it that way because another warning beside it, for a fast path
that stopped following new interfaces, does name a restart. A stream shorter
than ten seconds is reported nowhere: the fast path outlasts a burst of commits.
While the fast path is unavailable or detached, show doctor reports that
alone: no program reads the firewall gate then, so a stream of commits changes
nothing for bare ESP.
Ze reads base chains only. A rule that can match ESP and jumps to another chain,
goes to one, returns, or picks its verdict from a verdict map counts as one that
could drop ESP, and Ze does not read the chain it leads to: in the kernel a
return in a base chain skips every later rule and meets the chain's policy, so a
later accept would prove nothing. To keep the fast path, accept ESP ahead of the
jump. The flowspec-firewall plugin's base chain flowspec-in, in table
ze_flowspec, holds such a jump with no match while Ze selects a FlowSpec route
whose action is a traffic-rate limit above zero, or a traffic-action whose
terminal bit asks for later routes to apply too, and ends with a goto with no
match while it selects a route that marks traffic. Either keeps the fast path
off while that route is selected, and the warning names the plugin's command,
show bgp rib best | family ipv4/flow, which lists the routes the table
follows.
With the fast path off, the complete path carries the bare ESP the firewall lets
through. It reads a datagram after the input chain, so a rule there has
already judged it, and writes it into ze-espform, where it reaches the firewall
a second time, as UDP to port 4500. That costs what the complete path costs: at
most 5000 datagrams per second, with a burst of 10000. Ze drops the datagrams
above that rate before XFRM decrypts them. A rule keyed on the input interface
sees ze-espform, not the link the datagram arrived on.
The fast path cannot see every filter on the host, and it cannot take back a datagram it already rewrote. Ze reads only the nftables ruleset, so anything else that decides on bare ESP after tc ingress sees the rewritten datagram as UDP to port 4500. The list below holds the limits known today, each with what to do about it. It is not a complete list of what can run on a Linux host: a filter of another kind that matches ESP after tc ingress meets the same limit, and the same fix applies to it: match UDP to port 4500 from the peer as well as ESP.
-
Rules loaded with iptables-legacy live in the kernel's x_tables, which Ze does not read, so the fast path rewrites bare ESP past them. Write the rule in nftables, or load it with iptables-nft, whose rules are nftables rules that Ze reads.
-
Bridge rules loaded with ebtables-legacy live in the kernel's ebtables tables, which Ze does not read either, so on a bridge port the fast path rewrites bare ESP past them. Write the rule in an nftables
bridgetable, which Ze reads, or load it with ebtables-nft. -
A BPF program attached to a netfilter hook (a
BPF_LINK_TYPE_NETFILTERlink, atpreroutingorinput) runs inside netfilter, but it is not an nftables rule, and no nftables dump shows it. It sees a rewritten datagram as UDP to port 4500.sudo bpftool link showlists these links. Make the program match UDP to port 4500 from the peer as well as ESP, or detach it. -
A tc ingress program or filter that Ze did not install and that runs after Ze's program sees a rewritten datagram as UDP to port 4500. Ze attaches its program at the head of the interface's TCX chain and passes every packet on. Match UDP port 4500 from the peer there as well as ESP, or remove that program.
-
Linux chooses a route for each packet, and checks its source address, after tc ingress, so an
ip rulethat selects on the protocol (ipproto esp) sees a rewritten datagram as UDP. Two cases reach that difference:- With reverse-path filtering on (
rp_filter1 or 2), Linux checks the source with a route lookup back to the peer. That lookup walks the rules, and thelocalrule at priority 0 does not stop it, because the peer's address is not local. Anipproto esprule that answersprohibit,blackholeorunreachable, or that sends the lookup to a table with no route back to the peer (in strict mode,rp_filter1, no route back through that link), then drops bare ESP as a reverse-path failure and lets the rewritten datagram through. Withrp_filter0 the check drops nothing. - When the
localrule no longer sits at priority 0, as the usual Linux VRF setup moves it, the route lookup for the packet itself reaches the rules placed ahead of thelocalrule. Anipproto esprule there then decides on bare ESP and not on the rewritten datagram.
Only an
ip ruleyou wrote that selects onipproto espreaches this difference. Ze does not read the routing rules, as it does not read iptables-legacy rules. A firewall rule that sets a mark on ESP, for anfwmarkrule to pick up, keeps the fast path off, so no datagram the fast path rewrote misses a mark that rule would have set.Ze adds no
ipprotorule and never moves thelocalrule: its own rules select on a source address or on a mark, behind thelocalrule. Where you added such a rule, give UDP from the peer to port 4500 the same priority and the same action, keeping any other selector your rule has. For the route lookup of the packet itself (the second case):sudo ip rule add priority <priority> from <peer> ipproto udp dport 4500 <action>For the reverse-path lookup (the first case), which looks up the route back to the peer, so the peer is its destination, and in which Linux swaps the two ports, so
sport 4500names the datagram's destination port:sudo ip rule add priority <priority> to <peer> ipproto udp sport 4500 <action><priority>and<action>are youripproto esprule's (for exampleprohibit, orlookup <table>), and<peer>is the IPsec peer's address. For the second case, keeping thelocalrule at priority 0 also removes the difference, because locally addressed traffic is then delivered before any later rule is read. - With reverse-path filtering on (
-
Ze learns of a commit another program makes (an
nftcommand, firewalld) only after it lands, from the nftables monitor, which turns the fast path off until Ze has judged the ruleset again. A reading that such a commit lands in the middle of is not used when the generation number Ze reads around it moved. When the commit moved that number just before the reading began and applied its changes during it, the reading can be used, and the monitor's notice of that commit then turns the fast path off again. Bare ESP that arrives in between, the monitor's latency plus the end of a reading already under way, is rewritten past the new rule. It is still decrypted and checked against the Child SA's selectors: what it misses is the rule. If that window matters, commit the rule that drops ESP through Ze's firewall, whose commits hold the fast path off while they land. -
An IKE engine run as an external plugin takes no hold across Ze's own firewall reloads, so those reloads have the same monitor window. Where the window matters, run the IKE engine inside the daemon, as Ze does by default.
-
The hold Ze's own firewall commit takes stops the fast path from rewriting from the moment it begins. A datagram the fast path rewrote just before that is still on its way to the firewall hooks as UDP to port 4500, and if the commit lands before those hooks see it, a rule the commit adds for bare ESP does not see it. The window is the time one datagram takes from tc ingress to the input hook, and no setting closes it. Where that matters, commit the rule before the IPsec peer comes up.
-
A rule that drops UDP, such as
meta l4proto udp drop, cannot match bare ESP, so Ze reads it as one that cannot drop ESP and keeps the fast path on, yet it drops the datagram the fast path rewrote into UDP. That fails closed: the ESP is lost, never let through. Such a rule also drops the peer's IKE messages on UDP port 4500 unless an earlier rule accepts them, and the rewritten datagram carries the same ports as those messages, so an earlier rule that accepts the peer's IKE on UDP port 4500 accepts it too. Accept the peer's IKE ahead of the UDP drop, as the IKE SA needs anyway.
A peer that encapsulates ESP itself (strongSwan encap = yes) never uses either
path.
The reader carries a per-socket inbound policy exemption. Linux applies the inbound IPsec
policy check before it queues a packet to a raw socket. Ze's own Child SA policy refuses
exactly the datagrams this reader exists to recover. The exemption reaches that one socket,
and covers only the reading of the still-encrypted copy: the datagram Ze writes into
ze-espform gets the inbound policy check like any other. XFRM still decrypts and still
owns the replay window.
Receiving both forms over an IPv6 outer header is a gap owed after the first release.
Ze has no IPv6 IKE transport yet: the IKE listener opens IPv4 sockets only, so no Child SA
has IPv6 outer addresses. An SA that asks for both forms over IPv6 is refused rather than
installed with one form. plan/post-release/features/spec-ike-ipv6-transport.md owns the
work. The fast path's program already holds an IPv6 rewrite, which nothing reaches yet,
and it leaves alone an IPv6 header followed by an extension header and an IPv6 datagram
whose checksum the network card already summed; no complete path serves those over IPv6
either, since it reads IPv4 only. The form Ze SENDS is a separate decision and follows the NAT verdict alone: Ze
encapsulates when it detected a NAT.
Traffic selectors and narrowing
A peer's traffic-selector list states which traffic its Child SAs carry. It is also the
policy RFC 7296 Section 2.9 narrows a peer's proposal against.
vpn { ipsec { site-to-site { peer branch-1 {
traffic-selector 1 {
protocol 6
local { prefix 10.3.0.0/24; port 179; }
remote { prefix 10.2.0.0/16; }
}
traffic-selector 2 {
protocol 6
local { prefix 10.3.0.0/24; port 179; }
remote { prefix 10.4.0.0/24; }
}
} } } }
When the list is absent the peer accepts whatever the remote endpoint proposes. That is the behaviour of every configuration written before the list existed, so adding the list is what restricts a peer, never omitting it.
A Child SA carries every combination of its local and remote selectors. RFC 7296 Section
3.13: "a packet matches a given TSi/TSr if it matches at least one of the individual
selectors in TSi, and at least one of the individual selectors in TSr." So the list must
name every combination of the local and remote selectors it uses, as the example above
does with one local and two remote selectors. A packet is either IPv4 or IPv6, so an IPv4
selector is never combined with an IPv6 one: a dual-stack peer with one IPv4 entry and one
IPv6 entry already names every combination. A list such as local 10.1.0.0/16 with remote
10.2.0.0/16, then local 10.3.0.0/16 with remote 10.4.0.0/16, would be offered as
10.1.0.0/16 with 10.4.0.0/16 as well, so ze config verify refuses it and names the
missing combination. Add the missing entries, or remove the entry that brings in the
extra prefix.
An omitted port, or port any, leaves that side unconstrained. A specific port
requires a protocol that defines the field: TCP (6), UDP (17), SCTP (132) or
UDP-Lite (136). DCCP (33) defines ports too, but Linux XFRM cannot select them,
so Ze refuses a specific DCCP port; DCCP with port any is accepted. Protocols
without ports, including GRE (47) and ESP (50), require port any.
For ICMP, the number is the IKE type/code value: type times 256 plus code.
For IPv6 Mobility Header protocol 135, the IKE value is the Type times 256,
with a zero low octet: Type 5 is 1280, rather than 5. Ze understands that
encoding, but refuses every specific MH Type at config verify and negotiation.
The Linux receive-flow decoder does not fill the Type used by XFRM: an exact
Type 5 policy drops even matching received and forwarded packets.
protocol 135 with port any remains usable. The wanted exact-Type kernel
feature is tracked in plan/post-release/kernel/spec-xfrm-ipv6-mh-selector.md.
The VPP backend refuses constrained MH and UDP-Lite selectors because its SPD does not compare those fields. Linux supports UDP-Lite ports.
The inner family of a tunnel does not have to match its outer family. RFC 4301 Section 5.1.2: "IPsec allows the IP version of the encapsulating header to be different from that of the inner header." On Linux, a tunnel-mode SA Ze installs carries IPv4 or IPv6 inner traffic over an outer pair of either family, so one Child SA whose selectors hold an IPv4 and an IPv6 pair carries both. The two outer addresses of a tunnel always share one family.
What you can configure today is narrower, because Ze's IKE sockets are IPv4 only: a tunnel has an IPv4 outer pair and carries IPv4 or IPv6 inside it. IPv4 inside an IPv6 outer pair works in the kernel datapath, but no configuration reaches it until IKE runs over IPv6.
IPv6 inside an IPv4 tunnel on a VTI
A route-based peer that carries both families writes one entry for each family. A peer with no list proposes the wildcard of its outer family alone, so a peer reached over IPv4 would never propose IPv6.
interface {
xfrm vti0 {
if-id 7;
unit 0 { ipv6 { address [ fd00:db8:1::1/128 ]; } }
}
}
static {
table default {
route fd00:db8:1::/112 { next { interface vti0 { } } }
}
}
vpn { ipsec { site-to-site { peer hq {
vti { bind vti0; }
traffic-selector 1 { local { prefix 0.0.0.0/0; } remote { prefix 0.0.0.0/0; } }
traffic-selector 2 { local { prefix ::/0; } remote { prefix ::/0; } }
} } } }
Ze proposes both entries, the IPv4 one first. A responder whose own policy names IPv6
alone, such as strongSwan with local_ts = ::/0 and remote_ts = ::/0, answers ::/0
on both sides. RFC 7296 Section 2.9 allows that: "When the responder chooses a subset of
the traffic proposed by the initiator, it narrows the Traffic Selectors to some subset
of the initiator's proposal (provided the set does not become the null set)." Ze then
installs what the responder answered and nothing more: an IPv6 policy for each of the
in, out and forward directions, each carrying vti0's if_id, and no IPv4 policy, so the
router's own IPv4 traffic never enters vti0. An answer wider than the entry Ze proposed
is refused. show vpn ipsec sa reports the narrowed selectors and the if-id. The
vti-ipv6-inner-ipv4-outer interop scenario runs this configuration against strongSwan,
with a ping before and after a Child SA rekey.
The mgmt-tunnel and mgmt-tunnel-ed25519 topology scenarios run the same shape
from a CPE behind PPPoE, authenticating with a P-256 and an Ed25519 certificate:
strongSwan narrows the selectors to ::/0, an IPv6 ping crosses vti0 with each
direction's ESP counters advancing, and MOBIKE moves the IKE SA to UDP 4500.
As responder, Ze narrows the initiator's proposed TSi and TSr to a subset the list allows,
and leads the answer with the initiator's first choices. When the pairs it accepts are not
every combination of their own selectors, it answers the largest part that is, starting
from the first choice, because the initiator installs every combination it is answered. A proposal it cannot narrow to a
non-empty subset draws a TS_UNACCEPTABLE notification. As initiator, Ze proposes the list
in order, because RFC 7296 reads the order as the preference order.
The selectors Ze puts on the wire are the selectors it programs. A proposal it cannot program exactly is narrowed FURTHER, never rounded outward: an address range that is not a prefix becomes the largest prefix inside it, and a port range that is neither all ports nor one port becomes its first port. A rekey is never narrowed below the scope in use.
A proposed or answered selector of exactly port 0, or under ICMP of type 0 code 0 (the
IKE port value 0), is dropped from the answer as responder and refused as initiator. Linux
reads no port, ICMP type or ICMP code from an IP fragment, so it classifies every fragment
as port 0, type 0 and code 0, and it classifies forwarded traffic before reassembling it.
A Child SA with such a selector would carry every fragment between its prefixes, and RFC
4301 Section 7.3 forbids that: "a receiver MUST discard non-initial fragments that arrive
on an SA with non-trivial port (or ICMP type/code or MH type) selector values unless this
feature has been negotiated." Ze negotiates no NON_FIRST_FRAGMENTS_ALSO. Any port, any
other single port, and an ICMP selector of any other type or code are unaffected.
Editing a peer's traffic-selector list and committing restarts that peer. The tunnel
drops and comes back carrying the new selectors, and the kernel policy follows. This is
what RFC 7296 Section 2.9.2 asks for: a rekey that would need a narrower scope means the
policy changed, and the SA should have been deleted when the change took effect. Narrowing
a live tunnel by waiting for the rekey timer is not an option the protocol offers.
A REMOTE peer whose selectors narrow while a tunnel is up proposes exactly that at its next
rekey. Ze refuses such a rekey with TS_UNACCEPTABLE instead of replacing the SA with a
narrower one, and the log line names both selector sets. A repeating refusal means the
other end narrowed its policy and left its tunnel up. Narrow the selectors on the Ze end
too, or clear the peer.
The same floor applies to a rekey Ze STARTS. Ze installs the selectors the peer answered
with, never the retired SA's, so both ends program the same traffic. An answer narrower
than the scope in use is refused: Ze keeps the SA that is carrying traffic, sends no error
notification (RFC 7296 Section 2.21.3), and logs both selector sets. It retries at each
lifetime tick, so a repeating narrows the scope in use line means the peer's policy
shrank and the tunnel will hard-expire unless one end is corrected.
| Port value | Meaning | RFC 7296 Section 3.13.1 encoding |
|---|---|---|
any (the default) |
every port | start 0, end 65535 |
1..65535 |
one port | start N, end N |
A port other than any needs protocol to name a protocol that defines ports, such as 6
for TCP or 17 for UDP. Section 3.13.1 requires the port fields to be 0 and 65535 whenever
the protocol is 0, so the combination is refused at commit rather than widened silently.
Opaque ports are refused at commit too. OPAQUE names a port that is not visible in the
packet, and Ze does not yet map that meaning onto a dataplane selector, so it refuses
rather than install a guess.
Transport mode
mode transport asks the peer for transport mode with the USE_TRANSPORT_MODE
notification of RFC 7296 Section 1.3.1. Tunnel mode is the default, and it is the RFC's own
default.
vpn { ipsec { site-to-site { peer host-1 {
mode transport
transport-required true
traffic-selector 1 {
local { prefix 10.0.0.3/32; }
remote { prefix 10.0.0.4/32; }
}
} } } }
Transport mode constrains the selectors. RFC 7296 Section 2.23.1 requires exactly one IP
address in TSi and in TSr, so every prefix must be a single host, and a vti binding is
refused because an XFRM interface carries tunnel encapsulation. A transport-mode Child SA
also carries exactly one selector pair: the kernel's transport-mode SA holds one selector
(LL-XFRM-STATE-ONE-SELECTOR),
and one wide enough for several pairs would admit traffic that no pair negotiated. So
ze config verify and ze config commit refuse a transport-mode peer that configures more
than one traffic-selector entry: keep one entry, or set mode tunnel. The far end can
still propose several pairs. As responder Ze answers such a proposal with the first one. As
initiator it refuses an answer of several pairs and deletes the SA, so configure one selector
on the far end too.
A tunnel-mode peer's vti { bind <name> } names an interface { xfrm <name> { if-id } }
block. The Child SA is installed with that interface's if_id, so the tunnel's traffic
enters and leaves through the named interface and the interface's MTU is the tunnel's.
The interface has to exist when the peer's first Child SA is created: a binding that names
no xfrm interface, or one configured with if-id 0, fails the Child SA with an error
naming the interface. show mtu reports whether that interface's MTU fits the measured
path (docs/architecture/diagnostics/path-mtu.md).
A peer that declines the request establishes the Child SA in tunnel mode. Set
transport-required true when that downgrade is unacceptable: Ze then deletes the SA
instead, which is what Section 1.3.1 asks of an initiator. It defaults to false, so a peer
without transport mode keeps a working tunnel.
Transport mode behind a NAT
Transport mode works across an address-translating NAT, on both roles, and it needs no
extra configuration. Write the addresses each end's own stack holds in local-address,
local-id and the local half of every traffic-selector, and write the address you DIAL
in remote-address, remote-id and the remote half. A respond peer writes the address
it SEES the far end at, which is the translated one, because Ze accepts an unsolicited
IKE_SA_INIT only from the configured remote-address.
Ze then substitutes the selector addresses for you. RFC 7296 Section 2.23.1 requires it:
the peer answers in the addresses ITS stack sees, and those exist on neither node. Ze
replaces them with the addresses it observed, so the policy it programs matches the packets
its own kernel handles. This is the one place where the selectors on the wire and the
selectors in show vpn ipsec sa differ, and the command reports what was programmed.
show vpn ipsec sa names which side is translated. nat-detected says a NAT is on the
path, behind-nat says this node's own address was translated, and peer-behind-nat says
the far end's was. Both can be true at once. A transport tunnel that does not come up
behind a NAT is diagnosed with those three fields first: all false means the peer sent no
NAT_DETECTION notification, which no conforming IKEv2 implementation omits.
The command shows both selector pairs, so you can see the substitution rather than infer
it. original-tsi and original-tsr are the addresses the peer put on the wire, and
ts-local and ts-remote inside child-sa are the addresses the kernel programs. On a
tunnel-mode peer, and on any peer that never negotiated transport mode, the two original
fields are null.
Tunnel mode across the same NAT is unaffected. Section 2.23.1 governs transport mode alone, so a tunnel-mode Child SA negotiates the selectors you configured, untouched.
The VPP dataplane backend does not implement transport mode. It refuses a transport-mode install with a clear error rather than programming a tunnel-mode entry and reporting success. The SA path and the policy path each refuse it on their own.
The VPP dataplane backend cannot be driven by IKE, and no configuration selects it.
It installs security associations, and it refuses every security policy the IKE engine
produces for them. VPP has no node-wide policy database: a policy lives in a security
policy database that acts only on the interfaces it is bound to, and nothing tells the
backend which interface to use. The backend is reached only through a private test
override, it is compiled in only with the ze_vpp build tag, and no test has sent ESP
through it. Use the XFRM backend, which is the default and the production path.
PKI certificate store
The pki { } block stores X.509 certificates, private keys, CA certificates, and the certificate revocation lists each CA published. A ca entry holds a CA certificate and its crl list; a certificate entry holds its certificate, its intermediate list and an optional private { key }. Each value is written inline in the config, not read from a file, and is validated at commit time. The key leaf accepts PKCS8, SEC1 and PKCS1 encodings, and IKEv2 signs with RSA, ECDSA, Ed25519 and Ed448 keys (Ed25519 and Ed448 only for a peer that announces RFC 8420's Identity hash). An Ed448 key is read from its PKCS8 encoding, and its certificate must come from a CA that does not itself sign with Ed448. The PKI store also serves TLS certificates for the web UI and gRPC API.
Health monitoring reports certificate expiry as a warning at 30 days and an error after expiry. Prometheus exposes ze_pki_certificate_expiry_seconds and ze_pki_certificate_valid.
XFRM interfaces
XFRM interfaces provide route-based IPsec. Traffic routed through the XFRM interface is encrypted, and incoming traffic is decrypted before it appears on the interface. The generated configuration reference documents the interface surface.
Reading the kernel dataplane
Every other IPsec command reports what the IKE engine believes it installed. The show vpn ipsec dataplane commands read the kernel instead. Three failures become visible: a state
the kernel refused, a state it expired, and a policy that outlived its owner.
| Command | What it reads |
|---|---|
show vpn ipsec dataplane sa [spi <spi>] |
The Security Association Database: SPI, addresses, if-id, mode, algorithms, replay window, byte and packet counters, timestamps, and the df-bit, dscp-map and icmp-error-check the SA holds. spi <spi> selects every matching SPI, which can occur under different destinations or interfaces. SPI 0 is refused under RFC 4303 Section 2.1 |
show vpn ipsec dataplane policy |
The Security Policy Database: selector prefixes and ports, direction, priority, upper-layer protocol, if-id, if-index, tunnel endpoints, and the peer that installed each policy. spd names the SPD holding the policy (node for if-id 0, the XFRM interface a peer binds with vti bind, or if-id <n> for one no bound interface has), and role names the job Ze installed it for (catch-all, interface-catch-all, interface-exemption, ike-bypass, child-sa, operator, ospf). A policy Ze did not install reports its owner and its role as unknown |
show vpn ipsec dataplane drift |
Each expected Child SA identity absent from the kernel. The command exits non-zero when it finds drift, so a script can test it |
RFC 4301 Section 4.4 keeps the SPD and the SAD separate, and so does this command tree.
Each SA row also carries the options the SA holds, read back from the kernel, never from
the config: df-bit (copy or clear, RFC 4301 Section 8.1), dscp-map (copy, or the
fixed outer DSCP as a decimal value, Section 5.1.2.1) and icmp-error-check (true or
false, Section 6.2). On Linux they come from the state's XFRM_STATE_NOPMTUDISC,
XFRM_SA_XFLAG_DONT_ENCAP_DSCP and XFRM_STATE_ICMP flags. The row says what the kernel
does, which can differ from the config: the kernel clears the DF bit of an IPv4 outbound
SA whenever net.ipv4.ip_no_pmtu_disc is set, and the row then reads df-bit clear. A backend that
cannot read them back sets options-known: false and the three keys to null.
An SA row's direction is in or out only when the kernel recorded one for the state
(its XFRMA_SA_DIR attribute), and unknown otherwise. A known direction nulls the
options that side cannot carry: an in row shows df-bit and dscp-map as null, an out
row shows icmp-error-check as null. Ze installs its states without a direction, so its own
rows read unknown and show all three options as the kernel holds them.
Each policy row carries icmp-error-return (true or false): whether the kernel may send
an outbound ICMP error that no SA and no entry carries through the SA this entry resolves to,
the RFC 4301 Section 6.2 mapping. On Linux it is the policy's XFRM_POLICY_ICMP flag, which Ze
sets on the outbound policy of a peer with icmp-error-check true.
A read that cannot happen is an error, never an empty table. No backend loaded, a backend that cannot enumerate, and a process without CAP_NET_ADMIN each get their own message. An empty table answers "is my tunnel programmed?" with "no", and that is the wrong answer when the truth is that nobody asked the kernel.
Drift compares expected SA identities: SPI, destination, protocol, and XFRM interface ID. Extra kernel SAs are permitted during rekey. RFC 7296 Section 2.8 permits the old and new Child SAs to coexist until cleanup.
show vpn ipsec sa and show vpn ipsec peer name <name> carry the kernel counters in each
child SA object: bytes-in, packets-in, bytes-out, and packets-out. They come from
the kernel because the IKE engine never sees ESP payload. A failed or changing
observation sets counters-known: false and all counters to null. A stable SAD
read sets counters-known: true; a missing SA then has null counters, while an
SA that carried no traffic has numeric zero counters.
The health registry uses the same observation. A missing expected Child SA
reports degraded and names the peer. An unreadable or changing observation
also reports degraded, with an unknown-dataplane diagnosis.
IPsec is an enrolled kernel capability. When the configuration installs a Security
Association and the kernel holds no XFRM dataplane, ze doctor reports
doctor-ipsec-xfrm-unavailable as an ERROR, ze refuses to start with the same message
and exit 1, and ze config validate fails. There is no override: a daemon that negotiates
a tunnel and encrypts nothing is the hazard this removes.
The probe opens the XFRM netlink socket, which needs no CAP_NET_ADMIN, and it reports
absence only for the errno that means the kernel carries no XFRM protocol. Every other
failure, a permission denial included, is doctor-ipsec-xfrm-unknown at warning severity
and ze still starts: no kernel rebuild fixes a privilege fault.
An empty vpn { ipsec { } } block installs no Security Association, so it is not IPsec in
use. It gates nothing, warns about no kernel module, and binds no IKE listener.
doctor-ipsec-udp-encap is an error, and it covers a NAT-T socket that would not bind as
well as one the kernel will not decapsulate through. Both leave a tunnel that establishes
and carries no traffic.
CLI
| Command | Description |
|---|---|
show vpn ipsec status |
Tunnel and peer status summary |
show vpn ipsec sa |
Active IKE and Child SAs, including algorithms, kernel byte and packet counters, rekey timers, SPIs, NAT detection, and initiator role |
show vpn ipsec peer name <name> |
Detail for one configured peer |
show vpn ipsec dataplane sa [spi <spi>] |
The SAs the kernel holds. See Reading the kernel dataplane |
show vpn ipsec dataplane policy |
The policies the kernel holds |
show vpn ipsec dataplane drift |
Child SAs the engine expects that the kernel does not hold. Exits non-zero on drift |
clear vpn ipsec sa all, clear vpn ipsec sa peer <name> |
Tear down and re-establish every SA, or one peer's. The bare clear vpn ipsec sa is refused and names both forms |
monitor vpn ipsec |
Stream sa-up, sa-down, child-up, child-down, and child-rekey lifecycle events |
show pki certificates |
List loaded certificates with expiry information |
When scripting these commands with | json, decode the rendered answer rather
than the handler's internal wrapper. The JSON formatter unwraps a single-key
object whose value is an array:
Command with | json |
JSON shape |
|---|---|
show vpn ipsec sa |
Array of SA records; [] when none exist |
show vpn ipsec dataplane sa |
Array of kernel SA records; [] when none exist |
show vpn ipsec dataplane drift |
[] when there is no drift; drift is a command error |
show vpn ipsec peer name <name> |
Object with peer-name and the ike-sas array |
show log recent level warn |
Object with count and the entries array, including each entry's structured attributes |
clear vpn ipsec sa peer <name> |
Object with action: "clear-peer" and peer |
The live demonstration validator uses these same rendered shapes for its absence, negotiation, kernel and refusal-log checks.
show vpn ipsec sa also reports peer-window-size, the number of outstanding requests
the peer promised in its SET_WINDOW_SIZE notification. Zero means the peer sent none, which
RFC 7296 Section 2.3 reads as a window of one. Ze holds one request outstanding and accepts
exactly one request id.
The child-sa object of show vpn ipsec sa describes the Child SA as installed.
esp-encryption and esp-integrity name the proposal the peer accepted: with two
proposals in the esp-group and a peer that accepts only the second, the payload names
the second. If Ze cannot resolve that proposal's transforms, which only a Ze defect
produces, esp-integrity is absent and esp-transform-error says why. mode is
tunnel or transport, udp-encapsulation says the SA receives
ESP inside UDP on the ports the IKE SA uses: Ze's NAT-T port (4500) and the port the
peer's authenticated IKE traffic comes from, which a NAT may have translated to any
port, and remote-address is the endpoint the SA was installed
on, which behind a NAT differs from the configured remote-address of the peer. Those
three, with the transform, are what size an ESP packet on the tunnel.
Both clear vpn ipsec sa forms send a best-effort encrypted IKE Delete before removing
local state. Initiator peers then re-establish immediately. If the UDP Delete is
lost, the normal DPD path still removes the stale remote SA.
Health and metrics
The IPsec component registers with the health registry. It reports healthy when all configured tunnels are established, degraded when some are down, and down when critical tunnels fail.
Prometheus exposes ze_ipsec_sa_count, ze_ipsec_tunnel_up{peer}, ze_ipsec_tunnel_degraded{peer}, and ze_ipsec_rekey_total{peer}.
ze_ipsec_error_notify_sent_total{type,protected} counts error notifications Ze sent, by
notify type and by whether the carrying message was encrypted.
ze_ipsec_error_notify_suppressed_total{reason} counts the ones a guard stopped, by the
name of that guard. Four reasons count IKE messages that failed their integrity check,
which Ze drops without answering and without changing the SA (RFC 7296 Section 2.4):
handshake-unauthenticated during the IKE_AUTH exchange, in either role;
established-unauthenticated on an established SA; invalid-msgid-unauthenticated for
an out-of-window request on an established SA; and held-successor-decrypt-failed on a
re-authenticated IKE SA held before adoption. A rising count means someone is sending
datagrams under the SPIs of a live SA, or a path is damaging them.
ze doctor warns under ipsec-unauthenticated-input for each peer whose handshake in
progress dropped such a message, naming the peer, how many were dropped and the
handshake state. The handshake keeps waiting for the peer's genuine answer, so the
tunnel comes up late or not at all while the forgeries win the race. The warning
clears when the handshake establishes or a new attempt starts.
ze doctor also warns under ipsec-peer-malformed-message for each peer whose live IKE
SA received messages that passed their integrity check and do not parse. Only the peer
can build such a message, so the defect is in the peer's IKE software: Ze drops it and
keeps the SA, but the exchange it carried is lost. Collect the peer's log and report it
to the peer's vendor.
Three more counters report the COOKIE challenge described under Denial-of-service protection. ze_ipsec_cookie_challenges_total{peer} counts the challenges Ze issues, ze_ipsec_cookie_verify_failures_total{peer} counts inbound cookies that did not verify, and ze_ipsec_sa_init_retries_total{peer,cause} counts the IKE_SA_INIT retries Ze sends, labeled cookie or invalid-ke-payload. A rising verify-failure count is either an attacker probing the half-open slot or a secret rotation catching an in-flight challenge. A rising retry count on the cookie cause is the signature of the forged-notify flood RFC 7296 Section 2.6 describes.
Two more gauges report kernel state. ze_ipsec_dataplane_sa_count{if_id} counts
SAs under each interface ID used by an installed Child SA.
ze_ipsec_dataplane_drift{peer} reads 1 when the kernel lacks an expected SA
identity. Kernel expiry or an external flush can produce drift while
ze_ipsec_tunnel_up still reports a successful install.
ze_ipsec_virtual_ip_leases{pool} counts the virtual IP addresses live IKE SAs
hold in each remote-access pool. ze doctor warns under ipsec-virtual-ip-pool
when one family of a pool is at least 90% held, because a full pool refuses the
next client with INTERNAL_ADDRESS_FAILURE; widen range or range6, or bind some
peers to another pool.
A failed or changing dataplane observation removes both gauge families' previous series. Absent series mean the observation is unknown, not that the kernel holds no SAs or that no drift exists. Peer removal also removes the peer's drift series and unused interface-ID series.
ze_ipsec_tunnel_up reads 1 only when the IKE SA is established and the Child SA is
installed in the dataplane. A tunnel whose ESP install the kernel refused reads
ze_ipsec_tunnel_up 0 and ze_ipsec_tunnel_degraded 1. Such a tunnel has a live
control plane and carries no encrypted traffic. Alert on the degraded gauge, because
the two gauges together separate a lost session from a session with no ESP.
The daemon logs child-sa: dataplane refused the ESP state, tunnel is degraded and carries no encrypted traffic when this happens.
Interop testing
The IKE implementation includes interop tests against strongSwan 6.1.0, built from the
upstream release on Alpine 3.24.3 (test/interop-ipsec/Dockerfile.strongswan).
The infrastructure in test/interop-ipsec/ drives strongSwan containers as remote
IKE peers. The scenarios cover:
| Area | Scenarios |
|---|---|
| Authentication | PSK, EAP-MSCHAPv2, EAP-TLS, and EAP-TLS over TLS 1.3 |
| Ze as responder | PSK, EAP-MSCHAPv2, EAP-TLS over TLS 1.3, IKE SA rekey started by strongSwan, and a fresh IKE_SA_INIT accepted beside an established SA |
| Rekey and teardown | Child SA rekey with make-before-break, clear vpn ipsec sa and re-establishment, and a Delete sent while the one request window is held |
| Negotiation | The INVALID_KE_PAYLOAD retry and the COOKIE challenge |
| Dataplane | A live Child SA whose peer changes ESP form mid-session, BGP routes exchanged with FRR over the tunnel, and IPv6 carried inside an IPv4 Child SA on an xfrm interface after strongSwan narrows a two-family proposal to ::/0 (vti-ipv6-inner-ipv4-outer) |
| NAT traversal | Transport mode and tunnel mode with ESP in UDP 4500, each measuring what Ze's stack does with the inner TCP and UDP checksum after decapsulation (RFC 3948 Section 3.1.2) |
| MOBIKE | mobike-initiator and mobike-responder remove the mobile peer's original outer address, retain the same IKE and Child SPIs, and require encrypted traffic in both directions after migration |
| Traffic selectors | Child SA rekey narrowing, an answer that narrows the initiator's proposal, ESN offered both ways, and a peer reload that narrows |
There is no certificate-only (mode x509) scenario. The certificate paths are proven by
unit tests and by the EAP-TLS scenarios, which authenticate both ends with certificates.
rfc/short/rfc7296.md records the extracted requirements and their tagged-test
status. Those unit checks and the independent-peer scenarios cover different
boundaries; neither is a claim that every IKE extension is implemented.
See also
- The generated configuration reference covers every IPsec and XFRM configuration leaf.
- Monitoring covers the health registry and operational visibility.
- Feature inventory shows the maturity of each IKE and IPsec capability.
A WAN address that comes and goes
A CPE often dials its tunnel from a PPPoE or DHCP WAN whose address does not exist at boot and can change on every reconnect. Ze follows it.
| You write | Local address of a peer that names no local-address |
|---|---|
vpn ipsec interface <name> |
The interface's first IPv4 address, followed as it changes |
Neither interface nor local-address |
The source address the route to the remote selects, looked up at the start of every connection attempt |
With interface set:
- At boot with no address yet, Ze warns, starts the peers that carry their own
local-address, and holds the others.ze doctorreports each waiting peer (checkipsec-interface-address). - When the address appears, the waiting peers start from it.
- When it changes, those peers restart from the new address, and their old Child SAs are removed.
- When it leaves, those peers stop, remove their Child SAs, and wait.
- A peer with its own
local-addresshas its own socket and is never restarted by any of this.
Ze hears these changes from the kernel's interface address table, so it follows
the interface whether or not the configuration has an interface block for it,
and also when the interface does not exist yet at boot.
An interface that is deleted, as ppp0 is when a PPPoE session ends, holds no
address: its peers stop and wait exactly as when the address leaves, and start
again when the interface returns with an address. Ze logs one warning when the
interface goes missing, not one for every address change while it stays
missing. A read of the interface that fails for another reason (a netlink
error) is not taken as absence: the running peers are kept, and Ze logs a
warning.
A reload whose interface has no IPv4 address is still refused: an address that arrives later is followed without a commit.
local-address takes an IP address and nothing else. local-address any is
refused; leave the leaf out instead.
remote-address may be a DNS name. It is resolved at the start of every
connection attempt: a name that does not resolve yet is retried with the
reconnect backoff (1 s, doubling to 60 s, never giving up), and the address it
resolves to is the one NAT detection, the Child SA and transport mode use. A
respond peer configured by name accepts an initiation from any address the
name resolved to at the last refresh (every 60 s and after each commit); an
incoming packet never causes a DNS query.
On a host with several addresses, the route-chosen source is also the address
replies to an initiating peer leave from, which is not always the address the
request reached (RFC 7296 Section 2.11; tracked by
plan/release/fixes/spec-rfcgate-1b-rfc7296-pilot-deferred-ike-source-address.md).