Project

General

Profile

updown Plugin

Purpose

The updown plugin invokes a script when an IKEv2 CHILD_SA or an IKEv1 Quick Mode gets established or deleted.

The plugin is enabled by default, but can be disabled using the

--disable-updown
to the ./configure option.

Configuration

To invoke the default updown script, the ipsec.conf option leftfirewall may be set to yes. The default updown script installs ACCEPT Netfilter rules on Linux by invoking iptables for the established traffic selectors, allowing default DROP policies. Please refer to the script for details

With the ipsec.conf leftupdown option, alternatively an external script can be invoked to install custom rules or perform other actions.

Behavior

The plugin allows the invocation of custom commands associated with CHILD_SA up and down events. The script is compatible to the updown script originally used in the pluto daemon. Please refer to the default updown for a description of the passed variables.

While pluto used the prepare* verbs to install routes, the updown plugin in charon does not invoke these hooks anymore. It does implicit route installation directly in the networking backend of the daemon. The plugin invokes the hook with the following verbs:

PLUTO_VERB Description
up-host CHILD_SA up event, where the negotiated local traffic selector is a single IPv4 host
up-host-v6 Same as up-host, but for a single IPv6 host
up-client Same as up-host, but the local traffic selector is an IPv4 subnet
up-client-v6 Same as up-client, but for an IPv6 subnet
down-host CHILD_SA down event, counterpart of up-host
down-host-v6 CHILD_SA down event, counterpart of up-host-v6
down-client CHILD_SA down event, counterpart of up-client
down-client-v6 CHILD_SA down event, counterpart of up-client-v6

Note that while CHILD_SA rekeying establishes a new CHILD_SA, the hooks do not get invoked.

With IKEv2, a negotiated CHILD_SA may contain multiple hosts or subnets in the negotiated traffic selectors. To keep compatibility with the scripts originally designed for IKEv1, the script gets invoked for each traffic selector combination once. This means with multiple traffic selectors, establishing/closing a CHILD_SA invokes the script more than once.

Logging

The default updown script additionally logs the CHILD_SA event to syslog. This behavior can be disabled by commenting out the VPN_LOGGING option in the script.

Alternatives

The updown script allows the installation of custom IPtables rules and is often very simple to implement custom logic. It has, however, some limitations for historical reasons, and might not scale very with many tunnels.

To accept traffic with default DROP policies, one may alternatively use global, non-tunnel specific rules matching IPsec traffic with the Netfilter policy match.