Ubuntu Manpage: swanctl.conf - swanctl configuration file

Provided by: strongswan-swanctl_5.9.5-2ubuntu2.3_amd64

NAME

       swanctl.conf - swanctl configuration file

DESCRIPTION

       swanctl.conf is the configuration file used by the swanctl(8) tool to load configurations and credentials
       into the strongSwan IKE daemon.

       For  a  description  of  the  basic  file  syntax,  including  how  to  reference  sections  or split the
       configuration in multiple files by including other files, refer to strongswan.conf(5).

TIME FORMATS

       For all options that define a time, the time is specified  in  seconds.  The  s,  m,  h  and  d  suffixes
       explicitly define the units for seconds, minutes, hours and days, respectively.

SETTINGS

The following settings can be used to configure connections, credentials and pools.

connections
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 <conn>, but an arbitrary yet unique connection
name can be chosen for each connection subsection.

connections.<conn>
Section for an IKE connection named <conn>.

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

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.

If FQDNs are assigned they are resolved every time a configuration lookup is done. If DNS
resolution times out, the lookup is delayed for that time.

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.

If FQDNs are assigned they are resolved every time a configuration lookup is done. If DNS
resolution times out, the lookup is delayed for that time.

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

connections.<conn>.local_port [500]
Local UDP port for IKE communication. By default the port of the socket backend is used, which is
usually 500. If port 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).

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

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 default forms a default proposal of supported algorithms considered safe, and is
usually a good choice for interoperability.

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

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.

connections.<conn>.pull [yes]
If the default of yes is used, Mode Config works in pull mode, where the initiator actively
requests a virtual IP. With 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.

connections.<conn>.dscp [000000]
Differentiated Services Field Codepoint to set on outgoing IKE packets for this connection. The
value is a six digit binary encoded string specifying the Codepoint to set, as defined in RFC
2474.

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.

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.

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.

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.

connections.<conn>.fragmentation [yes]
Use IKE fragmentation (proprietary IKEv1 extension or RFC 7383 IKEv2 fragmentation). Acceptable
values are yes (the default), accept, force and no. If set to yes, and the peer
supports it, oversized IKE messages will be sent in fragments. If set to accept, support for
fragmentation is announced to the peer but the daemon does not send its own messages in fragments.
If set to force (only supported for IKEv1) the initial IKE message will already be fragmented if
required. Finally, setting the option to no will disable announcing support for this feature.

Note that fragmented IKE messages sent by a peer are always accepted irrespective of the value of
this option (even when set to no).

connections.<conn>.childless [allow]
Use childless IKE_SA initiation (RFC 6023) for IKEv2. Acceptable values are allow (the default),
force and never. If set to allow, responders will accept childless IKE_SAs (as indicated via
notify in the IKE_SA_INIT response) while initiators continue to create regular IKE_SAs with the
first CHILD_SA created during IKE_AUTH, unless the IKE_SA is initiated explicitly without any
children (which will fail if the responder does not support or has disabled this extension). If
set to force, only childless initiation is accepted and the first CHILD_SA is created with a
separate CREATE_CHILD_SA exchange (e.g. to use an independent DH exchange for all CHILD_SAs).
Finally, setting the option to never disables support for childless IKE_SAs as responder.

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.

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

connections.<conn>.ppk_id []
String identifying the Postquantum Preshared Key (PPK) to be used.

connections.<conn>.ppk_required [no]
Whether a Postquantum Preshared Key (PPK) is required for this connection.

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 1, additional
sequences may be started according to the configured value. A value of 0 initiates a new sequence
until the connection establishes or fails with a permanent error.

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 never does never enforce such a policy, even if a
peer included INITIAL_CONTACT notification messages, whereas no replaces existing connections for
the same identity if a new one has the INITIAL_CONTACT notify. keep rejects new connection
attempts if the same user already has an active connection, 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). Unless set to never the client will send a notify.

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.

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 rand_time.
If a reauth_time is configured, rekey_time defaults to zero disabling rekeying; explicitly set
both to enforce rekeying and reauthentication.

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, over_time is relative in time to the rekey_time and reauth_time
values, as it applies to both.

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

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 over_time.

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 pools section or an external
pool.

