1SWANCTL.CONF(5) strongSwan SWANCTL.CONF(5)
2
6 swanctl.conf - swanctl configuration file
7
9 swanctl.conf is the configuration file used by the swanctl(8) tool to
10 load configurations and credentials into the strongSwan IKE daemon.
11 For a description of the basic file syntax, including how to reference
13 sections or split the configuration in multiple files by including
14 other files, refer to strongswan.conf(5).
15
18 For all options that define a time, the time is specified in seconds.
19 The s, m, h and d suffixes explicitly define the units for seconds,
20 minutes, hours and days, respectively.
21
24 The following settings can be used to configure connections, creden‐
25 tials and pools.
26 connections
28 Section defining IKE connection configurations.
29 The connections section defines IKE connection configurations,
31 each in its own subsections. In the keyword description below,
32 the connection is named <conn>, but an arbitrary yet unique con‐
33 nection name can be chosen for each connection subsection.
34 connections.<conn>
37 Section for an IKE connection named <conn>.
38 connections.<conn>.version [0]
41 IKE major version to use for connection. 1 uses IKEv1 aka
42 ISAKMP, 2 uses IKEv2. A connection using the default of 0
43 accepts both IKEv1 and IKEv2 as responder, and initiates the
44 connection actively with IKEv2.
45 connections.<conn>.local_addrs [%any]
48 Local address(es) to use for IKE communication, comma separated.
49 Takes single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP
50 address ranges.
51 As initiator, the first non-range/non-subnet is used to initiate
53 the connection from. As responder, the local destination address
54 must match at least to one of the specified addresses, subnets
55 or ranges.
56 If FQDNs are assigned they are resolved every time a configura‐
58 tion lookup is done. If DNS resolution times out, the lookup is
59 delayed for that time.
60 connections.<conn>.remote_addrs [%any]
63 Remote address(es) to use for IKE communication, comma sepa‐
64 rated. Takes single IPv4/IPv6 addresses, DNS names, CIDR subnets
65 or IP address ranges.
66 As initiator, the first non-range/non-subnet is used to initiate
68 the connection to. As responder, the initiator source address
69 must match at least to one of the specified addresses, subnets
70 or ranges.
71 If FQDNs are assigned they are resolved every time a configura‐
73 tion lookup is done. If DNS resolution times out, the lookup is
74 delayed for that time.
75 To initiate a connection, at least one specific address or DNS
77 name must be specified.
78 connections.<conn>.local_port [500]
81 Local UDP port for IKE communication. By default the port of the
82 socket backend is used, which is usually 500. If port 500 is
83 used, automatic IKE port floating to port 4500 is used to work
84 around NAT issues.
85 Using a non-default local IKE port requires support from the
87 socket backend in use (socket-dynamic).
88 connections.<conn>.remote_port [500]
91 Remote UDP port for IKE communication. If the default of port
92 500 is used, automatic IKE port floating to port 4500 is used to
93 work around NAT issues.
94 connections.<conn>.proposals [default]
97 A proposal is a set of algorithms. For non-AEAD algorithms, this
98 includes for IKE an encryption algorithm, an integrity algo‐
99 rithm, a pseudo random function and a Diffie-Hellman group. For
100 AEAD algorithms, instead of encryption and integrity algorithms,
101 a combined algorithm is used.
102 In IKEv2, multiple algorithms of the same kind can be specified
104 in a single proposal, from which one gets selected. In IKEv1,
105 only one algorithm per kind is allowed per proposal, more algo‐
106 rithms get implicitly stripped. Use multiple proposals to offer
107 different algorithms combinations in IKEv1.
108 Algorithm keywords get separated using dashes. Multiple propos‐
110 als may be separated by commas. The special value default forms
111 a default proposal of supported algorithms considered safe, and
112 is usually a good choice for interoperability.
113 connections.<conn>.vips []
116 Comma separated list of virtual IPs to request in IKEv2 configu‐
117 ration payloads or IKEv1 Mode Config. The wildcard addresses
118 0.0.0.0 and :: request an arbitrary address, specific addresses
119 may be defined. The responder may return a different address,
120 though, or none at all.
121 connections.<conn>.aggressive [no]
124 Enables Aggressive Mode instead of Main Mode with Identity Pro‐
125 tection. Aggressive Mode is considered less secure, because the
126 ID and HASH payloads are exchanged unprotected. This allows a
127 passive attacker to snoop peer identities, and even worse, start
128 dictionary attacks on the Preshared Key.
129 connections.<conn>.pull [yes]
132 If the default of yes is used, Mode Config works in pull mode,
133 where the initiator actively requests a virtual IP. With no,
134 push mode is used, where the responder pushes down a virtual IP
135 to the initiating peer.
136 Push mode is currently supported for IKEv1, but not in IKEv2. It
138 is used by a few implementations only, pull mode is recommended.
139 connections.<conn>.dscp [000000]
142 Differentiated Services Field Codepoint to set on outgoing IKE
143 packets for this connection. The value is a six digit binary
144 encoded string specifying the Codepoint to set, as defined in
145 RFC 2474.
146 connections.<conn>.encap [no]
149 To enforce UDP encapsulation of ESP packets, the IKE daemon can
150 fake the NAT detection payloads. This makes the peer believe
151 that NAT takes place on the path, forcing it to encapsulate ESP
152 packets in UDP.
153 Usually this is not required, but it can help to work around
155 connectivity issues with too restrictive intermediary firewalls.
156 connections.<conn>.mobike [yes]
159 Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by
160 default on IKEv2 connections, and allows mobility of clients and
161 multi-homing on servers by migrating active IPsec tunnels.
162 Usually keeping MOBIKE enabled is unproblematic, as it is not
164 used if the peer does not indicate support for it. However, due
165 to the design of MOBIKE, IKEv2 always floats to port 4500 start‐
166 ing from the second exchange. Some implementations don't like
167 this behavior, hence it can be disabled.
168 connections.<conn>.dpd_delay [0s]
171 Interval to check the liveness of a peer actively using IKEv2
172 INFORMATIONAL exchanges or IKEv1 R_U_THERE messages. Active DPD
173 checking is only enforced if no IKE or ESP/AH packet has been
174 received for the configured DPD delay.
175 connections.<conn>.dpd_timeout [0s]
178 Charon by default uses the normal retransmission mechanism and
179 timeouts to check the liveness of a peer, as all messages are
180 used for liveness checking. For compatibility reasons, with
181 IKEv1 a custom interval may be specified; this option has no
182 effect on connections using IKE2.
183 connections.<conn>.fragmentation [yes]
186 Use IKE fragmentation (proprietary IKEv1 extension or RFC 7383
187 IKEv2 fragmentation). Acceptable values are yes (the
188 default), accept, force and no. If set to yes, and the peer
189 supports it, oversized IKE messages will be sent in fragments.
190 If set to accept, support for fragmentation is announced to the
191 peer but the daemon does not send its own messages in fragments.
192 If set to force (only supported for IKEv1) the initial IKE mes‐
193 sage will already be fragmented if required. Finally, setting
194 the option to no will disable announcing support for this fea‐
195 ture.
196 Note that fragmented IKE messages sent by a peer are always
198 accepted irrespective of the value of this option (even when set
199 to no).
200 connections.<conn>.send_certreq [yes]
204 Send certificate request payloads to offer trusted root CA cer‐
205 tificates to the peer. Certificate requests help the peer to
206 choose an appropriate certificate/private key for authentication
207 and are enabled by default.
208 Disabling certificate requests can be useful if too many trusted
210 root CA certificates are installed, as each certificate request
211 increases the size of the initial IKE packets.
212 connections.<conn>.send_cert [ifasked]
215 Send certificate payloads when using certificate authentication.
216 With the default of ifasked the daemon sends certificate pay‐
217 loads only if certificate requests have been received. never
218 disables sending of certificate payloads altogether, always
219 causes certificate payloads to be sent unconditionally whenever
220 certificate authentication is used.
221 connections.<conn>.ppk_id []
224 String identifying the Postquantum Preshared Key (PPK) to be
225 used.
226 connections.<conn>.ppk_required [no]
229 Whether a Postquantum Preshared Key (PPK) is required for this
230 connection.
231 connections.<conn>.keyingtries [1]
234 Number of retransmission sequences to perform during initial
235 connect. Instead of giving up initiation after the first
236 retransmission sequence with the default value of 1, additional
237 sequences may be started according to the configured value. A
238 value of 0 initiates a new sequence until the connection estab‐
239 lishes or fails with a permanent error.
240 connections.<conn>.unique [no]
243 Connection uniqueness policy to enforce. To avoid multiple con‐
244 nections from the same user, a uniqueness policy can be
245 enforced. The value never does never enforce such a policy, even
246 if a peer included INITIAL_CONTACT notification messages,
247 whereas no replaces existing connections for the same identity
248 if a new one has the INITIAL_CONTACT notify. keep rejects new
249 connection attempts if the same user already has an active con‐
250 nection, replace deletes any existing connection if a new one
251 for the same user gets established.
252 To compare connections for uniqueness, the remote IKE identity
254 is used. If EAP or XAuth authentication is involved, the
255 EAP-Identity or XAuth username is used to enforce the uniqueness
256 policy instead.
257 On initiators this setting specifies whether an INITIAL_CONTACT
259 notify is sent during IKE_AUTH if no existing connection is
260 found with the remote peer (determined by the identities of the
261 first authentication round). Unless set to never the client will
262 send a notify.
263 connections.<conn>.reauth_time [0s]
266 Time to schedule IKE reauthentication. IKE reauthentication
267 recreates the IKE/ISAKMP SA from scratch and re-evaluates the
268 credentials. In asymmetric configurations (with EAP or configu‐
269 ration payloads) it might not be possible to actively reauthen‐
270 ticate as responder. The IKEv2 reauthentication lifetime negoti‐
271 ation can instruct the client to perform reauthentication.
272 Reauthentication is disabled by default. Enabling it usually may
274 lead to small connection interruptions, as strongSwan uses a
275 break-before-make policy with IKEv2 to avoid any conflicts with
276 associated tunnel resources.
277 connections.<conn>.rekey_time [4h]
280 IKE rekeying refreshes key material using a Diffie-Hellman
281 exchange, but does not re-check associated credentials. It is
282 supported in IKEv2 only, IKEv1 performs a reauthentication pro‐
283 cedure instead.
284 With the default value IKE rekeying is scheduled every 4 hours,
286 minus the configured rand_time. If a reauth_time is configured,
287 rekey_time defaults to zero disabling rekeying; explicitly set
288 both to enforce rekeying and reauthentication.
289 connections.<conn>.over_time [10% of rekey_time/reauth_time]
292 Hard IKE_SA lifetime if rekey/reauth does not complete, as time.
293 To avoid having an IKE/ISAKMP kept alive if IKE reauthentication
294 or rekeying fails perpetually, a maximum hard lifetime may be
295 specified. If the IKE_SA fails to rekey or reauthenticate within
296 the specified time, the IKE_SA gets closed.
297 In contrast to CHILD_SA rekeying, over_time is relative in time
299 to the rekey_time and reauth_time values, as it applies to both.
300 The default is 10% of the longer of rekey_time and reauth_time.
302 connections.<conn>.rand_time [over_time]
306 Time range from which to choose a random value to subtract from
307 rekey/reauth times. To avoid having both peers initiating the
308 rekey/reauth procedure simultaneously, a random time gets sub‐
309 tracted from the rekey/reauth times.
310 The default is equal to the configured over_time.
312 connections.<conn>.pools []
316 Comma separated list of named IP pools to allocate virtual IP
317 addresses and other configuration attributes from. Each name
318 references a pool by name from either the pools section or an
319 external pool.
320 connections.<conn>.mediation [no]
323 Whether this connection is a mediation connection, that is,
324 whether this connection is used to mediate other connections
325 using the IKEv2 Mediation Extension. Mediation connections cre‐
326 ate no CHILD_SA.
327 connections.<conn>.mediated_by []
330 The name of the connection to mediate this connection through.
331 If given, the connection will be mediated through the named
332 mediation connection. The mediation connection must have media‐
333 tion enabled.
334 connections.<conn>.mediation_peer []
337 Identity under which the peer is registered at the mediation
338 server, that is, the IKE identity the other end of this connec‐
339 tion uses as its local identity on its connection to the media‐
340 tion server. This is the identity we request the mediation
341 server to mediate us with. Only relevant on connections that set
342 mediated_by. If it is not given, the remote IKE identity of the
343 first authentication round of this connection will be used.
344 connections.<conn>.local<suffix>
347 Section for a local authentication round. A local authentication
348 round defines the rules how authentication is performed for the
349 local peer. Multiple rounds may be defined to use IKEv2 RFC 4739
350 Multiple Authentication or IKEv1 XAuth.
351 Each round is defined in a section having local as prefix, and
353 an optional unique suffix. To define a single authentication
354 round, the suffix may be omitted.
355 connections.<conn>.local<suffix>.round [0]
358 Optional numeric identifier by which authentication rounds are
359 sorted. If not specified rounds are ordered by their position
360 in the config file/VICI message.
361 connections.<conn>.local<suffix>.certs []
364 Comma separated list of certificate candidates to use for
365 authentication. The certificates may use a relative path from
366 the swanctl x509 directory or an absolute path.
367 The certificate used for authentication is selected based on the
369 received certificate request payloads. If no appropriate CA can
370 be located, the first certificate is used.
371 connections.<conn>.local<suffix>.cert<suffix> []
374 Section for a certificate candidate to use for authentication.
375 Certificates in certs are transmitted as binary blobs, these
376 sections offer more flexibility.
377 connections.<conn>.local<suffix>.cert<suffix>.file []
380 Absolute path to the certificate to load. Passed as-is to the
381 daemon, so it must be readable by it.
382 Configure either this or handle, but not both, in one section.
384 connections.<conn>.local<suffix>.cert<suffix>.handle []
387 Hex-encoded CKA_ID of the certificate on a token.
388 Configure either this or file, but not both, in one section.
390 connections.<conn>.local<suffix>.cert<suffix>.slot []
393 Optional slot number of the token that stores the certificate.
394 connections.<conn>.local<suffix>.cert<suffix>.module []
397 Optional PKCS#11 module name.
398 connections.<conn>.local<suffix>.pubkeys []
401 Comma separated list of raw public key candidates to use for
402 authentication. The public keys may use a relative path from the
403 swanctl pubkey directory or an absolute path.
404 Even though multiple local public keys could be defined in prin‐
406 ciple, only the first public key in the list is used for authen‐
407 tication.
408 connections.<conn>.local<suffix>.auth [pubkey]
411 Authentication to perform locally. pubkey uses public key
412 authentication using a private key associated to a usable cer‐
413 tificate. psk uses pre-shared key authentication. The IKEv1
414 specific xauth is used for XAuth or Hybrid authentication, while
415 the IKEv2 specific eap keyword defines EAP authentication.
416 For xauth, a specific backend name may be appended, separated by
418 a dash. The appropriate xauth backend is selected to perform the
419 XAuth exchange. For traditional XAuth, the xauth method is usu‐
420 ally defined in the second authentication round following an
421 initial pubkey (or psk) round. Using xauth in the first round
422 performs Hybrid Mode client authentication.
423 For eap, a specific EAP method name may be appended, separated
425 by a dash. An EAP module implementing the appropriate method is
426 selected to perform the EAP conversation.
427 If both peers support RFC 7427 ("Signature Authentication in
429 IKEv2") specific hash algorithms to be used during IKEv2 authen‐
430 tication may be configured. To do so use ike: followed by a
431 trust chain signature scheme constraint (see description of the
432 remote section's auth keyword). For example, with ike:pub‐
433 key-sha384-sha256 a public key signature scheme with either
434 SHA-384 or SHA-256 would get used for authentication, in that
435 order and depending on the hash algorithms supported by the
436 peer. If no specific hash algorithms are configured, the default
437 is to prefer an algorithm that matches or exceeds the strength
438 of the signature key. If no constraints with ike: prefix are
439 configured any signature scheme constraint (without ike: prefix)
440 will also apply to IKEv2 authentication, unless this is disabled
441 in strongswan.conf(5). To use RSASSA-PSS signatures use rsa/pss
442 instead of pubkey or rsa as in e.g. ike:rsa/pss-sha256. If
443 pubkey or rsa constraints are configured RSASSA-PSS signatures
444 will only be used if enabled in strongswan.conf(5).
445 connections.<conn>.local<suffix>.id []
449 IKE identity to use for authentication round. When using cer‐
450 tificate authentication, the IKE identity must be contained in
451 the certificate, either as subject or as subjectAltName.
452 The identity can be an IP address, a fully-qualified domain
454 name, an email address or a Distinguished Name for which the ID
455 type is determined automatically and the string is converted to
456 the appropriate encoding. To enforce a specific identity type, a
457 prefix may be used, followed by a colon (:). If the number sign
458 (#) follows the colon, the remaining data is interpreted as hex
459 encoding, otherwise the string is used as-is as the identifica‐
460 tion data. Note that this implies that no conversion is per‐
461 formed for non-string identities. For example, ipv4:10.0.0.1
462 does not create a valid ID_IPV4_ADDR IKE identity, as it does
463 not get converted to binary 0x0a000001. Instead, one could use
464 ipv4:#0a000001 to get a valid identity, but just using the
465 implicit type with automatic conversion is usually simpler. The
466 same applies to the ASN1 encoded types. The following prefixes
467 are known: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns,
468 asn1dn, asn1gn and keyid. Custom type prefixes may be specified
469 by surrounding the numerical type value by curly brackets.
470 connections.<conn>.local<suffix>.eap_id [id]
473 Client EAP-Identity to use in EAP-Identity exchange and the EAP
474 method.
475 connections.<conn>.local<suffix>.aaa_id [remote-id]
478 Server side EAP-Identity to expect in the EAP method. Some EAP
479 methods, such as EAP-TLS, use an identity for the server to per‐
480 form mutual authentication. This identity may differ from the
481 IKE identity, especially when EAP authentication is delegated
482 from the IKE responder to an AAA backend.
483 For EAP-(T)TLS, this defines the identity for which the server
485 must provide a certificate in the TLS exchange.
486 connections.<conn>.local<suffix>.xauth_id [id]
489 Client XAuth username used in the XAuth exchange.
490 connections.<conn>.remote<suffix>
493 Section for a remote authentication round. A remote authentica‐
494 tion round defines the constraints how the peers must authenti‐
495 cate to use this connection. Multiple rounds may be defined to
496 use IKEv2 RFC 4739 Multiple Authentication or IKEv1 XAuth.
497 Each round is defined in a section having remote as prefix, and
499 an optional unique suffix. To define a single authentication
500 round, the suffix may be omitted.
501 connections.<conn>.remote<suffix>.round [0]
504 Optional numeric identifier by which authentication rounds are
505 sorted. If not specified rounds are ordered by their position
506 in the config file/VICI message.
507 connections.<conn>.remote<suffix>.id [%any]
510 IKE identity to expect for authentication round. Refer to the
511 local id section for details.
512 connections.<conn>.remote<suffix>.eap_id [id]
515 Identity to use as peer identity during EAP authentication. If
516 set to %any the EAP-Identity method will be used to ask the
517 client for an identity.
518 connections.<conn>.remote<suffix>.groups []
521 Comma separated authorization group memberships to require. The
522 peer must prove membership to at least one of the specified
523 groups. Group membership can be certified by different means,
524 for example by appropriate Attribute Certificates or by an AAA
525 backend involved in the authentication.
526 connections.<conn>.remote<suffix>.cert_policy []
529 Comma separated list of certificate policy OIDs the peer's cer‐
530 tificate must have. OIDs are specified using the numerical dot‐
531 ted representation.
532 connections.<conn>.remote<suffix>.certs []
535 Comma separated list of certificates to accept for authentica‐
536 tion. The certificates may use a relative path from the swanctl
537 x509 directory or an absolute path.
538 connections.<conn>.remote<suffix>.cert<suffix> []
541 Section for a certificate to accept for authentication. Certifi‐
542 cates in certs are transmitted as binary blobs, these sections
543 offer more flexibility.
544 connections.<conn>.remote<suffix>.cert<suffix>.file []
547 Absolute path to the certificate to load. Passed as-is to the
548 daemon, so it must be readable by it.
549 Configure either this or handle, but not both, in one section.
551 connections.<conn>.remote<suffix>.cert<suffix>.handle []
554 Hex-encoded CKA_ID of the certificate on a token.
555 Configure either this or file, but not both, in one section.
557 connections.<conn>.remote<suffix>.cert<suffix>.slot []
560 Optional slot number of the token that stores the certificate.
561 connections.<conn>.remote<suffix>.cert<suffix>.module []
564 Optional PKCS#11 module name.
565 connections.<conn>.remote<suffix>.cacerts []
568 Comma separated list of CA certificates to accept for authenti‐
569 cation. The certificates may use a relative path from the
570 swanctl x509ca directory or an absolute path.
571 connections.<conn>.remote<suffix>.cacert<suffix> []
574 Section for a CA certificate to accept for authentication. Cer‐
575 tificates in cacerts are transmitted as binary blobs, these sec‐
576 tions offer more flexibility.
577 connections.<conn>.remote<suffix>.cacert<suffix>.file []
580 Absolute path to the certificate to load. Passed as-is to the
581 daemon, so it must be readable by it.
582 Configure either this or handle, but not both, in one section.
584 connections.<conn>.remote<suffix>.cacert<suffix>.handle []
587 Hex-encoded CKA_ID of the CA certificate on a token.
588 Configure either this or file, but not both, in one section.
590 connections.<conn>.remote<suffix>.cacert<suffix>.slot []
593 Optional slot number of the token that stores the CA certifi‐
594 cate.
595 connections.<conn>.remote<suffix>.cacert<suffix>.module []
598 Optional PKCS#11 module name.
599 connections.<conn>.remote<suffix>.pubkeys []
602 Comma separated list of raw public keys to accept for authenti‐
603 cation. The public keys may use a relative path from the swanctl
604 pubkey directory or an absolute path.
605 connections.<conn>.remote<suffix>.revocation [relaxed]
608 Certificate revocation policy for CRL or OCSP revocation.
609 A strict revocation policy fails if no revocation information is
611 available, i.e. the certificate is not known to be unrevoked.
612 ifuri fails only if a CRL/OCSP URI is available, but certificate
614 revocation checking fails, i.e. there should be revocation
615 information available, but it could not be obtained.
616 The default revocation policy relaxed fails only if a certifi‐
618 cate is revoked, i.e. it is explicitly known that it is bad.
619 connections.<conn>.remote<suffix>.auth [pubkey]
622 Authentication to expect from remote. See the local section's
623 auth keyword description about the details of supported mecha‐
624 nisms.
625 To require a trustchain public key strength for the remote side,
627 specify the key type followed by the minimum strength in bits
628 (for example ecdsa-384 or rsa-2048-ecdsa-256). To limit the
629 acceptable set of hashing algorithms for trustchain validation,
630 append hash algorithms to pubkey or a key strength definition
631 (for example pubkey-sha256-sha512, rsa-2048-sha256-sha384-sha512
632 or rsa-2048-sha256-ecdsa-256-sha256-sha384). Unless disabled in
633 strongswan.conf(5), or explicit IKEv2 signature constraints are
634 configured (refer to the description of the local section's auth
635 keyword for details), such key types and hash algorithms are
636 also applied as constraints against IKEv2 signature authentica‐
637 tion schemes used by the remote side. To require RSASSA-PSS sig‐
638 natures use rsa/pss instead of pubkey or rsa as in e.g.
639 rsa/pss-sha256. If pubkey or rsa constraints are configured
640 RSASSA-PSS signatures will only be accepted if enabled in
641 strongswan.conf(5).
642 To specify trust chain constraints for EAP-(T)TLS, append a
645 colon to the EAP method, followed by the key type/size and hash
646 algorithm as discussed above (e.g. eap-tls:ecdsa-384-sha384).
647 connections.<conn>.children.<child>
651 CHILD_SA configuration sub-section. Each connection definition
652 may have one or more sections in its children subsection. The
653 section name defines the name of the CHILD_SA configuration,
654 which must be unique within the connection.
655 connections.<conn>.children.<child>.ah_proposals []
658 AH proposals to offer for the CHILD_SA. A proposal is a set of
659 algorithms. For AH, this includes an integrity algorithm and an
660 optional Diffie-Hellman group. If a DH group is specified,
661 CHILD_SA/Quick Mode rekeying and initial negotiation uses a sep‐
662 arate Diffie-Hellman exchange using the specified group (refer
663 to esp_proposals for details).
664 In IKEv2, multiple algorithms of the same kind can be specified
666 in a single proposal, from which one gets selected. In IKEv1,
667 only one algorithm per kind is allowed per proposal, more algo‐
668 rithms get implicitly stripped. Use multiple proposals to offer
669 different algorithms combinations in IKEv1.
670 Algorithm keywords get separated using dashes. Multiple propos‐
672 als may be separated by commas. The special value default forms
673 a default proposal of supported algorithms considered safe, and
674 is usually a good choice for interoperability. By default no AH
675 proposals are included, instead ESP is proposed.
676 connections.<conn>.children.<child>.esp_proposals [default]
679 ESP proposals to offer for the CHILD_SA. A proposal is a set of
680 algorithms. For ESP non-AEAD proposals, this includes an
681 integrity algorithm, an encryption algorithm, an optional
682 Diffie-Hellman group and an optional Extended Sequence Number
683 Mode indicator. For AEAD proposals, a combined mode algorithm is
684 used instead of the separate encryption/integrity algorithms.
685 If a DH group is specified, CHILD_SA/Quick Mode rekeying and
687 initial negotiation use a separate Diffie-Hellman exchange using
688 the specified group. However, for IKEv2, the keys of the
689 CHILD_SA created implicitly with the IKE_SA will always be
690 derived from the IKE_SA's key material. So any DH group speci‐
691 fied here will only apply when the CHILD_SA is later rekeyed or
692 is created with a separate CREATE_CHILD_SA exchange. A proposal
693 mismatch might, therefore, not immediately be noticed when the
694 SA is established, but may later cause rekeying to fail.
695 Extended Sequence Number support may be indicated with the esn
697 and noesn values, both may be included to indicate support for
698 both modes. If omitted, noesn is assumed.
699 In IKEv2, multiple algorithms of the same kind can be specified
701 in a single proposal, from which one gets selected. In IKEv1,
702 only one algorithm per kind is allowed per proposal, more algo‐
703 rithms get implicitly stripped. Use multiple proposals to offer
704 different algorithms combinations in IKEv1.
705 Algorithm keywords get separated using dashes. Multiple propos‐
707 als may be separated by commas. The special value default forms
708 a default proposal of supported algorithms considered safe, and
709 is usually a good choice for interoperability. If no algorithms
710 are specified for AH nor ESP, the default set of algorithms for
711 ESP is included.
712 connections.<conn>.children.<child>.sha256_96 [no]
715 HMAC-SHA-256 is used with 128-bit truncation with IPsec. For
716 compatibility with implementations that incorrectly use 96-bit
717 truncation this option may be enabled to configure the shorter
718 truncation length in the kernel. This is not negotiated, so
719 this only works with peers that use the incorrect truncation
720 length (or have this option enabled).
721 connections.<conn>.children.<child>.local_ts [dynamic]
724 Comma separated list of local traffic selectors to include in
725 CHILD_SA. Each selector is a CIDR subnet definition, followed by
726 an optional proto/port selector. The special value dynamic may
727 be used instead of a subnet definition, which gets replaced by
728 the tunnel outer address or the virtual IP, if negotiated. This
729 is the default.
730 A protocol/port selector is surrounded by opening and closing
732 square brackets. Between these brackets, a numeric or getser‐
733 vent(3) protocol name may be specified. After the optional pro‐
734 tocol restriction, an optional port restriction may be speci‐
735 fied, separated by a slash. The port restriction may be numeric,
736 a getservent(3) service name, or the special value opaque for
737 RFC 4301 OPAQUE selectors. Port ranges may be specified as well,
738 none of the kernel backends currently support port ranges,
739 though.
740 When IKEv1 is used only the first selector is interpreted,
742 except if the Cisco Unity extension plugin is used. This is due
743 to a limitation of the IKEv1 protocol, which only allows a sin‐
744 gle pair of selectors per CHILD_SA. So to tunnel traffic matched
745 by several pairs of selectors when using IKEv1 several children
746 (CHILD_SAs) have to be defined that cover the selectors.
747 The IKE daemon uses traffic selector narrowing for IKEv1, the
749 same way it is standardized and implemented for IKEv2. However,
750 this may lead to problems with other implementations. To avoid
751 that, configure identical selectors in such scenarios.
752 connections.<conn>.children.<child>.remote_ts [dynamic]
755 Comma separated list of remote selectors to include in CHILD_SA.
756 See local_ts for a description of the selector syntax.
757 connections.<conn>.children.<child>.rekey_time [1h]
760 Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes
761 key material, optionally using a Diffie-Hellman exchange if a
762 group is specified in the proposal.
763 To avoid rekey collisions initiated by both ends simultaneously,
765 a value in the range of rand_time gets subtracted to form the
766 effective soft lifetime.
767 By default CHILD_SA rekeying is scheduled every hour, minus
769 rand_time.
770 connections.<conn>.children.<child>.life_time [rekey_time + 10%]
774 Maximum lifetime before CHILD_SA gets closed. Usually this hard
775 lifetime is never reached, because the CHILD_SA gets rekeyed
776 before. If that fails for whatever reason, this limit closes the
777 CHILD_SA.
778 The default is 10% more than the rekey_time.
780 connections.<conn>.children.<child>.rand_time [life_time - rekey_time]
784 Time range from which to choose a random value to subtract from
785 rekey_time. The default is the difference between life_time and
786 rekey_time.
787 connections.<conn>.children.<child>.rekey_bytes [0]
791 Number of bytes processed before initiating CHILD_SA rekeying.
792 CHILD_SA rekeying refreshes key material, optionally using a
793 Diffie-Hellman exchange if a group is specified in the proposal.
794 To avoid rekey collisions initiated by both ends simultaneously,
796 a value in the range of rand_bytes gets subtracted to form the
797 effective soft volume limit.
798 Volume based CHILD_SA rekeying is disabled by default.
800 connections.<conn>.children.<child>.life_bytes [rekey_bytes + 10%]
803 Maximum bytes processed before CHILD_SA gets closed. Usually
804 this hard volume limit is never reached, because the CHILD_SA
805 gets rekeyed before. If that fails for whatever reason, this
806 limit closes the CHILD_SA.
807 The default is 10% more than rekey_bytes.
809 connections.<conn>.children.<child>.rand_bytes [life_bytes -
813 rekey_bytes]
814 Byte range from which to choose a random value to subtract from
815 rekey_bytes. The default is the difference between life_bytes
816 and rekey_bytes.
817 connections.<conn>.children.<child>.rekey_packets [0]
821 Number of packets processed before initiating CHILD_SA rekeying.
822 CHILD_SA rekeying refreshes key material, optionally using a
823 Diffie-Hellman exchange if a group is specified in the proposal.
824 To avoid rekey collisions initiated by both ends simultaneously,
826 a value in the range of rand_packets gets subtracted to form the
827 effective soft packet count limit.
828 Packet count based CHILD_SA rekeying is disabled by default.
830 connections.<conn>.children.<child>.life_packets [rekey_packets + 10%]
833 Maximum number of packets processed before CHILD_SA gets closed.
834 Usually this hard packets limit is never reached, because the
835 CHILD_SA gets rekeyed before. If that fails for whatever rea‐
836 son, this limit closes the CHILD_SA.
837 The default is 10% more than rekey_bytes.
839 connections.<conn>.children.<child>.rand_packets [life_packets -
843 rekey_packets]
844 Packet range from which to choose a random value to subtract
845 from rekey_packets. The default is the difference between
846 life_packets and rekey_packets.
847 connections.<conn>.children.<child>.updown []
851 Updown script to invoke on CHILD_SA up and down events.
852 connections.<conn>.children.<child>.hostaccess [yes]
855 Hostaccess variable to pass to updown script.
856 connections.<conn>.children.<child>.mode [tunnel]
859 IPsec Mode to establish CHILD_SA with. tunnel negotiates the
860 CHILD_SA in IPsec Tunnel Mode, whereas transport uses IPsec
861 Transport Mode. transport_proxy signifying the special Mobile
862 IPv6 Transport Proxy Mode. beet is the Bound End to End Tunnel
863 mixture mode, working with fixed inner addresses without the
864 need to include them in each packet.
865 Both transport and beet modes are subject to mode negotiation;
867 tunnel mode is negotiated if the preferred mode is not avail‐
868 able.
869 pass and drop are used to install shunt policies which explic‐
871 itly bypass the defined traffic from IPsec processing or drop
872 it, respectively.
873 connections.<conn>.children.<child>.policies [yes]
876 Whether to install IPsec policies or not. Disabling this can be
877 useful in some scenarios e.g. MIPv6, where policies are not man‐
878 aged by the IKE daemon.
879 connections.<conn>.children.<child>.policies_fwd_out [no]
882 Whether to install outbound FWD IPsec policies or not. Enabling
883 this is required in case there is a drop policy that would match
884 and block forwarded traffic for this CHILD_SA.
885 connections.<conn>.children.<child>.dpd_action [clear]
888 Action to perform for this CHILD_SA on DPD timeout. The default
889 clear closes the CHILD_SA and does not take further action.
890 trap installs a trap policy, which will catch matching traffic
891 and tries to re-negotiate the tunnel on-demand. restart immedi‐
892 ately tries to re-negotiate the CHILD_SA under a fresh IKE_SA.
893 connections.<conn>.children.<child>.ipcomp [no]
896 Enable IPComp compression before encryption. If enabled, IKE
897 tries to negotiate IPComp compression to compress ESP payload
898 data prior to encryption.
899 connections.<conn>.children.<child>.inactivity [0s]
902 Timeout before closing CHILD_SA after inactivity. If no traffic
903 has been processed in either direction for the configured time‐
904 out, the CHILD_SA gets closed due to inactivity. The default
905 value of 0 disables inactivity checks.
906 connections.<conn>.children.<child>.reqid [0]
909 Fixed reqid to use for this CHILD_SA. This might be helpful in
910 some scenarios, but works only if each CHILD_SA configuration is
911 instantiated not more than once. The default of 0 uses dynamic
912 reqids, allocated incrementally.
913 connections.<conn>.children.<child>.priority [0]
916 Optional fixed priority for IPsec policies. This could be useful
917 to install high-priority drop policies. The default of 0 uses
918 dynamically calculated priorities based on the size of the traf‐
919 fic selectors.
920 connections.<conn>.children.<child>.interface []
923 Optional interface name to restrict IPsec policies.
924 connections.<conn>.children.<child>.mark_in [0/0x00000000]
927 Netfilter mark and mask for input traffic. On Linux, Netfilter
928 may require marks on each packet to match an SA/policy having
929 that option set. This allows installing duplicate policies and
930 enables Netfilter rules to select specific SAs/policies for
931 incoming traffic. Note that inbound marks are only set on poli‐
932 cies, by default, unless *mark_in_sa* is enabled. The special
933 value %unique sets a unique mark on each CHILD_SA instance,
934 beyond that the value %unique-dir assigns a different unique
935 mark for each CHILD_SA direction (in/out).
936 An additional mask may be appended to the mark, separated by /.
938 The default mask if omitted is 0xffffffff.
939 connections.<conn>.children.<child>.mark_in_sa [no]
942 Whether to set *mark_in* on the inbound SA. By default, the
943 inbound mark is only set on the inbound policy. The tuple desti‐
944 nation address, protocol and SPI is unique and the mark is not
945 required to find the correct SA, allowing to mark traffic after
946 decryption instead (where more specific selectors may be used)
947 to match different policies. Marking packets before decryption
948 is still possible, even if no mark is set on the SA.
949 connections.<conn>.children.<child>.mark_out [0/0x00000000]
952 Netfilter mark and mask for output traffic. On Linux, Netfilter
953 may require marks on each packet to match a policy/SA having
954 that option set. This allows installing duplicate policies and
955 enables Netfilter rules to select specific policies/SAs for out‐
956 going traffic. The special value %unique sets a unique mark on
957 each CHILD_SA instance, beyond that the value %unique-dir
958 assigns a different unique mark for each CHILD_SA direction
959 (in/out).
960 An additional mask may be appended to the mark, separated by /.
962 The default mask if omitted is 0xffffffff.
963 connections.<conn>.children.<child>.set_mark_in [0/0x00000000]
966 Netfilter mark applied to packets after the inbound IPsec SA
967 processed them. This way it's not necessary to mark packets via
968 Netfilter before decryption or right afterwards to match poli‐
969 cies or process them differently (e.g. via policy routing).
970 An additional mask may be appended to the mark, separated by /.
972 The default mask if omitted is 0xffffffff. The special value
973 %same uses the value (but not the mask) from mark_in as mark
974 value, which can be fixed, %unique or %unique-dir.
975 Setting marks in XFRM input requires Linux 4.19 or higher.
978 connections.<conn>.children.<child>.set_mark_out [0/0x00000000]
981 Netfilter mark applied to packets after the outbound IPsec SA
982 processed them. This allows processing ESP packets differently
983 than the original traffic (e.g. via policy routing).
984 An additional mask may be appended to the mark, separated by /.
986 The default mask if omitted is 0xffffffff. The special value
987 %same uses the value (but not the mask) from mark_out as mark
988 value, which can be fixed, %unique or %unique-dir.
989 Setting marks in XFRM output is supported since Linux 4.14. Set‐
992 ting a mask requires at least Linux 4.19.
993 connections.<conn>.children.<child>.tfc_padding [0]
996 Pads ESP packets with additional data to have a consistent ESP
997 packet size for improved Traffic Flow Confidentiality. The pad‐
998 ding defines the minimum size of all ESP packets sent.
999 The default value of 0 disables TFC padding, the special value
1001 mtu adds TFC padding to create a packet size equal to the Path
1002 Maximum Transfer Unit.
1003 connections.<conn>.children.<child>.replay_window [32]
1006 IPsec replay window to configure for this CHILD_SA. Larger val‐
1007 ues than the default of 32 are supported using the Netlink back‐
1008 end only, a value of 0 disables IPsec replay protection.
1009 connections.<conn>.children.<child>.hw_offload [no]
1012 Enable hardware offload for this CHILD_SA, if supported by the
1013 IPsec implementation. The value yes enforces offloading and the
1014 installation will fail if it's not supported by either kernel or
1015 device. The value auto enables offloading, if it's sup‐
1016 ported, but the installation does not fail otherwise.
1017 connections.<conn>.children.<child>.copy_df [yes]
1020 Whether to copy the DF bit to the outer IPv4 header in tunnel
1021 mode. This effectively disables Path MTU discovery (PMTUD).
1022 Controlling this behavior is not supported by all kernel inter‐
1023 faces.
1024 connections.<conn>.children.<child>.copy_ecn [yes]
1027 Whether to copy the ECN (Explicit Congestion Notification)
1028 header field to/from the outer IP header in tunnel mode. Con‐
1029 trolling this behavior is not supported by all kernel inter‐
1030 faces.
1031 connections.<conn>.children.<child>.copy_dscp [out]
1034 Whether to copy the DSCP (Differentiated Services Field Code‐
1035 point) header field to/from the outer IP header in tunnel mode.
1036 The value out only copies the field from the inner to the outer
1037 header, the value in does the opposite and only copies the field
1038 from the outer to the inner header when decapsulating, the value
1039 yes copies the field in both directions, and the value no dis‐
1040 ables copying the field altogether. Setting this to yes or in
1041 could allow an attacker to adversely affect other traffic at the
1042 receiver, which is why the default is out. Controlling this
1043 behavior is not supported by all kernel interfaces.
1044 connections.<conn>.children.<child>.start_action [none]
1047 Action to perform after loading the configuration. The default
1048 of none loads the connection only, which then can be manually
1049 initiated or used as a responder configuration.
1050 The value trap installs a trap policy, which triggers the tunnel
1052 as soon as matching traffic has been detected. The value start
1053 initiates the connection actively.
1054 When unloading or replacing a CHILD_SA configuration having a
1056 start_action different from none, the inverse action is per‐
1057 formed. Configurations with start get closed, while such with
1058 trap get uninstalled.
1059 connections.<conn>.children.<child>.close_action [none]
1062 Action to perform after a CHILD_SA gets closed by the peer. The
1063 default of none does not take any action, trap installs a trap
1064 policy for the CHILD_SA. start tries to re-create the CHILD_SA.
1065 close_action does not provide any guarantee that the CHILD_SA is
1067 kept alive. It acts on explicit close messages only, but not on
1068 negotiation failures. Use trap policies to reliably re-create
1069 failed CHILD_SAs.
1070 secrets
1073 Section defining secrets for IKE/EAP/XAuth authentication and
1074 private key decryption. The secrets section takes sub-sections
1075 having a specific prefix which defines the secret type.
1076 It is not recommended to define any private key decryption
1078 passphrases, as then there is no real security benefit in having
1079 encrypted keys. Either store the key unencrypted or enter the
1080 keys manually when loading credentials.
1081 secrets.eap<suffix>
1084 EAP secret section for a specific secret. Each EAP secret is
1085 defined in a unique section having the eap prefix. EAP secrets
1086 are used for XAuth authentication as well.
1087 secrets.eap<suffix>.secret []
1090 Value of the EAP/XAuth secret. It may either be an ASCII string,
1091 a hex encoded string if it has a 0x prefix or a Base64 encoded
1092 string if it has a 0s prefix in its value.
1093 secrets.eap<suffix>.id<suffix> []
1096 Identity the EAP/XAuth secret belongs to. Multiple unique iden‐
1097 tities may be specified, each having an id prefix, if a secret
1098 is shared between multiple users.
1099 secrets.xauth<suffix>
1102 XAuth secret section for a specific secret. xauth is just an
1103 alias for eap, secrets under both section prefixes are used for
1104 both EAP and XAuth authentication.
1105 secrets.ntlm<suffix>
1108 NTLM secret section for a specific secret. Each NTLM secret is
1109 defined in a unique section having the ntlm prefix. NTLM secrets
1110 may only be used for EAP-MSCHAPv2 authentication.
1111 secrets.ntlm<suffix>.secret []
1114 Value of the NTLM secret, which is the NT Hash of the actual
1115 secret, that is, MD4(UTF-16LE(secret)). The resulting 16-byte
1116 value may either be given as a hex encoded string with a 0x pre‐
1117 fix or as a Base64 encoded string with a 0s prefix.
1118 secrets.ntlm<suffix>.id<suffix> []
1121 Identity the NTLM secret belongs to. Multiple unique identities
1122 may be specified, each having an id prefix, if a secret is
1123 shared between multiple users.
1124 secrets.ike<suffix>
1127 IKE preshared secret section for a specific secret. Each IKE PSK
1128 is defined in a unique section having the ike prefix.
1129 secrets.ike<suffix>.secret []
1132 Value of the IKE preshared secret. It may either be an ASCII
1133 string, a hex encoded string if it has a 0x prefix or a Base64
1134 encoded string if it has a 0s prefix in its value.
1135 secrets.ike<suffix>.id<suffix> []
1138 IKE identity the IKE preshared secret belongs to. Multiple
1139 unique identities may be specified, each having an id prefix, if
1140 a secret is shared between multiple peers.
1141 secrets.ppk<suffix>
1144 Postquantum Preshared Key (PPK) section for a specific secret.
1145 Each PPK is defined in a unique section having the ppk pre‐
1146 fix.
1147 secrets.ppk<suffix>.secret []
1150 Value of the PPK. It may either be an ASCII string, a hex
1151 encoded string if it has a 0x prefix or a Base64 encoded string
1152 if it has a 0s prefix in its value. Should have at least 256
1153 bits of entropy for 128-bit security.
1154 secrets.ppk<suffix>.id<suffix> []
1157 PPK identity the PPK belongs to. Multiple unique identities may
1158 be specified, each having an id prefix, if a secret is shared
1159 between multiple peers.
1160 secrets.private<suffix>
1163 Private key decryption passphrase for a key in the private
1164 folder.
1165 secrets.private<suffix>.file []
1168 File name in the private folder for which this passphrase should
1169 be used.
1170 secrets.private<suffix>.secret []
1173 Value of decryption passphrase for private key.
1174 secrets.rsa<suffix>
1177 Private key decryption passphrase for a key in the rsa folder.
1178 secrets.rsa<suffix>.file []
1181 File name in the rsa folder for which this passphrase should be
1182 used.
1183 secrets.rsa<suffix>.secret []
1186 Value of decryption passphrase for RSA key.
1187 secrets.ecdsa<suffix>
1190 Private key decryption passphrase for a key in the ecdsa folder.
1191 secrets.ecdsa<suffix>.file []
1194 File name in the ecdsa folder for which this passphrase should
1195 be used.
1196 secrets.ecdsa<suffix>.secret []
1199 Value of decryption passphrase for ECDSA key.
1200 secrets.pkcs8<suffix>
1203 Private key decryption passphrase for a key in the pkcs8 folder.
1204 secrets.pkcs8<suffix>.file []
1207 File name in the pkcs8 folder for which this passphrase should
1208 be used.
1209 secrets.pkcs8<suffix>.secret []
1212 Value of decryption passphrase for PKCS#8 key.
1213 secrets.pkcs12<suffix>
1216 PKCS#12 decryption passphrase for a container in the pkcs12
1217 folder.
1218 secrets.pkcs12<suffix>.file []
1221 File name in the pkcs12 folder for which this passphrase should
1222 be used.
1223 secrets.pkcs12<suffix>.secret []
1226 Value of decryption passphrase for PKCS#12 container.
1227 secrets.token<suffix>
1230 Definition for a private key that's stored on a token/smartcard.
1231 secrets.token<suffix>.handle []
1234 Hex-encoded CKA_ID of the private key on the token.
1235 secrets.token<suffix>.slot []
1238 Optional slot number to access the token.
1239 secrets.token<suffix>.module []
1242 Optional PKCS#11 module name to access the token.
1243 secrets.token<suffix>.pin []
1246 Optional PIN required to access the key on the token. If none is
1247 provided the user is prompted during an interactive --load-creds
1248 call.
1249 pools
1252 Section defining named pools. Named pools may be referenced by
1253 connections with the pools option to assign virtual IPs and
1254 other configuration attributes.
1255 pools.<name>
1258 Section defining a single pool with a unique name.
1259 pools.<name>.addrs []
1262 Subnet or range defining addresses allocated in pool. Accepts a
1263 single CIDR subnet defining the pool to allocate addresses from
1264 or an address range (<from>-<to>). Pools must be unique and
1265 non-overlapping.
1266 pools.<name>.<attr> []
1269 Comma separated list of additional attributes of type <attr>.
1270 The attribute type may be one of dns, nbns, dhcp, netmask,
1271 server, subnet, split_include and split_exclude to define
1272 addresses or CIDR subnets for the corresponding attribute types.
1273 Alternatively, <attr> can be a numerical identifier, for which
1274 string attribute values are accepted as well.
1275 authorities
1278 Section defining attributes of certification authorities.
1279 authorities.<name>
1282 Section defining a certification authority with a unique name.
1283 authorities.<name>.cacert []
1286 CA certificate belonging to the certification authority. The
1287 certificates may use a relative path from the swanctl x509ca
1288 directory or an absolute path.
1289 Configure one of cacert, file, or handle per section.
1291 authorities.<name>.file []
1294 Absolute path to the certificate to load. Passed as-is to the
1295 daemon, so it must be readable by it.
1296 Configure one of cacert, file, or handle per section.
1298 authorities.<name>.handle []
1301 Hex-encoded CKA_ID of the CA certificate on a token.
1302 Configure one of cacert, file, or handle per section.
1304 authorities.<name>.slot []
1307 Optional slot number of the token that stores the CA certifi‐
1308 cate.
1309 authorities.<name>.module []
1312 Optional PKCS#11 module name.
1313 authorities.<name>.crl_uris []
1316 Comma-separated list of CRL distribution points (ldap, http, or
1317 file URI).
1318 authorities.<name>.ocsp_uris []
1321 Comma-separated list of OCSP URIs.
1322 authorities.<name>.cert_uri_base []
1325 Defines the base URI for the Hash and URL feature supported by
1326 IKEv2. Instead of exchanging complete certificates, IKEv2 allows
1327 one to send an URI that resolves to the DER encoded certificate.
1328 The certificate URIs are built by appending the SHA1 hash of the
1329 DER encoded certificates to this base URI.
1330
1333 /etc/swanctl/swanctl.conf configuration file
1334
1336 swanctl(8)
13375.7.2 SWANCTL.CONF(5)