1IPSEC.CONF(5) Executable programs IPSEC.CONF(5)
2
3
4
6 ipsec.conf - IPsec configuration and connections
7
9 The ipsec.conf file specifies most configuration and control
10 information for the Libreswan IPsec subsystem. (The major exception is
11 secrets for authentication; see ipsec.secrets(5).) Its contents are not
12 security-sensitive. Configurations can be added using this
13 configuration file or by using ipsec whack directly. This means that
14 technically, the ipsec.conf file is optional, but a few warnings might
15 show up when this file is missing.
16
17 ipsec.conf is a text file, consisting of one or more sections. White
18 space followed by # followed by anything to the end of the line is a
19 comment and is ignored, as are empty lines that are not within a
20 section.
21
22 A line that contains include and a file name, separated by white space,
23 is replaced by the contents of that file, preceded and followed by
24 empty lines. If the file name is not a full pathname, it is considered
25 to be relative to the directory that contains the including file. Such
26 inclusions can be nested. Only a single filename may be supplied, and
27 it may not contain white space, but it may include shell wildcards (see
28 sh(1)); for example:
29
30 include /etc/ipsec.d/*.conf
31
32 The intention of the include facility is mostly to permit keeping
33 information on connections, or sets of connections, separate from the
34 main configuration file. This permits such connection descriptions to
35 be changed, copied to the other security gateways involved, etc.,
36 without having to constantly extract them from the configuration file
37 and then insert them back into it. Note also the also and alsoflip
38 parameters (described below) which permit splitting a single logical
39 section (e.g. a connection description) into several distinct sections.
40
41 The first significant line of the file may specify a version of this
42 specification for backwards compatibility with freeswan and openswan.
43 It is ignored and unused. For compatibility with openswan, specify:
44
45 version 2
46
47 A section begins with a line of the form:
48
49 type name
50
51 where type indicates what type of section follows, and name is an
52 arbitrary name that distinguishes the section from others of the same
53 type. (Names must start with a letter and may contain only letters,
54 digits, periods, underscores, and hyphens.) All subsequent non-empty
55 lines that begin with white space are part of the section; comments
56 within a section must begin with white space too. There may be only one
57 section of a given type with a given name.
58
59 Lines within the section are generally of the form
60
61 parameter=value
62
63 (note the mandatory preceding white space). There can be white space on
64 either side of the =. Parameter names follow the same syntax as section
65 names, and are specific to a section type. Unless otherwise explicitly
66 specified, no parameter name may appear more than once in a section.
67
68 An empty value stands for the system default value (if any) of the
69 parameter, i.e. it is roughly equivalent to omitting the parameter line
70 entirely. A value may contain white space only if the entire value is
71 enclosed in double quotes ("); a value cannot itself contain a double
72 quote, nor may it be continued across more than one line.
73
74 Numeric values are specified to be either an “integer” (a sequence of
75 digits) or a “decimal number” (sequence of digits optionally followed
76 by `.' and another sequence of digits).
77
78 There is currently one parameter that is available in any type of
79 section:
80
81 also
82 the value is a section name; the parameters of that section are
83 appended to this section, as if they had been written as part of
84 it. The specified section must exist, must follow the current one,
85 and must have the same section type. (Nesting is permitted, and
86 there may be more than one also in a single section, although it is
87 forbidden to append the same section more than once.) This allows,
88 for example, keeping the encryption keys for a connection in a
89 separate file from the rest of the description, by using both an
90 also parameter and an include line. (Caution, see BUGS below for
91 some restrictions.)
92
93 alsoflip
94 can be used in a conn section. It acts like an also that flips the
95 referenced section's entries left-for-right.
96
97 Parameter names beginning with x- (or X-, or x_, or X_) are reserved
98 for user extensions and will never be assigned meanings by IPsec.
99 Parameters with such names must still observe the syntax rules (limits
100 on characters used in the name; no white space in a non-quoted value;
101 no newlines or double quotes within the value). All other as-yet-unused
102 parameter names are reserved for future IPsec improvements.
103
104 A section with name %default specifies defaults for sections of the
105 same type. For each parameter in it, any section of that type that does
106 not have a parameter of the same name gets a copy of the one from the
107 %default section. There may be multiple %default sections of a given
108 type, but only one default may be supplied for any specific parameter
109 name. %default sections may not contain also or alsoflip parameters.
110
111 Currently there are two types of section: a config section specifies
112 general configuration information for IPsec, while a conn section
113 specifies an IPsec connection.
114
116 A conn section contains a connection specification, defining a network
117 connection to be made using IPsec. The name given is arbitrary, and is
118 used to identify the connection to ipsec_auto(8) Here's a simple
119 example:
120
121
122 conn snt
123 left=10.11.11.1
124 leftsubnet=10.0.1.0/24
125 leftnexthop=172.16.55.66
126 leftsourceip=10.0.1.1
127 right=192.168.22.1
128 rightsubnet=10.0.2.0/24
129 rightnexthop=172.16.88.99
130 rightsourceip=10.0.2.1
131 keyingtries=%forever
132
133 A note on terminology... In automatic keying, there are two kinds of
134 communications going on: transmission of user IP packets, and
135 gateway-to-gateway negotiations for keying, rekeying, and general
136 control. The data path (a set of “IPsec SAs”) used for user packets is
137 herein referred to as the “connection”; the path used for negotiations
138 (built with “ISAKMP SAs”) is referred to as the “keying channel”.
139
140 To avoid trivial editing of the configuration file to suit it to each
141 system involved in a connection, connection specifications are written
142 in terms of left and right participants, rather than in terms of local
143 and remote. Which participant is considered left or right is arbitrary;
144 IPsec figures out which one it is being run on based on internal
145 information. This permits using identical connection specifications on
146 both ends. There are cases where there is no symmetry; a good
147 convention is to use left for the local side and right for the remote
148 side (the first letters are a good mnemonic).
149
150 Many of the parameters relate to one participant or the other; only the
151 ones for left are listed here, but every parameter whose name begins
152 with left has a right counterpart, whose description is the same but
153 with left and right reversed.
154
155 Parameters are optional unless marked “(required)”
156
157 CONN PARAMETERS: GENERAL
158 The following parameters are relevant to IKE automatic keying. Unless
159 otherwise noted, for a connection to work, in general it is necessary
160 for the two ends to agree exactly on the values of these parameters.
161
162 keyexchange
163 method of key exchange; the default and currently the only accepted
164 value is ike
165
166 hostaddrfamily
167 the address family of the hosts; currently the accepted values are
168 ipv4 and ipv6. The default is to detect this based on the IP
169 addresses specified or the IP addresses resolved, so this option is
170 not needed, unless you specify hostnames that resolve to both IPv4
171 and IPv6. This option used to be named connaddrfamily but its use
172 was broken so it was obsoleted in favour or using the new
173 hostaddrfamily and clientaddrfamily.
174
175 clientaddrfamily
176 the address family of the clients (subnets); currently the accepted
177 values are ipv4 and ipv6. The default is to detect this based on
178 the network IP addresses specified or the network IP addresses
179 resolved, so this option is not needed, unless you specify names
180 that resolve to both IPv4 and IPv6.
181
182 type
183 the type of the connection; currently the accepted values are
184 tunnel (the default) signifying a host-to-host, host-to-subnet, or
185 subnet-to-subnet tunnel; transport, signifying host-to-host
186 transport mode; passthrough, signifying that no IPsec processing
187 should be done at all; drop, signifying that packets should be
188 discarded; and reject, signifying that packets should be discarded
189 and a diagnostic ICMP returned.
190
191 left
192 (required) the IP address or DNS hostname of the left participant's
193 public-network interface, Currently, IPv4 and IPv6 IP addresses are
194 supported. If a DNS hostname is used, it will be resolved to an IP
195 address on load time, and whenever a connection is rekeying or
196 restarting (such as when restarted via a DPD failure detection).
197 This allows one to use a DNS hostname when the endpoint is on a
198 dynamic IP address.
199
200 There are several magic values. If it is %defaultroute, left will
201 be filled in automatically with the local address of the
202 default-route interface (as determined at IPsec startup time); this
203 also overrides any value supplied for leftnexthop. (Either left or
204 right may be %defaultroute, but not both.) The value %any signifies
205 an address to be filled in (by automatic keying) during
206 negotiation. The value %opportunistic signifies that both left and
207 leftnexthop are to be filled in (by automatic keying) from DNS data
208 for left's client. The value can also contain the interface name,
209 which will then later be used to obtain the IP address from to fill
210 in. For example %ppp0. The values %group and %opportunisticgroup
211 makes this a policy group conn: one that will be instantiated into
212 a regular or opportunistic conn for each CIDR block listed in the
213 policy group file with the same name as the conn.
214
215 If using IP addresses in combination with NAT, always use the
216 actual local machine's (NATed) IP address, and if the remote (eg
217 right=) is NATed as well, the remote's public (not NATed) IP
218 address. Note that this makes the configuration no longer
219 symmetrical on both sides, so you cannot use an identical
220 configuration file on both hosts.
221
222 leftsubnet
223 private subnet behind the left participant, expressed as
224 network/netmask (actually, any form acceptable to
225 ipsec_ttosubnet(3)); Currently, IPv4 and IPv6 ranges are supported.
226 if omitted, essentially assumed to be left/32, signifying that the
227 left end of the connection goes to the left participant only
228
229 It supports two magic shorthands vhost: and vnet:, which can list
230 subnets in the same syntax as virtual-private. The value %priv
231 expands to the networks specified in virtual-private. The value %no
232 means no subnet. A common use for allowing roadwarriors to come in
233 on public IPs or via accepted NATed networks from RFC1918 is to use
234 leftsubnet=vhost:%no,%priv. The vnet: option can be used to allow
235 RFC1918 subnets without hardcoding them. When using vnet the
236 connection will instantiate, allowing for multiple tunnels with
237 different subnets.
238
239 leftsubnets
240 specify multiple private subnets behind the left participant,
241 expressed as { networkA/netmaskA, networkB/netmaskB [...] } If
242 both a leftsubnets= and rightsubnets= are defined, all combinations
243 of subnet tunnels will be established as IPsec tunnels. You cannot
244 use leftsubnet= and leftsubnets= together. For examples see
245 testing/pluto/multinet-*. Be aware that when using spaces as
246 separator, that the entire option value needs to be in double
247 quotes.
248
249 leftvti
250 the address/mask to configure on the VTI interface when
251 vti-interface is set. It takes the form of network/netmask
252 (actually, any form acceptable to ipsec_ttosubnet(3)); Currently,
253 IPv4 and IPv6 ranges are supported. This option is often used in
254 combination with routed based VPNs.
255
256 leftaddresspool
257 address pool from where the IKEv1 ModeCFG or IKEv2 server can
258 assign IP addresses to clients. When configured as a server, using
259 leftxauthserver=yes this option specifies the address pool from
260 which IP addresses are taken to assign the clients. The syntax of
261 the address pool specifies a range (not a CIDR) for IPv4 and CIDR
262 for IPv6, in the following syntax:
263 rightaddresspool=192.168.1.100-192.168.1.200 or
264 rightaddresspool=2001:db8:0:3:1::/97 Generally, the
265 rightaddresspool= option will be accompanied by
266 rightxauthclient=yes, leftxauthserver=yes and leftsubnet=0.0.0.0/0
267 option.
268
269 When leftaddresspool= is specified, the connection may not specify
270 either leftsubnet= or leftsubnets=. Address pools are fully
271 allocated when the connection is loaded, so the ranges should be
272 sane. For example, specifying a range
273 rightaddresspool=10.0.0.0-11.0.0.0 will lead to massive memory
274 allocation. Address pools specifying the exact same range are
275 shared between different connections. Different addresspools should
276 not be defined to partially overlap.
277
278 leftprotoport
279 allowed protocols and ports over connection, also called Port
280 Selectors. The argument is in the form protocol, which can be a
281 number or a name that will be looked up in /etc/protocols, such as
282 leftprotoport=icmp, or in the form of protocol/port, such as
283 tcp/smtp. Ports can be defined as a number (eg. 25) or as a name
284 (eg smtp) which will be looked up in /etc/services. A special
285 keyword %any can be used to allow all ports of a certain protocol.
286 The most common use of this option is for L2TP connections to only
287 allow l2tp packets (UDP port 1701), eg: leftprotoport=17/1701.
288
289 To filter on specific icmp type and code, use the higher 8 bits for
290 type and the lower 8 bits for port. For example, to allow icmp echo
291 packets (type 8, code 0) the 'port' would be 0x0800, or 2048 in
292 decimal, so you configure leftprotoport=icmp/2048. Similarly, to
293 allow ipv6-icmp Neighbour Discovery which has type 136 (0x88) and
294 code 0(0x00) this becomes 0x8800 or in decimal 34816 resulting in
295 leftprotoport=ipv6-icmp/34816 .
296
297 Some clients, notably older Windows XP and some Mac OSX clients,
298 use a random high port as source port. In those cases
299 rightprotoport=17/%any can be used to allow all UDP traffic on the
300 connection. Note that this option is part of the proposal, so it
301 cannot be arbitrarily left out if one end does not care about the
302 traffic selection over this connection - both peers have to agree.
303 The Port Selectors show up in the output of ipsec eroute and ipsec
304 auto --status eg:"l2tp":
305 193.110.157.131[@aivd.libreswan.org]:7/1701...%any:17/1701 This
306 option only filters outbound traffic. Inbound traffic selection
307 must still be based on firewall rules activated by an updown
308 script. The variables $PLUTO_MY_PROTOCOL, $PLUTO_PEER_PROTOCOL,
309 $PLUTO_MY_PORT, and $PLUTO_PEER_PORT are available for use in
310 updown scripts. Older workarounds for bugs involved a setting of
311 17/0 to denote any single UDP port (not UDP port 0). Some clients,
312 most notably OSX, uses a random high port, instead of port 1701 for
313 L2TP.
314
315 leftnexthop
316 next-hop gateway IP address for the left participant's connection
317 to the public network; defaults to %direct (meaning right). If the
318 value is to be overridden by the left=%defaultroute method (see
319 above), an explicit value must not be given. If that method is not
320 being used, but leftnexthop is %defaultroute, and
321 interfaces=%defaultroute is used in the config setup section, the
322 next-hop gateway address of the default-route interface will be
323 used. The magic value %direct signifies a value to be filled in (by
324 automatic keying) with the peer's address. Relevant only locally,
325 other end need not agree on it.
326
327 leftsourceip
328 the IP address for this host to use when transmitting a packet to
329 the other side of this link. Relevant only locally, the other end
330 need not agree. This option is used to make the gateway itself use
331 its internal IP, which is part of the leftsubnet, to communicate to
332 the rightsubnet or right. Otherwise, it will use its nearest IP
333 address, which is its public IP address. This option is mostly used
334 when defining subnet-subnet connections, so that the gateways can
335 talk to each other and the subnet at the other end, without the
336 need to build additional host-subnet, subnet-host and host-host
337 tunnels. Both IPv4 and IPv6 addresses are supported.
338
339 leftupdown
340 what "updown" script to run to adjust routing and/or firewalling
341 when the status of the connection changes (default ipsec _updown).
342 May include positional parameters separated by white space
343 (although this requires enclosing the whole string in quotes);
344 including shell metacharacters is unwise. An example to enable
345 routing when using the NETKEY stack, one can use:
346
347 leftupdown="ipsec _updown --route yes"
348
349 To disable calling an updown script, set it to the empty string, eg
350 leftupdown="" or leftupdown="%disabled".
351
352 See ipsec_pluto(8) for details. Relevant only locally, other end
353 need not agree on it.
354
355 leftcat
356 Whether to perform Client Address Translation ("CAT") when using
357 Opportunistic IPsec behind NAT. Accepted values are no (the
358 default) and yes. This option should only be enabled on the special
359 Opportunistic IPsec connections, usually called "private" and
360 "private-or-clear". When set, this option causes the given
361 addresspool IP from the remote peer to be NATed with iptables. It
362 will also install an additional IPsec SA policy to cover the
363 pre-NAT IP. See the Opportunistic IPsec information on the
364 libreswan website for more information and examples.
365
366 leftfirewall
367 This option is obsolete and should not used anymore.
368
369 If one or both security gateways are doing forwarding firewalling
370 (possibly including masquerading), and this is specified using the
371 firewall parameters, tunnels established with IPsec are exempted from
372 it so that packets can flow unchanged through the tunnels. (This means
373 that all subnets connected in this manner must have distinct,
374 non-overlapping subnet address blocks.) This is done by the default
375 updown script (see ipsec_pluto(8)).
376
377 The implementation of this makes certain assumptions about firewall
378 setup, and the availability of the Linux Advanced Routing tools. In
379 situations calling for more control, it may be preferable for the user
380 to supply his own updown script, which makes the appropriate
381 adjustments for his system.
382
383 CONN PARAMETERS: AUTOMATIC KEYING
384 The following parameters are relevant to automatic keying via IKE.
385 Unless otherwise noted, for a connection to work, in general it is
386 necessary for the two ends to agree exactly on the values of these
387 parameters.
388
389 auto
390 what operation, if any, should be done automatically at IPsec
391 startup; currently-accepted values are add (signifying an ipsec
392 auto --add), ondemand (signifying that plus an ipsec auto
393 --ondemand), start (signifying that plus an ipsec auto --up), and
394 ignore (also the default) (signifying no automatic startup
395 operation), and keep (signifying an add plus an attempt to keep the
396 connection up once the remote peer brought it up). See the config
397 setup discussion below. Relevant only locally, other end need not
398 agree on it (but in general, for an intended-to-be-permanent
399 connection, both ends should use auto=start to ensure that any
400 reboot causes immediate renegotiation).
401
402 The option ondemand used to be called route
403
404 authby
405 how the two security gateways should authenticate each other; the
406 default value is rsasig,ecdsa which allows ECDSA with SHA-2 and RSA
407 with SHA2 or SHA1. To limit this further, there are the options of
408 ecdsa for ECDSA digital signatures using SHA-2, rsa-sha2 for
409 RSASSA-PSS digital signatures based authentication with SHA2-256,
410 rsa-sha2_384 for RSASSA-PSS digital signatures based authentication
411 with SHA2-384, rsa-sha2_512 for RSASSA-PSS digital signatures based
412 authentication with SHA2-512, rsa-sha1 for RSA-PKCSv1.5 digital
413 signatures based authentication with SHA1, secret for shared
414 secrets (PSK) authentication, secret|rsasig for either, never if
415 negotiation is never to be attempted or accepted (useful for
416 shunt-only conns), and null for null-authentication.
417
418 If asymmetric authentication is requested, IKEv2 must be enabled,
419 and the options leftauth= and rightauth= should be used instead of
420 authby.
421
422 For IKEv1, SHA2 based signatures are not defined and ECDSA is not
423 implemented, so the default authby= value is rsa-sha1. Using
424 authby=rsasig results in only rsa-sha1 as well. For IKEv2, using
425 authby=rsasig means using rsa-sha2_512, rsa-sha2_384, rsa-sha2_256
426 and rsa-sha1, where rsa-sha1 will used only if RFC 7427 is not
427 supported by the peer.
428
429 As per RFC 8221, authby=rsa-sha1 is only supported in the old
430 style, meaning RSA-PKCSv1.5. The SHA2 variants are only supported
431 for the new style of RFC 7427, so authby=rsa-sha2 will use the new
432 style. The default authby= will remove rsa-sha1 in the near future.
433 It is strongly recommended that if certificates are used, the
434 certificates and the authby= signature methods used are the same,
435 as it increases interoperability and keeps the authentication of
436 everything within one digital signature system.
437
438 Digital signatures are superior in every way to shared secrets.
439 Especially IKEv1 in Aggressive Mode is vulnerable to offline
440 dictionary attacks and is performed routinely by at least the NSA
441 on monitored internet traffic globally. The never option is only
442 used for connections that do not actually start an IKE negotiation,
443 such as type=passthrough connections. The auth method null is used
444 for "anonymous opportunistic IPsec" and should not be used for
445 regular pre-configured IPsec VPNs.
446
447 ike
448 IKE encryption/authentication algorithm to be used for the
449 connection (phase 1 aka ISAKMP SA or IKE SA). If this option is not
450 set, the builtin defaults will be used. This is the prefered
451 method, and allows for gradual automatic updates using the same
452 configuration. Some distributions, such as Fedora and RHEL/CentOS,
453 use a System Wide Crypto Policy that sets the default ike= (and
454 esp=) lines. Specifying your own ike= line means overriding all
455 these system or software recommended defaults, but can be
456 neccessary at times. Note that libreswan does not support using a
457 PRF algorithm that is different from the INTEGRITY (hash) algorithm
458 by design.
459
460 The format is "cipher-hash;modpgroup, cipher-hash;modpgroup, ..."
461 Any omitited option will be filled in with all allowed default
462 values. Multiple proposals are separated by a comma. If an ike=
463 line is specified, no other received proposals will be accepted
464 than those specified on the IKE line. Some examples are
465 ike=3des-sha1,aes-sha1, ike=aes, ike=aes_ctr, ike=aes_gcm256-sha2,
466 ike=aes128-md5;modp2048, ike=aes256-sha2;dh19,
467 ike=aes128-sha1;dh22, ike=3des-md5;modp1024,aes-sha1;modp1536.
468
469 IKEv2 allows combining elements into a single proposal. These can
470 be specified by using the + symbol. An example is:
471 ike=aes_gcm+chacha20_poly1305;dh14+dh19,aes+3des-sha2+sha1;dh14.
472 Note that AEAD algorithms (aes_gcm, aes_ccm, chacha20_poly1305) and
473 non-AEAD algorithms (aes, 3des) cannot be combined into a single
474 proposal. To support aes and aes_gcm, two proposals seperated by a
475 comma must be used.
476
477 The default IKE proposal depends on the version of libreswan used.
478 It follow the recommendations of RFC4306, RFC7321 and as of this
479 writing their successor draft documents RFC4306bis and RFC7321bis.
480 As for libreswan 3.32, SHA1 and MODP1536(dh5) are still allowed per
481 default for backwards compatibility, but 3DES and MODP1024(dh2) are
482 not allowed per default. As of libreswan 4.x, modp1024(dh2) support
483 is no longer compiled in at all. For IKEv2, the defaults include
484 AES, AES-GCM, DH14 and stronger, and SHA2. The default key size is
485 256 bits. The default AES_GCM ICV is 16 bytes.
486
487 Note that AES-GCM is an AEAD algorithm, meaning that it performs
488 encryption+authentication in one step. This means that AES-GCM must
489 not specify an authentication algorithm. However, for IKE it does
490 require a PRF function, so the second argument to an AEAD algorithm
491 denotes the PRF. So ike=aes_gcm-sha2 means propose AES_GCM with
492 SHA2 as the prf. Note that for phase2alg, there is no prf, so
493 AES-GCM is specified for ESP as esp=aes_gcm-null. The AES-GCM and
494 AES-CCM algorithms support 8,12 and 16 byte ICV's. These can be
495 specified using a postfix, for example aes_gcm_a (for 8), aes_gcm_b
496 (for 12) and aes_gcm_c (for 16). The default (aes_gcm without
497 postfix) refers to the 16 byte ICV version. It is strongly
498 recommended to NOT use the 8 or 12 byte versions of GCM or CCM.
499 These versions are NOT included in the default and will be removed
500 in a future version, following the recommendation of RFC 8247 or it
501 successor.
502
503 Weak algorithms are regularly removed from libreswan. Currently,
504 1DES and modp768(DH1) have been removed and modp1024(DH2) has been
505 disabled at compile time. Additionally, MD5 and SHA1 will be
506 removed within the next few years. Null encryption is available,
507 and should only be used for testing or benchmarking purposes.
508 Please do not request for insecure algorithms to be re-added to
509 libreswan. IKEv1 has been disabled per default, and will soon no
510 longer be compiled in by default.
511
512 For all Diffie-Hellman groups, the "dh" keyword can be used instead
513 of the "modp" keyword. For example ike=3des-sha1;dh19.
514 Diffie-Hellman groups 19,20 and 21 from RFC-5903 are supported.
515 Curve25519 from RFC-8031 is supported as "dh31". Curve448 and GOST
516 DH groups are not yet supported in libreswan because these are not
517 supported yet in the NSS crypto library.
518
519 Diffie-Hellman groups 22, 23 and 24 from RFC-5114 are implemented
520 but not compiled in by default. These DH groups are extremely
521 controversial and MUST NOT be used unless forced (administratively)
522 by the other party. This is further documented in RFC 8247, but the
523 summary is that it cannot be proven that these DH groups do not
524 contain a cryptographic trapdoor (a backdoor by the USG who
525 provided these primes without revealing the seeds and generation
526 process used).
527
528 The modp syntax will be removed in favour of the dh syntax in the
529 future
530
531 phase2
532 Sets the type of SA that will be produced. Valid options are: esp
533 for encryption (the default), ah for authentication only.
534
535 The very first IPsec designs called for use of AH plus ESP to offer
536 authentication, integrity and confidentiality. That dual protocol
537 use was a significant burden, so ESP was extended to offer all
538 three services, and AH remained as an auth/integ. The old mode of
539 ah+esp is no longer supported in compliance with RFC 8221 Section
540 4. Additionally, AH does not play well with NATs, so it is strongly
541 recommended to use ESP with the null cipher if you require
542 unencrypted authenticated transport.
543
544 phase2alg
545 This option is alias to esp.
546
547 sha2-truncbug
548 The default ESP hash truncation for sha2_256 is 128 bits. Some
549 IPsec implementations (Linux before 2.6.33, some Cisco (2811?)
550 routers) implement the draft version which stated 96 bits. If a
551 draft implementation communicates with an RFC implementation, both
552 ends will reject encrypted packets from each other.
553
554 This option enables using the draft 96 bits version to interop with
555 those implementations. Currently the accepted values are no, (the
556 default) signifying default RFC truncation of 128 bits, or yes,
557 signifying the draft 96 bits truncation.
558
559 Another workaround is to switch from sha2_256 to sha2_128 or
560 sha2_512.
561
562 ms-dh-downgrade
563 Whether to allow a downgrade of DiffieHellman group during rekey
564 (using CREATE_CHILD_SA). Microsoft Windows (at the time of writing,
565 Feb 2018) defaults to using the very weak modp1024 (DH2). This can
566 be changed using a Windows registry setting to use modp2048 (DH14).
567 However, at rekey times, it will shamelessly use modp1024 again and
568 the connection might fail. Setting this option to yes (and adding
569 modp1024 proposals to the ike line) this will allow this downgrade
570 attack to happen. This should only be used to support Windows that
571 feature this bug. Currently the accepted values are no, (the
572 default) or yes.
573
574 dns-match-id
575 Whether to perform an additional DNS lookup and confirm the remote
576 ID payload with the DNS name in the reverse DNS PTR record.
577 Accepted values are no (the default) or yes. This check should be
578 enabled when Opportunistic IPsec is enabled in a mode that is based
579 on packet triggers (on-demand) using IPSECKEY records in DNS. Since
580 in that case the IKE daemon pluto does not know the remote ID, it
581 only knows the remote IP address, this option forces it to confirm
582 the peer's proposed ID (and thus its public/private key) with its
583 actual IP address as listed in the DNS. This prevents attacks where
584 mail.example.com's IP address is taken over by a neighbour machine
585 with a valid web.example.com setup. This check is not needed for
586 certificate based Opportunistic IPsec, as "mail.example.com"s
587 certificate does not have an entry for "web.example.com". It is
588 also not needed for DNS server triggered Opportunistic IPsec, as in
589 that case the IKE daemon pluto is informed of both the IP address,
590 and the hostname/public key.
591
592 require-id-on-certificate
593 When using certificates, check whether the IKE peer ID is present
594 as a subjectAltName (SAN) on the peer certificate. Accepted values
595 are yes (the default) or no. This check should only be disabled
596 when intentionally using certificates that do not have their peer
597 ID specified as a SAN on the certificate. These certificates
598 violate RFC 4945 Section 3.1 and are normally rejected to prevent a
599 compromised host from assuming the IKE identity of another host.
600 The SAN limits the IDs that the peer is able to assume.
601
602 ppk
603 EXPERIMENTAL: Post-quantum preshared keys (PPKs) to be used.
604 Currently the accepted values are propose or yes (the default),
605 signifying we propose to use PPK for this connection; insist,
606 signifying we allow communication only if PPK is used for key
607 derivation; never or no, signifying that PPK should not be used for
608 key derivation. PPKs can be used in connections that allow only
609 IKEv2. In libreswan that would mean that ikev2 option must have
610 value insist. (currently based on draft-fluhrer-qr-ikev2, not
611 raft-ietf-ipsecme-qr-ikev2-00)
612
613 nat-ikev1-method
614 NAT Traversal in IKEv1 is negotiated via Vendor ID options as
615 specified in RFC 3947. However, many implementations only support
616 the draft version of the RFC. Libreswan sends both the RFC and the
617 most common draft versions (02, 02_n and 03) to maximize
618 interoperability. Unfortunately, there are known broken
619 implementations of RFC 3947, notably Cisco routers that have not
620 been updated to the latest firmware. As the NAT-T payload is sent
621 in the very first packet of the initiator, there is no method to
622 auto-detect this problem and initiate a workaround.
623
624 This option allows fine tuning which of the NAT-T payloads to
625 consider for sending and processing. Currently the accepted values
626 are drafts, rfc, both (the default) and none. To interoperate with
627 known broken devices, use nat-ikev1-method=drafts. To prevent the
628 other end from triggering IKEv1 NAT-T encapsulation, set this to
629 none. This will omit the NAT-T payloads used to determine NAT,
630 forcing the other end not to use encapsulation.
631
632 esp
633 Specifies the algorithms that will be offered/accepted for a Child
634 SA negotiation. If not specified, a secure set of defaults will be
635 used. Sets are separated using comma's and pluses.
636
637 The format for ESP is ENC-AUTH followed by one optional PFSgroup.
638 For instance, "aes_gcm256" or "aes256-sha2_512-dh14" or
639 "aes-sha2_512+sha2_256". When specifying multiple algorithms,
640 specify the PFSgroup last, e.g.
641 "aes128+aes256-sha2_512+sha2_256-dh14+dh19".
642
643 The format for AH is AUTH followed by an optional PFSgroup. For
644 instance, "sha2_512" or "sha2_256-dh14".
645
646 AEAD algorithms such as AES-GCM and AES-CCM don't require separate
647 hashing algorithm, for example esp=aes_gcm256 or esp=aes_ccm. Note
648 that the ike= syntax for aes_gcm does require the prf hashing
649 algorithm which is not needed for esp=. The supported key sizes for
650 aes_gcm are 128, 192 and 256, which are specified similarly to
651 plain aes, i.e. esp=aes_gcm256. A subscript of _c, _b or _a can be
652 used to refer to the different ICV variants where a means 8 bytes,
653 b means 12 bytes and c means 16 bytes. The default when not using a
654 subscript is the 16 byte ICV, the recommended value by RFC-4106 and
655 RFC-8247. Therefore esp=aes_gcm256 is equivalent to
656 esp=aes_gcm_c256. It is recommended to migrate to the _c versions
657 (without specifying _c), as support for smaller ICV's might be
658 removed in the near future.
659
660 The supported algorithms depend on the libreswan version, OS and
661 kernel stack used. Possible ciphers are aes, 3des, aes_ctr,
662 aes_gcm, aes_ccm, camellia and chacha20_poly1305.
663
664 Note that openswan and versions of libreswan up to 3.6 require
665 manually adding the salt size to the key size. Therefore, to
666 configure an older version of openswan or libreswan, use:
667 "esp=aes_ccm_c-280-null" to interop with a new libreswan using
668 "esp=aes_ccm256". For CCM, the 'keysize' needs to be increased by
669 24, resulted in valid keysizes of 152, 215 and 280. For GCM the
670 'keysize' needs to be increased by 32, resulting valid 'keysizes'
671 of 160, 224 and 288.
672
673 ah
674 AH authentication algorithm to be used for the connection, e.g
675 here. sha2_512 The options must be suitable as a value of
676 ipsec_spi(8)'s --ah option. The default is not to use AH. If for
677 some (invalid) reason you still think you need AH, please use esp
678 with the null encryption cipher instead. Note also that not all
679 ciphers available to the kernel (eg through CryptoAPI) are
680 necessarily supported here.
681
682 fragmentation
683 Whether or not to allow IKE fragmentation. Valid values are yes,
684 (the default), no or force.
685
686 IKEv1 fragmentation capabilities are negotiated via a well-known
687 private vendor id. IKEv2 fragmentation support is implemented using
688 RFC 7383. If pluto does not receive the fragmentation payload, no
689 IKE fragments will be sent, regardless of the fragmentation=
690 setting. When set to yes, IKE fragmentation will be attempted on
691 the first re-transmit of an IKE packet of a size larger then 576
692 bytes for IPv4 and 1280 bytes for IPv6. If fragmentation is set to
693 force, IKE fragmentation is used on initial transmits of such sized
694 packets as well. When we have received IKE fragments for a
695 connection, pluto behaves as if in force mode.
696
697 ikepad
698 Whether or not to pad IKEv1 messages to a multiple of 4 bytes.
699 Valid values are yes, (the default) and no.
700
701 IKE padding is allowed in IKEv1 but has been known to cause
702 interoperability issues. The ikepad= option can be used to disable
703 IKEv1 padding. This used to be required for some devices (such as
704 Checkpoint in Aggressive Mode) that reject padded IKEv1 packets. A
705 bug was fixed in libreswan 3.25 that applied wrong IKE padding in
706 XAUTH, so it is suspected that Checkpoint padding issue bas been
707 resolved. And this option should not be needed by anyone. In IKEv2,
708 no padding is allowed, and this option has no effect. If you find a
709 device that seems to require IKE padding, please contact the
710 libreswan developers. This option should almost never be enabled
711 and might be removed in a future version.
712
713 ikev2
714 Whether to use IKEv1 (RFC 4301) or IKEv2 (RFC 7296) settings to be
715 used. Currently the accepted values are no(the default), signifying
716 only IKEv1 is accepted, or yes, signifying only IKEv2 is accepted.
717 Previous versions allowed the keywords propose or permit that would
718 allow either IKEv1 or IKEv2, but this is no longer supported. The
719 permit option is interpreted as no and the propose option is
720 interpreted as yes. Older versions also supported keyword insist
721 which is now interpreted as yes.
722
723 mobike
724 Whether to allow MOBIKE (RFC 4555) to enable a connection to
725 migrate its endpoint without needing to restart the connection from
726 scratch. This is used on mobile devices that switch between wired,
727 wireless or mobile data connections. Current values are no (the
728 default) or yes, Only connection acting as modecfgclient will allow
729 the initiator to migrate using mobike. Only connections acting as
730 modecfgserver will allow clients to migrate.
731
732 VTI and MOBIKE might not work well when used together.
733
734 esn
735 Whether or not to enable Extended Sequence Number (ESN) for the
736 IPsec SA. ESN is typically used for very high-speed links (10Gbps
737 or faster) where the standard 32 bit sequence number is exhausted
738 too quickly, causing IPsec SA's rekeys to happen too often.
739 Accepted values are no (the default), yes and either. If either is
740 specified as an initiator, the responder will make the choice. As a
741 responder, if either is received, no is picked.
742
743 decap-dscp
744 Enable decapsulating the Differentiated Services Code Point (DSCP,
745 formerly known as Terms Of Service (TOS)) bits. If these bits are
746 set on the inner (encrypted) IP packets, these bits are set on the
747 decrypted IP packets. Acceptable values are no (the default) or
748 yes. Currently this feature is only implemented for the Linux
749 XFRM/NETKEY stack.
750
751 nopmtudisc
752 Disable Path MTU discovery for the IPsec SA. Acceptable values are
753 no (the default) or yes. Currently this feature is only implemented
754 for the Linux XFRM/NETKEY stack.
755
756 narrowing
757 IKEv2 (RFC5996) Section 2.9 Traffic Selector narrowing options.
758 Currently the accepted values are no, (the default) signifying no
759 narrowing will be proposed or accepted, or yes, signifying IKEv2
760 negotiation may allow establishing an IPsec connection with
761 narrowed down traffic selectors. This option is ignored for IKEv1.
762
763 There are security implications in allowing narrowing down the
764 proposal. For one, what should be done with packets that we hoped
765 to tunnel, but cannot. Should these be dropped or send in the
766 clear? Second, this could cause thousands of narrowed down Child
767 SAs to be created if the conn has a broad policy (eg 0/0 to 0/0).
768 One possible good use case scenario is that a remote end (that you
769 fully trust) allows you to define a 0/0 to them, while adjusting
770 what traffic you route via them, and what traffic remains outside
771 the tunnel. However, it is always preferred to setup the exact
772 tunnel policy you want, as this will be much clearer to the user.
773
774 sareftrack
775 Set the method of tracking reply packets with SArefs when using an
776 SAref compatible stack. Currently only the mast stack supports
777 this. Acceptable values are yes (the default), no or conntrack.
778 This option is ignored when SArefs are not supported. This option
779 is passed as PLUTO_SAREF_TRACKING to the updown script which makes
780 the actual decisions whether to perform any iptables/ip_conntrack
781 manipulation. A value of yes means that an IPSEC mangle table will
782 be created. This table will be used to match reply packets. A value
783 of conntrack means that additionally, subsequent packets using this
784 connection will be marked as well, reducing the lookups needed to
785 find the proper SAref by using the ip_conntrack state. A value of
786 no means no IPSEC mangle table is created, and SAref tracking is
787 left to a third-party (kernel) module. In case of a third party
788 module, the SArefs can be relayed using the statsbin= notification
789 helper.
790
791 nic-offload
792 Set the method of Network Interface Controller (NIC) hardware
793 offload for ESP/AH packet processing. Acceptable values are auto
794 (the default), yes or no. This option is separate from any CPU
795 hardware offload available and is currently only available on Linux
796 4.13+ using the NETKEY/XFRM IPsec stack, when compiled with the
797 options CONFIG_XFRM_OFFLOAD, CONFIG_INET_ESP_OFFLOAD and
798 CONFIG_INET6_ESP_OFFLOAD. The auto option will attempt to
799 auto-detect the presence of kernel and hardware support, and then
800 automatically mark the IPsec SA for hardware offloading. One vendor
801 supporting this offload method is Mellanox.
802
803 leftid
804 how the left participant should be identified for authentication;
805 defaults to left. Can be an IP address or a fully-qualified domain
806 name which will be resolved. If preceded by @, the value is used as
807 a literal string and will not be resolved. To support opaque
808 identifiers (usually of type ID_KEY_ID, such as used by Cisco to
809 specify Group Name, use square brackets, eg rightid=@[GroupName].
810 The magic value %fromcert causes the ID to be set to a DN taken
811 from a certificate that is loaded. Prior to 2.5.16, this was the
812 default if a certificate was specified. The magic value %none sets
813 the ID to no ID. This is included for completeness, as the ID may
814 have been set in the default conn, and one wishes for it to default
815 instead of being explicitly set. The magic value %myid stands for
816 the current setting of myid. This is set in config setup or by
817 ipsec_whack(8)), or, if not set, it is the IP address in
818 %defaultroute (if that is supported by a TXT record in its reverse
819 domain), or otherwise it is the system's hostname (if that is
820 supported by a TXT record in its forward domain), or otherwise it
821 is undefined.
822
823 When using certificate based ID's, one need to specify the full
824 RDN, optionally using wildcard matching (eg CN='*'). If the RDN
825 contains a comma, this can be masked using a comma (eg OU='Foo,,
826 Bar and associates')
827
828 leftrsasigkey
829 the left participant's public key for RSA signature authentication,
830 in RFC 2537 format using ipsec_ttodata(3) encoding. The magic value
831 %none means the same as not specifying a value (useful to override
832 a default). The value %dnsondemand (the default) means the key is
833 to be fetched from DNS at the time it is needed. The value
834 %dnsonload means the key is to be fetched from DNS at the time the
835 connection description is read from ipsec.conf; currently this will
836 be treated as %none if right=%any or right=%opportunistic. The
837 value %dns is currently treated as %dnsonload but will change to
838 %dnsondemand in the future. The identity used for the left
839 participant must be a specific host, not %any or another magic
840 value. The value %cert will load the information required from a
841 certificate defined in %leftcert and automatically define leftid
842 for you. Caution: if two connection descriptions specify different
843 public keys for the same leftid, confusion and madness will ensue.
844
845 leftcert
846 If you are using leftrsasigkey=%cert this defines the certificate
847 nickname of your certificate in the NSS database. This can be on
848 software or hardware security device.
849
850 leftckaid
851 The hex CKAID of the X.509 certificate. Certificates are stored in
852 the NSS database.
853
854 leftauth
855 How the security gateways will authenticate to the other side in
856 the case of asymmetric authentication; acceptable values are rsasig
857 for RSA Authentication with SHA-1, rsa-sha2 for RSA-PSS digital
858 signatures based authentication with SHA2-256, rsa-sha2_384 for
859 RSA-PSS digital signatures based authentication with SHA2-384,
860 rsa-sha2_512 for RSA-PSS digital signatures based authentication
861 with SHA2-512, secret for shared secrets (PSK) authentication and
862 null for null-authentication. There is no default value - if unset,
863 the symmetrical authby= keyword is used to determine the
864 authentication policy of the connection.
865
866 If asymmetric authentication is requested, IKEv1 must be disabled.
867 If symmetric authentication is required, use authby= instead of
868 leftauth/rightauth. If leftauth is set, rightauth must also be set
869 and authby= must not be set. Asymmetric authentication cannot use
870 secret (psk) on one side and null on the other side - use psk on
871 both ends instead.
872
873 Be aware that the symmetric keyword is authby= but the asymmetric
874 keyword is leftauth and rightauth (without the "by").
875
876 leftca
877 specifies the authorized Certificate Authority (CA) that signed the
878 certificate of the peer. If undefined, it defaults to the CA that
879 signed the certificate specified in leftcert. The special
880 rightca=%same is implied when not specifying a rightca and means
881 that only peers with certificates signed by the same CA as the
882 leftca will be allowed. This option is only useful in complex multi
883 CA certificate situations. When using a single CA, it can be safely
884 omitted for both left and right.
885
886 leftikeport
887 The UDP IKE port to listen on or send data to. This port cannot be
888 0 or 500. For TCP, see tcp-remoteport=
889
890 leftsendcert
891 This option configures when Libreswan will send X.509 certificates
892 to the remote host. Acceptable values are yes|always (signifying
893 that we should always send a certificate), sendifasked (signifying
894 that we should send a certificate if the remote end asks for it),
895 and no|never (signifying that we will never send a X.509
896 certificate). The default for this option is sendifasked which may
897 break compatibility with other vendor's IPsec implementations, such
898 as Cisco and SafeNet. If you find that you are getting errors about
899 no ID/Key found, you likely need to set this to always. This
900 per-conn option replaces the obsolete global nocrsend option.
901
902 leftxauthserver
903 Left is an XAUTH server. This can use PAM for authentication or md5
904 passwords in /etc/ipsec.d/passwd. These are additional credentials
905 to verify the user identity, and should not be confused with the
906 XAUTH group secret, which is just a regular PSK defined in
907 ipsec.secrets. The other side of the connection should be
908 configured as rightxauthclient. XAUTH connections cannot rekey, so
909 rekey=no should be specified in this conn. For further details on
910 how to compile and use XAUTH, see README.XAUTH. Acceptable values
911 are yes or no (the default).
912
913 leftxauthclient
914 Left is an XAUTH client. The xauth connection will have to be
915 started interactively and cannot be configured using auto=start.
916 Instead, it has to be started from the commandline using ipsec auto
917 --up connname. You will then be prompted for the username and
918 password. To setup an XAUTH connection non-interactively, which
919 defeats the whole purpose of XAUTH, but is regularly requested by
920 users, it is possible to use a whack command - ipsec whack --name
921 baduser --ipsecgroup-xauth --xauthname badusername --xauthpass
922 password --initiate The other side of the connection should be
923 configured as rightxauthserver. Acceptable values are yes or no
924 (the default).
925
926 leftusername
927 The username associated with this connection. The username can be
928 the IKEv2 XAUTH username, a GSSAPI username or IKEv2 CP username.
929 For the XAUTH username, the XAUTH password can be configured in the
930 ipsec.secrets file. This option was previously called
931 leftxauthusername.
932
933 leftmodecfgserver
934 Left is a Mode Config server. It can push network configuration to
935 the client. Acceptable values are yes or no (the default).
936
937 leftmodecfgclient
938 Left is a Mode Config client. It can receive network configuration
939 from the server. Acceptable values are yes or no (the default).
940
941 xauthby
942 When IKEv1 XAUTH support is available, set the method used by XAUTH
943 to authenticate the user with IKEv1. The currently supported values
944 are file (the default), pam or alwaysok. The password file is
945 located at /etc/ipsec.d/passwd, and follows a syntax similar to the
946 Apache htpasswd file, except an additional connection name argument
947 (and optional static IP address) are also present:
948
949 username:password:conname:ipaddress
950
951 For supported password hashing methods, see crypt(3). If pluto is
952 running in FIPS mode, some hash methods, such as MD5, might not be
953 available. Threads are used to launch an xauth authentication
954 helper for file as well as PAM methods.
955
956 The alwaysok should only be used if the XAUTH user authentication
957 is not really used, but is required for interoperability, as it
958 defeats the whole point of XAUTH which is to rely on a secret only
959 known by a human. See also pam-authorize=yes
960
961 xauthfail
962 When XAUTH support is available, set the failure method desired
963 when authentication has failed. The currently supported values are
964 hard (the default) and soft. A soft failure means the IPsec SA is
965 allowed to be established, as if authentication had passed
966 successfully, but the XAUTH_FAILED environment variable will be set
967 to 1 for the updown script, which can then be used to redirect the
968 user into a walled garden, for example a payment portal.
969
970 pam-authorize
971 IKEv1 supports PAM authorization via XAUTH using xauthby=pam. IKEv2
972 does not support receiving a plaintext username and password.
973 Libreswan does not yet support EAP authentication methods for IKE.
974 The pam-authorize=yes option performs an authorization call via
975 PAM, but only includes the remote ID (not username or password).
976 This allows for backends to disallow an ID based on non-password
977 situations, such as "user disabled" or "user over quota". See also
978 xauthby=pam
979
980 modecfgpull
981 Pull the Mode Config network information from the server.
982 Acceptable values are yes or no (the default).
983
984 modecfgdns, modecfgdomains, modecfgbanner
985 When configured as IKEv1 ModeCFG or IKEv2 server, specifying any of
986 these options will cause those options and values to be sent to the
987 connecting client. Libreswan as a client will use these received
988 options to either update /etc/resolv.conf or the running unbound
989 DNS server. When the connection is brought down, the previous DNS
990 resolving state is restored.
991
992 The modecfgdns option takes a comma or space separated list of IP
993 addresses that can be used for DNS resolution. The modecfgdomains
994 option takes a comma or space separated list of internal domain
995 names that are reachable via the supplied modecfgdns DNS servers.
996
997 The IKEv1 split tunnel directive will be sent automatically if the
998 xauth server side has configured a network other than 0.0.0.0/0.
999 For IKEv2, this is automated via narrowing.
1000
1001 remote-peer-type
1002 Set the remote peer type. This can enable additional processing
1003 during the IKE negotiation. Acceptable values are cisco or ietf
1004 (the default). When set to cisco, support for Cisco IPsec gateway
1005 redirection and Cisco obtained DNS and domainname are enabled. This
1006 includes automatically updating (and restoring) /etc/resolv.conf.
1007 These options require that XAUTH is also enabled on this
1008 connection.
1009
1010 nm-configured
1011 Mark this connection as controlled by Network Manager. Acceptable
1012 values are yes or no (the default). Currently, setting this to yes
1013 will cause libreswan to skip reconfiguring resolv.conf when used
1014 with XAUTH and ModeConfig.
1015
1016 encapsulation
1017 In some cases, for example when ESP packets are filtered or when a
1018 broken IPsec peer does not properly recognise NAT, it can be useful
1019 to force RFC-3948 encapsulation. In other cases, where IKE is
1020 NAT'ed but ESP packets can or should flow without encapsulation, it
1021 can be useful to ignore the NAT-Traversal auto-detection.
1022 encapsulation=yes forces the NAT detection code to lie and tell the
1023 remote peer that RFC-3948 encapsulation (ESP in port 4500 packets)
1024 is required. encapsulation=no ignores the NAT detection causing
1025 ESP packets to send send without encapsulation. The default value
1026 of encapsulation=auto follows the regular outcome of the NAT
1027 auto-detection code performed in IKE. This option replaced the
1028 obsoleted forceencaps option.
1029
1030 enable-tcp
1031 Normally, IKE negotiation and ESP encapsulation happens over UDP.
1032 This option enables support for IKE and ESP over TCP as per RFC
1033 8229. Acceptable values are no(the default), yes meaning only TCP
1034 will be used, or fallback meaning that TCP will be attempted only
1035 after negotiation over UDP failed. Since performance over TCP is
1036 much less, and TCP sessions are vulnerable to simply RST resets and
1037 MITM attacks causing the TCP connection to close, this option
1038 should really only be used in fallback mode. If used in fallback
1039 mode, it is recommend to reduce the retransmit-timeout from the
1040 default 60s to a much shorter value such as 10s, so that one does
1041 not have to wait a minute for the TCP fallback to be attempted.
1042
1043 tcp-remoteport
1044 Which remote TCP port to use when IKE over TCP is attempted. The
1045 default value is to use the NAT-T IKE port (4500). This value is
1046 not negotiated and should be configured properly on all endpoints.
1047 When opening a TCP socket to the remote host in this port, a
1048 regular ephemeral source port is obtained from the OS. For changing
1049 the UDP ports, see leftikeport=
1050
1051 nat-keepalive
1052 whether to send any NAT-T keep-alives. These one byte packets are
1053 send to prevent the NAT router from closing its port when there is
1054 not enough traffic on the IPsec connection. Acceptable values are:
1055 yes (the default) and no.
1056
1057 initial-contact
1058 whether to send an INITIAL_CONTACT payload to the peer we are
1059 initiating to, if we currently have no IPsec SAs up with that peer.
1060 Acceptable values are: yes (the default) and no. It is recommended
1061 to leave this option set, unless multiple clients with the same
1062 identity are expected to connect using the same subnets and should
1063 operate at the same time. Or if a reconnecting client should not
1064 delete its old instance (eg perhaps it is still running). This is
1065 unlikely to be true.
1066
1067 cisco-unity
1068 whether to send a CISCO_UNITY payload to the peer. Acceptable
1069 values are: no (the default) and yes. It is recommended to leave
1070 this option unset, unless the remote peer (Cisco client or server)
1071 requires it. This option does not modify local behaviour. It can be
1072 needed to connect as a client to a Cisco server. It can also be
1073 needed to act as a server for a Cisco client, which otherwise might
1074 send back an error DEL_REASON_NON_UNITY_PEER.
1075
1076 ignore-peer-dns
1077 whether to ignore received DNS configuration. Acceptable values
1078 are: no (the default) and yes. Normally, when a roadwarrior
1079 connects to a remote VPN, the remote VPN server sends a list of DNS
1080 domains and DNS nameserver IP addresses that the roadwarrior can
1081 use to reach internal only resources through the VPN. This option
1082 allows the roadwarrior to ignore the server's suggestion. The
1083 roadwarrior will normally use this information to update the DNS
1084 resolving process. What is changed depends on the detected DNS
1085 configuration. It can modify /etc/resolv.conf directly, or
1086 reconfigure a locally running DNS server (unbound, knot, stubby or
1087 systemd-resolved) or inform NetworkManager.
1088
1089 accept-redirect
1090 Whether requests of the remote peer to redirect IKE/IPsec SA's are
1091 accepted. Valid options are no (the default) and yes. See also
1092 accept-redirect-to.
1093
1094 accept-redirect-to
1095 Specify the comma separated list of addresses we accept being
1096 redirected to. Both IPv4 and IPv6 addresses are supported as well
1097 the FQDNs. The value %any, as well as not specifying any address,
1098 signifes that we will redirect to any address gateway sends us in
1099 REDIRECT notify payload.
1100
1101 The value of this option is not considered at all if
1102 accept-redirect is set to no.
1103
1104 send-redirect
1105 Whether to send requests for the remote peer to redirect IKE/IPsec
1106 SA's during IKE_AUTH. Valid options are no (the default) and yes.
1107 If set, the option redirect-to= must also be set to indicate where
1108 to redirect peers to. For redirection during IKE_SA_INIT exchange,
1109 see the global-redirect= and global-redirect-to= options. Runtime
1110 redirects can be triggered via the ipsec whack --redirect command.
1111
1112 redirect-to
1113 Where to send remote peers to via the send-redirect option. This
1114 can be an IP address or hostname (FQDN).
1115
1116 fake-strongswan
1117 whether to send a STRONGSWAN Vendor ID payload to the peer.
1118 Acceptable values are: no (the default) and yes. This used to be
1119 required because strongswan rejects certain proposals with private
1120 use numbers such as esp=twofish or esp=serpent unless it receives a
1121 strongswan vendorid by the peer. This option sends such an
1122 (unversioned) vendor id. Note that libreswan and strongswan no
1123 longer support twofish or serpent, so enabling this option likely
1124 will no longer do anything.
1125
1126 send-vendorid
1127 whether to send our Vendor ID during IKE. Acceptable values are: no
1128 (the default) and yes. The vendor id sent can be configured using
1129 the "config setup" option myvendorid=. It defaults to
1130 OE-Libreswan-VERSION.
1131
1132 Vendor ID's can be useful in tracking interoperability problems.
1133 However, specific vendor identification and software versions can
1134 be useful to an attacker when there are known vulnerabilities to a
1135 specific vendor/version.
1136
1137 The prefix OE stands for "Opportunistic Encryption". This prefix
1138 was historically used by The FreeS/WAN Project and The Openswan
1139 Project (openswan up to version 2.6.38) and in one Xeleranized
1140 openswan versions (2.6.39). Further Xeleranized openswan's use the
1141 prefix OSW.
1142
1143 overlapip
1144 a boolean (yes/no) that determines, when (left|right)subnet=vhost:
1145 is used, if the virtual IP claimed by this states created from this
1146 connection can with states created from other connections.
1147
1148 Note that connection instances created by the Opportunistic
1149 Encryption or PKIX (x.509) instantiation system are distinct
1150 internally. They will inherit this policy bit.
1151
1152 The default is no.
1153
1154 This feature is only available with kernel drivers that support SAs
1155 to overlapping conns. At present only the (klips) mast protocol
1156 stack supports this feature.
1157
1158 reqid
1159 a unique identifier used to match IPsec SAs using iptables with
1160 NETKEY/XFRM. This identifier is normally automatically allocated in
1161 groups of 4. It is exported to the _updown script as REQID. On
1162 Linux, reqids are supported with IP Connection Tracking and NAT
1163 (iptables). Automatically generated values use the range 16380 and
1164 higher. Manually specified reqid values therefore must be between 1
1165 and 16379.
1166
1167 Automatically generated reqids use a range of 0-3 (eg 16380-16383
1168 for the first reqid). These are used depending on the exact policy
1169 (AH, AH+ESP, IPCOMP, etc).
1170
1171 WARNING: Manually assigned reqids are all identical. Instantiations
1172 of connections (those using %any wildcards) will all use the same
1173 reqid. If you use manual assigning you should make sure your
1174 connections only match single road warrior only or you break
1175 multiple road warriors behind same NAT router because this feature
1176 requires unique reqids to work.
1177
1178 For KLIPS, when using the MAST variant, a different mechanism
1179 called SAref is in use. See overlapip and sareftrack.
1180
1181 dpddelay
1182 Set the delay (in time units, defaults to seconds) between Dead
1183 Peer Detection (IKEv1 RFC 3706) or IKEv2 Liveness keepalives that
1184 are sent for this connection (default 0 seconds). Set to enable
1185 checking. If dpddelay is set, dpdtimeout also needs to be set.
1186
1187 dpdtimeout
1188 Set the length of time (in time units, defaults to seconds) that we
1189 will idle without hearing back from our peer. After this period has
1190 elapsed with no response and no traffic, we will declare the peer
1191 dead, and remove the SA (default 0 seconds). Set value bigger than
1192 dpddelay to enable. If dpdtimeout is set, dpddelay also needs to be
1193 set.
1194
1195 dpdaction
1196 When a DPD enabled peer is declared dead, what action should be
1197 taken. hold (default) means the eroute will be put into %hold
1198 status, while clear means the eroute and SA with both be cleared.
1199 restart means that ALL SAs to the dead peer will renegotiated.
1200
1201 dpdaction=clear is really only useful on the server of a Road
1202 Warrior config.
1203
1204 The value restart_by_peer has been obsoleted and its functionality
1205 moved into the regular restart action.
1206
1207 pfs
1208 whether Perfect Forward Secrecy of keys is desired on the
1209 connection's keying channel (with PFS, penetration of the
1210 key-exchange protocol does not compromise keys negotiated earlier);
1211 Acceptable values are yes (the default) and no.
1212
1213 pfsgroup
1214 This option is obsoleted, please use phase2alg if you need the PFS
1215 to be different from phase1 (the default) using:
1216 phase2alg=aes128-md5;modp1024
1217
1218 aggressive
1219 Use IKEv1 Aggressive Mode instead of IKEv1 Main Mode. This option
1220 has no effect when IKEv2 is used. Acceptable values are no (the
1221 default) or yes. When this option is enabled, IKEv1 Main Mode will
1222 no longer be allowed for this connection. The old name of this
1223 option was aggrmode.
1224
1225 Aggressive Mode is less secure, and more vulnerable to Denial Of
1226 Service attacks. It is also vulnerable to brute force attacks with
1227 software such as ikecrack. It should not be used, and it should
1228 especially not be used with XAUTH and group secrets (PSK). If the
1229 remote system administrator insists on staying irresponsible,
1230 enable this option.
1231
1232 Aggressive Mode is further limited to only proposals with one DH
1233 group as there is no room to negotiate the DH group. Therefore it
1234 is mandatory for Aggressive Mode connections that both ike= and
1235 phase2alg= options are specified with only one fully specified
1236 proposal using one DH group.
1237
1238 The KE payload is created in the first exchange packet when using
1239 aggressive mode. The KE payload depends on the DH group used. This
1240 is why there cannot be multiple DH groups in IKEv1 aggressive mode.
1241 In IKEv2, which uses a similar method to IKEv1 Aggressive Mode,
1242 there is an INVALID_KE response payload that can inform the
1243 initiator of the responder's desired DH group and so an IKEv2
1244 connection can actually recover from picking the wrong DH group by
1245 restarting its negotiation.
1246
1247 salifetime
1248 how long a particular instance of a connection (a set of
1249 encryption/authentication keys for user packets) should last, from
1250 successful negotiation to expiry; acceptable values are an integer
1251 optionally followed by s (a time in seconds) or a decimal number
1252 followed by m, h, or d (a time in minutes, hours, or days
1253 respectively) (default 8h, maximum 24h). Normally, the connection
1254 is renegotiated (via the keying channel) before it expires. The two
1255 ends need not exactly agree on salifetime, although if they do not,
1256 there will be some clutter of superseded connections on the end
1257 which thinks the lifetime is longer.
1258
1259 The keywords "keylife" and "lifetime" are obsoleted aliases for
1260 "salifetime." Change your configs to use "salifetime" instead.
1261
1262 replay-window
1263 The size of the IPsec SA replay window protection. The default is
1264 kernel stack specific, but usually 32. Linux NETKEY/XFRM allows at
1265 least up to 2048. A value of of 0 disables replay protection.
1266 Disabling of replay protection is sometimes used on a pair of IPsec
1267 servers in a High Availability setup, or on servers with very
1268 unpredictable latency, such as mobile networks, which can cause an
1269 excessive amount of out of order packets. Sequence errors can be
1270 seen in /proc/net/xfrm_stat. Note that technically, at least the
1271 Linux kernel can install IPsec SA's with an IPsec SA Sequence
1272 Number, but this is currently not supported by libreswan.
1273
1274 rekey
1275 whether a connection should be renegotiated when it is about to
1276 expire; acceptable values are yes (the default) and no. The two
1277 ends need not agree, but while a value of no prevents Pluto from
1278 requesting renegotiation, it does not prevent responding to
1279 renegotiation requested from the other end, so no will be largely
1280 ineffective unless both ends agree on it.
1281
1282 rekeymargin
1283 how long before connection expiry or keying-channel expiry should
1284 attempts to negotiate a replacement begin; acceptable values as for
1285 salifetime (default 9m). Relevant only locally, other end need not
1286 agree on it.
1287
1288 rekeyfuzz
1289 maximum percentage by which rekeymargin should be randomly
1290 increased to randomize rekeying intervals (important for hosts with
1291 many connections); acceptable values are an integer, which may
1292 exceed 100, followed by a `%' (default set by ipsec_pluto(8),
1293 currently 100%). The value of rekeymargin, after this random
1294 increase, must not exceed salifetime. The value 0% will suppress
1295 time randomization. Relevant only locally, other end need not agree
1296 on it.
1297
1298 keyingtries
1299 how many attempts (a whole number or %forever) should be made to
1300 negotiate a connection, or a replacement for one, before giving up
1301 (default %forever). The value %forever or 0 means to keep trying
1302 forever. For Opportunistic Encryption connections, a keyingtries
1303 value of %forever or 0 is set to 1 and a warning message will be
1304 logged. This is because an expired failureshunt triggers new
1305 keyingtries on-demand later, when there is traffic. This prevents
1306 accumulating an infinite amount of attempts to peers that do not
1307 support Opportunistic Encryption. For Opportunistic, a keyingtries
1308 value of > 1 is allowed but currently not recommended. The meaning
1309 of failureshunt= is unclear when there is continued (failed) keying
1310 happening with a negotiationshunt installed. Relevant only locally,
1311 other end need not agree on it.
1312
1313 ikelifetime
1314 how long the keying channel of a connection (buzzphrase: “IKE SA”
1315 or “Parent SA”) should last before being renegotiated; acceptable
1316 values as for salifetime. The default as of version 4.2 is 8h,
1317 before that it was 1h. The maximum is 24h. The two-ends-disagree
1318 case is similar to that of salifetime.
1319
1320 retransmit-timeout
1321 how long a single packet, including retransmits of that packet, may
1322 take before the IKE attempt is aborted. If rekeying is enabled, a
1323 new IKE attempt is started. The default set by ipsec_pluto(8),
1324 currently is 60s. See also: retransmit-interval, rekey and
1325 keyingtries.
1326
1327 retransmit-interval
1328 the initial interval time period, specified in msecs, that pluto
1329 waits before retransmitting an IKE packet. This interval is doubled
1330 for each attempt (exponential back-off). The default set by
1331 ipsec_pluto(8), currently is 500. See also: retransmit-timeout,
1332 rekey and keyingtries.
1333
1334 compress
1335 whether IPComp compression of content is proposed on the connection
1336 (link-level compression does not work on encrypted data, so to be
1337 effective, compression must be done before encryption); acceptable
1338 values are yes and no (the default).
1339
1340 For IKEv1, compress settings on both peers must match. For IKEv2,
1341 compression can only be suggested and a mismatched compress setting
1342 results in connection without compression.
1343
1344 When set to yes, compression is negotiated for the DEFLATE
1345 compression algorithm.
1346
1347 metric
1348 Set the metric for added routes. This value is passed to the
1349 _updown scripts as PLUTO_METRIC. Acceptable values are positive
1350 numbers, with the default being 1.
1351
1352 mtu
1353 Set the MTU for the route(s) to the remote endpoint and/or subnets.
1354 This is sometimes required when the overhead of the IPsec
1355 encapsulation would cause the packet the become too big for a
1356 router on the path. Since IPsec cannot trust any unauthenticated
1357 ICMP messages, PATH MTU discovery does not work. This can also be
1358 needed when using "6to4" IPV6 deployments, which adds another
1359 header on the packet size. Acceptable values are positive numbers.
1360 There is no default.
1361
1362 tfc
1363 Enable Traffic Flow Confidentiality ("TFC") (RFC-4303) for outgoing
1364 ESP packets in Tunnel Mode. When enabled, ESP packets are padded to
1365 the specified size (up to the PMTU size) to prevent leaking
1366 information based on ESP packet size. This option is ignored for AH
1367 and for ESP in Transport Mode as those always leak traffic
1368 characteristics and applying TFC will not do anything. Acceptable
1369 values are positive numbers. The value 0 means TFC padding is not
1370 performed. Currently this feature is only implemented for the Linux
1371 XFRM/NETKEY stack. In IKEv2, when the notify payload
1372 ESP_TFC_PADDING_NOT_SUPPORTED is received, TFC padding is disabled.
1373 The default is not to do any TFC padding, but this might change in
1374 the near future.
1375
1376 send-no-esp-tfc
1377 Whether or not to tell the remote peer that we do not support
1378 Traffic Flow Confidentiality ("TFC") (RFC-4303). Possible values
1379 are no (the default) which allows the peer to use TFC or yes which
1380 prevents to peer from using TFC. This does not affect whether this
1381 endpoint uses TFC, which only depends on the local tfc setting.
1382 This option is only valid for IKEv2.
1383
1384 nflog
1385 If set, the NFLOG group number to log this connection's pre-crypt
1386 and post-decrypt traffic to. The default value of 0 means no
1387 logging at all. This option is only available on linux kernel
1388 2.6.14 and later. It allows common network utilities such as
1389 tcpdump, wireshark and dumpcap, to use nflog:XXX pseudo interfaces
1390 where XXX is the nflog group number. During the updown phase of a
1391 connection, iptables will be used to add and remove the
1392 source/destination pair to the nflog group specified. The rules are
1393 setup with the nflog-prefix matching the connection name. See also
1394 the global nflog-all option.
1395
1396 mark
1397 If set, the MARK to set for the IPsec SA of this connection. The
1398 format of a CONNMARK is mark/mask. If the mask is left out, a
1399 default mask of 0xffffffff is used. A mark value of -1 means to
1400 assign a new global unique mark number for each instance of the
1401 connection. Global marks start at 1001. This option is only
1402 available on linux NETKEY/XFRM kernels. It can be used with
1403 iptables to create custom iptables rules using CONNMARK. It can
1404 also be used with Virtual Tunnel Interfaces ("VTI") to direct
1405 marked traffic to specific vtiXX devices.
1406
1407 mark-in
1408 The same as mark, but mark-in only applies to the inbound half of
1409 the IPsec SA. It overrides any mark= setting.
1410
1411 mark-out
1412 The same as mark, but mark-out only applies to the outbound half of
1413 the IPsec SA. It overrides any mark= setting.
1414
1415 vti-interface
1416 This option is used to create "Routing based VPNs" (as opposed to
1417 "Policy based VPNs"). It will create a new interface that can be
1418 used to route traffic in for encryption/decryption. The Virtual
1419 Tunnel Interface ("VTI") interface name is used to for all IPsec
1420 SA's created by this connection. This requires that the connection
1421 also enables either the mark= or mark-in= / mark-out- option(s).
1422 All traffic marked with the proper MARKs will be automatically
1423 encrypted if there is an IPsec SA policy covering the
1424 source/destination traffic. Tools such as tcpdump and iptables can
1425 be used on all cleartext pre-encrypt and post-decrypt traffic on
1426 the device. See the libreswan wiki for example configurations that
1427 use VTI.
1428
1429 VTI interfaces are currently only supported on Linux with
1430 XFRM/NETKEY. The _updown script handles certain Linux specific
1431 interfaces settings required for proper functioning
1432 (disable_policy, rp_filter, forwarding, etc). Interface names are
1433 limited to 16 characters and may not allow all characters to be
1434 used. If marking and vti-routing=yes is used, no manual iptables
1435 should be required. However, administrators can use the iptables
1436 mangle table to mark traffic manually if desired.
1437
1438 vti-routing
1439 Whether or not to add network rules or routes for IPsec SA's to the
1440 respective VTI devices. Valid values are yes (the default) or no.
1441 When using "routing based VPNs" with a subnets policy of 0.0.0.0/0,
1442 this setting needs to set to no to prevent imploding the tunnel,
1443 and the administrator is expected to manually add ip rules and ip
1444 routes to configure what traffic must be encrypted. When set to
1445 yes, the _updown script will automatically route the
1446 leftsubnet/rightsubnet traffic into the VTI device specified with
1447 vti-interface
1448
1449 vti-shared
1450 Whether or not the VTI device is shared amongst connections. Valid
1451 values are no (the default) or yes. When set to no, the VTI device
1452 is automatically deleted if the connection is a single
1453 non-instantiated connection. If a connection instantiates (eg
1454 right=%any) then this option has no effect, as the VTI device is
1455 not removed as it is shared with multiple roadwarriors.
1456
1457 ipsec-interface
1458 Create or use an existing virtual interface ipsecXXX for "Routing
1459 based VPNs" (as opposed to "Policy based VPNs"). Valid options are
1460 yes, no or a number. When using a number, the IPsec interface
1461 created and/or used will use that number as part of the interface
1462 name. For example setting ipsec-interface=5 will create and/or use
1463 the ipsec5 interface. The value 0 cannot be used and is interpreted
1464 as no. The value yes is interpreted as the number 1, and thus will
1465 use the interface named ipsec1. An IP address can be configured for
1466 this interface via the interface-ip= option.
1467
1468 The ipsec-interface is used to route outbound traffic that needs to
1469 be encrypted, and will decrypt inbound traffic that arrives on this
1470 interface. All traffic that is routed to this interface will be
1471 automatically encrypted providing the IPsec SA policy covers this
1472 traffic. Traffic not matching the IPsec SA will be dropped. Tools
1473 such as tcpdump, iptables, ifconfig and tools that need traffic
1474 counters can be used on all cleartext pre-encrypt and post-decrypt
1475 traffic on the device. When leftsubnet= is equal to rightsubnet=,
1476 the routing needs to be manged by an external routing daemon or
1477 manually by the administrator.
1478
1479 This option is currently only supported on Linux kernels 4.19 or
1480 later when compiled with XFRMi support (CONFIG_XFRM_INTERFACE). The
1481 number of the ipsecX device corresponds with the XFRM IF_ID policy
1482 option of the IPsec SA in the Linux kernel. On Linux, XFRMi
1483 interfaces can be managed by libreswan automatically or can be
1484 preconfigured on the system using the existing init system or via
1485 networking tools such as systemd-networkd and NetworkManager. The
1486 _updown script handles certain Linux specific interfaces settings
1487 required for proper functioning, such as forwarding and routing
1488 rules for IPsec traffic.
1489
1490 The ipsec-interface=0 will create an interface with the same name
1491 as the old KLIPS interface, ipsec0. This interface name should only
1492 be used when required for migration from KLIPS to XFRM interfaces.
1493 Since XFRM IF_ID and marking cannot use 0, this is mapped to 16384.
1494 This means that the devices ipsec0 and ipsec16384 cannot both be in
1495 use.
1496
1497 interface-ip=
1498 NOTE: This option is currently not implemented pending pluto IP
1499 address reference counting. The IP address and netmask to configure
1500 on a virtual device (eg ipsecXXX). This is often used when building
1501 Routing based IPsec tunnels using transport mode and GRE, but can
1502 also be useful in other scenarios. Currently requires
1503 ipsec-interface=. See also leftvti= for cnofiguring IP addresses
1504 when using VTI.
1505
1506 priority
1507 The priority in the kernel SPD/SAD database, when matching up
1508 packets. Each kernel (NETKEY, KLIPS, OSX, etc) has its own
1509 mechanism for setting the priority. Setting this option to non-zero
1510 passes the priority to the kernel stack unmodified. The maximum
1511 value depends on the stack. It is recommended not to exceed 65536
1512
1513 KLIPS and NETKEY use a priority system based on "most specific
1514 match first". It uses an internal algorithm to calculate these
1515 based on network prefix length, protocol and port selectors. A
1516 lower value means a higher priority.
1517
1518 Typical values are about the 2000 range. These can be seen on the
1519 NETKEY stack using ip xfrm policy when the connection is up. For
1520 "anonymous IPsec" or Opportunistic Encryption based connections, a
1521 much lower priority (65535) is used to ensure administrator
1522 configured IPsec always takes precedence over opportunistic IPsec.
1523
1524 sendca
1525 How much of our available X.509 trust chain to send with the End
1526 certificate, excluding any root CA's. Specifying issuer sends just
1527 the issuing intermediate CA, while
1528 all will send the entire chain of intermediate CA's.none (the
1529 default) will not send any CA certs.
1530
1531 labeled-ipsec
1532 This option is obsolete. To enable labeled IPsec, setting the
1533 policy-label= is enough. See also policy-label= and
1534 secctx-attr-type=
1535
1536 policy-label
1537 The string representation of an access control security label that
1538 is interpreted by the LSM (e.g. SELinux) for use with Labeled
1539 IPsec. See also labeled-ipsec= and secctx-attr-type=. For example,
1540 policy-label=system_u:object_r:ipsec_spd_t:s0-s15:c0.c1023
1541
1542 failureshunt
1543 what to do with packets when negotiation fails. The default is
1544 none: no shunt; passthrough, drop, and reject have the obvious
1545 meanings.
1546
1547 negotiationshunt
1548 What to do with packets during the IKE negotiation. Valid options
1549 are hold (the default) or passthrough. This should almost always be
1550 left to the default hold value to avoid cleartext packet leaking.
1551 The only reason to set this to passthrough is if plaintext service
1552 availability is more important than service security or privacy, a
1553 scenario that also implies failureshunt=passthrough and most likely
1554 authby=%null using Opportunistic Encryption.
1555
1557 At present, the only config section known to the IPsec software is the
1558 one named setup, which contains information used when the software is
1559 being started (see ipsec_setup(8)). Here's an example:
1560
1561
1562 config setup
1563 logfile=/var/log/pluto.log
1564 plutodebug=all
1565
1566 Parameters are optional unless marked “(required)”.
1567
1568 The currently-accepted parameter names in a config setup section are:
1569
1570 protostack
1571 decide which protocol stack is going to be used. Valid values are
1572 "xfrm" and "bsd". This option should no longer be set, as the stack
1573 is currently auto-detected. The values "klips, "mast", "netkey",
1574 "native", "kame" and "auto" are obsolete. The option is kept only
1575 because it is suspected that Linux and BSD will get userspace
1576 stacks with IPsec support soon (such as dpdk).
1577
1578 interfaces
1579 virtual and physical interfaces for IPsec to use: a single
1580 virtual=physical pair, a (quoted!) list of pairs separated by white
1581 space, or %none. One of the pairs may be written as %defaultroute,
1582 which means: find the interface d that the default route points to,
1583 and then act as if the value was ``ipsec0=d''. %defaultroute is
1584 the default; %none must be used to denote no interfaces, or when
1585 using the NETKEY stack. If %defaultroute is used (implicitly or
1586 explicitly) information about the default route and its interface
1587 is noted for use by ipsec_auto(8).)
1588
1589 listen
1590 IP address to listen on (default depends on interfaces= setting).
1591 Currently only accepts one IP address.
1592
1593 ike-socket-bufsize
1594 Set the IKE socket buffer size. Default size is determined by the
1595 OS (as of writing, this seems to be set to 212992. On Linux this is
1596 visible via /proc/sys/net/core/rmem_default and
1597 /proc/sys/net/core/wmem_default. On Linux, this option uses
1598 SO_RCVBUFFORCE and SO_SNDBUFFORCE so that it can override
1599 rmem_max/wmem_max values of the OS. This requires CAP_NET_ADMIN
1600 (which is also required for other tasks). This option can also be
1601 toggled on a running system using ipsec whack --ike-socket-bufsize
1602 bufsize.
1603
1604 ike-socket-errqueue
1605 Whether to enable or disable receiving socket errors via
1606 IP_RECVERR. The default is enabled. This will cause the socket to
1607 receive, process and log socket errors, such as ICMP unreachable
1608 messages or Connection Refused messages. Disabling this only makes
1609 sense on very busy servers, and even then it might not make much of
1610 a difference. This option can also be toggled on a running system
1611 using ipsec whack --ike-socket-errqueue-toggle.
1612
1613 listen-udp
1614 Whether the pluto IKE daemon should listen on the standard UDP
1615 ports of 500 and 4500. The value "yes" means to listen on these
1616 ports, and is the default. This should almost never be disabled. In
1617 the rare case where it is known that only ever TCP or non-standard
1618 UDP ports will be used, this option can disable the standard UDP
1619 ports. Connections can specify their own non-standard port using
1620 leftikeport=.
1621
1622 listen-tcp
1623 Whether the pluto IKE daemon should listen on the (pseudo) standard
1624 TCP port 4500. The value "no" is the current default, but this will
1625 be changed in the future to "yes". The TCP usage complies to RFC
1626 8229 for IKE and ESP over TCP support. Connections can specify
1627 their own non-standard port using leftikeport=.
1628
1629 nflog-all
1630 If set, the NFLOG group number to log all pre-crypt and
1631 post-decrypt traffic to. The default value of 0 means no logging at
1632 all. This option is only available on linux kernel 2.6.14 and
1633 later. It allows common network utilities such as tcpdump,
1634 wireshark and dumpcap, to use nflog:XXX pseudo interfaces where XXX
1635 is the nflog group number. During startup and shutdown of the IPsec
1636 service, iptables commands will be used to add or remove the global
1637 NFLOG table rules. The rules are setup with the nflog-prefix
1638 all-ipsec. See also the per-connection nflog option.
1639
1640 keep-alive
1641 The delay (in seconds) for NAT-T keep-alive packets, if these are
1642 enabled using nat-keepalive This parameter may eventually become
1643 per-connection.
1644
1645 virtual-private
1646 contains the networks that are allowed as (left|right)subnet= for
1647 the remote clients when using the vhost: or vnet: keywords in the
1648 (left|right)subnet= parameters. In other words, the address ranges
1649 that may live behind a NAT router through which a client connects.
1650 This value is usually set to all the RFC-1918 address space,
1651 excluding the space used in the local subnet behind the NAT (An IP
1652 address cannot live at two places at once). IPv4 address ranges are
1653 denoted as %v4:a.b.c.d/mm and IPv6 is denoted as
1654 %v6:aaaa::bbbb:cccc:dddd:eeee/mm. One can exclude subnets by using
1655 the !. For example, if the VPN server is giving access to
1656 192.168.1.0/24, this option should be set to:
1657 virtual-private=%v4:10.0.0.0/8,%v4:192.168.0.0/16,%v4:172.16.0.0/12,%v4:!192.168.1.0/24.
1658 This parameter is only needed on the server side and not on the
1659 client side that resides behind the NAT router, as the client will
1660 just use its IP address for the inner IP setting. This parameter
1661 may eventually become per-connection. See also leftsubnet=
1662
1663 Note: It seems that T-Mobile in the US and Rogers/Fido in Canada
1664 have started using 25.0.0.0/8 as their pre-NAT range. This range
1665 technically belongs to the Defence Interoperable Network Services
1666 Authority (DINSA), an agency of the Ministry of Defence of the
1667 United Kingdom. The network range seems to not have been announced
1668 for decades, which is probably why these organisations "borrowed"
1669 this range. To support roadwarriors on these 3G networks, you might
1670 have to add it to the virtual-private= line.
1671
1672 myvendorid
1673 The string to use as our vendor id (VID) when send-vendorid=yes.
1674 The default is OE-Libreswan-VERSION.
1675
1676 nhelpers
1677 how many pluto helpers are started to help with cryptographic
1678 operations. Pluto will start as many helpers as the number of
1679 CPU's, minus 1 to dedicate to the main thread. For machines with
1680 less than 4 CPU's, an equal number of helpers to CPU's are started.
1681 A value of 0 forces pluto to do all operations inline using the
1682 main process. A value of -1 tells pluto to perform the above
1683 calculation. Any other value forces the number to that amount.
1684
1685 seedbits
1686 Pluto uses the NSS crypto library as its random source. Some
1687 government Three Letter Agencies require that pluto reads
1688 additional bits from /dev/random and feed these into the NSS RNG
1689 before drawing random from the NSS library, despite the NSS library
1690 itself already seeding its internal state. This process can block
1691 pluto for an extended time during startup, depending on the entropy
1692 of the system. Therefore, the default is to not perform this
1693 redundant seeding. If specifying a value, it is recommended to
1694 specify at least 460 bits (for FIPS) or 440 bits (for BSI).
1695
1696 ikev1-secctx-attr-type
1697 The value for the IKEv1 IPsec SA security context attribute
1698 identifier that is used for Labeled IPsec. Defaults to the private
1699 use IANA value 32001 from the IPsec SA attributes registry. Old
1700 openswan versions might still be using the (stolen) value 10, which
1701 has since been assigned by IANA for something else. Other values
1702 are not recommended unless IANA assigns an actual value for this
1703 option. Labeled IPsec using IKEv2 does not use this option, it only
1704 uses an IANA allocated Notify number. See also policy-label.
1705
1706 ikev1-policy
1707 What to do with received IKEv1 packets. Valid options are accept
1708 (default), reject which will reply with an error, and drop which
1709 will silently drop any received IKEv1 packet. If this option is set
1710 to drop or reject, an attempt to load an IKEv1 connection will
1711 fail, as these connections would never be able to receive a packet
1712 for processing.
1713
1714 crlcheckinterval
1715 interval expressed in second units, for example crlcheckinterval=8h
1716 for 8 hours, after which pluto will fetch new Certificate
1717 Revocation List (CRL) from crl distribution points. List of used
1718 CRL distribution points are collected from CA certificates and end
1719 certificates. Loaded X.509 CRL's are verified to be valid and
1720 updates are imported to NSS database. If set to 0, which is also
1721 the default value if this option is not specified, CRL updating is
1722 disabled.
1723
1724 crl-strict
1725 if not set, pluto is tolerant about missing or expired X.509
1726 Certificate Revocation Lists (CRL's), and will allow peer
1727 certificates as long as they do not appear on an expired CRL. When
1728 this option is enabled, all connections with an expired or missing
1729 CRL will be denied. Active connections will be terminated at rekey
1730 time. This setup is more secure, but vulnerable to downtime if the
1731 CRL expires. Acceptable values are yes or no (the default). This
1732 option used to be called strictcrlpolicy.
1733
1734 curl-iface
1735 The name of the interface that is used for CURL lookups. This is
1736 needed on rare situations where the interface needs to be forced to
1737 be different from the default interface used based on the routing
1738 table.
1739
1740 curl-timeout
1741 The timeout for the curl library calls used to fetch CRL and OCSP
1742 requests. The default is 5s.
1743
1744 ocsp-enable
1745 Whether to perform Online Certificate Store Protocol ("OCSP")
1746 checks on those certificates that have an OCSP URI defined.
1747 Acceptable values are yes or no (the default).
1748
1749 ocsp-strict
1750 if set to no, pluto is tolerant about failing to obtain an OCSP
1751 responses and a certificate is not rejected when the OCSP request
1752 fails, only when the OCSP request succeeds and lists the
1753 certificate as revoked. If set to yes, any failure on obtaining an
1754 OCSP status for a certificate will be fatal and the certificate
1755 will be rejected. Acceptable values are yes or no (the default).
1756
1757 The strict mode refers to the NSS
1758 ocspMode_FailureIsVerificationFailure mode, while non-strict mode
1759 refers to the NSS ocspMode_FailureIsNotAVerificationFailure mode.
1760
1761 ocsp-method
1762 The HTTP methods used for fetching OCSP data. Valid options are get
1763 (the default) and post. Note that this behaviour depends on the NSS
1764 crypto library that is actually performing the fetching. When set
1765 to the get method, post is attempted only as fallback in case of
1766 failure. When set to post, only the post method is ever used.
1767
1768 ocsp-timeout
1769 The time until an OCSP request is aborted and considered failed.
1770 The default value is 2 seconds.
1771
1772 ocsp-uri
1773 The URI to use for OCSP requests instead of the default OCSP URI
1774 listed in the CA certificate. This requires the ocsp-trustname
1775 option to be set to the nick (friendly name) of the OCSP server
1776 certificate, which needs to be present in the NSS database. These
1777 option combined with the next option sets the OCSP default
1778 responder.
1779
1780 ocsp-trustname
1781 The nickname of the certificate that has been imported into the NSS
1782 database of the server handling the OCSP requests. This requires
1783 the ocsp-uri option to be set as well. This option and the previous
1784 options sets the OCSP default responder.
1785
1786 ocsp-cache-size
1787 The maximum size (in number of certificates) of OCSP responses that
1788 will be kept in the cache. The default is 1000. Setting this value
1789 to 0 means the cache is disabled.
1790
1791 ocsp-cache-min-age
1792 The minimum age (in seconds) before a new fetch will be attempted.
1793 The default is 1 hour.
1794
1795 ocsp-cache-max-age
1796 The maximum age (in seconds) before a new fetch will be attempted.
1797 The default is 1 day.
1798
1799 syslog
1800 the syslog(2) “facility” name and priority to use for
1801 startup/shutdown log messages, default daemon.error.
1802
1803 plutodebug
1804 how much Pluto debugging output should be logged. An empty value,
1805 or the magic value none, means no debug output (the default).
1806 Otherwise only the specified types of output (a quoted list, names
1807 without the --debug- prefix, separated by white space) are enabled;
1808
1809 The current option values are base that represents moderate amounts
1810 of information, cpu-usage for getting timing/load based information
1811 (best used without any other debugging options), crypt for all
1812 crypto related operations and tmi (Too Much Information) for
1813 excessive logging. To log any sensitive private key or password
1814 material, use the special private value.
1815
1816 The old plutodebug options (control, controlmore, x509, kernel,
1817 etc) are mapped to either base or tmi. Note that all maps to base
1818 and not tmi.
1819
1820 uniqueids
1821 Whether IDs should be considered identifying remote parties
1822 uniquely. Acceptable values are yes (the default) and no.
1823 Participant IDs normally are unique, so a new connection instance
1824 using the same remote ID is almost invariably intended to replace
1825 an old existing connection.
1826
1827 When the connection is defined to be a server (using xauthserver=)
1828 and the connection policy is authby=secret, this option is ignored
1829 (as of 3.20) and old connections will never be replaced. This
1830 situation is commonly known as clients using a "Group ID".
1831
1832 This option may disappear in the near future. People using
1833 identical X.509 certificates on multiple devices are urged to
1834 upgrade to use separate certificates per client and device.
1835
1836 logfile
1837 do not use syslog, but rather log to stderr, and direct stderr to
1838 the argument file. This option used to be called plutostderrlog=
1839
1840 logappend
1841 If pluto is instructed to log to a file using logfile=, this option
1842 determines whether the log file should be appended to or
1843 overwritten. Valid options are yes (the default) to append and no
1844 to overwrite. Since on modern systems, pluto is restarted by other
1845 daemons, such as systemd, this option should be left at its default
1846 yes value to preserve the log entries of previous runs of pluto.
1847 The option is mainly of use for running the test suite, which needs
1848 to create new log files from scratch.
1849
1850 logip
1851 If pluto is instructed to log the IP address of incoming
1852 connections. Valid options are yes (the default) and no. Note that
1853 this only affects regular logging. Any enabled debugging via
1854 plutodebug= will still contain IP addresses of peers. This option
1855 is mostly meant for servers that want to avoid logging IP addresses
1856 of incoming clients. Other identifiable information might still be
1857 logged, such as ID payloads and X.509 certificate details. When
1858 using ID of type IP address, this option will not hide the actual
1859 IP address as part of the ID. Most deployments will not want to
1860 change this from the default. If logging of IP addresses is
1861 unwanted, audit-log=no should also be set.
1862
1863 audit-log
1864 Whether pluto should produce Linux Auditing System log messages. If
1865 enabled, pluto will log start, stop and fail for the negotiation of
1866 IKE and IPsec SA's. The kernel will also log success and failures
1867 for actually adding and removing IPsec SA's from the kernel's SADB.
1868 Valid options are yes(the default) and no. On non-Linux systems,
1869 this option is ignored. If enabled but the kernel is lacking audit
1870 support, audit messages are not sent. If the kernel has audit
1871 support and using it fails, pluto will abort. Note that for
1872 compliance reasons, audit log messages contain the relevant IP
1873 addresses, even if logip=no.
1874
1875 logtime
1876 When pluto is directed to log to a file using logfile=, this option
1877 determines whether or not to log the current timestamp as prefix.
1878 Values are yes (the default) or no. The no value can be used to
1879 create logs without ephemeral timestamps, such as those created
1880 when running the test suite. This option used to be called
1881 plutostderrlogtime=
1882
1883 ddos-mode
1884 The startup mode of the DDoS defense mechanism. Acceptable values
1885 are busy, unlimited or auto (the default). This option can also be
1886 given to the IKE daemon while running, for example by issuing ipsec
1887 whack --ddos--busy. When in busy mode, pluto activates anti-DDoS
1888 counter measures. Currently, counter measures consist of requiring
1889 IKEv2 anti-DDoS cookies on new incoming IKE requests, and a more
1890 aggressive cleanup of partially established or AUTH_NULL
1891 connections.
1892
1893 ddos-ike-threshold
1894 The number of half-open IKE SAs before the pluto IKE daemon will be
1895 placed in busy mode. When in busy mode, pluto activates anti-DDoS
1896 counter measures. The default is 25000. See also ddos-mode and
1897 ipsec whack --ddos-XXX.
1898
1899 global-redirect
1900 Whether to send requests for the remote peer to redirect IKE/IPsec
1901 SA's during IKE_SA_INIT. Valid options are no (the default), yes
1902 and auto, where auto means that the requests will be sent if DDoS
1903 mode is active (see ddos-mode). If set, the option
1904 global-redirect-to= must also be set to indicate where to redirect
1905 peers to. For specific connection redirection after IKE SA
1906 authentication, see the send-redirect= and redirect-to= options.
1907 This configuration can be changed at runtime via the ipsec whack
1908 --global-redirect command.
1909
1910 global-redirect-to
1911 Where to send remote peers to via the global-redirect option. This
1912 can be a list, or a single entry, of IP addresses or hostnames
1913 (FQDNs). If there is a list of entries, they must be separated with
1914 comma's. One specified entry means all peers will be redirected to
1915 it, while multiple specified entries means peers will be evenly
1916 distributed across the specified servers. This configuration can be
1917 changed at runtime via the ipsec whack --global-redirect-to
1918 command.
1919
1920 max-halfopen-ike
1921 The number of half-open IKE SAs before the IKE daemon starts
1922 refusing all new IKE attempts. Established IKE peers are not
1923 affected. The default value is 50000.
1924
1925 shuntlifetime
1926 The time until bare shunts (kernel policies not associated with
1927 connections) are deleted from the kernel. The default value is 15m.
1928 When using Opportunistic Encryption to a specific host fails, the
1929 system will either install a %pass or %hold shunt to let the
1930 traffic out clear text or block it. During the the shuntlifetime,
1931 no new Opportunistic Encryption attempt will be started, although
1932 the system will still respond to incoming OE requests from the
1933 remote IP. See also failureshunt and negotiationshunt
1934
1935 xfrmlifetime
1936 The time in seconds until the NETKEY/XFRM acquire state times out.
1937 The default value is 30 seconds. For auto=ondemand connections and
1938 Opportunistic connections an IPsec policy is installed in the
1939 kernel. If an incoming or outgoing packet matches this policy, a
1940 state is created in the kernel and the kernel sends an ACQUIRE
1941 message to the IKE daemon pluto. While this state is in place, no
1942 new acquires will come in for this connection. The default should
1943 be fine for most people. One use case of shortening these is if
1944 opportunistc encryption is used towards cloud instances that can
1945 quickly re-use IP addresses. This value is only used during the
1946 libreswan startup process by the ipsec _stackmanager helper. See
1947 also failureshunt and negotiationshunt
1948
1949 dumpdir
1950 in what directory should things started by setup (notably the Pluto
1951 daemon) be allowed to dump core? The default value is
1952 /var/run/pluto. When SELinux runs in enforced mode, changing this
1953 requires a similar change in the SELinux policy for the pluto
1954 daemon.
1955
1956 statsbin
1957 This option specifies an optional external program to report tunnel
1958 state changes too. The default is not to report tunnel state
1959 changes. This program can be used to notify the user's desktop
1960 (dbus, NetworkManager) or to report tunnel changes to a central
1961 logging server.
1962
1963 ipsecdir
1964 Specifies a directory for administrator-controlled configuration
1965 files and directories. The default value is /etc/ipsec.d. It may
1966 contain the following files and directories:
1967
1968 passwd
1969 (optional) for XAUTH support if not using PAM (this file should
1970 not be world-readable). See README.XAUTH for more information.
1971
1972 nsspassword
1973 (optional) passwords needed to unlock the NSS database in
1974 /var/lib/ipsec/nss (this file should not be world-readable).
1975 See README.nss for more information.
1976
1977 policies/
1978 a directory containing policy group configuration information.
1979 See POLICY GROUP FILES in this document for more information.
1980
1981 cacerts/
1982 DEPRECATED: a directory to store trust anchors (root
1983 certificate authority certificates). The preferred (and
1984 default) approach is to store CA certs in the NSS database
1985 instead. See README.nss for more information.
1986
1987 crls/
1988 DEPRECATED: a directory to store certificate revocation lists.
1989 The preferred (and default) approach is to store CRLs in the
1990 NSS database instead. See README.nss for more information.
1991
1992 When SELinux runs in enforced mode, changing this requires a
1993 similar change in the SELinux policy for the pluto daemon.
1994
1995 nssdir
1996 Specifies a directory for NSS database files. The default value is
1997 /var/lib/ipsec/nss. It may contain the following files:
1998
1999 pkcs11.txt
2000 Detailed info about NSS database creation parameteres.
2001
2002 cert9.db
2003 NSS Certificate database.
2004
2005 key4.db
2006 NSS Key database.
2007
2008 When SELinux runs in enforced mode, changing this requires a
2009 similar change in the SELinux policy for the pluto daemon.
2010
2011 secretsfile
2012 pathname of the file that stores the secret credentials such as
2013 preshared keys (PSKs). See man ipsec.secrets for the syntax. The
2014 default value is /etc/ipsec.secrets.
2015
2016 seccomp
2017 Set the seccomp kernel syscall whitelisting feature. When set to
2018 enabled, if pluto calls a syscall that is not on the compiled-in
2019 whitelist, the kernel will assume an exploit is attempting to use
2020 pluto for malicious access to the system and terminate the pluto
2021 daemon. When set to tolerant, the kernel will only block the rogue
2022 syscall and pluto will attempt to continue. If set to disabled,
2023 pluto is allowed to call any syscall offered by the kernel,
2024 although it might be restricted via other security mechanisms, such
2025 as capabilities, SElinux, AppArmor or other OS security features.
2026
2027 The current default is disabled, but it is expected that in the
2028 future this feature will be enabled on all supported operating
2029 systems. Similarly, it is expected that further privilege
2030 separation will reduce the allowed syscalls - for example for the
2031 crypto helpers or DNS helpers.
2032
2033 Warning: The restrictions of pluto are inherited by the updown
2034 scripts, so these scripts are also not allowed to use syscalls that
2035 are forbidden for pluto.
2036
2037 This feature can be tested using ipsec whack --seccomp-crashtest.
2038 Warning: With seccomp=enabled, pluto will be terminated by the
2039 kernel. With seccomp=tolerant or seccomp=disabled, pluto will
2040 report the results of the seccomp test. SECCOMP will log the
2041 forbidden syscall numbers to the audit log, but only with
2042 seccomp=enabled. The tool scmp_sys_resolver from the libseccomp
2043 development package can be used to translate the syscall number
2044 into a name. See programs/pluto/pluto_seccomp.c for the list of
2045 allowed syscalls.
2046
2047 dnssec-enable
2048 Whether pluto should perform dnssec validation using libunbound,
2049 provided libreswan was compiled with USE_DNSSEC. A value of yes
2050 (the default) means pluto should perform DNSSEC validation. Note
2051 that pluto reads the file /etc/resolv.conf to determine which
2052 nameservers to use.
2053
2054 dnssec-rootkey-file
2055 The location of the DNSSEC root zone public key file. The default
2056 is /var/lib/unbound/root.key but this can be changed at compile
2057 time.
2058
2059 dnssec-anchors
2060 The location of a file containing additional DNSSEC Trust Anchors.
2061 This can be used when a network is using split-DNS and the internal
2062 hierarchy is using DNSSEC trust anchors. There is no default value.
2063
2065 The system automatically defines several conns to implement default
2066 policy groups. Each can be overridden by explicitly defining a new conn
2067 with the same name. If the new conn has auto=ignore, the definition is
2068 suppressed.
2069
2070 Here are the automatically supplied definitions.
2071
2072
2073 conn clear
2074 type=passthrough
2075 authby=never
2076 left=%defaultroute
2077 right=%group
2078 auto=route
2079
2080 conn clear-or-private
2081 type=passthrough
2082 left=%defaultroute
2083 leftid=%myid
2084 right=%opportunisticgroup
2085 failureshunt=passthrough
2086 keyingtries=3
2087 ikelifetime=1h
2088 salifetime=1h
2089 rekey=no
2090 auto=route
2091
2092 conn private-or-clear
2093 type=tunnel
2094 left=%defaultroute
2095 leftid=%myid
2096 right=%opportunisticgroup
2097 failureshunt=passthrough
2098 keyingtries=3
2099 ikelifetime=1h
2100 salifetime=1h
2101 rekey=no
2102 auto=route
2103
2104 conn private
2105 type=tunnel
2106 left=%defaultroute
2107 leftid=%myid
2108 right=%opportunisticgroup
2109 failureshunt=drop
2110 keyingtries=3
2111 ikelifetime=1h
2112 salifetime=1h
2113 rekey=no
2114 auto=route
2115
2116 conn block
2117 type=reject
2118 authby=never
2119 left=%defaultroute
2120 right=%group
2121 auto=route
2122
2123 # default policy
2124 conn packetdefault
2125 type=tunnel
2126 left=%defaultroute
2127 leftid=%myid
2128 left=0.0.0.0/0
2129 right=%opportunistic
2130 failureshunt=passthrough
2131 keyingtries=3
2132 ikelifetime=1h
2133 salifetime=1h
2134 rekey=no
2135 auto=route
2136
2137 These conns are not affected by anything in conn %default. They will
2138 only work if %defaultroute works. The leftid will be the interfaces IP
2139 address; this requires that reverse DNS records be set up properly.
2140
2141 The implicit conns are defined after all others. It is appropriate and
2142 reasonable to use also=private-or-clear (for example) in any other
2143 opportunistic conn.
2144
2146 The optional files under /etc/ipsec.d/policies, including
2147
2148
2149 /etc/ipsec.d/policies/clear
2150 /etc/ipsec.d/policies/clear-or-private
2151 /etc/ipsec.d/policies/private-or-clear
2152 /etc/ipsec.d/policies/private
2153 /etc/ipsec.d/policies/block
2154
2155
2156 may contain policy group configuration information to supplement
2157 ipsec.conf. Their contents are not security-sensitive.
2158
2159 These files are text files. Each consists of a list of CIDR blocks, one
2160 per line. White space followed by # followed by anything to the end of
2161 the line is a comment and is ignored, as are empty lines.
2162
2163 A connection in ipsec.conf that has right=%group or
2164 right=%opportunisticgroup is a policy group connection. When a policy
2165 group file of the same name is loaded, with
2166
2167 ipsec auto --rereadgroups
2168
2169 or at system start, the connection is instantiated such that each CIDR
2170 block serves as an instance's right value. The system treats the
2171 resulting instances as normal connections.
2172
2173 For example, given a suitable connection definition private, and the
2174 file /etc/ipsec.d/policies/private with an entry 192.0.2.3, the system
2175 creates a connection instance private#192.0.2.3. This connection
2176 inherits all details from private, except that its right client is
2177 192.0.2.3.
2178
2180 The standard Libreswan install includes several policy groups which
2181 provide a way of classifying possible peers into IPsec security
2182 classes: private (talk encrypted only), private-or-clear (prefer
2183 encryption), clear-or-private (respond to requests for encryption),
2184 clear and block. Implicit policy groups apply to the local host only,
2185 and are implemented by the IMPLICIT CONNECTIONS described above.
2186
2188 When choosing a connection to apply to an outbound packet caught with a
2189 %trap, the system prefers the one with the most specific eroute that
2190 includes the packet's source and destination IP addresses. Source
2191 subnets are examined before destination subnets. For initiating, only
2192 routed connections are considered. For responding, unrouted but added
2193 connections are considered.
2194
2195 When choosing a connection to use to respond to a negotiation that
2196 doesn't match an ordinary conn, an opportunistic connection may be
2197 instantiated. Eventually, its instance will be /32 -> /32, but for
2198 earlier stages of the negotiation, there will not be enough information
2199 about the client subnets to complete the instantiation.
2200
2202 /etc/ipsec.conf
2203 /etc/ipsec.d/policies/clear
2204 /etc/ipsec.d/policies/clear-or-private
2205 /etc/ipsec.d/policies/private-or-clear
2206 /etc/ipsec.d/policies/private
2207 /etc/ipsec.d/policies/block
2208
2210 ipsec(8), ipsec_auto(8), ipsec_rsasigkey(8)
2211
2213 Designed for the FreeS/WAN project <https://www.freeswan.org> by Henry
2214 Spencer.
2215
2217 Before reporting new bugs, please ensure you are using the latest
2218 version of Libreswan, and if not using KLIPS, please ensure you are
2219 using the latest kernel code for your IPsec stack.
2220
2221 When type or failureshunt is set to drop or reject, Libreswan blocks
2222 outbound packets using eroutes, but assumes inbound blocking is handled
2223 by the firewall. Libreswan offers firewall hooks via an “updown”
2224 script. However, the default ipsec _updown provides no help in
2225 controlling a modern firewall.
2226
2227 Including attributes of the keying channel (authentication methods,
2228 ikelifetime, etc.) as an attribute of a connection, rather than of a
2229 participant pair, is dubious and incurs limitations.
2230
2231 The use of %any with the protoport= option is ambiguous. Should the SA
2232 permits any port through or should the SA negotiate any single port
2233 through? The first is a basic conn with a wildcard. The second is a
2234 template. The second is the current behaviour, and it's wrong for quite
2235 a number of uses involving TCP. The keyword %one may be introduced in
2236 the future to separate these two cases.
2237
2238 It would be good to have a line-continuation syntax, especially for the
2239 very long lines involved in RSA signature keys.
2240
2241 First packet caching is only implemented for the KLIPS(NG) and MAST
2242 stacks. NETKEY returns POSIX-breaking responses, visible as connect:
2243 Resource temporarily unavailable errors. This affects Opportunistic
2244 Encryption and DPD. Functionality on the BSD and Windows stacks is
2245 unknown.
2246
2247 Some state information is only available when using KLIPS, and will
2248 return errors on other IPsec stacks. These include ipsec eroute, ipsec
2249 spi and ipsec look.
2250
2251 Multiple L2TP clients behind the same NAT router, and multiple L2TP
2252 clients behind different NAT routers using the same Virtual IP is
2253 currently only working for the KLIPSNG stack.
2254
2255 The ability to specify different identities, authby, and public keys
2256 for different automatic-keyed connections between the same participants
2257 is misleading; this doesn't work dependably because the identity of the
2258 participants is not known early enough. This is especially awkward for
2259 the “Road Warrior” case, where the remote IP address is specified as
2260 0.0.0.0, and that is considered to be the “participant” for such
2261 connections.
2262
2263 If conns are to be added before DNS is available, left=FQDN,
2264 leftnextop=FQDN, and leftrsasigkey=%dnsonload will fail.
2265 ipsec_pluto(8) does not actually use the public key for our side of a
2266 conn but it isn't generally known at a add-time which side is ours
2267 (Road Warrior and Opportunistic conns are currently exceptions).
2268
2269 The myid option does not affect explicit
2270 ipsec auto --add or ipsec auto --replace commands for implicit conns.
2271
2273 Paul Wouters
2274 documenter
2275
2276
2277
2278libreswan 08/26/2021 IPSEC.CONF(5)