connections.<conn>.if_id_in [0]
XFRM interface ID set on inbound policies/SA, can be overridden by child config, see there for
details.

connections.<conn>.if_id_out [0]
XFRM interface ID set on outbound policies/SA, can be overridden by child config, see there for
details.

connections.<conn>.mediation [no]
Whether this connection is a mediation connection, that is, whether this connection is used to
mediate other connections using the IKEv2 Mediation Extension. Mediation connections create no
CHILD_SA.

connections.<conn>.mediated_by []
The name of the connection to mediate this connection through. If given, the connection will be
mediated through the named mediation connection. The mediation connection must have mediation
enabled.

connections.<conn>.mediation_peer []
Identity under which the peer is registered at the mediation server, that is, the IKE identity the
other end of this connection uses as its local identity on its connection to the mediation server.
This is the identity we request the mediation server to mediate us with. Only relevant on
connections that set mediated_by. If it is not given, the remote IKE identity of the first
authentication round of this connection will be used.

connections.<conn>.local<suffix>
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 local as prefix, and an optional unique suffix. To
define a single authentication round, the suffix may be omitted.

connections.<conn>.local<suffix>.round [0]
Optional numeric identifier by which authentication rounds are sorted. If not specified rounds
are ordered by their position in the config file/VICI message.

connections.<conn>.local<suffix>.certs []
Comma separated list of certificate candidates to use for authentication. The certificates may use
a relative path from the swanctl 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.

connections.<conn>.local<suffix>.cert<suffix> []
Section for a certificate candidate to use for authentication. Certificates in certs are
transmitted as binary blobs, these sections offer more flexibility.

connections.<conn>.local<suffix>.cert<suffix>.file []
Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by
it.

Configure either this or handle, but not both, in one section.

connections.<conn>.local<suffix>.cert<suffix>.handle []
Hex-encoded CKA_ID of the certificate on a token.

Configure either this or file, but not both, in one section.

connections.<conn>.local<suffix>.cert<suffix>.slot []
Optional slot number of the token that stores the certificate.

connections.<conn>.local<suffix>.cert<suffix>.module []
Optional PKCS#11 module name.

connections.<conn>.local<suffix>.pubkeys []
Comma separated list of raw public key candidates to use for authentication. The public keys may
use a relative path from the swanctl pubkey directory or an absolute path.

Even though multiple local public keys could be defined in principle, only the first public key in
the list is used for authentication.

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

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

For 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.

If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific hash algorithms to
be used during IKEv2 authentication may be configured. To do so use ike: followed by a trust chain
signature scheme constraint (see description of the remote section's auth keyword). For example,
with ike:pubkey-sha384-sha256 a public key signature scheme with either SHA-384 or SHA-256 would
get used for authentication, in that order and depending on the hash algorithms supported by the
peer. If no specific hash algorithms are configured, the default is to prefer an algorithm that
matches or exceeds the strength of the signature key. If no constraints with ike: prefix are
configured any signature scheme constraint (without ike: prefix) will also apply to IKEv2
authentication, unless this is disabled in strongswan.conf(5). To use RSASSA-PSS signatures use
rsa/pss instead of pubkey or rsa as in e.g. ike:rsa/pss-sha256. If pubkey or rsa constraints are
configured RSASSA-PSS signatures will only be used if enabled in strongswan.conf(5).

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, 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 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: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns, asn1dn, asn1gn and
keyid. Custom type prefixes may be specified by surrounding the numerical type value by curly
brackets.

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

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.

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

connections.<conn>.remote<suffix>
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 remote as prefix, and an optional unique suffix. To
define a single authentication round, the suffix may be omitted.

connections.<conn>.remote<suffix>.round [0]
Optional numeric identifier by which authentication rounds are sorted. If not specified rounds
are ordered by their position in the config file/VICI message.

connections.<conn>.remote<suffix>.id [%any]
IKE identity to expect for authentication round. Refer to the local section's id keyword for
details.

It's possible to use wildcards to match remote identities (e.g. *@strongswan.org,
*.strongswan.org, or C=CH,O=strongSwan,CN=*). Connections with exact matches are preferred. When
using distinguished names with wildcards, the charon.rdn_matching option in strongswan.conf(5)
specifies how RDNs are matched.

