path: root/src/swanctl/swanctl.conf.5.main

.TP
.B connections
.br
Section defining IKE connection configurations.

The connections section defines IKE connection configurations, each in its own
subsections. In the keyword description below, the connection is named
.RI "" "<conn>" ","
but an arbitrary yet unique connection name can be chosen for each connection
subsection.

.TP
.B connections.<conn>
.br
Section for an IKE connection named <conn>.

.TP
.BR connections.<conn>.version " [0]"
IKE major version to use for connection.
.RI "" "1" ""
uses IKEv1 aka ISAKMP,
.RI "" "2" ""
uses
IKEv2. A connection using the default of
.RI "" "0" ""
accepts both IKEv1 and IKEv2 as
responder, and initiates the connection actively with IKEv2.

.TP
.BR connections.<conn>.local_addrs " [%any]"
Local address(es) to use for IKE communication, comma separated. Takes single
IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.

As initiator, the first non\-range/non\-subnet is used to initiate the connection
from. As responder, the local destination address must match at least to one of
the specified addresses, subnets or ranges.

.TP
.BR connections.<conn>.remote_addrs " [%any]"
Remote address(es) to use for IKE communication, comma separated. Takes single
IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.

As initiator, the first non\-range/non\-subnet is used to initiate the connection
to. As responder, the initiator source address must match at least to one of the
specified addresses, subnets or ranges.

To initiate a connection, at least one specific address or DNS name must be
specified.

.TP
.BR connections.<conn>.local_port " [500]"
Local UPD port for IKE communication. By default the port of the socket backend
is used, which is usually
.RI "" "500" "."
If port
.RI "" "500" ""
is used, automatic IKE port
floating to port 4500 is used to work around NAT issues.

Using a non\-default local IKE port requires support from the socket backend in
use (socket\-dynamic).

.TP
.BR connections.<conn>.remote_port " [500]"
Remote UPD port for IKE communication. If the default of port
.RI "" "500" ""
is used,
automatic IKE port floating to port 4500 is used to work around NAT issues.

.TP
.BR connections.<conn>.proposals " [default]"
A proposal is a set of algorithms. For non\-AEAD algorithms, this includes for
IKE an encryption algorithm, an integrity algorithm, a pseudo random function
and a Diffie\-Hellman group. For AEAD algorithms, instead of encryption and
integrity algorithms, a combined algorithm is used.

In IKEv2, multiple algorithms of the same kind can be specified in a single
proposal, from which one gets selected. In IKEv1, only one algorithm per kind is
allowed per proposal, more algorithms get implicitly stripped. Use multiple
proposals to offer different algorithms combinations in IKEv1.

Algorithm keywords get separated using dashes. Multiple proposals may be
separated by commas. The special value
.RI "" "default" ""
forms a default proposal of
supported algorithms considered safe, and is usually a good choice for
interoperability.

.TP
.BR connections.<conn>.vips " []"
Comma separated list of virtual IPs to request in IKEv2 configuration payloads
or IKEv1 Mode Config. The wildcard addresses
.RI "" "0.0.0.0" ""
and
.RI "" "::" ""
request an
arbitrary address, specific addresses may be defined. The responder may return a
different address, though, or none at all.

.TP
.BR connections.<conn>.aggressive " [no]"
Enables Aggressive Mode instead of Main Mode with Identity Protection.
Aggressive Mode is considered less secure, because the ID and HASH payloads are
exchanged unprotected. This allows a passive attacker to snoop peer identities,
and even worse, start dictionary attacks on the Preshared Key.

.TP
.BR connections.<conn>.pull " [yes]"
If the default of
.RI "" "yes" ""
is used, Mode Config works in pull mode, where the
initiator actively requests a virtual IP. With
.RI "" "no" ","
push mode is used, where
the responder pushes down a virtual IP to the initiating peer.

Push mode is currently supported for IKEv1, but not in IKEv2. It is used by a
few implementations only, pull mode is recommended.

.TP
.BR connections.<conn>.encap " [no]"
To enforce UDP encapsulation of ESP packets, the IKE daemon can fake the NAT
detection payloads. This makes the peer believe that NAT takes place on the
path, forcing it to encapsulate ESP packets in UDP.

Usually this is not required, but it can help to work around connectivity issues
with too restrictive intermediary firewalls.

.TP
.BR connections.<conn>.mobike " [yes]"
Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2
connections, and allows mobility of clients and multi\-homing on servers by
migrating active IPsec tunnels.

