1IPSEC.CONF(5) [FIXME: manual] IPSEC.CONF(5)
2
6 ipsec.conf - IPsec configuration and connections
7
9 The optional ipsec.conf file specifies most configuration and control
10 information for the Openswan IPsec subsystem. (The major exception is
11 secrets for authentication; see ipsec.secrets(5).) Its contents are not
12 security-sensitive unless manual keying is being done for more than
13 just testing, in which case the encryption/authentication keys in the
14 descriptions for the manually-keyed connections are very sensitive (and
15 those connection descriptions are probably best kept in a separate
16 file, via the include facility described below).
17 The file is a text file, consisting of one or more sections. White
19 space followed by # followed by anything to the end of the line is a
20 comment and is ignored, as are empty lines which are not within a
21 section.
22 A line which contains include and a file name, separated by white
24 space, is replaced by the contents of that file, preceded and followed
25 by empty lines. If the file name is not a full pathname, it is
26 considered to be relative to the directory containing the including
27 file. Such inclusions can be nested. Only a single filename may be
28 supplied, and it may not contain white space, but it may include shell
29 wildcards (see sh(1)); for example:
30 include ipsec.*.conf
32 The intention of the include facility is mostly to permit keeping
34 information on connections, or sets of connections, separate from the
35 main configuration file. This permits such connection descriptions to
36 be changed, copied to the other security gateways involved, etc.,
37 without having to constantly extract them from the configuration file
38 and then insert them back into it. Note also the also and alsoflip
39 parameters (described below) which permit splitting a single logical
40 section (e.g. a connection description) into several actual sections.
41 The first significant line of the file must specify the version of this
43 specification that it conforms to:
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 which 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 which 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 which 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 which
106 does not have a parameter of the same name gets a copy of the one from
107 the %default section. There may be multiple %default sections of a
108 given type, but only one default may be supplied for any specific
109 parameter name, and all %default sections of a given type must precede
110 all non-%default sections of that type. %default sections may not
111 contain also or alsoflip parameters.
112 Currently there are two types of section: a config section specifies
114 general configuration information for IPsec, while a conn section
115 specifies an IPsec connection.
116
118 A conn section contains a connection specification, defining a network
119 connection to be made using IPsec. The name given is arbitrary, and is
120 used to identify the connection to ipsec_auto(8) and ipsec_manual(8).
121 Here's a simple example:
122 conn snt
125 left=10.11.11.1
126 leftsubnet=10.0.1.0/24
127 leftnexthop=172.16.55.66
128 leftsourceip=10.0.1.1
129 right=192.168.22.1
130 rightsubnet=10.0.2.0/24
131 rightnexthop=172.16.88.99
132 rightsourceip=10.0.2.1
133 keyingtries=%forever
134 A note on terminology... In automatic keying, there are two kinds of
136 communications going on: transmission of user IP packets, and
137 gateway-to-gateway negotiations for keying, rekeying, and general
138 control. The data path (a set of “IPsec SAs”) used for user packets is
139 herein referred to as the “connection”; the path used for negotiations
140 (built with “ISAKMP SAs”) is referred to as the “keying channel”.
141 To avoid trivial editing of the configuration file to suit it to each
143 system involved in a connection, connection specifications are written
144 in terms of left and right participants, rather than in terms of local
145 and remote. Which participant is considered left or right is arbitrary;
146 IPsec figures out which one it is being run on based on internal
147 information. This permits using identical connection specifications on
148 both ends. There are cases where there is no symmetry; a good
149 convention is to use left for the local side and right for the remote
150 side (the first letters are a good mnemonic).
151 Many of the parameters relate to one participant or the other; only the
153 ones for left are listed here, but every parameter whose name begins
154 with left has a right counterpart, whose description is the same but
155 with left and right reversed.
156 Parameters are optional unless marked “(required)”; a parameter
158 required for manual keying need not be included for a connection which
159 will use only automatic keying, and vice versa.
160 CONN PARAMETERS: GENERAL
162 The following parameters are relevant to both automatic and manual
163 keying. Unless otherwise noted, for a connection to work, in general it
164 is necessary for the two ends to agree exactly on the values of these
165 parameters.
166 connaddrfamily
168 the connection addrress family of the connection; currently the
169 accepted values are ipv4 (the default); or ipv6,
170 The ipv6 family is currently only supported using the NETKEY stack.
172 type
174 the type of the connection; currently the accepted values are
175 tunnel (the default) signifying a host-to-host, host-to-subnet, or
176 subnet-to-subnet tunnel; transport, signifying host-to-host
177 transport mode; passthrough, signifying that no IPsec processing
178 should be done at all; drop, signifying that packets should be
179 discarded; and reject, signifying that packets should be discarded
180 and a diagnostic ICMP returned.
181 left
183 (required) the IP address of the left participant's public-network
184 interface, in any form accepted by ipsec_ttoaddr(3). Currently,
185 IPv4 and IPv6 IP addresses are supported. There are several magic
186 values. If it is %defaultroute, and the config setup section's,
187 interfaces specification contains %defaultroute, left will be
188 filled in automatically with the local address of the default-route
189 interface (as determined at IPsec startup time); this also
190 overrides any value supplied for leftnexthop. (Either left or right
191 may be %defaultroute, but not both.) The value %any signifies an
192 address to be filled in (by automatic keying) during negotiation.
193 The value %opportunistic signifies that both left and leftnexthop
194 are to be filled in (by automatic keying) from DNS data for left's
195 client. The value can also contain the interface name, which will
196 then later be used to obtain the IP address from to fill in. For
197 example %ppp0 The values %group and %opportunisticgroup makes this
198 a policy group conn: one that will be instantiated into a regular
199 or opportunistic conn for each CIDR block listed in the policy
200 group file with the same name as the conn.
201 If using IP addresses in combination with NAT, always use the
203 actual local machine's (NAT'ed) IP address, and if the remote (eg
204 right=) is NAT'ed as well, the remote's public (not NAT'ed) IP
205 address. Note that this makes the configuration no longer
206 symmetrical on both sides, so you cannot use an identical
207 configuration file on both hosts.
208 leftsubnet
210 private subnet behind the left participant, expressed as
211 network/netmask (actually, any form acceptable to
212 ipsec_ttosubnet(3)); Currentlly, IPv4 and IPv6 ranges are
213 supported. if omitted, essentially assumed to be left/32,
214 signifying that the left end of the connection goes to the left
215 participant only
216 leftsubnets
218 specify multiple private subnets behind the left participant,
219 expressed as { networkA/netmaskA networkB/netmaskB [...] } If both
220 a leftsubnets= and rightsubnets= is defined, all combinations of
221 subnet tunnels will be instantiated. You cannot use leftsubnet and
222 leftsubnets together. For examples see testing/pluto/multinet-*.
223 leftprotoport
225 allowed protocols and ports over connection, also called Port
226 Selectors. The argument is in the form protocol, which can be a
227 number or a name that will be looked up in /etc/protocols, such as
228 leftprotoport=icmp, or in the form of protocol/port, such as
229 tcp/smtp. Ports can be defined as a number (eg. 25) or as a name
230 (eg smtp) which will be looked up in /etc/services. A special
231 keyword %any can be used to allow all ports of a certain protocol.
232 The most common use of this option is for L2TP connections to only
233 allow l2tp packets (UDP port 1701), eg: leftprotoport=17/1701. Some
234 clients, notably older Windows XP and some Mac OSX clients, use a
235 random high port as source port. In those cases
236 rightprotoport=17/%any can be used to allow all UDP traffic on the
237 connection. Note that this option is part of the proposal, so it
238 cannot be arbitrarily left out if one end does not care about the
239 traffic selection over this connection - both peers have to agree.
240 The Port Selectors show up in the output of ipsec eroute and ipsec
241 auto --status eg:"l2tp":
242 193.110.157.131[@aivd.xelernace.com]:7/1701...%any:17/1701 This
243 option only filters outbound traffic. Inbound traffic selection
244 must still be based on firewall rules activated by an updown
245 script. The variablees $PLUTO_MY_PROTOCOL, $PLUTO_PEER_PROTOCOL,
246 $PLUTO_MY_PORT, and $PLUTO_PEER_PORT are available for use in
247 updown scripts. Older workarounds for bugs involved a setting of
248 17/0 to denote any single UDP port (not UDP port 0). Some clients,
249 most notably OSX, uses a random high port, instead of port 1705 for
250 L2TP.
251 leftnexthop
253 next-hop gateway IP address for the left participant's connection
254 to the public network; defaults to %direct (meaning right). If the
255 value is to be overridden by the left=%defaultroute method (see
256 above), an explicit value must not be given. If that method is not
257 being used, but leftnexthop is %defaultroute, and
258 interfaces=%defaultroute is used in the config setup section, the
259 next-hop gateway address of the default-route interface will be
260 used. The magic value %direct signifies a value to be filled in (by
261 automatic keying) with the peer's address. Relevant only locally,
262 other end need not agree on it.
263 leftsourceip
265 the IP address for this host to use when transmitting a packet to
266 the other side of this link. Relevant only locally, the other end
267 need not agree. This option is used to make the gateway itself use
268 its internal IP, which is part of the leftsubnet, to communicate to
269 the rightsubnet or right. Otherwise, it will use its nearest IP
270 address, which is its public IP address. This option is mostly used
271 when defining subnet-subnet connections, so that the gateways can
272 talk to each other and the subnet at the other end, without the
273 need to build additional host-subnet, subnet-host and host-host
274 tunnels. Both IPv4 and IPv6 addresses are supported.
275 leftupdown
277 what “updown” script to run to adjust routing and/or firewalling
278 when the status of the connection changes (default ipsec _updown).
279 May include positional parameters separated by white space
280 (although this requires enclosing the whole string in quotes);
281 including shell metacharacters is unwise. An example to enable
282 routing when using the NETKEY stack, one can use:
283 leftupdown="ipsec _updown --route yes"
285 See ipsec_pluto(8) for details. Relevant only locally, other end
287 need not agree on it.
288 leftfirewall
290 This option is obsolete and should not used anymore.
291 If one or both security gateways are doing forwarding firewalling
293 (possibly including masquerading), and this is specified using the
294 firewall parameters, tunnels established with IPsec are exempted from
295 it so that packets can flow unchanged through the tunnels. (This means
296 that all subnets connected in this manner must have distinct,
297 non-overlapping subnet address blocks.) This is done by the default
298 updown script (see ipsec_pluto(8)).
299 The implementation of this makes certain assumptions about firewall
301 setup, and the availability of the Linux Advanced Routing tools. In
302 situations calling for more control, it may be preferable for the user
303 to supply his own updown script, which makes the appropriate
304 adjustments for his system.
305 CONN PARAMETERS: AUTOMATIC KEYING
307 The following parameters are relevant only to automatic keying, and are
308 ignored in manual keying. Unless otherwise noted, for a connection to
309 work, in general it is necessary for the two ends to agree exactly on
310 the values of these parameters.
311 auto
313 what operation, if any, should be done automatically at IPsec
314 startup; currently-accepted values are add (signifying an ipsec
315 auto --add), route (signifying that plus an ipsec auto --route),
316 start (signifying that plus an ipsec auto --up), manual (signifying
317 an ipsec manual --up), and ignore (also the default) (signifying no
318 automatic startup operation). See the config setup discussion
319 below. Relevant only locally, other end need not agree on it (but
320 in general, for an intended-to-be-permanent connection, both ends
321 should use auto=start to ensure that any reboot causes immediate
322 renegotiation).
323 authby
325 how the two security gateways should authenticate each other;
326 acceptable values are secret for shared secrets, rsasig for RSA
327 digital signatures (the default), secret|rsasig for either, and
328 never if negotiation is never to be attempted or accepted (useful
329 for shunt-only conns). Digital signatures are superior in every way
330 to shared secrets.
331 ike
333 IKE encryption/authentication algorithm to be used for the
334 connection (phase 1 aka ISAKMP SA). The format is
335 "cipher-hash;modpgroup, cipher-hash;modpgroup, ..." Any left out
336 option will be filled in with all allowed default options. Multiple
337 proposals are separated by a comma. If an ike= line is specified,
338 no other received proposals will be accepted. Formerly there was a
339 distinction (by using a "!" symbol) between "strict mode" or not.
340 That mode has been obsoleted. If an ike= option is specified, the
341 mode is always strict, meaning no other received proposals will be
342 accepted. Some examples are ike=3des-sha1,aes-sha1, ike=aes,
343 ike=aes128-md5;modp2048, ike=aes128-sha1;dh22,
344 ike=3des-md5;modp1024,aes-sha1;modp1536 or ike=modp1536. The
345 options must be suitable as a value of ipsec_spi(8)'s --ike option.
346 The default is to use IKE, and to allow all combinations of:
347 cipher: 3des or aes
349 hash: sha1 or md5
350 pfsgroup (DHgroup): modp1024 or modp1536
351 If Openswan was compiled with extra INSECURE and BROKEN options,
353 then the des (1des) and null cipher, as well as modp768 are
354 available. This turns your VPN into a joke. Do not enable these
355 options.
356 If openswan was compiled with USE_MODP_RFC5114 support, then
358 Diffie-Hellman groups 22, 23 and 24 are also implemented as per
359 RFC-5114. Instead of the modp key syntax, use the "dh" keyword, for
360 example ike=3des-sha1;dh23
361 phase2
363 Sets the type of SA that will be produced. Valid options are: esp
364 for encryption (the default), and ah for authentication only.
365 phase2alg
367 Specifies the algorithms that will be offered/accepted for a phase2
368 negotiation. If not specified, a secure set of defaults will be
369 used. Sets are separated using comma's.
370 The default values are the same as for ike= Note also that not all
372 ciphers available to the kernel (eg through CryptoAPI) are
373 necessarilly supported here.
374 The format for ESP is ENC-AUTH followed by an optional PFSgroup.
376 For instance, "3des-md5" or "aes256-sha1;modp2048" or
377 "aes-sha1,aes-md5".
378 For RFC-5114 DH groups, use the "dh" keyword, eg "aes256-sha1;dh23"
380 The format for AH is AUTH followed by an optional PFSgroup. For
382 instance, "md5" or "sha1;modp1536".
383 A special case is AES CCM, which uses the syntax of
385 "phase2alg=aes_ccm_a-152-null"
386 sha2_truncbug
388 The default hash truncation for sha2_256 is 128 bits. Linux
389 implemented the draft version which stated 96 bits. This option
390 enables using the bad 96 bits version to interop with older linux
391 kernels (unpatched version 2.6.33 and older) and openswan versions
392 before 2.6.38. Currently the accepted values are no, (the default)
393 signifying default IETF truncation of 128 bits, or yes, signifying
394 96 bits broken Linux kernel style truncation.
395 esp
397 This option is obsolete. Please use phase2alg instead.
398 ah
400 AH authentication algorithm to be used for the connection, e.g
401 here. hmac-md5 The options must be suitable as a value of
402 ipsec_spi(8)'s --ah option. The default is not to use AH. If for
403 some (invalid) reason you still think you need AH, please use esp
404 with the null encryption cipher instead. Note also that not all
405 ciphers available to the kernel (eg through CryptoAPI) are
406 necessarilly supported here.
407 ikev2
409 IKEv2 (RFC4309) settings to be used. Currently the accepted values
410 are permit, (the default) signifying no IKEv2 should be
411 transmitted, but will be accepted if the other ends initiates to us
412 with IKEv2; never or no signifying no IKEv2 negotiation should be
413 transmitted or accepted; propose or yes signifying that we permit
414 IKEv2, and also use it as the default to initiate; insist,
415 signifying we only accept and receive IKEv2 - IKEv1 negotiations
416 will be rejected.
417 If the ikev2= setting is set to permit or propose, Openswan will
419 try and detect a "bid down" attack from IKEv2 to IKEv1. Since there
420 is no standard for transmitting the IKEv2 capability with IKEv1,
421 Openswan uses a special Vendor ID "CAN-IKEv2". If a fall back from
422 IKEv2 to IKEv1 was detected, and the IKEv1 negotiation contains
423 Vendor ID "CAN-IKEv2", Openswan will immediately attempt and IKEv2
424 rekey and refuse to use the IKEv1 connection. With an ikev2=
425 setting of insist, no IKEv1 negotiation is allowed, and no bid down
426 attack is possible.
427 sareftrack
429 Set the method of tracking reply packets with SArefs when using an
430 SAref compatible stack. Currently only the mast stack supports
431 this. Acceptable values are yes (the default), no. This option is
432 ignored when SArefs are not supported. This option is passed as
433 PLUTO_SAREF_TRACKING to the updown script which makes the actual
434 decisions whether to perform any iptables/ip_conntrack
435 manipulation. A value of yes means that an IPSEC mangle table will
436 be created. This table will be used to match reply packets. A value
437 of no means no IPSEC mangle table is created, and SAref tracking is
438 left to a third-party (kernel) module. In case of a third party
439 module, the SArefs can be relayed using the HAVE_STATSD deamon.
440 leftid
442 how the left participant should be identified for authentication;
443 defaults to left. Can be an IP address (in any ipsec_ttoaddr(3)
444 syntax) or a fully-qualified domain name preceded by @ (which is
445 used as a literal string and not resolved). The magic value
446 %fromcert causes the ID to be set to a DN taken from a certificate
447 that is loaded. Prior to 2.5.16, this was the default if a
448 certificate was specified. The magic value %none sets the ID to no
449 ID. This is included for completeness, as the ID may have been set
450 in the default conn, and one wishes for it to default instead of
451 being explicitly set. The magic value %myid stands for the current
452 setting of myid. This is set in config setup or by ipsec_whack(8)),
453 or, if not set, it is the IP address in %defaultroute (if that is
454 supported by a TXT record in its reverse domain), or otherwise it
455 is the system's hostname (if that is supported by a TXT record in
456 its forward domain), or otherwise it is undefined.
457 leftrsasigkey
459 the left participant's public key for RSA signature authentication,
460 in RFC 2537 format using ipsec_ttodata(3) encoding. The magic value
461 %none means the same as not specifying a value (useful to override
462 a default). The value %dnsondemand (the default) means the key is
463 to be fetched from DNS at the time it is needed. The value
464 %dnsonload means the key is to be fetched from DNS at the time the
465 connection description is read from ipsec.conf; currently this will
466 be treated as %none if right=%any or right=%opportunistic. The
467 value %dns is currently treated as %dnsonload but will change to
468 %dnsondemand in the future. The identity used for the left
469 participant must be a specific host, not %any or another magic
470 value. The value %cert will load the information required from a
471 certificate defined in %leftcert and automatically define leftid
472 for you. Caution: if two connection descriptions specify different
473 public keys for the same leftid, confusion and madness will ensue.
474 leftrsasigkey2
476 if present, a second public key. Either key can authenticate the
477 signature, allowing for key rollover.
478 leftcert
480 If you are using leftrsasigkey=%cert this defines the certificate
481 you would like to use. It should point to a X.509 encoded
482 certificate file. If you do not specify a full pathname, by default
483 it will look in /etc/ipsec.d/certs. If openswan has been compiled
484 with USE_LIBNSS=true, then openswan will also check the NSS
485 database for RSA keys. These can be software or hardware.
486 leftca
488 specifies the authorized Certificate Authority (CA) that signed the
489 certificate of the peer. If undefined, it defaults to the CA that
490 signed the certificate specified in leftcert. The special
491 rightca=%same is implied when not specifying a rightca and means
492 that only peers with certificates signed by the same CA as the
493 leftca will be allowed. This option is only useful in complex multi
494 CA certificate situations. When using a single CA, it can be safely
495 omitted for both left and right.
496 leftsendcert
498 This option configures when Openswan will send X.509 certificates
499 to the remote host. Acceptable values are yes|always (signifying
500 that we should always send a certificate), ifasked (signifying that
501 we should send a certificate if the remote end asks for it), and
502 no|never (signifying that we will never send a X.509 certificate).
503 The default for this option is ifasked which may break
504 compatibility with other vendor's IPSec implementations, such as
505 Cisco and SafeNet. If you find that you are getting errors about no
506 ID/Key found, you likely need to set this to always. This per-conn
507 option replaces the obsolete global nocrsend option.
508 leftxauthserver
510 Left is an XAUTH server. This can use PAM for authentication or md5
511 passwords in /etc/ipsec.d/passwd. These are additional credentials
512 to verify the user identity, and should not be confused with the
513 XAUTH group secret, which is just a regular PSK defined in
514 ipsec.secrets. The other side of the connection should be
515 configured as rightxauthclient. XAUTH connections cannot rekey, so
516 rekey=no should be specified in this conn. For further details on
517 how to compile and use XAUTH, see README.XAUTH. Acceptable values
518 are yes or no (the default).
519 leftxauthclient
521 Left is an XAUTH client. The xauth connection will have to be
522 started interactively and cannot be configured using auto=start.
523 Instead, it has to be started from the commandline using ipsec auto
524 --up connname. You will then be prompted for the username and
525 password. To setup an XAUTH connection non-interactively, which
526 defeats the whole purpose of XAUTH, but is regularly requested by
527 users, it is possible to use a whack command - ipsec whack --name
528 baduser --ipsecgroup-xauth --xauthname badusername --xauthpass
529 password --initiate The other side of the connection should be
530 configured as rightxauthserver. Acceptable values are yes or no
531 (the default).
532 leftxauthusername
534 The XAUTH username associated with this XAUTH connection. The XAUTH
535 password can be configured in the ipsec.secrets file.
536 leftmodecfgserver
538 Left is a Mode Config server. It can push network configuration to
539 the client. Acceptable values are yes or no (the default).
540 leftmodecfgclient
542 Left is a Mode Config client. It can receive network configuration
543 from the server. Acceptable values are yes or no (the default).
544 modecfgpull
546 Pull the Mode Config network information from the server.
547 Acceptable values are yes or no (the default).
548 modecfgdns1, modecfgdns2
550 Specify the IP address for DNS servers for the client to use.
551 remote_peer_type
553 Set the remote peer type. This can enable additional processing
554 during the IKE negotiation. Acceptable values are cisco or ietf
555 (the default). When set to cisco, support for Cisco IPsec gateway
556 redirection and Cisco obtained DNS and domainname are enabled. This
557 includes automatically updating (and restoring) /etc/resolv.conf.
558 These options require that XAUTH is also enabled on this
559 connection.
560 nm_configured
562 Mark this connection as controlled by Network Manager. Acceptable
563 values are yes or no (the default). Currently, setting this to yes
564 will cause openswan to skip reconfiguring resolv.conf when used
565 with XAUTH and ModeConfig.
566 forceencaps
568 In some cases, for example when ESP packets are filtered or when a
569 broken IPsec peer does not properly recognise NAT, it can be useful
570 to force RFC-3948 encapsulation. forceencaps=yes forces the NAT
571 detection code to lie and tell the remote peer that RFC-3948
572 encapsulation (ESP in UDP port 4500 packets) is required. For this
573 option to have any effect, the setup section option
574 nat_traversal=yes needs to be set. Acceptable values are yes or no
575 (the default).
576 overlapip
578 a boolean (yes/no) that determines, when *subnet=vhost: is used, if
579 the virtual IP claimed by this states created from this connection
580 can with states created from other connections.
581 Note that connection instances created by the Opportunistic
583 Encryption or PKIX (x.509) instantiation system are distinct
584 internally. They will inherit this policy bit.
585 The default is no.
587 This feature is only available with kernel drivers that support SAs
589 to overlapping conns. At present only the (klips)mast protocol
590 stack supports this feature.
591 dpddelay
593 Set the delay (in seconds) between Dead Peer Dectection (RFC 3706)
594 keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for this
595 connection (default 30 seconds). If dpddelay is set, dpdtimeout
596 also needs to be set.
597 dpdtimeout
599 Set the length of time (in seconds) we will idle without hearing
600 either an R_U_THERE poll from our peer, or an R_U_THERE_ACK reply.
601 After this period has elapsed with no response and no traffic, we
602 will declare the peer dead, and remove the SA (default 120
603 seconds). If dpdtimeout is set, dpdaction also needs to be set.
604 dpdaction
606 When a DPD enabled peer is declared dead, what action should be
607 taken. hold (default) means the eroute will be put into %hold
608 status, while clear means the eroute and SA with both be cleared.
609 restart means the the SA will immediately be renegotiated, and
610 restart_by_peer means that ALL SA's to the dead peer will
611 renegotiated.
612 dpdaction=clear is really only useful on the server of a Road
614 Warrior config.
615 pfs
617 whether Perfect Forward Secrecy of keys is desired on the
618 connection's keying channel (with PFS, penetration of the
619 key-exchange protocol does not compromise keys negotiated earlier);
620 Since there is no reason to ever refuse PFS, Openswan will allow a
621 connection defined with pfs=no to use PFS anyway. Acceptable values
622 are yes (the default) and no.
623 pfsgroup
625 This option is obsoleted, please use phase2alg if you need the pfs
626 to be different from phase1 (the default) using:
627 phase2alg=aes128-md5;modp1024
628 aggrmode
630 Use Aggressive Mode instead of Main Mode. Aggressive Mode is less
631 secure, and vulnerable to Denial Of Service attacks. It is also
632 vulnerable to brute force attacks with software such as ikecrack.
633 It should not be used, and it should especially not be used with
634 XAUTH and group secrets (PSK). If the remote system administrator
635 insists on staying irresponsible, enable this option.
636 Aggressive Mode is further limited to only proposals with one DH
638 group as there is no room to negotiate the DH group. Therefor it is
639 mandatory for Aggressive Mode connections that both ike= and
640 phase2alg= options are specified with only fully specified proposal
641 using one DH group. Acceptable values are yes or no (the default).
642 The ISAKMP SA is created in exchange 1 in aggressive mode. Openswan
644 has to send the exponent during that exchange, so it has to know
645 what DH group to use before starting. This is why you can not have
646 multiple DH groups in aggressive mode. In IKEv2, which uses a
647 similar method to IKEv1 Aggressive Mode, there is a message to
648 convey the DH group is wrong, and so an IKEv2 connection can
649 actually recover from picking the wrong DH group by restarting its
650 negotiation.
651 salifetime
653 how long a particular instance of a connection (a set of
654 encryption/authentication keys for user packets) should last, from
655 successful negotiation to expiry; acceptable values are an integer
656 optionally followed by s (a time in seconds) or a decimal number
657 followed by m, h, or d (a time in minutes, hours, or days
658 respectively) (default 8h, maximum 24h). Normally, the connection
659 is renegotiated (via the keying channel) before it expires. The two
660 ends need not exactly agree on salifetime, although if they do not,
661 there will be some clutter of superseded connections on the end
662 which thinks the lifetime is longer.
663 The keywords "keylife" and "lifetime" are aliases for "salifetime."
665 rekey
667 whether a connection should be renegotiated when it is about to
668 expire; acceptable values are yes (the default) and no. The two
669 ends need not agree, but while a value of no prevents Pluto from
670 requesting renegotiation, it does not prevent responding to
671 renegotiation requested from the other end, so no will be largely
672 ineffective unless both ends agree on it.
673 rekeymargin
675 how long before connection expiry or keying-channel expiry should
676 attempts to negotiate a replacement begin; acceptable values as for
677 salifetime (default 9m). Relevant only locally, other end need not
678 agree on it.
679 rekeyfuzz
681 maximum percentage by which rekeymargin should be randomly
682 increased to randomize rekeying intervals (important for hosts with
683 many connections); acceptable values are an integer, which may
684 exceed 100, followed by a `%' (default set by ipsec_pluto(8),
685 currently 100%). The value of rekeymargin, after this random
686 increase, must not exceed salifetime. The value 0% will suppress
687 time randomization. Relevant only locally, other end need not agree
688 on it.
689 keyingtries
691 how many attempts (a whole number or %forever) should be made to
692 negotiate a connection, or a replacement for one, before giving up
693 (default %forever). The value %forever means “never give up”
694 (obsolete: this can be written 0). Relevant only locally, other end
695 need not agree on it.
696 ikelifetime
698 how long the keying channel of a connection (buzzphrase: “ISAKMP
699 SA”) should last before being renegotiated; acceptable values as
700 for keylife (default set by ipsec_pluto(8), currently 1h, maximum
701 24h). The two-ends-disagree case is similar to that of keylife.
702 compress
704 whether IPComp compression of content is proposed on the connection
705 (link-level compression does not work on encrypted data, so to be
706 effective, compression must be done before encryption); acceptable
707 values are yes and no (the default). The two ends need not agree. A
708 value of yes causes IPsec to propose both compressed and
709 uncompressed, and prefer compressed. A value of no prevents IPsec
710 from proposing compression; a proposal to compress will still be
711 accepted.
712 metric
714 Set the metric for the routes to the ipsecX or mastX interface.
715 This makes it possible to do host failover from another interface
716 to ipsec using route management. This value is passed to the
717 _updown scripts as PLUTO_METRIC. This option is only available with
718 KLIPS or MAST on Linux. Acceptable values are positive numbers,
719 with the default being 1.
720 disablearrivalcheck
722 whether KLIPS's normal tunnel-exit check (that a packet emerging
723 from a tunnel has plausible addresses in its header) should be
724 disabled; acceptable values are yes and no (the default).
725 Tunnel-exit checks improve security and do not break any normal
726 configuration. Relevant only locally, other end need not agree on
727 it.
728 failureshunt
730 what to do with packets when negotiation fails. The default is
731 none: no shunt; passthrough, drop, and reject have the obvious
732 meanings.
733 CONN PARAMETERS: MANUAL KEYING
735 This command was obsoleted around the same time that Al Gore invented
736 the internet. ipsec manual was used in the jurassic period to load
737 static keys into the kernel. There are no rational reasons to use this,
738 and it is not supported anymore. If you need to create static SAs, then
739 you can use ipsec spi and ipsec eroute when using KLIPS or ip xfrm or
740 setkey when using NETKEY.
741 No rational person uses static keys. They are not easier to use.
743 REPEAT: they are not easier to use.
744
746 At present, the only config section known to the IPsec software is the
747 one named setup, which contains information used when the software is
748 being started (see ipsec_setup(8)). Here's an example:
749 config setup
752 interfaces="ipsec0=eth1 ipsec1=ppp0"
753 klipsdebug=none
754 plutodebug=control
755 protostack=auto
756 manualstart=
757 Parameters are optional unless marked “(required)”.
759 The currently-accepted parameter names in a config setup section are:
761 myid
763 the identity to be used for %myid. %myid is used in the implicit
764 policy group conns and can be used as an identity in explicit
765 conns. If unspecified, %myid is set to the IP address in
766 %defaultroute (if that is supported by a TXT record in its reverse
767 domain), or otherwise the system's hostname (if that is supported
768 by a TXT record in its forward domain), or otherwise it is
769 undefined. An explicit value generally starts with ``@''.
770 protostack
772 decide which protocol stack is going to be used. Valid values are
773 "auto", "klips", "netkey" and "mast". The "mast" stack is a
774 variation for the klips stack.
775 interfaces
777 virtual and physical interfaces for IPsec to use: a single
778 virtual=physical pair, a (quoted!) list of pairs separated by white
779 space, or %none. One of the pairs may be written as %defaultroute,
780 which means: find the interface d that the default route points to,
781 and then act as if the value was ``ipsec0=d''. %defaultroute is
782 the default; %none must be used to denote no interfaces, or when
783 using the NETKEY stack. If %defaultroute is used (implicitly or
784 explicitly) information about the default route and its interface
785 is noted for use by ipsec_manual(8) and ipsec_auto(8).)
786 listen
788 IP address to listen on (default depends on interfaces= setting).
789 Currently only accepts one IP address.
790 nat_traversal
792 whether to accept/offer to support NAT (NAPT, also known as "IP
793 Masqurade") workaround for IPsec. Acceptable values are: yes and no
794 (the default). This parameter may eventually become per-connection.
795 disable_port_floating
797 whether to enable the newer NAT-T standards for port floating.
798 Acceptable values are no (the default) and yes .
799 force_keepalive
801 whether to force sending NAT-T keep-alives to support NAT which are
802 send to prevent the NAT router from closing its port when there is
803 not enough traffic on the IPsec connection. Acceptable values are:
804 yes and no (the default). This parameter may eventually become
805 per-connection.
806 keep_alive
808 The delay (in seconds) for NAT-T keep-alive packets, if these are
809 enabled using force_keepalive This parameter may eventually become
810 per-connection.
811 virtual_private
813 contains the networks that are allowed as subnet= for the remote
814 client. In other words, the address ranges that may live behind a
815 NAT router through which a client connects. This value is usually
816 set to all the RFC-1918 address space, excluding the space used in
817 the local subnet behind the NAT (An IP address cannot live at two
818 places at once). IPv4 address ranges are denoted as %v4:a.b.c.d/mm
819 and IPv6 is denoted as %v6:aaaa::bbbb:cccc:dddd:eeee/mm. One can
820 exclude subnets by using the !. For example, if the VPN server is
821 giving access to 192.168.1.0/24, this option should be set to:
822 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.
823 This parameter is only needed on the server side and not on the
824 client side that resides behind the NAT router, as the client will
825 just use its IP address for the inner IP setting. This parameter
826 may eventually become per-connection.
827 oe
829 a boolean (yes/no) that determines if Opportunistic Encryption will
830 be enabled. Opportunistic Encryption is the term to describe using
831 IPsec tunnels without prearrangement. It uses IPSECKEY or TXT
832 records to announce public RSA keys for certain IP's or identities.
833 For a complete description see
835 /doc/draft-richardson-ipsec-opportunistic.txt,
836 doc/opportunism-spec.txt and doc/opportunism.howto. See also the
837 IETF BTNS working group and RFC4025.
838 The default is no.
840 This feature is only available with kernel drivers that support the
842 caching of packets (%hold eroutes or equivalent) that allows us to
843 respond to a packet from an unknown IP address. At present only the
844 (klips)mast protocol stack supports this feature.
845 nhelpers
847 how many pluto helpers are started to help with cryptographic
848 operations. Pluto will start (n-1) of them, where n is the number
849 of CPU's you have (including hypherthreaded CPU's). A value of 0
850 forces pluto to do all operations in the main process. A value of
851 -1 tells pluto to perform the above calculation. Any other value
852 forces the number to that amount.
853 crlcheckinterval
855 interval, specified in seconds, after which pluto will verify
856 loaded X.509 CRL's for expiration. If any of the CRL's is expired,
857 or if they previously failed to get updated, a new attempt at
858 updating the CRL is made. The first attempt to update a CRL is
859 started at two times the crlcheckinterval. If set to 0, which is
860 also the default value if this option is not specified, CRL
861 updating is disabled.
862 strictcrlpolicy
864 if not set, pluto is tolerant about missing or expired X.509
865 Certificate Revocation Lists (CRL's), and will allow peer
866 certificates as long as they do not appear on an expired CRL. When
867 this option is enabled, all connections with an expired or missing
868 CRL will be denied. Active connections will be terminated at rekey
869 time. This setup is more secure, but also dangerous. If the CRL is
870 fetched through an IPsec tunnel with a CRL that expired, the entire
871 VPN server will be dead in the water until a new CRL is manually
872 transferred to the machine (if it allows non-IPsec connections).
873 Acceptable values are yes or no (the default).
874 forwardcontrol
876 This option is obsolete and ignored. Please use
877 net.ipv4.ip_forward = 0 in /etc/sysctl.conf instead to control the
878 ip forwarding behaviour.
879 rp_filter
881 This option is obsolete and ignored. Please use the
882 net.ipv4.conf/[iface]/rp_filter = 0 options in /etc/sysctl.conf
883 instead. This option is badly documented; it must be 0 in many
884 cases for ipsec to function.
885 syslog
887 the syslog(2) “facility” name and priority to use for
888 startup/shutdown log messages, default daemon.error.
889 klipsdebug
891 how much KLIPS debugging output should be logged. An empty value,
892 or the magic value none, means no debugging output (the default).
893 The magic value all means full output. Otherwise only the specified
894 types of output (a quoted list, names separated by white space) are
895 enabled; for details on available debugging types, see
896 ipsec_klipsdebug(8). This KLIPS option has no effect on NETKEY,
897 Windows or BSD stacks.
898 plutodebug
900 how much Pluto debugging output should be logged. An empty value,
901 or the magic value none, means no debugging output (the default).
902 The magic value all means full output. Otherwise only the specified
903 types of output (a quoted list, names without the --debug- prefix,
904 separated by white space) are enabled; for details on available
905 debugging types, see ipsec_pluto(8).
906 uniqueids
908 whether a particular participant ID should be kept unique, with any
909 new (automatically keyed) connection using an ID from a different
910 IP address deemed to replace all old ones using that ID. Acceptable
911 values are yes (the default) and no. Participant IDs normally are
912 unique, so a new (automatically-keyed) connection using the same ID
913 is almost invariably intended to replace an old one.
914 plutorestartoncrash
916 prevent pluto from restarting after it crashed. This option should
917 only be used when debugging a crasher. It will prevent overwriting
918 a core file on a new start, or a cascade of core files. This option
919 is also required if used with plutostderrlog= to avoid clearing the
920 logs of the crasher. Values can be yes (the default) or no.
921 plutoopts
923 additional options to pass to pluto upon startup. See
924 ipsec_pluto(8).
925 plutostderrlog
927 do not use syslog, but rather log to stderr, and direct stderr to
928 the argument file.
929 pluto
931 whether to start Pluto or not; Values are yes (the default) or no
932 (useful only in special circumstances).
933 plutowait
935 should Pluto wait for each negotiation attempt that is part of
936 startup to finish before proceeding with the next? Values are yes
937 or no (the default).
938 prepluto
940 shell command to run before starting Pluto (e.g., to decrypt an
941 encrypted copy of the ipsec.secrets file). It's run in a very
942 simple way; complexities like I/O redirection are best hidden
943 within a script. Any output is redirected for logging, so running
944 interactive commands is difficult unless they use /dev/tty or
945 equivalent for their interaction. Default is none.
946 postpluto
948 shell command to run after starting Pluto (e.g., to remove a
949 decrypted copy of the ipsec.secrets file). It's run in a very
950 simple way; complexities like I/O redirection are best hidden
951 within a script. Any output is redirected for logging, so running
952 interactive commands is difficult unless they use /dev/tty or
953 equivalent for their interaction. Default is none.
954 dumpdir
956 in what directory should things started by setup (notably the Pluto
957 daemon) be allowed to dump core? The empty value (the default)
958 means they are not allowed to.
959 fragicmp
961 whether a tunnel's need to fragment a packet should be reported
962 back with an ICMP message, in an attempt to make the sender lower
963 his PMTU estimate; acceptable values are yes (the default) and no.
964 This KLIPS option has no effect on NETKEY, Windows or BSD stacks.
965 hidetos
967 whether a tunnel packet's TOS field should be set to 0 rather than
968 copied from the user packet inside; acceptable values are yes (the
969 default) and no. This KLIPS option has no effect on NETKEY, Windows
970 or BSD stacks.
971 overridemtu
973 value that the MTU of the ipsecn interface(s) should be set to,
974 overriding IPsec's (large) default. This parameter is needed only
975 in special situations. This KLIPS option has no effect on NETKEY,
976 Windows or BSD stacks.
977
979 The system automatically defines several conns to implement default
980 policy groups. Each can be overridden by explicitly defining a new conn
981 with the same name. If the new conn has auto=ignore, the definition is
982 suppressed.
983 Here are the automatically supplied definitions.
985 conn clear
988 type=passthrough
989 authby=never
990 left=%defaultroute
991 right=%group
992 auto=route
993 conn clear-or-private
995 type=passthrough
996 left=%defaultroute
997 leftid=%myid
998 right=%opportunisticgroup
999 failureshunt=passthrough
1000 keyingtries=3
1001 ikelifetime=1h
1002 salifetime=1h
1003 rekey=no
1004 auto=route
1005 conn private-or-clear
1007 type=tunnel
1008 left=%defaultroute
1009 leftid=%myid
1010 right=%opportunisticgroup
1011 failureshunt=passthrough
1012 keyingtries=3
1013 ikelifetime=1h
1014 salifetime=1h
1015 rekey=no
1016 auto=route
1017 conn private
1019 type=tunnel
1020 left=%defaultroute
1021 leftid=%myid
1022 right=%opportunisticgroup
1023 failureshunt=drop
1024 keyingtries=3
1025 ikelifetime=1h
1026 salifetime=1h
1027 rekey=no
1028 auto=route
1029 conn block
1031 type=reject
1032 authby=never
1033 left=%defaultroute
1034 right=%group
1035 auto=route
1036 # default policy
1038 conn packetdefault
1039 type=tunnel
1040 left=%defaultroute
1041 leftid=%myid
1042 left=0.0.0.0/0
1043 right=%opportunistic
1044 failureshunt=passthrough
1045 keyingtries=3
1046 ikelifetime=1h
1047 salifetime=1h
1048 rekey=no
1049 auto=route
1050 These conns are not affected by anything in conn %default. They will
1052 only work if %defaultroute works. The leftid will be the interfaces IP
1053 address; this requires that reverse DNS records be set up properly.
1054 The implicit conns are defined after all others. It is appropriate and
1056 reasonable to use also=private-or-clear (for example) in any other
1057 opportunistic conn.
1058
1060 The optional files under /etc/ipsec.d/policy, including
1061 /etc/ipsec.d/policies/clear
1064 /etc/ipsec.d/policies/clear-or-private
1065 /etc/ipsec.d/policies/private-or-clear
1066 /etc/ipsec.d/policies/private
1067 /etc/ipsec.d/policies/block
1068 may contain policy group configuration information to supplement
1071 ipsec.conf. Their contents are not security-sensitive.
1072 These files are text files. Each consists of a list of CIDR blocks, one
1074 per line. White space followed by # followed by anything to the end of
1075 the line is a comment and is ignored, as are empty lines.
1076 A connection in ipsec.conf which has right=%group or
1078 right=%opportunisticgroup is a policy group connection. When a policy
1079 group file of the same name is loaded, with
1080 ipsec auto --rereadgroups
1082 or at system start, the connection is instantiated such that each CIDR
1084 block serves as an instance's right value. The system treats the
1085 resulting instances as normal connections.
1086 For example, given a suitable connection definition private, and the
1088 file /etc/ipsec.d/policy/private with an entry 192.0.2.3, the system
1089 creates a connection instance private#192.0.2.3. This connection
1090 inherits all details from private, except that its right client is
1091 192.0.2.3.
1092
1094 The standard Openswan install includes several policy groups which
1095 provide a way of classifying possible peers into IPsec security
1096 classes: private (talk encrypted only), private-or-clear (prefer
1097 encryption), clear-or-private (respond to requests for encryption),
1098 clear and block. Implicit policy groups apply to the local host only,
1099 and are implemented by the IMPLICIT CONNECTIONS described above.
1100
1102 When choosing a connection to apply to an outbound packet caught with a
1103 %trap, the system prefers the one with the most specific eroute that
1104 includes the packet's source and destination IP addresses. Source
1105 subnets are examined before destination subnets. For initiating, only
1106 routed connections are considered. For responding, unrouted but added
1107 connections are considered.
1108 When choosing a connection to use to respond to a negotiation which
1110 doesn't match an ordinary conn, an opportunistic connection may be
1111 instantiated. Eventually, its instance will be /32 -> /32, but for
1112 earlier stages of the negotiation, there will not be enough information
1113 about the client subnets to complete the instantiation.
1114
1116 /etc/ipsec.conf
1117 /etc/ipsec.d/policies/clear
1118 /etc/ipsec.d/policies/clear-or-private
1119 /etc/ipsec.d/policies/private-or-clear
1120 /etc/ipsec.d/policies/private
1121 /etc/ipsec.d/policies/block
1122
1124 ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8),
1125 ipsec_rsasigkey(8)
1126
1128 Designed for the FreeS/WAN project <http://www.freeswan.org> by Henry
1129 Spencer.
1130
1132 Before reporting new bugs, please ensure you are using the latest
1133 version of Openswan, and if not using KLIPS, please ensure you are
1134 using the latest kernel code for your IPsec stack.
1135 When type or failureshunt is set to drop or reject, Openswan blocks
1137 outbound packets using eroutes, but assumes inbound blocking is handled
1138 by the firewall. Openswan offers firewall hooks via an “updown” script.
1139 However, the default ipsec _updown provides no help in controlling a
1140 modern firewall.
1141 Including attributes of the keying channel (authentication methods,
1143 ikelifetime, etc.) as an attribute of a connection, rather than of a
1144 participant pair, is dubious and incurs limitations.
1145 The use of %any with the protoport= option is ambiguous. Should the SA
1147 permits any port through or should the SA negotiate any single port
1148 through? The first is a basic conn with a wildcard. The second is a
1149 template. The second is the current behaviour, and it's wrong for quite
1150 a number of uses involving TCP. The keyword %one may be introduced in
1151 the future to separate these two cases.
1152 ipsec_manual is not nearly as generous about the syntax of subnets,
1154 addresses, etc. as the usual Openswan user interfaces. Four-component
1155 dotted-decimal must be used for all addresses. It is smart enough to
1156 translate bit-count netmasks to dotted-decimal form.
1157 It would be good to have a line-continuation syntax, especially for the
1159 very long lines involved in RSA signature keys.
1160 First packet caching is only implemented for the KLIPS(NG) and MAST
1162 stacks. NETKEY returns POSIX-breaking responses, visiable as connect:
1163 Resource temporarily unavailable errors. This affects Opportunistic
1164 Encryption and DPD. Functionality on the BSD and Windows stacks is
1165 unknown.
1166 Some state information is only available when using KLIPS, and will
1168 return errors on other IPsec stacks. These include ipsec eroute, ipsec
1169 spi and ipsec look.
1170 Multiple L2TP clients behind the same NAT router, and multiple L2TP
1172 clients behind different NAT routers using the same Virtual IP is
1173 currently only working for the KLIPSNG stack.
1174 The ability to specify different identities, authby, and public keys
1176 for different automatic-keyed connections between the same participants
1177 is misleading; this doesn't work dependably because the identity of the
1178 participants is not known early enough. This is especially awkward for
1179 the “Road Warrior” case, where the remote IP address is specified as
1180 0.0.0.0, and that is considered to be the “participant” for such
1181 connections.
1182 In principle it might be necessary to control MTU on an
1184 interface-by-interface basis, rather than with the single global
1185 override that overridemtu provides. This feature is planned for a
1186 future release.
1187 A number of features which could be implemented in both manual and
1189 automatic keying actually are not yet implemented for manual keying.
1190 This is unlikely to be fixed any time soon.
1191 If conns are to be added before DNS is available, left=FQDN,
1193 leftnextop=FQDN, and leftrsasigkey=%dnsonload will fail.
1194 ipsec_pluto(8) does not actually use the public key for our side of a
1195 conn but it isn't generally known at a add-time which side is ours
1196 (Road Warrior and Opportunistic conns are currently exceptions).
1197 The myid option does not affect explicit
1199 ipsec auto --add or ipsec auto --replace commands for implicit conns.
1200[FIXME: source] 04/03/2013 IPSEC.CONF(5)