connections.<conn>.remote<suffix>.eap_id [id]
Identity to use as peer identity during EAP authentication. If set to %any the EAP-Identity method
will be used to ask the client for an identity.

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.

connections.<conn>.remote<suffix>.cert_policy []
Comma separated list of certificate policy OIDs the peer's certificate must have. OIDs are
specified using the numerical dotted representation.

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

connections.<conn>.remote<suffix>.cert<suffix> []
Section for a certificate to accept for authentication. Certificates in certs are transmitted as
binary blobs, these sections offer more flexibility.

connections.<conn>.remote<suffix>.cert<suffix>.file []
Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by
it.

Configure either this or handle, but not both, in one section.

connections.<conn>.remote<suffix>.cert<suffix>.handle []
Hex-encoded CKA_ID of the certificate on a token.

Configure either this or file, but not both, in one section.

connections.<conn>.remote<suffix>.cert<suffix>.slot []
Optional slot number of the token that stores the certificate.

connections.<conn>.remote<suffix>.cert<suffix>.module []
Optional PKCS#11 module name.

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

connections.<conn>.remote<suffix>.cacert<suffix> []
Section for a CA certificate to accept for authentication. Certificates in cacerts are transmitted
as binary blobs, these sections offer more flexibility.

connections.<conn>.remote<suffix>.cacert<suffix>.file []
Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by
it.

Configure either this or handle, but not both, in one section.

connections.<conn>.remote<suffix>.cacert<suffix>.handle []
Hex-encoded CKA_ID of the CA certificate on a token.

Configure either this or file, but not both, in one section.

connections.<conn>.remote<suffix>.cacert<suffix>.slot []
Optional slot number of the token that stores the CA certificate.

connections.<conn>.remote<suffix>.cacert<suffix>.module []
Optional PKCS#11 module name.

connections.<conn>.remote<suffix>.ca_id []
The specified identity must be contained in one (intermediate) CA of the remote peer trustchain,
either as subject or as subjectAltName. This has the same effect as specifying cacerts to force
clients under a CA to specific connections; it does not require the CA certificate to be available
locally, and can be received from the peer during the IKE exchange.

connections.<conn>.remote<suffix>.pubkeys []
Comma separated list of raw public keys to accept for authentication. The public keys may use a
relative path from the swanctl pubkey directory or an absolute path.

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

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

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 relaxed fails only if a certificate is revoked, i.e. it is
explicitly known that it is bad.

connections.<conn>.remote<suffix>.auth [pubkey]
Authentication to expect from remote. See the local section's auth keyword description about the
details of supported mechanisms.

To require a trustchain public key strength for the remote side, specify the key type followed by
the minimum strength in bits (for example ecdsa-384 or rsa-2048-ecdsa-256). To limit the
acceptable set of hashing algorithms for trustchain validation, append hash algorithms to pubkey
or a key strength definition (for example pubkey-sha256-sha512, rsa-2048-sha256-sha384-sha512 or
rsa-2048-sha256-ecdsa-256-sha256-sha384). Unless disabled in strongswan.conf(5), or explicit
IKEv2 signature constraints are configured (refer to the description of the local section's auth
keyword for details), such key types and hash algorithms are also applied as constraints against
IKEv2 signature authentication schemes used by the remote side. To require RSASSA-PSS signatures
use rsa/pss instead of pubkey or rsa as in e.g. rsa/pss-sha256. If pubkey or rsa constraints are
configured RSASSA-PSS signatures will only be accepted if enabled in strongswan.conf(5).