Usually keeping MOBIKE enabled is unproblematic, as it is not used if the peer
does not indicate support for it. However, due to the design of MOBIKE, IKEv2
always floats to port 4500 starting from the second exchange. Some
implementations don't like this behavior, hence it can be disabled.

.TP
.BR connections.<conn>.dpd_delay " [0s]"
Interval to check the liveness of a peer actively using IKEv2 INFORMATIONAL
exchanges or IKEv1 R_U_THERE messages. Active DPD checking is only enforced if
no IKE or ESP/AH packet has been received for the configured DPD delay.

.TP
.BR connections.<conn>.dpd_timeout " [0s]"
Charon by default uses the normal retransmission mechanism and timeouts to check
the liveness of a peer, as all messages are used for liveness checking. For
compatibility reasons, with IKEv1 a custom interval may be specified; this
option has no effect on connections using IKE2.

.TP
.BR connections.<conn>.fragmentation " [no]"
The default of
.RI "" "no" ""
disables IKEv1 fragmentation mechanism,
.RI "" "yes" ""
enables it if
support has been indicated by the peer.
.RI "" "force" ""
enforces fragmentation if
required even before the peer had a chance to indicate support for it.

IKE fragmentation is currently not supported with IKEv2.

.TP
.BR connections.<conn>.send_certreq " [yes]"
Send certificate request payloads to offer trusted root CA certificates to the
peer. Certificate requests help the peer to choose an appropriate
certificate/private key for authentication and are enabled by default.

Disabling certificate requests can be useful if too many trusted root CA
certificates are installed, as each certificate request increases the size of
the initial IKE packets.

.TP
.BR connections.<conn>.send_cert " [ifasked]"
Send certificate payloads when using certificate authentication. With the
default of
.RI "" "ifasked" ""
the daemon sends certificate payloads only if certificate
requests have been received.
.RI "" "never" ""
disables sending of certificate payloads
altogether,
.RI "" "always" ""
causes certificate payloads to be sent unconditionally
whenever certificate authentication is used.

.TP
.BR connections.<conn>.keyingtries " [1]"
Number of retransmission sequences to perform during initial connect. Instead of
giving up initiation after the first retransmission sequence with the default
value of
.RI "" "1" ","
additional sequences may be started according to the configured
value. A value of
.RI "" "0" ""
initiates a new sequence until the connection establishes
or fails with a permanent error.

.TP
.BR connections.<conn>.unique " [no]"
Connection uniqueness policy to enforce. To avoid multiple connections from the
same user, a uniqueness policy can be enforced. The value
.RI "" "never" ""
does never
enforce such a policy, even if a peer included INITIAL_CONTACT notification
messages, whereas
.RI "" "no" ""
replaces existing connections for the same identity if a
new one has the INITIAL_CONTACT notify.
.RI "" "keep" ""
rejects new connection attempts
if the same user already has an active connection,
.RI "" "replace" ""
deletes any
existing connection if a new one for the same user gets established.

To compare connections for uniqueness, the remote IKE identity is used. If EAP
or XAuth authentication is involved, the EAP\-Identity or XAuth username is used
to enforce the uniqueness policy instead.

On initiators this setting specifies whether an INITIAL_CONTACT notify is sent
during IKE_AUTH if no existing connection is found with the remote peer
(determined by the identities of the first authentication round). Only if set to
.RI "" "keep" ""
or
.RI "" "replace" ""
will the client send a notify.

.TP
.BR connections.<conn>.reauth_time " [0s]"
Time to schedule IKE reauthentication. IKE reauthentication recreates the
IKE/ISAKMP SA from scratch and re\-evaluates the credentials. In asymmetric
configurations (with EAP or configuration payloads) it might not be possible to
actively reauthenticate as responder. The IKEv2 reauthentication lifetime
negotiation can instruct the client to perform reauthentication.

Reauthentication is disabled by default. Enabling it usually may lead to small
connection interruptions, as strongSwan uses a break\-before\-make policy with
IKEv2 to avoid any conflicts with associated tunnel resources.

.TP
.BR connections.<conn>.rekey_time " [4h]"
IKE rekeying refreshes key material using a Diffie\-Hellman exchange, but does
not re\-check associated credentials. It is supported in IKEv2 only, IKEv1
performs a reauthentication procedure instead.

