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