To specify trust chain constraints for EAP-(T)TLS, append a colon to the EAP method, followed by
the key type/size and hash algorithm as discussed above (e.g. eap-tls:ecdsa-384-sha384).

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

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 (refer to esp_proposals for details).

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 negotiation use a separate
Diffie-Hellman exchange using the specified group. However, for IKEv2, the keys of the CHILD_SA
created implicitly with the IKE_SA will always be derived from the IKE_SA's key material. So any
DH group specified here will only apply when the CHILD_SA is later rekeyed or is created with a
separate CREATE_CHILD_SA exchange. A proposal mismatch might, therefore, not immediately be
noticed when the SA is established, but may later cause rekeying to fail.

Extended Sequence Number support may be indicated with the esn and noesn values, both may be
included to indicate support for both modes. If omitted, noesn is assumed.

connections.<conn>.children.<child>.sha256_96 [no]
HMAC-SHA-256 is used with 128-bit truncation with IPsec. For compatibility with implementations
that incorrectly use 96-bit truncation this option may be enabled to configure the shorter
truncation length in the kernel. This is not negotiated, so this only works with peers that use
the incorrect truncation length (or have this option enabled).

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 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 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 getservent(3) service name, or the special value opaque for RFC 4301
OPAQUE selectors. Port ranges may be specified as well, none of the kernel backends currently
support port ranges, though.

When IKEv1 is used only the first selector is interpreted, except if the Cisco Unity extension
plugin is used. This is due to a limitation of the IKEv1 protocol, which only allows a single pair
of selectors per CHILD_SA. So to tunnel traffic matched by several pairs of selectors when using
IKEv1 several children (CHILD_SAs) have to be defined that cover the selectors.

The IKE daemon uses traffic selector narrowing for IKEv1, the same way it is standardized and
implemented for IKEv2. However, this may lead to problems with other implementations. To avoid
that, configure identical selectors in such scenarios.

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

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 rand_time
gets subtracted to form the effective soft lifetime.

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

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 rekey_time.

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

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
rand_bytes gets subtracted to form the effective soft volume limit.

Volume based CHILD_SA rekeying is disabled by default.

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 rekey_bytes.

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

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
rand_packets gets subtracted to form the effective soft packet count limit.

Packet count based CHILD_SA rekeying is disabled by default.

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 rekey_bytes.

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

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

connections.<conn>.children.<child>.hostaccess [no]
Hostaccess variable to pass to updown script.

connections.<conn>.children.<child>.mode [tunnel]
IPsec Mode to establish CHILD_SA with. tunnel negotiates the CHILD_SA in IPsec Tunnel Mode,
whereas transport uses IPsec Transport Mode. transport_proxy signifying the special Mobile IPv6
Transport Proxy Mode. 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 transport and beet modes are subject to mode negotiation; tunnel mode is negotiated if the
preferred mode is not available.

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

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.

connections.<conn>.children.<child>.policies_fwd_out [no]
Whether to install outbound FWD IPsec policies or not. Enabling this is required in case there is
a drop policy that would match and block forwarded traffic for this CHILD_SA.

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

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.

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 0 disables inactivity checks.

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 0 uses dynamic
reqids, allocated incrementally.

connections.<conn>.children.<child>.priority [0]
Optional fixed priority for IPsec policies. This could be useful to install high-priority drop
policies. The default of 0 uses dynamically calculated priorities based on the size of the
traffic selectors.

connections.<conn>.children.<child>.interface []
Optional interface name to restrict IPsec policies.

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/policy having that option set. This allows installing duplicate policies and enables
Netfilter rules to select specific SAs/policies for incoming traffic. Note that inbound marks are
only set on policies, by default, unless *mark_in_sa* is enabled. The special value %unique sets a
unique mark on each CHILD_SA instance, beyond that the value %unique-dir assigns a different
unique mark for each CHILD_SA direction (in/out).

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