With the default value IKE rekeying is scheduled every 4 hours, minus the
configured
.RB "" "rand_time" "."
If a
.RB "" "reauth_time" ""
is configured,
.RB "" "rekey_time" ""
defaults to zero disabling rekeying; explicitly set both to enforce rekeying and
reauthentication.

.TP
.BR connections.<conn>.over_time " [10% of rekey_time/reauth_time]"
Hard IKE_SA lifetime if rekey/reauth does not complete, as time. To avoid having
an IKE/ISAKMP kept alive if IKE reauthentication or rekeying fails perpetually,
a maximum hard lifetime may be specified. If the IKE_SA fails to rekey or
reauthenticate within the specified time, the IKE_SA gets closed.

In contrast to CHILD_SA rekeying,
.RB "" "over_time" ""
is relative in time to the
.RB "" "rekey_time" ""
.RI "" "and" ""
.RB "" "reauth_time" ""
values, as it applies to both.

The default is 10% of the longer of
.RB "" "rekey_time" ""
and
.RB "" "reauth_time" "."


.TP
.BR connections.<conn>.rand_time " [over_time]"
Time range from which to choose a random value to subtract from rekey/reauth
times. To avoid having both peers initiating the rekey/reauth procedure
simultaneously, a random time gets subtracted from the rekey/reauth times.

The default is equal to the configured
.RB "" "over_time" "."


.TP
.BR connections.<conn>.pools " []"
Comma separated list of named IP pools to allocate virtual IP addresses and
other configuration attributes from. Each name references a pool by name from
either the
.RB "" "pools" ""
section or an external pool.

.TP
.B connections.<conn>.local<suffix>
.br
Section for a local authentication round. A local authentication round defines
the rules how authentication is performed for the local peer. Multiple rounds
may be defined to use IKEv2 RFC 4739 Multiple Authentication or IKEv1 XAuth.

Each round is defined in a section having
.RI "" "local" ""
as prefix, and an optional
unique suffix. To define a single authentication round, the suffix may be
omitted.

.TP
.BR connections.<conn>.local<suffix>.certs " []"
Comma separated list of certificate candidates to use for authentication. The
certificates may use a relative path from the
.RB "" "swanctl" ""
.RI "" "x509" ""
directory, or
an absolute path.

The certificate used for authentication is selected based on the received
certificate request payloads. If no appropriate CA can be located, the first
certificate is used.

.TP
.BR connections.<conn>.local<suffix>.auth " [pubkey]"
Authentication to perform locally.
.RI "" "pubkey" ""
uses public key authentication using
a private key associated to a usable certificate.
.RI "" "psk" ""
uses pre\-shared key
authentication. The IKEv1 specific
.RI "" "xauth" ""
is used for XAuth or Hybrid
authentication, while the IKEv2 specific
.RI "" "eap" ""
keyword defines EAP
authentication.

