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