connections.<conn>.children.<child>.mark_in_sa [no]
Whether to set *mark_in* on the inbound SA. By default, the inbound mark is only set on the
inbound policy. The tuple destination address, protocol and SPI is unique and the mark is not
required to find the correct SA, allowing to mark traffic after decryption instead (where more
specific selectors may be used) to match different policies. Marking packets before decryption is
still possible, even if no mark is set on the SA.

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/SA having that option set. This allows installing duplicate policies and enables
Netfilter rules to select specific policies/SAs for outgoing traffic. The special value %unique
sets a unique mark on each CHILD_SA instance, beyond that the value %unique-dir assigns a
different unique mark for each CHILD_SA direction (in/out).

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

connections.<conn>.children.<child>.set_mark_in [0/0x00000000]
Netfilter mark applied to packets after the inbound IPsec SA processed them. This way it's not
necessary to mark packets via Netfilter before decryption or right afterwards to match policies or
process them differently (e.g. via policy routing).

An additional mask may be appended to the mark, separated by /. The default mask if omitted is
0xffffffff. The special value %same uses the value (but not the mask) from mark_in as mark value,
which can be fixed, %unique or %unique-dir.

Setting marks in XFRM input requires Linux 4.19 or higher.

connections.<conn>.children.<child>.set_mark_out [0/0x00000000]
Netfilter mark applied to packets after the outbound IPsec SA processed them. This allows
processing ESP packets differently than the original traffic (e.g. via policy routing).

An additional mask may be appended to the mark, separated by /. The default mask if omitted is
0xffffffff. The special value %same uses the value (but not the mask) from mark_out as mark value,
which can be fixed, %unique or %unique-dir.

Setting marks in XFRM output is supported since Linux 4.14. Setting a mask requires at least Linux
4.19.

connections.<conn>.children.<child>.if_id_in [0]
XFRM interface ID set on inbound policies/SA. This allows installing duplicate policies/SAs and
associates them with an interface with the same ID. The special value %unique sets a unique
interface ID on each CHILD_SA instance, beyond that the value %unique-dir assigns a different
unique interface ID for each CHILD_SA direction (in/out).

connections.<conn>.children.<child>.if_id_out [0]
XFRM interface ID set on outbound policies/SA. This allows installing duplicate policies/SAs and
associates them with an interface with the same ID. The special value %unique sets a unique
interface ID on each CHILD_SA instance, beyond that the value %unique-dir assigns a different
unique interface ID for each CHILD_SA direction (in/out).

The daemon will not install routes for CHILD_SAs that have this option set.

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 mtu adds TFC padding to create a
packet size equal to the Path Maximum Transfer Unit.

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.

connections.<conn>.children.<child>.hw_offload [no]
Enable hardware offload for this CHILD_SA, if supported by the IPsec implementation. The value yes
enforces offloading and the installation will fail if it's not supported by either kernel or
device. The value auto enables offloading, if it's supported, but the installation does not
fail otherwise.

connections.<conn>.children.<child>.copy_df [yes]
Whether to copy the DF bit to the outer IPv4 header in tunnel mode. This effectively disables Path
MTU discovery (PMTUD). Controlling this behavior is not supported by all kernel interfaces.

connections.<conn>.children.<child>.copy_ecn [yes]
Whether to copy the ECN (Explicit Congestion Notification) header field to/from the outer IP
header in tunnel mode. Controlling this behavior is not supported by all kernel interfaces.