For
.RI "" "xauth" ","
a specific backend name may be appended, separated by a dash. The
appropriate
.RI "" "xauth" ""
backend is selected to perform the XAuth exchange. For
traditional XAuth, the
.RI "" "xauth" ""
method is usually defined in the second
authentication round following an initial
.RI "" "pubkey" ""
(or
.RI "" "psk" ")"
round. Using
.RI "" "xauth" ""
in the first round performs Hybrid Mode client authentication.

For
.RI "" "eap" ","
a specific EAP method name may be appended, separated by a dash. An
EAP module implementing the appropriate method is selected to perform the EAP
conversation.

.TP
.BR connections.<conn>.local<suffix>.id " []"
IKE identity to use for authentication round. When using certificate
authentication, the IKE identity must be contained in the certificate, either as
subject or as subjectAltName.

The identity can be an IP address, a fully\-qualified domain name, an email
address or a Distinguished Name for which the ID type is determined
automatically and the string is converted to the appropriate encoding. To
enforce a specific identity type, a prefix may be used, followed by a colon (:).
If the number sign (#) follows the colon, the remaining data is interpreted as
hex encoding, otherwise the string is used as\-is as the identification data.
Note that this implies that no conversion is performed for non\-string
identities. For example,
.RI "" "ipv4:10.0.0.1" ""
does not create a valid ID_IPV4_ADDR
IKE identity, as it does not get converted to binary 0x0a000001. Instead, one
could use
.RI "" "ipv4:#0a000001" ""
to get a valid identity, but just using the implicit
type with automatic conversion is usually simpler. The same applies to the ASN1
encoded types. The following prefixes are known:
.RI "" "ipv4" ","
.RI "" "ipv6" ","
.RI "" "rfc822" ","
.RI "" "email" ","
.RI "" "userfqdn" ","
.RI "" "fqdn" ","
.RI "" "dns" ","
.RI "" "asn1dn" ","
.RI "" "asn1gn" ""
and
.RI "" "keyid" "."
Custom type
prefixes may be specified by surrounding the numerical type value by curly
brackets.

.TP
.BR connections.<conn>.local<suffix>.eap_id " [id]"
Client EAP\-Identity to use in EAP\-Identity exchange and the EAP method.

.TP
.BR connections.<conn>.local<suffix>.aaa_id " [remote-id]"
Server side EAP\-Identity to expect in the EAP method. Some EAP methods, such as
EAP\-TLS, use an identity for the server to perform mutual authentication. This
identity may differ from the IKE identity, especially when EAP authentication is
delegated from the IKE responder to an AAA backend.

For EAP\-(T)TLS, this defines the identity for which the server must provide a
certificate in the TLS exchange.

.TP
.BR connections.<conn>.local<suffix>.xauth_id " [id]"
Client XAuth username used in the XAuth exchange.

.TP
.B connections.<conn>.remote<suffix>
.br
Section for a remote authentication round. A remote authentication round defines
the constraints how the peers must authenticate to use this connection. Multiple
rounds may be defined to use IKEv2 RFC 4739 Multiple Authentication or IKEv1
XAuth.

Each round is defined in a section having
.RI "" "remote" ""
as prefix, and an optional
unique suffix. To define a single authentication round, the suffix may be
omitted.

.TP
.BR connections.<conn>.remote<suffix>.id " [%any]"
IKE identity to expect for authentication round. Refer to the
.RI "" "local" ""
.RI "" "id" ""
section for details.

.TP
.BR connections.<conn>.remote<suffix>.groups " []"
Comma separated authorization group memberships to require. The peer must prove
membership to at least one of the specified groups. Group membership can be
certified by different means, for example by appropriate Attribute Certificates
or by an AAA backend involved in the authentication.

.TP
.BR connections.<conn>.remote<suffix>.certs " []"
Comma separated list of certificates to accept for authentication. The
certificates may use a relative path from the
.RB "" "swanctl" ""
.RI "" "x509" ""
directory, or
an absolute path.

.TP
.BR connections.<conn>.remote<suffix>.cacerts " []"
Comma separated list of CA certificates to accept for authentication. The
certificates may use a relative path from the
.RB "" "swanctl" ""
.RI "" "x509ca" ""
directory, or
an absolute path.

.TP
.BR connections.<conn>.remote<suffix>.revocation " [relaxed]"
Certificate revocation policy for CRL or OCSP revocation.

A
.RI "" "strict" ""
revocation policy fails if no revocation information is available,
i.e. the certificate is not known to be unrevoked.

.RI "" "ifuri" ""
fails only if a CRL/OCSP URI is available, but certificate revocation
checking fails, i.e. there should be revocation information available, but it
could not be obtained.

The default revocation policy
.RI "" "relaxed" ""
fails only if a certificate is revoked,
i.e. it is explicitly known that it is bad.

.TP
.BR connections.<conn>.remote<suffix>.auth " [pubkey]"
Authentication to expect from remote. See the
.RB "" "local" ""
sections
.RB "" "auth" ""
keyword description about the details of supported mechanisms.

.TP
.B connections.<conn>.children.<child>
.br
CHILD_SA configuration sub\-section. Each connection definition may have one or
more sections in its
.RI "" "children" ""
subsection. The section name defines the name of
the CHILD_SA configuration, which must be unique within the connection.

.TP
.BR connections.<conn>.children.<child>.ah_proposals " []"
AH proposals to offer for the CHILD_SA. A proposal is a set of algorithms. For
AH, this includes an integrity algorithm and an optional Diffie\-Hellman group.
If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial negotiation
uses a separate Diffie\-Hellman exchange using the specified group.

In IKEv2, multiple algorithms of the same kind can be specified in a single
proposal, from which one gets selected. In IKEv1, only one algorithm per kind is
allowed per proposal, more algorithms get implicitly stripped. Use multiple
proposals to offer different algorithms combinations in IKEv1.

Algorithm keywords get separated using dashes. Multiple proposals may be
separated by commas. The special value
.RI "" "default" ""
forms a default proposal of
supported algorithms considered safe, and is usually a good choice for
interoperability. By default no AH proposals are included, instead ESP is
proposed.

.TP
.BR connections.<conn>.children.<child>.esp_proposals " [default]"
ESP proposals to offer for the CHILD_SA. A proposal is a set of algorithms. For
ESP non\-AEAD proposals, this includes an integrity algorithm, an encryption
algorithm, an optional Diffie\-Hellman group and an optional Extended Sequence
Number Mode indicator. For AEAD proposals, a combined mode algorithm is used
instead of the separate encryption/integrity algorithms.

If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial (non
IKE_AUTH piggybacked) negotiation uses a separate Diffie\-Hellman exchange using
the specified group. Extended Sequence Number support may be indicated with the
.RI "" "esn" ""
and
.RI "" "noesn" ""
values, both may be included to indicate support for both
modes. If omitted,
.RI "" "noesn" ""
is assumed.

In IKEv2, multiple algorithms of the same kind can be specified in a single
proposal, from which one gets selected. In IKEv1, only one algorithm per kind is
allowed per proposal, more algorithms get implicitly stripped. Use multiple
proposals to offer different algorithms combinations in IKEv1.

Algorithm keywords get separated using dashes. Multiple proposals may be
separated by commas. The special value
.RI "" "default" ""
forms a default proposal of
supported algorithms considered safe, and is usually a good choice for
interoperability. If no algorithms are specified for AH nor ESP, the
.RI "" "default" ""
set of algorithms for ESP is included.

.TP
.BR connections.<conn>.children.<child>.local_ts " [dynamic]"
Comma separated list of local traffic selectors to include in CHILD_SA. Each
selector is a CIDR subnet definition, followed by an optional proto/port
selector. The special value
.RI "" "dynamic" ""
may be used instead of a subnet
definition, which gets replaced by the tunnel outer address or the virtual IP,
if negotiated. This is the default.

A protocol/port selector is surrounded by opening and closing square brackets.
Between these brackets, a numeric or
.RB "" "getservent" "(3)"
protocol name may be
specified. After the optional protocol restriction, an optional port restriction
may be specified, separated by a slash. The port restriction may be numeric, a
.RB "" "getservent" "(3)"
service name, or the special value
.RI "" "opaque" ""
for RFC 4301
OPAQUE selectors. Port ranges may be specified as well, none of the kernel
backends currently support port ranges, though.

Unless the Unity extension is used, IKEv1 supports the first specified selector
only. IKEv1 uses very similar traffic selector narrowing as it is supported in
the IKEv2 protocol.

.TP
.BR connections.<conn>.children.<child>.remote_ts " [dynamic]"
Comma separated list of remote selectors to include in CHILD_SA. See
.RB "" "local_ts" ""
for a description of the selector syntax.

.TP
.BR connections.<conn>.children.<child>.rekey_time " [1h]"
Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes key material,
optionally using a Diffie\-Hellman exchange if a group is specified in the
proposal.

To avoid rekey collisions initiated by both ends simultaneously, a value in the
range of
.RB "" "rand_time" ""
gets subtracted to form the effective soft lifetime.

By default CHILD_SA rekeying is scheduled every hour, minus
.RB "" "rand_time" "."


.TP
.BR connections.<conn>.children.<child>.life_time " [rekey_time + 10%]"
Maximum lifetime before CHILD_SA gets closed. Usually this hard lifetime is
never reached, because the CHILD_SA gets rekeyed before. If that fails for
whatever reason, this limit closes the CHILD_SA.

The default is 10% more than the
.RB "" "rekey_time" "."


.TP
.BR connections.<conn>.children.<child>.rand_time " [life_time - rekey_time]"
Time range from which to choose a random value to subtract from
.RB "" "rekey_time" "."
The default is the difference between
.RB "" "life_time" ""
and
.RB "" "rekey_time" "."


.TP
.BR connections.<conn>.children.<child>.rekey_bytes " [0]"
Number of bytes processed before initiating CHILD_SA rekeying. CHILD_SA rekeying
refreshes key material, optionally using a Diffie\-Hellman exchange if a group is
specified in the proposal.

To avoid rekey collisions initiated by both ends simultaneously, a value in the
range of
.RB "" "rand_bytes" ""
gets subtracted to form the effective soft volume limit.

Volume based CHILD_SA rekeying is disabled by default.

.TP
.BR connections.<conn>.children.<child>.life_bytes " [rekey_bytes + 10%]"
Maximum bytes processed before CHILD_SA gets closed. Usually this hard volume
limit is never reached, because the CHILD_SA gets rekeyed before. If that fails
for whatever reason, this limit closes the CHILD_SA.

The default is 10% more than
.RB "" "rekey_bytes" "."


.TP
.BR connections.<conn>.children.<child>.rand_bytes " [life_bytes - rekey_bytes]"
Byte range from which to choose a random value to subtract from
.RB "" "rekey_bytes" "."
The default is the difference between
.RB "" "life_bytes" ""
and
.RB "" "rekey_bytes" "."


.TP
.BR connections.<conn>.children.<child>.rekey_packets " [0]"
Number of packets processed before initiating CHILD_SA rekeying. CHILD_SA
rekeying refreshes key material, optionally using a Diffie\-Hellman exchange if a
group is specified in the proposal.

To avoid rekey collisions initiated by both ends simultaneously, a value in the
range of
.RB "" "rand_packets" ""
gets subtracted to form the effective soft packet
count limit.

Packet count based CHILD_SA rekeying is disabled by default.

.TP
.BR connections.<conn>.children.<child>.life_packets " [rekey_packets + 10%]"
Maximum number of packets processed before CHILD_SA gets closed. Usually this
hard packets limit is never reached, because the CHILD_SA gets rekeyed before.
If that fails for whatever reason, this limit closes the CHILD_SA.

The default is 10% more than
.RB "" "rekey_bytes" "."


.TP
.BR connections.<conn>.children.<child>.rand_packets " [life_packets - rekey_packets]"
Packet range from which to choose a random value to subtract from
.RB "" "rekey_packets" "."
The default is the difference between
.RB "" "life_packets" ""
and
.RB "" "rekey_packets" "."


.TP
.BR connections.<conn>.children.<child>.updown " []"
Updown script to invoke on CHILD_SA up and down events.

.TP
.BR connections.<conn>.children.<child>.hostaccess " [yes]"
Hostaccess variable to pass to
.RB "" "updown" ""
script.

.TP
.BR connections.<conn>.children.<child>.mode " [tunnel]"
IPsec Mode to establish CHILD_SA with.
.RI "" "tunnel" ""
negotiates the CHILD_SA in IPsec
Tunnel Mode, whereas
.RI "" "transport" ""
uses IPsec Transport Mode.
.RI "" "beet" ""
is the Bound
End to End Tunnel mixture mode, working with fixed inner addresses without the
need to include them in each packet.

Both
.RI "" "transport" ""
and
.RI "" "beet" ""
modes are subject to mode negotiation;
.RI "" "tunnel" ""
mode
is negotiated if the preferred mode is not available.

.RI "" "pass" ""
and
.RI "" "drop" ""
are used to install shunt policies, which explicitly bypass
the defined traffic from IPsec processing, or drop it, respectively.

.TP
.BR connections.<conn>.children.<child>.policies " [yes]"
Whether to install IPsec policies or not. Disabling this can be useful in some
scenarios e.g. MIPv6, where policies are not managed by the IKE daemon.

.TP
.BR connections.<conn>.children.<child>.dpd_action " [clear]"
Action to perform for this CHILD_SA on DPD timeout. The default
.RI "" "clear" ""
closes
the CHILD_SA and does not take further action.
.RI "" "trap" ""
installs a trap policy,
which will catch matching traffic and tries to re\-negotiate the tunnel
on\-demand.
.RI "" "restart" ""
immediately tries to re\-negotiate the CHILD_SA under a
fresh IKE_SA.

.TP
.BR connections.<conn>.children.<child>.ipcomp " [no]"
Enable IPComp compression before encryption. If enabled, IKE tries to negotiate
IPComp compression to compress ESP payload data prior to encryption.

.TP
.BR connections.<conn>.children.<child>.inactivity " [0s]"
Timeout before closing CHILD_SA after inactivity. If no traffic has been
processed in either direction for the configured timeout, the CHILD_SA gets
closed due to inactivity. The default value of
.RI "" "0" ""
disables inactivity checks.

.TP
.BR connections.<conn>.children.<child>.reqid " [0]"
Fixed reqid to use for this CHILD_SA. This might be helpful in some scenarios,
but works only if each CHILD_SA configuration is instantiated not more than
once. The default of
.RI "" "0" ""
uses dynamic reqids, allocated incrementally.

.TP
.BR connections.<conn>.children.<child>.mark_in " [0/0x00000000]"
Netfilter mark and mask for input traffic. On Linux Netfilter may require marks
on each packet to match an SA having that option set. This allows Netfilter
rules to select specific tunnels for incoming traffic. The special value
.RI "" "%unique" ""
sets a unique mark on each CHILD_SA instance.

An additional mask may be appended to the mark, separated by _/_. The default
mask if omitted is 0xffffffff.

.TP
.BR connections.<conn>.children.<child>.mark_out " [0/0x00000000]"
Netfilter mark and mask for output traffic. On Linux Netfilter may require marks
on each packet to match a policy having that option set. This allows Netfilter
rules to select specific tunnels for outgoing traffic. The special value
.RI "" "%unique" ""
sets a unique mark on each CHILD_SA instance.

An additional mask may be appended to the mark, separated by _/_. The default
mask if omitted is 0xffffffff.

.TP
.BR connections.<conn>.children.<child>.tfc_padding " [0]"
Pads ESP packets with additional data to have a consistent ESP packet size for
improved Traffic Flow Confidentiality. The padding defines the minimum size of
all ESP packets sent.

The default value of 0 disables TFC padding, the special value
.RI "" "mtu" ""
adds TFC
padding to create a packet size equal to the Path Maximum Transfer Unit.

.TP
.BR connections.<conn>.children.<child>.replay_window " [32]"
IPsec replay window to configure for this CHILD_SA. Larger values than the
default of 32 are supported using the Netlink backend only, a value of 0
disables IPsec replay protection.

.TP
.BR connections.<conn>.children.<child>.start_action " [none]"
Action to perform after loading the configuration. The default of
.RI "" "none" ""
loads
the connection only, which then can be manually initiated or used as a responder
configuration.

The value
.RI "" "trap" ""
installs a trap policy, which triggers the tunnel as soon as
matching traffic has been detected. The value
.RI "" "start" ""
initiates the connection
actively.

When unloading or replacing a CHILD_SA configuration having a
.RB "" "start_action" ""
different from
.RI "" "none" ","
the inverse action is performed. Configurations with
.RI "" "start" ""
get closed, while such with
.RI "" "trap" ""
get uninstalled.

.TP
.BR connections.<conn>.children.<child>.close_action " [none]"
Action to perform after a CHILD_SA gets closed by the peer. The default of
.RI "" "none" ""
does not take any action,
.RI "" "trap" ""
installs a trap policy for the CHILD_SA.
.RI "" "start" ""
tries to re\-create the CHILD_SA.

.RB "" "close_action" ""
does not provide any guarantee that the CHILD_SA is kept alive.
It acts on explicit close messages only, but not on negotiation failures. Use
trap policies to reliably re\-create failed CHILD_SAs.

.TP
.B secrets
.br
Section defining secrets for IKE/EAP/XAuth authentication and private key
decryption. The
.RB "" "secrets" ""
section takes sub\-sections having a specific prefix
which defines the secret type.

It is not recommended to define any private key decryption passphrases, as then
there is no real security benefit in having encrypted keys. Either store the key
unencrypted, or enter the keys manually when loading credentials.

.TP
.B secrets.eap<suffix>
.br
EAP secret section for a specific secret. Each EAP secret is defined in a unique
section having the
.RI "" "eap" ""
prefix. EAP secrets are used for XAuth authentication
as well.

.TP
.BR secrets.eap<suffix>.secret " []"
Value of the EAP/XAuth secret. It may either be an ASCII string, a hex encoded
string if it has a
.RI "" "0x" ""
prefix, or a Base64 encoded string if it has a
.RI "" "0s" ""
prefix in its value.

.TP
.BR secrets.eap<suffix>.id<suffix> " []"
Identity the EAP/XAuth secret belongs to. Multiple unique identities may be
specified, each having an
.RI "" "id" ""
prefix, if a secret is shared between multiple
users.

.TP
.B secrets.xauth<suffix>
.br
XAuth secret section for a specific secret.
.RB "" "xauth" ""
is just an alias for
.RB "" "eap" ","
secrets under both section prefixes are used for both EAP and XAuth
authentication.

.TP
.B secrets.ike<suffix>
.br
IKE preshared secret section for a specific secret. Each IKE PSK is defined in a
unique section having the
.RI "" "ike" ""
prefix.

.TP
.BR secrets.ike<suffix>.secret " []"
Value of the IKE preshared secret. It may either be an ASCII string, a hex
encoded string if it has a
.RI "" "0x" ""
prefix, or a Base64 encoded string if it has a
.RI "" "0s" ""
prefix in its value.

.TP
.BR secrets.ike<suffix>.id<suffix> " []"
IKE identity the IKE preshared secret belongs to. Multiple unique identities may
be specified, each having an
.RI "" "id" ""
prefix, if a secret is shared between multiple
peers.

.TP
.B secrets.rsa<suffix>
.br
Private key decryption passphrase for a key in the
.RI "" "rsa" ""
folder.

.TP
.BR secrets.rsa<suffix>.file " []"
File name in the
.RI "" "rsa" ""
folder for which this passphrase should be used.

.TP
.BR secrets.rsa<suffix>.secret " []"
Value of decryption passphrase for RSA key.

.TP
.B secrets.ecdsa<suffix>
.br
Private key decryption passphrase for a key in the
.RI "" "ecdsa" ""
folder.

.TP
.BR secrets.ecdsa<suffix>.file " []"
File name in the
.RI "" "ecdsa" ""
folder for which this passphrase should be used.

.TP
.BR secrets.ecdsa<suffix>.secret " []"
Value of decryption passphrase for ECDSA key.

.TP
.B secrets.pkcs8<suffix>
.br
Private key decryption passphrase for a key in the
.RI "" "pkcs8" ""
folder.

.TP
.BR secrets.pkcs8<suffix>.file " []"
File name in the
.RI "" "pkcs8" ""
folder for which this passphrase should be used.

.TP
.BR secrets.pkcs8<suffix>.secret " []"
Value of decryption passphrase for PKCS#8 key.

.TP
.B secrets.pkcs12<suffix>
.br
PKCS#12 decryption passphrase for a container in the
.RI "" "pkcs12" ""
folder.

.TP
.BR secrets.pkcs12<suffix>.file " []"
File name in the
.RI "" "pkcs12" ""
folder for which this passphrase should be used.

.TP
.BR secrets.pkcs12<suffix>.secret " []"
Value of decryption passphrase for PKCS#12 container.

.TP
.B pools
.br
Section defining named pools. Named pools may be referenced by connections with
the
.RB "" "pools" ""
option to assign virtual IPs and other configuration attributes.

.TP
.B pools.<name>
.br
Section defining a single pool with a unique name.

.TP
.BR pools.<name>.addrs " []"
Subnet or range defining addresses allocated in pool. Accepts a single CIDR
subnet defining the pool to allocate addresses from, or an address range
(<from>\-<to>).  Pools must be unique and non\-overlapping.

.TP
.BR pools.<name>.<attr> " []"
Comma separated list of additional attributes of type
.RB "" "<attr>" "."
The attribute
type may be one of
.RI "" "dns" ","
.RI "" "nbns" ","
.RI "" "dhcp" ","
.RI "" "netmask" ","
.RI "" "server" ","
.RI "" "subnet" ","
.RI "" "split_include" ""
and
.RI "" "split_exclude" ""
to define addresses or CIDR subnets for the
corresponding attribute types. Alternatively,
.RB "" "<attr>" ""
can be a numerical
identifier, for which string attribute values are accepted as well.

.TP
.B authorities
.br
Section defining attributes of certification authorities.

.TP
.B authorities.<name>
.br
Section defining a certification authority with a unique name.

.TP
.BR authorities.<name>.cacert " []"
The certificates may use a relative path from the
.RB "" "swanctl" ""
.RI "" "x509ca" ""
directory, or an absolute path.

.TP
.BR authorities.<name>.crl_uris " []"
Comma\-separated list of CRL distribution points (ldap, http, or file URI)

.TP
.BR authorities.<name>.ocsp_uris " []"
Comma\-separated list of OCSP URIs

.TP
.BR authorities.<name>.cert_uri_base " []"
Defines the base URI for the Hash and URL feature supported by IKEv2. Instead of
exchanging complete certificates, IKEv2 allows one to send an URI that resolves
to the DER encoded certificate. The certificate URIs are built by appending the
SHA1 hash of the DER encoded certificates to this base URI.