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