swanctl.conf: IKEv2 fragmentation supported
[strongswan.git] / src / swanctl / swanctl.opt
1 connections { # }
2         Section defining IKE connection configurations.
3
4         Section defining IKE connection configurations.
5
6         The connections section defines IKE connection configurations, each in
7         its own subsections. In the keyword description below, the connection
8         is named _<conn>_, but an arbitrary yet unique connection name can be
9         chosen for each connection subsection.
10
11 connections.<conn> { # }
12         Section for an IKE connection named <conn>.
13
14 connections.<conn>.version = 0
15         IKE major version to use for connection.
16
17         IKE major version to use for connection. _1_ uses IKEv1 aka ISAKMP, _2_
18         uses IKEv2. A connection using the default of _0_ accepts both IKEv1
19         and IKEv2 as responder, and initiates the connection actively with IKEv2.
20
21 connections.<conn>.local_addrs = %any
22         Local address(es) to use for IKE communication, comma separated.
23
24         Local address(es) to use for IKE communication, comma separated. Takes
25         single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
26
27         As initiator, the first non-range/non-subnet is used to initiate the
28         connection from. As responder, the local destination address must match at
29         least to one of the specified addresses, subnets or ranges.
30
31 connections.<conn>.remote_addrs = %any
32         Remote address(es) to use for IKE communication, comma separated.
33
34         Remote address(es) to use for IKE communication, comma separated. Takes
35         single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
36
37         As initiator, the first non-range/non-subnet is used to initiate the
38         connection to. As responder, the initiator source address must match at
39         least to one of the specified addresses, subnets or ranges.
40
41         To initiate a connection, at least one specific address or DNS name must
42         be specified.
43
44 connections.<conn>.local_port = 500
45         Local UPD port for IKE communication.
46
47         Local UPD port for IKE communication. By default the port of the socket
48         backend is used, which is usually _500_. If port _500_ is used, automatic
49         IKE port floating to port 4500 is used to work around NAT issues.
50
51         Using a non-default local IKE port requires support from the socket backend
52         in use (socket-dynamic).
53
54 connections.<conn>.remote_port = 500
55         Remote UDP port for IKE communication.
56
57         Remote UPD port for IKE communication. If the default of port _500_ is used,
58         automatic IKE port floating to port 4500 is used to work around NAT issues.
59
60 connections.<conn>.proposals = default
61         Comma separated proposals to accept for IKE.
62
63         A proposal is a set of algorithms. For non-AEAD algorithms, this includes
64         for IKE an encryption algorithm, an integrity algorithm, a pseudo random
65         function and a Diffie-Hellman group. For AEAD algorithms, instead of
66         encryption and integrity algorithms, a combined algorithm is used.
67
68         In IKEv2, multiple algorithms of the same kind can be specified in a single
69         proposal, from which one gets selected. In IKEv1, only one algorithm per
70         kind is allowed per proposal, more algorithms get implicitly stripped. Use
71         multiple proposals to offer different algorithms combinations in IKEv1.
72
73         Algorithm keywords get separated using dashes. Multiple proposals may be
74         separated by commas. The special value _default_ forms a default proposal
75         of supported algorithms considered safe, and is usually a good choice
76         for interoperability.
77
78 connections.<conn>.vips =
79         Virtual IPs to request in configuration payload / Mode Config.
80
81         Comma separated list of virtual IPs to request in IKEv2 configuration
82         payloads or IKEv1 Mode Config. The wildcard addresses _0.0.0.0_ and _::_
83         request an arbitrary address, specific addresses may be defined. The
84         responder may return a different address, though, or none at all.
85
86 connections.<conn>.aggressive = no
87         Use Aggressive Mode in IKEv1.
88
89         Enables Aggressive Mode instead of Main Mode with Identity Protection.
90         Aggressive Mode is considered less secure, because the ID and HASH
91         payloads are exchanged unprotected. This allows a passive attacker to
92         snoop peer identities, and even worse, start dictionary attacks on the
93         Preshared Key.
94
95 connections.<conn>.pull = yes
96         Set the Mode Config mode to use.
97
98         If the default of _yes_ is used, Mode Config works in pull mode, where
99         the initiator actively requests a virtual IP. With _no_, push mode is used,
100         where the responder pushes down a virtual IP to the initiating peer.
101
102         Push mode is currently supported for IKEv1, but not in IKEv2. It is used
103         by a few implementations only, pull mode is recommended.
104
105 connections.<conn>.encap = no
106         Enforce UDP encapsulation by faking NAT-D payloads.
107
108         To enforce UDP encapsulation of ESP packets, the IKE daemon can fake the
109         NAT detection payloads. This makes the peer believe that NAT takes
110         place on the path, forcing it to encapsulate ESP packets in UDP.
111
112         Usually this is not required, but it can help to work around connectivity
113         issues with too restrictive intermediary firewalls.
114
115 connections.<conn>.mobike = yes
116         Enables MOBIKE on IKEv2 connections.
117
118         Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2
119         connections, and allows mobility of clients and multi-homing on servers by
120         migrating active IPsec tunnels.
121
122         Usually keeping MOBIKE enabled is unproblematic, as it is not used if the
123         peer does not indicate support for it. However, due to the design of MOBIKE,
124         IKEv2 always floats to port 4500 starting from the second exchange. Some
125         implementations don't like this behavior, hence it can be disabled.
126
127 connections.<conn>.dpd_delay = 0s
128         Interval of liveness checks (DPD).
129
130         Interval to check the liveness of a peer actively using IKEv2 INFORMATIONAL
131         exchanges or IKEv1 R_U_THERE messages. Active DPD checking is only enforced
132         if no IKE or ESP/AH packet has been received for the configured DPD delay.
133
134 connections.<conn>.dpd_timeout = 0s
135         Timeout for DPD checks (IKEV1 only).
136
137         Charon by default uses the normal retransmission mechanism and timeouts to
138         check the liveness of a peer, as all messages are used for liveness
139         checking. For compatibility reasons, with IKEv1 a custom interval may be
140         specified; this option has no effect on connections using IKE2.
141
142 connections.<conn>.fragmentation = no
143         Use IKE UDP datagram fragmentation.  (_yes_, _no_ or _force_).
144
145         Use IKE fragmentation (proprietary IKEv1 extension or RFC 7383 IKEv2
146         fragmentation).  Acceptable  values  are _yes_, _force_ and _no_ (the
147         default). Fragmented IKE messages sent by a peer are always accepted
148         irrespective of  the  value  of  this option. If set to _yes_, and the peer
149         supports it, oversized IKE messages will be sent in fragments.  If set  to
150         _force_  (only  supported  for IKEv1) the initial IKE message will already
151         be fragmented if required.
152
153 connections.<conn>.send_certreq = yes
154         Send certificate requests payloads (_yes_ or _no_).
155
156         Send certificate request payloads to offer trusted root CA certificates
157         to the peer. Certificate requests help the peer to choose an appropriate
158         certificate/private key for authentication and are enabled by default.
159
160         Disabling certificate requests can be useful if too many trusted root CA
161         certificates are installed, as each certificate request increases the size
162         of the initial IKE packets.
163
164 connections.<conn>.send_cert = ifasked
165         Send certificate payloads (_always_, _never_ or _ifasked_).
166
167         Send certificate payloads when using certificate authentication. With the
168         default of _ifasked_ the daemon sends certificate payloads only if
169         certificate requests have been received. _never_ disables sending of
170         certificate payloads altogether, _always_ causes certificate payloads to be
171         sent unconditionally whenever certificate authentication is used.
172
173 connections.<conn>.keyingtries = 1
174         Number of retransmission sequences to perform during initial connect.
175
176         Number of retransmission sequences to perform during initial connect.
177         Instead of giving up initiation after the first retransmission sequence with
178         the default value of _1_, additional sequences may be started according to
179         the configured value. A value of _0_ initiates a new sequence until the
180         connection establishes or fails with a permanent error.
181
182 connections.<conn>.unique = no
183         Connection uniqueness policy (_never_, _no_, _keep_ or _replace_).
184
185         Connection uniqueness policy to enforce. To avoid multiple connections
186         from the same user, a uniqueness policy can be enforced. The value _never_
187         does never enforce such a policy, even if a peer included INITIAL_CONTACT
188         notification messages, whereas _no_ replaces existing connections for the
189         same identity if a new one has the INITIAL_CONTACT notify. _keep_ rejects
190         new connection attempts if the same user already has an active connection,
191         _replace_ deletes any existing connection if a new one for the same user
192         gets established.
193
194         To compare connections for uniqueness, the remote IKE identity is used. If
195         EAP or XAuth authentication is involved, the EAP-Identity or XAuth username
196         is used to enforce the uniqueness policy instead.
197
198         On initiators this setting specifies whether an INITIAL_CONTACT notify is
199         sent during IKE_AUTH if no existing connection is found with the remote
200         peer (determined by the identities of the first authentication round).
201         Only if set to _keep_ or _replace_ will the client send a notify.
202
203 connections.<conn>.reauth_time = 0s
204         Time to schedule IKE reauthentication.
205
206         Time to schedule IKE reauthentication. IKE reauthentication recreates the
207         IKE/ISAKMP SA from scratch and re-evaluates the credentials. In asymmetric
208         configurations (with EAP or configuration payloads) it might not be possible
209         to actively reauthenticate as responder. The IKEv2 reauthentication lifetime
210         negotiation can instruct the client to perform reauthentication.
211
212         Reauthentication is disabled by default. Enabling it usually may lead
213         to small connection interruptions, as strongSwan uses a break-before-make
214         policy with IKEv2 to avoid any conflicts with associated tunnel resources.
215
216 connections.<conn>.rekey_time = 4h
217         Time to schedule IKE rekeying.
218
219         IKE rekeying refreshes key material using a Diffie-Hellman exchange, but
220         does not re-check associated credentials. It is supported in IKEv2 only,
221         IKEv1 performs a reauthentication procedure instead.
222
223         With the default value IKE rekeying is scheduled every 4 hours, minus the
224         configured **rand_time**. If a **reauth_time** is configured, **rekey_time**
225         defaults to zero disabling rekeying; explicitly set both to enforce
226         rekeying and reauthentication.
227
228 connections.<conn>.over_time = 10% of rekey_time/reauth_time
229         Hard IKE_SA lifetime if rekey/reauth does not complete, as time.
230
231         Hard IKE_SA lifetime if rekey/reauth does not complete, as time.
232         To avoid having an IKE/ISAKMP kept alive if IKE reauthentication or rekeying
233         fails perpetually, a maximum hard lifetime may be specified. If the
234         IKE_SA fails to rekey or reauthenticate within the specified time, the
235         IKE_SA gets closed.
236
237         In contrast to CHILD_SA rekeying, **over_time** is relative in time to the
238         **rekey_time** _and_ **reauth_time** values, as it applies to both.
239
240         The default is 10% of the longer of **rekey_time** and **reauth_time**.
241
242 connections.<conn>.rand_time = over_time
243         Range of random time to subtract from rekey/reauth times.
244
245         Time range from which to choose a random value to subtract from
246         rekey/reauth times. To avoid having both peers initiating the rekey/reauth
247         procedure simultaneously, a random time gets subtracted from the
248         rekey/reauth times.
249
250         The default is equal to the configured **over_time**.
251
252 connections.<conn>.pools =
253         Comma separated list of named IP pools.
254
255         Comma separated list of named IP pools to allocate virtual IP addresses and
256         other configuration attributes from. Each name references a pool by name
257         from either the **pools** section or an external pool.
258
259 connections.<conn>.local<suffix> {}
260         Section for a local authentication round.
261
262         Section for a local authentication round. A local authentication round
263         defines the rules how authentication is performed for the local peer.
264         Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple Authentication
265         or IKEv1 XAuth.
266
267         Each round is defined in a section having _local_ as prefix, and an optional
268         unique suffix. To define a single authentication round, the suffix may be
269         omitted.
270
271 connections.<conn>.local<suffix>.certs =
272         Comma separated list of certificate candidates to use for authentication.
273
274         Comma separated list of certificate candidates to use for authentication.
275         The certificates may use a relative path from the **swanctl** _x509_
276         directory, or an absolute path.
277
278         The certificate used for authentication is selected based on the received
279         certificate request payloads. If no appropriate CA can be located, the
280         first certificate is used.
281
282 connections.<conn>.local<suffix>.auth = pubkey
283         Authentication to perform locally (_pubkey_, _psk_, _xauth[-backend]_ or
284         _eap[-method]_).
285
286         Authentication to perform locally. _pubkey_ uses public key authentication
287         using a private key associated to a usable certificate. _psk_ uses
288         pre-shared key authentication. The IKEv1 specific _xauth_ is used for
289         XAuth or Hybrid authentication, while the IKEv2 specific _eap_ keyword
290         defines EAP authentication.
291
292         For _xauth_, a specific backend name may be appended, separated by a dash.
293         The appropriate _xauth_ backend is selected to perform the XAuth exchange.
294         For traditional XAuth, the _xauth_ method is usually defined in the second
295         authentication round following an initial _pubkey_ (or _psk_) round. Using
296         _xauth_ in the first round performs Hybrid Mode client authentication.
297
298         For _eap_, a specific EAP method name may be appended, separated by a dash.
299         An EAP module implementing the appropriate method is selected to perform
300         the EAP conversation.
301
302 connections.<conn>.local<suffix>.id =
303         IKE identity to use for authentication round.
304
305         IKE identity to use for authentication round. When using certificate
306         authentication, the IKE identity must be contained in the certificate,
307         either as subject or as subjectAltName.
308
309         The identity can be an IP address, a fully-qualified domain name, an email
310         address or a Distinguished Name for which the ID type is determined
311         automatically and the string is converted to the appropriate encoding. To
312         enforce a specific identity type, a prefix may be used, followed by a colon
313         (:). If the number sign (#) follows the colon, the remaining data is
314         interpreted as hex encoding, otherwise the string is used as-is as the
315         identification data. Note that this implies that no conversion is performed
316         for non-string identities. For example, _ipv4:10.0.0.1_ does not create a
317         valid ID_IPV4_ADDR IKE identity, as it does not get converted to binary
318         0x0a000001. Instead, one could use _ipv4:#0a000001_ to get a valid identity,
319         but just using the implicit type with automatic conversion is usually
320         simpler. The same applies to the ASN1 encoded types. The following prefixes
321         are known: _ipv4_, _ipv6_, _rfc822_, _email_, _userfqdn_, _fqdn_, _dns_,
322         _asn1dn_, _asn1gn_ and _keyid_. Custom type prefixes may be specified by
323         surrounding the numerical type value by curly brackets.
324
325 connections.<conn>.local<suffix>.eap_id = id
326         Client EAP-Identity to use in EAP-Identity exchange and the EAP method.
327
328 connections.<conn>.local<suffix>.aaa_id = remote-id
329         Server side EAP-Identity to expect in the EAP method.
330
331         Server side EAP-Identity to expect in the EAP method. Some EAP methods, such
332         as EAP-TLS, use an identity for the server to perform mutual authentication.
333         This identity may differ from the IKE identity, especially when EAP
334         authentication is delegated from the IKE responder to an AAA backend.
335
336         For EAP-(T)TLS, this defines the identity for which the server must provide
337         a certificate in the TLS exchange.
338
339 connections.<conn>.local<suffix>.xauth_id = id
340         Client XAuth username used in the XAuth exchange.
341
342 connections.<conn>.remote<suffix> {}
343         Section for a remote authentication round.
344
345         Section for a remote authentication round. A remote authentication round
346         defines the constraints how the peers must authenticate to use this
347         connection. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple
348         Authentication or IKEv1 XAuth.
349
350         Each round is defined in a section having _remote_ as prefix, and an
351         optional unique suffix. To define a single authentication round, the suffix
352         may be omitted.
353
354 connections.<conn>.remote<suffix>.id = %any
355         IKE identity to expect for authentication round.
356
357         IKE identity to expect for authentication round. Refer to the _local_ _id_
358         section for details.
359
360 connections.<conn>.remote<suffix>.groups =
361         Authorization group memberships to require.
362
363         Comma separated authorization group memberships to require. The peer must
364         prove membership to at least one of the specified groups. Group membership
365         can be certified by different means, for example by appropriate Attribute
366         Certificates or by an AAA backend involved in the authentication.
367
368 connections.<conn>.remote<suffix>.certs =
369         Comma separated list of certificate to accept for authentication.
370
371         Comma separated list of certificates to accept for authentication.
372         The certificates may use a relative path from the **swanctl** _x509_
373         directory, or an absolute path.
374
375 connections.<conn>.remote<suffix>.cacerts =
376         Comma separated list of CA certificates to accept for authentication.
377
378         Comma separated list of CA certificates to accept for authentication.
379         The certificates may use a relative path from the **swanctl** _x509ca_
380         directory, or an absolute path.
381
382 connections.<conn>.remote<suffix>.revocation = relaxed
383         Certificate revocation policy, (_strict_, _ifuri_ or _relaxed_).
384
385         Certificate revocation policy for CRL or OCSP revocation.
386
387         A _strict_ revocation policy fails if no revocation information is
388         available, i.e. the certificate is not known to be unrevoked.
389
390         _ifuri_ fails only if a CRL/OCSP URI is available, but certificate
391         revocation checking fails, i.e. there should be revocation information
392         available, but it could not be obtained.
393
394         The default revocation policy _relaxed_ fails only if a certificate
395         is revoked, i.e. it is explicitly known that it is bad.
396
397 connections.<conn>.remote<suffix>.auth = pubkey
398         Authentication to expect from remote (_pubkey_, _psk_, _xauth[-backend]_ or
399         _eap[-method]_).
400
401         Authentication to expect from remote. See the **local** sections **auth**
402         keyword description about the details of supported mechanisms.
403
404 connections.<conn>.children.<child> {}
405         CHILD_SA configuration sub-section.
406
407         CHILD_SA configuration sub-section. Each connection definition may have
408         one or more sections in its _children_ subsection. The section name
409         defines the name of the CHILD_SA configuration, which must be unique within
410         the connection.
411
412 connections.<conn>.children.<child>.ah_proposals =
413         AH proposals to offer for the CHILD_SA.
414
415         AH proposals to offer for the CHILD_SA. A proposal is a set of algorithms.
416         For AH, this includes an integrity algorithm and an optional Diffie-Hellman
417         group. If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial
418         negotiation uses a separate Diffie-Hellman exchange using the specified
419         group.
420
421         In IKEv2, multiple algorithms of the same kind can be specified in a single
422         proposal, from which one gets selected. In IKEv1, only one algorithm per
423         kind is allowed per proposal, more algorithms get implicitly stripped. Use
424         multiple proposals to offer different algorithms combinations in IKEv1.
425
426         Algorithm keywords get separated using dashes. Multiple proposals may be
427         separated by commas. The special value _default_ forms a default proposal
428         of supported algorithms considered safe, and is usually a good choice
429         for interoperability. By default no AH proposals are included, instead ESP
430         is proposed.
431
432 connections.<conn>.children.<child>.esp_proposals = default
433         ESP proposals to offer for the CHILD_SA.
434
435         ESP proposals to offer for the CHILD_SA. A proposal is a set of algorithms.
436         For ESP non-AEAD proposals, this includes an integrity algorithm, an
437         encryption algorithm, an optional Diffie-Hellman group and an optional
438         Extended Sequence Number Mode indicator. For AEAD proposals, a combined
439         mode algorithm is used instead of the separate encryption/integrity
440         algorithms.
441
442         If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial (non
443         IKE_AUTH piggybacked) negotiation uses a separate Diffie-Hellman exchange
444         using the specified group. Extended Sequence Number support may be indicated
445         with the _esn_ and _noesn_ values, both may be included to indicate support
446         for both modes. If omitted, _noesn_ is assumed.
447
448         In IKEv2, multiple algorithms of the same kind can be specified in a single
449         proposal, from which one gets selected. In IKEv1, only one algorithm per
450         kind is allowed per proposal, more algorithms get implicitly stripped. Use
451         multiple proposals to offer different algorithms combinations in IKEv1.
452
453         Algorithm keywords get separated using dashes. Multiple proposals may be
454         separated by commas. The special value _default_ forms a default proposal
455         of supported algorithms considered safe, and is usually a good choice
456         for interoperability. If no algorithms are specified for AH nor ESP,
457         the _default_ set of algorithms for ESP is included.
458
459 connections.<conn>.children.<child>.local_ts = dynamic
460         Local traffic selectors to include in CHILD_SA.
461
462         Comma separated list of local traffic selectors to include in CHILD_SA.
463         Each selector is a CIDR subnet definition, followed by an optional
464         proto/port selector. The special value _dynamic_ may be used instead of a
465         subnet definition, which gets replaced by the tunnel outer address or the
466         virtual IP, if negotiated. This is the default.
467
468         A protocol/port selector is surrounded by opening and closing square
469         brackets. Between these brackets, a numeric or **getservent**(3) protocol
470         name may be specified. After the optional protocol restriction, an optional
471         port restriction may be specified, separated by a slash. The port
472         restriction may be numeric, a **getservent**(3) service name, or the special
473         value _opaque_ for RFC 4301 OPAQUE selectors. Port ranges may be specified
474         as well, none of the kernel backends currently support port ranges, though.
475
476         Unless the Unity extension is used, IKEv1 supports the first specified
477         selector only. IKEv1 uses very similar traffic selector narrowing as it is
478         supported in the IKEv2 protocol.
479
480 connections.<conn>.children.<child>.remote_ts = dynamic
481         Remote selectors to include in CHILD_SA.
482
483         Comma separated list of remote selectors to include in CHILD_SA. See
484         **local_ts** for a description of the selector syntax.
485
486 connections.<conn>.children.<child>.rekey_time = 1h
487         Time to schedule CHILD_SA rekeying.
488
489         Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes key
490         material, optionally using a Diffie-Hellman exchange if a group is
491         specified in the proposal.
492
493         To avoid rekey collisions initiated by both ends simultaneously, a value
494         in the range of **rand_time** gets subtracted to form the effective soft
495         lifetime.
496
497         By default CHILD_SA rekeying is scheduled every hour, minus **rand_time**.
498
499 connections.<conn>.children.<child>.life_time = rekey_time + 10%
500         Maximum lifetime before CHILD_SA gets closed, as time.
501
502         Maximum lifetime before CHILD_SA gets closed. Usually this hard lifetime
503         is never reached, because the CHILD_SA gets rekeyed before.
504         If that fails for whatever reason, this limit closes the CHILD_SA.
505
506         The default is 10% more than the **rekey_time**.
507
508 connections.<conn>.children.<child>.rand_time = life_time - rekey_time
509         Range of random time to subtract from **rekey_time**.
510
511         Time range from which to choose a random value to subtract from
512         **rekey_time**. The default is the difference between **life_time** and
513         **rekey_time**.
514
515 connections.<conn>.children.<child>.rekey_bytes = 0
516         Number of bytes processed before initiating CHILD_SA rekeying.
517
518         Number of bytes processed before initiating CHILD_SA rekeying. CHILD_SA
519         rekeying refreshes key material, optionally using a Diffie-Hellman exchange
520         if a group is specified in the proposal.
521
522         To avoid rekey collisions initiated by both ends simultaneously, a value
523         in the range of **rand_bytes** gets subtracted to form the effective soft
524         volume limit.
525
526         Volume based CHILD_SA rekeying is disabled by default.
527
528 connections.<conn>.children.<child>.life_bytes = rekey_bytes + 10%
529         Maximum bytes processed before CHILD_SA gets closed.
530
531         Maximum bytes processed before CHILD_SA gets closed. Usually this hard
532         volume limit is never reached, because the CHILD_SA gets rekeyed before.
533         If that fails for whatever reason, this limit closes the CHILD_SA.
534
535         The default is 10% more than **rekey_bytes**.
536
537 connections.<conn>.children.<child>.rand_bytes = life_bytes - rekey_bytes
538         Range of random bytes to subtract from **rekey_bytes**.
539
540         Byte range from which to choose a random value to subtract from
541         **rekey_bytes**. The default is the difference between **life_bytes** and
542         **rekey_bytes**.
543
544 connections.<conn>.children.<child>.rekey_packets = 0
545         Number of packets processed before initiating CHILD_SA rekeying.
546
547         Number of packets processed before initiating CHILD_SA rekeying. CHILD_SA
548         rekeying refreshes key material, optionally using a Diffie-Hellman exchange
549         if a group is specified in the proposal.
550
551         To avoid rekey collisions initiated by both ends simultaneously, a value
552         in the range of **rand_packets** gets subtracted to form the effective soft
553         packet count limit.
554
555         Packet count based CHILD_SA rekeying is disabled by default.
556
557 connections.<conn>.children.<child>.life_packets = rekey_packets + 10%
558         Maximum number of packets processed before CHILD_SA gets closed.
559
560         Maximum number of packets processed before CHILD_SA gets closed. Usually
561         this hard packets limit is never reached, because the CHILD_SA gets rekeyed
562         before. If that fails for whatever reason, this limit closes the CHILD_SA.
563
564         The default is 10% more than **rekey_bytes**.
565
566 connections.<conn>.children.<child>.rand_packets = life_packets - rekey_packets
567         Range of random packets to subtract from **packets_bytes**.
568
569         Packet range from which to choose a random value to subtract from
570         **rekey_packets**. The default is the difference between **life_packets**
571         and **rekey_packets**.
572
573 connections.<conn>.children.<child>.updown =
574         Updown script to invoke on CHILD_SA up and down events.
575
576 connections.<conn>.children.<child>.hostaccess = yes
577         Hostaccess variable to pass to **updown** script.
578
579 connections.<conn>.children.<child>.mode = tunnel
580         IPsec Mode to establish (_tunnel_, _transport_, _beet_, _pass_ or _drop_).
581
582         IPsec Mode to establish CHILD_SA with. _tunnel_ negotiates the CHILD_SA
583         in IPsec Tunnel Mode, whereas _transport_ uses IPsec Transport Mode. _beet_
584         is the Bound End to End Tunnel mixture mode, working with fixed inner
585         addresses without the need to include them in each packet.
586
587         Both _transport_ and _beet_ modes are subject to mode negotiation; _tunnel_
588         mode is negotiated if the preferred mode is not available.
589
590         _pass_ and _drop_ are used to install shunt policies, which explicitly
591         bypass the defined traffic from IPsec processing, or drop it, respectively.
592
593 connections.<conn>.children.<child>.policies = yes
594         Whether to install IPsec policies or not.
595
596         Whether to install IPsec policies or not. Disabling this can be useful in
597         some scenarios e.g. MIPv6, where policies are not managed by the IKE daemon.
598
599 connections.<conn>.children.<child>.dpd_action = clear
600         Action to perform on DPD timeout (_clear_, _trap_ or _restart_).
601
602         Action to perform for this CHILD_SA on DPD timeout. The default _clear_
603         closes the CHILD_SA and does not take further action. _trap_ installs
604         a trap policy, which will catch matching traffic and tries to re-negotiate
605         the tunnel on-demand. _restart_ immediately tries to re-negotiate the
606         CHILD_SA under a fresh IKE_SA.
607
608 connections.<conn>.children.<child>.ipcomp = no
609         Enable IPComp compression before encryption.
610
611         Enable IPComp compression before encryption. If enabled, IKE tries to
612         negotiate IPComp compression to compress ESP payload data prior to
613         encryption.
614
615 connections.<conn>.children.<child>.inactivity = 0s
616         Timeout before closing CHILD_SA after inactivity.
617
618         Timeout before closing CHILD_SA after inactivity. If no traffic has
619         been processed in either direction for the configured timeout, the CHILD_SA
620         gets closed due to inactivity. The default value of _0_ disables inactivity
621         checks.
622
623 connections.<conn>.children.<child>.reqid = 0
624         Fixed reqid to use for this CHILD_SA.
625
626         Fixed reqid to use for this CHILD_SA. This might be helpful in some
627         scenarios, but works only if each CHILD_SA configuration is instantiated
628         not more than once. The default of _0_ uses dynamic reqids, allocated
629         incrementally.
630
631 connections.<conn>.children.<child>.mark_in = 0/0x00000000
632         Netfilter mark and mask for input traffic.
633
634         Netfilter mark and mask for input traffic. On Linux Netfilter may require
635         marks on each packet to match an SA having that option set. This allows
636         Netfilter rules to select specific tunnels for incoming traffic. The
637         special value _%unique_ sets a unique mark on each CHILD_SA instance.
638
639         An additional mask may be appended to the mark, separated by _/_. The
640         default mask if omitted is 0xffffffff.
641
642 connections.<conn>.children.<child>.mark_out = 0/0x00000000
643         Netfilter mark and mask for output traffic.
644
645         Netfilter mark and mask for output traffic. On Linux Netfilter may require
646         marks on each packet to match a policy having that option set. This allows
647         Netfilter rules to select specific tunnels for outgoing traffic. The
648         special value _%unique_ sets a unique mark on each CHILD_SA instance.
649
650         An additional mask may be appended to the mark, separated by _/_. The
651         default mask if omitted is 0xffffffff.
652
653 connections.<conn>.children.<child>.tfc_padding = 0
654         Traffic Flow Confidentiality padding.
655
656         Pads ESP packets with additional data to have a consistent ESP packet size
657         for improved Traffic Flow Confidentiality. The padding defines the minimum
658         size of all ESP packets sent.
659
660         The default value of 0 disables TFC padding, the special value _mtu_ adds
661         TFC padding to create a packet size equal to the Path Maximum Transfer Unit.
662
663 connections.<conn>.children.<child>.replay_window = 32
664         IPsec replay window to configure for this CHILD_SA.
665
666         IPsec replay window to configure for this CHILD_SA. Larger values than the
667         default of 32 are supported using the Netlink backend only, a value of 0
668         disables IPsec replay protection.
669
670 connections.<conn>.children.<child>.start_action = none
671         Action to perform after loading the configuration (_none_, _trap_, _start_).
672
673         Action to perform after loading the configuration. The default of _none_
674         loads the connection only, which then can be manually initiated or used as
675         a responder configuration.
676
677         The value _trap_ installs a trap policy, which triggers the tunnel as soon
678         as matching traffic has been detected. The value _start_ initiates
679         the connection actively.
680
681         When unloading or replacing a CHILD_SA configuration having a
682         **start_action** different from _none_, the inverse action is performed.
683         Configurations with _start_ get closed, while such with _trap_ get
684         uninstalled.
685
686 connections.<conn>.children.<child>.close_action = none
687         Action to perform after a CHILD_SA gets closed (_none_, _trap_, _start_).
688
689         Action to perform after a CHILD_SA gets closed by the peer. The default of
690         _none_ does not take any action, _trap_ installs a trap policy for the
691         CHILD_SA. _start_ tries to re-create the CHILD_SA.
692
693         **close_action** does not provide any guarantee that the CHILD_SA is kept
694         alive. It acts on explicit close messages only, but not on negotiation
695         failures. Use trap policies to reliably re-create failed CHILD_SAs.
696
697 secrets { # }
698         Section defining secrets for IKE/EAP/XAuth authentication and private
699         key decryption.
700
701         Section defining secrets for IKE/EAP/XAuth authentication and private key
702         decryption. The **secrets** section takes sub-sections having a specific
703         prefix which defines the secret type.
704
705         It is not recommended to define any private key decryption passphrases,
706         as then there is no real security benefit in having encrypted keys. Either
707         store the key unencrypted, or enter the keys manually when loading
708         credentials.
709
710 secrets.eap<suffix> { # }
711         EAP secret section for a specific secret.
712
713         EAP secret section for a specific secret. Each EAP secret is defined in
714         a unique section having the _eap_ prefix. EAP secrets are used for XAuth
715         authentication as well.
716
717 secrets.xauth<suffix> { # }
718         XAuth secret section for a specific secret.
719
720         XAuth secret section for a specific secret. **xauth** is just an alias
721         for **eap**, secrets under both section prefixes are used for both EAP and
722         XAuth authentication.
723
724 secrets.eap<suffix>.secret =
725         Value of the EAP/XAuth secret.
726
727         Value of the EAP/XAuth secret. It may either be an ASCII string, a hex
728         encoded string if it has a _0x_ prefix, or a Base64 encoded string if it
729         has a _0s_ prefix in its value.
730
731 secrets.eap<suffix>.id<suffix> =
732         Identity the EAP/XAuth secret belongs to.
733
734         Identity the EAP/XAuth secret belongs to. Multiple unique identities may
735         be specified, each having an _id_ prefix, if a secret is shared between
736         multiple users.
737
738 secrets.ike<suffix> { # }
739         IKE preshared secret section for a specific secret.
740
741         IKE preshared secret section for a specific secret. Each IKE PSK is defined
742         in a unique section having the _ike_ prefix.
743
744 secrets.ike<suffix>.secret =
745         Value of the IKE preshared secret.
746
747         Value of the IKE preshared secret. It may either be an ASCII string,
748         a hex encoded string if it has a _0x_ prefix, or a Base64 encoded string if
749         it has a _0s_ prefix in its value.
750
751 secrets.ike<suffix>.id<suffix> =
752         IKE identity the IKE preshared secret belongs to.
753
754         IKE identity the IKE preshared secret belongs to. Multiple unique identities
755         may be specified, each having an _id_ prefix, if a secret is shared between
756         multiple peers.
757
758 secrets.rsa<suffix> { # }
759         Private key decryption passphrase for a key in the _rsa_ folder.
760
761 secrets.rsa<suffix>.file =
762         File name in the _rsa_ folder for which this passphrase should be used.
763
764 secrets.rsa<suffix>.secret
765         Value of decryption passphrase for RSA key.
766
767 secrets.ecdsa<suffix> { # }
768         Private key decryption passphrase for a key in the _ecdsa_ folder.
769
770 secrets.ecdsa<suffix>.file =
771         File name in the _ecdsa_ folder for which this passphrase should be used.
772
773 secrets.ecdsa<suffix>.secret
774         Value of decryption passphrase for ECDSA key.
775
776 secrets.pkcs8<suffix> { # }
777         Private key decryption passphrase for a key in the _pkcs8_ folder.
778
779 secrets.pkcs8<suffix>.file =
780         File name in the _pkcs8_ folder for which this passphrase should be used.
781
782 secrets.pkcs8<suffix>.secret
783         Value of decryption passphrase for PKCS#8 key.
784
785 secrets.pkcs12<suffix> { # }
786         PKCS#12 decryption passphrase for a container in the _pkcs12_ folder.
787
788 secrets.pkcs12<suffix>.file =
789         File name in the _pkcs12_ folder for which this passphrase should be used.
790
791 secrets.pkcs12<suffix>.secret
792         Value of decryption passphrase for PKCS#12 container.
793
794 pools { # }
795         Section defining named pools.
796
797         Section defining named pools. Named pools may be referenced by connections
798         with the **pools** option to assign virtual IPs and other configuration
799         attributes.
800
801 pools.<name> { # }
802         Section defining a single pool with a unique name.
803
804 pools.<name>.addrs =
805         Addresses allocated in pool.
806
807         Subnet or range defining addresses allocated in pool. Accepts a single CIDR
808         subnet defining the pool to allocate addresses from, or an address range
809         (<from>-<to>).  Pools must be unique and non-overlapping.
810
811 pools.<name>.<attr> =
812         Comma separated list of additional attributes from type <attr>.
813
814         Comma separated list of additional attributes of type **<attr>**. The
815         attribute type may be one of _dns_, _nbns_, _dhcp_, _netmask_, _server_,
816         _subnet_, _split_include_ and _split_exclude_ to define addresses or CIDR
817         subnets for the corresponding attribute types. Alternatively, **<attr>** can
818         be a numerical identifier, for which string attribute values are accepted
819         as well.
820
821 authorities { # }
822         Section defining attributes of certification authorities.
823
824 authorities.<name> { # }
825         Section defining a certification authority with a unique name.
826
827 authorities.<name>.cacert =
828         CA certificate belonging to the certification authority.
829
830         The certificates may use a relative path from the **swanctl** _x509ca_
831         directory, or an absolute path.
832
833 authorities.<name>.crl_uris =
834         Comma-separated list of CRL distribution points
835
836         Comma-separated list of CRL distribution points (ldap, http, or file URI)
837
838 authorities.<name>.ocsp_uris =
839         Comma-separated list of OCSP URIs
840
841         Comma-separated list of OCSP URIs
842
843 authorities.<name>.cert_uri_base =
844         Defines the base URI for the Hash and URL feature supported by IKEv2.
845
846         Defines the base URI for the Hash and URL feature supported by IKEv2.
847         Instead of exchanging complete certificates, IKEv2 allows one to send an
848         URI that resolves to the DER encoded certificate. The certificate URIs are
849         built by appending the SHA1 hash of the DER encoded certificates to this
850         base URI.
851