connections.<conn>.children.<child>.copy_dscp [out]
Whether to copy the DSCP (Differentiated Services Field Codepoint) header field to/from the outer
IP header in tunnel mode. The value out only copies the field from the inner to the outer header,
the value in does the opposite and only copies the field from the outer to the inner header when
decapsulating, the value yes copies the field in both directions, and the value no disables
copying the field altogether. Setting this to yes or in could allow an attacker to adversely
affect other traffic at the receiver, which is why the default is out. Controlling this behavior
is not supported by all kernel interfaces.

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

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

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

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

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.

secrets
Section defining secrets for IKE/EAP/XAuth authentication and private key decryption. The 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.

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

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
0x prefix or a Base64 encoded string if it has a 0s prefix in its value.

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

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

secrets.ntlm<suffix>
NTLM secret section for a specific secret. Each NTLM secret is defined in a unique section having
the ntlm prefix. NTLM secrets may only be used for EAP-MSCHAPv2 authentication.

secrets.ntlm<suffix>.secret []
Value of the NTLM secret, which is the NT Hash of the actual secret, that is,
MD4(UTF-16LE(secret)). The resulting 16-byte value may either be given as a hex encoded string
with a 0x prefix or as a Base64 encoded string with a 0s prefix.

secrets.ntlm<suffix>.id<suffix> []
Identity the NTLM secret belongs to. Multiple unique identities may be specified, each having an
id prefix, if a secret is shared between multiple users.

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

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 0x prefix or a Base64 encoded string if it has a 0s prefix in its value.

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

secrets.ppk<suffix>
Postquantum Preshared Key (PPK) section for a specific secret. Each PPK is defined in a
unique section having the ppk prefix.

secrets.ppk<suffix>.secret []
Value of the PPK. It may either be an ASCII string, a hex encoded string if it has a 0x prefix
or a Base64 encoded string if it has a 0s prefix in its value. Should have at least 256 bits of
entropy for 128-bit security.

secrets.ppk<suffix>.id<suffix> []
PPK identity the PPK belongs to. Multiple unique identities may be specified, each having an id
prefix, if a secret is shared between multiple peers.

secrets.private<suffix>
Private key decryption passphrase for a key in the private folder.

secrets.private<suffix>.file []
File name in the private folder for which this passphrase should be used.

secrets.private<suffix>.secret []
Value of decryption passphrase for private key.

secrets.rsa<suffix>
Private key decryption passphrase for a key in the rsa folder.

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

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

secrets.ecdsa<suffix>
Private key decryption passphrase for a key in the ecdsa folder.

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

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

secrets.pkcs8<suffix>
Private key decryption passphrase for a key in the pkcs8 folder.

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

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

secrets.pkcs12<suffix>
PKCS#12 decryption passphrase for a container in the pkcs12 folder.

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

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

secrets.token<suffix>
Definition for a private key that's stored on a token/smartcard.

secrets.token<suffix>.handle []
Hex-encoded CKA_ID of the private key on the token.

secrets.token<suffix>.slot []
Optional slot number to access the token.

secrets.token<suffix>.module []
Optional PKCS#11 module name to access the token.

secrets.token<suffix>.pin []
Optional PIN required to access the key on the token. If none is provided the user is prompted
during an interactive --load-creds call.

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

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

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.

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

authorities
Section defining attributes of certification authorities.

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

authorities.<name>.cacert []
CA certificate belonging to the certification authority. The certificates may use a relative path
from the swanctl x509ca directory or an absolute path.

Configure one of cacert, file, or handle per section.

authorities.<name>.file []
Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by
it.

Configure one of cacert, file, or handle per section.

authorities.<name>.handle []
Hex-encoded CKA_ID of the CA certificate on a token.

Configure one of cacert, file, or handle per section.

authorities.<name>.slot []
Optional slot number of the token that stores the CA certificate.

authorities.<name>.module []
Optional PKCS#11 module name.

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

authorities.<name>.ocsp_uris []
Comma-separated list of OCSP URIs.

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.

FILES

       /etc/swanctl/swanctl.conf       configuration file

NAME

DESCRIPTION

TIME FORMATS

SETTINGS

FILES

SEE ALSO