Rebuild library.lo after changing ./configure options
[strongswan.git] / src / starter /
1 .TH IPSEC.CONF 5 "2010-05-30" "@IPSEC_VERSION@" "strongSwan"
3 ipsec.conf \- IPsec configuration and connections
5 The optional
6 .I ipsec.conf
7 file
8 specifies most configuration and control information for the
9 strongSwan IPsec subsystem.
10 The major exception is secrets for authentication;
11 see
12 .IR ipsec.secrets (5).
13 Its contents are not security-sensitive.
14 .PP
15 The file is a text file, consisting of one or more
16 .IR sections .
17 White space followed by
18 .B #
19 followed by anything to the end of the line
20 is a comment and is ignored,
21 as are empty lines which are not within a section.
22 .PP
23 A line which contains
24 .B include
25 and a file name, separated by white space,
26 is replaced by the contents of that file,
27 preceded and followed by empty lines.
28 If the file name is not a full pathname,
29 it is considered to be relative to the directory containing the
30 including file.
31 Such inclusions can be nested.
32 Only a single filename may be supplied, and it may not contain white space,
33 but it may include shell wildcards (see
34 .IR sh (1));
35 for example:
36 .PP
37 .B include
38 .B "ipsec.*.conf"
39 .PP
40 The intention of the include facility is mostly to permit keeping
41 information on connections, or sets of connections,
42 separate from the main configuration file.
43 This permits such connection descriptions to be changed,
44 copied to the other security gateways involved, etc.,
45 without having to constantly extract them from the configuration
46 file and then insert them back into it.
47 Note also the
48 .B also
49 parameter (described below) which permits splitting a single logical
50 section (e.g. a connection description) into several actual sections.
51 .PP
52 A section
53 begins with a line of the form:
54 .PP
55 .I type
56 .I name
57 .PP
58 where
59 .I type
60 indicates what type of section follows, and
61 .I name
62 is an arbitrary name which distinguishes the section from others
63 of the same type.
64 Names must start with a letter and may contain only
65 letters, digits, periods, underscores, and hyphens.
66 All subsequent non-empty lines
67 which begin with white space are part of the section;
68 comments within a section must begin with white space too.
69 There may be only one section of a given type with a given name.
70 .PP
71 Lines within the section are generally of the form
72 .PP
73 \ \ \ \ \ \fIparameter\fB=\fIvalue\fR
74 .PP
75 (note the mandatory preceding white space).
76 There can be white space on either side of the
77 .BR = .
78 Parameter names follow the same syntax as section names,
79 and are specific to a section type.
80 Unless otherwise explicitly specified,
81 no parameter name may appear more than once in a section.
82 .PP
83 An empty
84 .I value
85 stands for the system default value (if any) of the parameter,
86 i.e. it is roughly equivalent to omitting the parameter line entirely.
87 A
88 .I value
89 may contain white space only if the entire
90 .I value
91 is enclosed in double quotes (\fB"\fR);
92 a
93 .I value
94 cannot itself contain a double quote,
95 nor may it be continued across more than one line.
96 .PP
97 Numeric values are specified to be either an ``integer''
98 (a sequence of digits) or a ``decimal number''
99 (sequence of digits optionally followed by `.' and another sequence of digits).
100 .PP
101 There is currently one parameter which is available in any type of
102 section:
103 .TP
104 .B also
105 the value is a section name;
106 the parameters of that section are appended to this section,
107 as if they had been written as part of it.
108 The specified section must exist, must follow the current one,
109 and must have the same section type.
110 (Nesting is permitted,
111 and there may be more than one
112 .B also
113 in a single section,
114 although it is forbidden to append the same section more than once.)
115 .PP
116 A section with name
117 .B %default
118 specifies defaults for sections of the same type.
119 For each parameter in it,
120 any section of that type which does not have a parameter of the same name
121 gets a copy of the one from the
122 .B %default
123 section.
124 There may be multiple
125 .B %default
126 sections of a given type,
127 but only one default may be supplied for any specific parameter name,
128 and all
129 .B %default
130 sections of a given type must precede all non-\c
131 .B %default
132 sections of that type.
133 .B %default
134 sections may not contain the
135 .B also
136 parameter.
137 .PP
138 Currently there are three types of sections:
139 a
140 .B config
141 section specifies general configuration information for IPsec, a
142 .B conn
143 section specifies an IPsec connection, while a
144 .B ca
145 section specifies special properties of a certification authority.
147 A
148 .B conn
149 section contains a
150 .IR "connection specification" ,
151 defining a network connection to be made using IPsec.
152 The name given is arbitrary, and is used to identify the connection.
153 Here's a simple example:
154 .PP
155 .ne 10
156 .nf
157 .ft B
158 .ta 1c
159 conn snt
160         left=
161         leftsubnet=
162         right=
163         rightsubnet=
164         keyingtries=%forever
165         auto=add
166 .ft
167 .fi
168 .PP
169 A note on terminology: There are two kinds of communications going on:
170 transmission of user IP packets, and gateway-to-gateway negotiations for
171 keying, rekeying, and general control.
172 The path to control the connection is called 'ISAKMP SA' in IKEv1
173 and 'IKE SA' in the IKEv2 protocol. That what is being negotiated, the kernel
174 level data path, is called 'IPsec SA' or 'Child SA'.
175 strongSwan currently uses two separate keying daemons. \fIpluto\fP handles
176 all IKEv1 connections, \fIcharon\fP is the daemon handling the IKEv2
177 protocol.
178 .PP
179 To avoid trivial editing of the configuration file to suit it to each system
180 involved in a connection,
181 connection specifications are written in terms of
182 .I left
183 and
184 .I right
185 participants,
186 rather than in terms of local and remote.
187 Which participant is considered
188 .I left
189 or
190 .I right
191 is arbitrary;
192 for every connection description an attempt is made to figure out whether
193 the local endpoint should act as the
194 .I left
195 or
196 .I right
197 endpoint. This is done by matching the IP addresses defined for both endpoints
198 with the IP addresses assigned to local network interfaces. If a match is found
199 then the role (left or right) that matches is going to be considered local.
200 If no match is found during startup,
201 .I left
202 is considered local.
203 This permits using identical connection specifications on both ends.
204 There are cases where there is no symmetry; a good convention is to
205 use
206 .I left
207 for the local side and
208 .I right
209 for the remote side (the first letters are a good mnemonic).
210 .PP
211 Many of the parameters relate to one participant or the other;
212 only the ones for
213 .I left
214 are listed here, but every parameter whose name begins with
215 .B left
216 has a
217 .B right
218 counterpart,
219 whose description is the same but with
220 .B left
221 and
222 .B right
223 reversed.
224 .PP
225 Parameters are optional unless marked '(required)'.
227 Unless otherwise noted, for a connection to work,
228 in general it is necessary for the two ends to agree exactly
229 on the values of these parameters.
230 .TP 14
231 .B ah
232 AH authentication algorithm to be used
233 for the connection, e.g.
234 .B hmac-md5.
235 .TP
236 .B auth
237 whether authentication should be done as part of
238 ESP encryption, or separately using the AH protocol;
239 acceptable values are
240 .B esp
241 (the default) and
242 .BR ah .
243 .br
244 The IKEv2 daemon currently supports ESP only.
245 .TP
246 .B authby
247 how the two security gateways should authenticate each other;
248 acceptable values are
249 .B secret
250 or
251 .B psk
252 for pre-shared secrets,
253 .B pubkey
254 (the default) for public key signatures as well as the synonyms
255 .B rsasig
256 for RSA digital signatures and
257 .B ecdsasig
258 for Elliptic Curve DSA signatures.
259 .B never
260 can be used if negotiation is never to be attempted or accepted (useful for
261 shunt-only conns).
262 Digital signatures are superior in every way to shared secrets.
263 IKEv1 additionally supports the values
264 .B xauthpsk
265 and
266 .B xauthrsasig
267 that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode
268 based on shared secrets  or digital RSA signatures, respectively.
269 IKEv2 additionally supports the value
270 .BR eap ,
271 which indicates an initiator to request EAP authentication. The EAP method
272 to use is selected by the server (see
273 .BR eap ).
274 This parameter is deprecated for IKEv2 connections, as two peers do not need
275 to agree on an authentication method. Use the
276 .B leftauth
277 parameter instead to define authentication methods in IKEv2.
278 .TP
279 .B auto
280 what operation, if any, should be done automatically at IPsec startup;
281 currently-accepted values are
282 .BR add ,
283 .BR route ,
284 .B start
285 and
286 .B ignore
287 (the default).
288 .B add
289 loads a connection without starting it.
290 .B route
291 loads a connection and installs kernel traps. If traffic is detected between
292 .B leftsubnet
293 and
294 .B rightsubnet
295 , a connection is established.
296 .B start
297 loads a connection and brings it up immediatly.
298 .B ignore
299 ignores the connection. This is equal to delete a connection from the config
300 file.
301 Relevant only locally, other end need not agree on it
302 (but in general, for an intended-to-be-permanent connection,
303 both ends should use
304 .B auto=start
305 to ensure that any reboot causes immediate renegotiation).
306 .TP
307 .B compress
308 whether IPComp compression of content is proposed on the connection
309 (link-level compression does not work on encrypted data,
310 so to be effective, compression must be done \fIbefore\fR encryption);
311 acceptable values are
312 .B yes
313 and
314 .B no
315 (the default). A value of
316 .B yes
317 causes IPsec to propose both compressed and uncompressed,
318 and prefer compressed.
319 A value of
320 .B no
321 prevents IPsec from proposing compression;
322 a proposal to compress will still be accepted.
323 .TP
324 .B dpdaction
325 controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
326 R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2)
327 are periodically sent in order to check the
328 liveliness of the IPsec peer. The values
329 .BR clear ,
330 .BR hold ,
331 and
332 .B restart
333 all activate DPD. If no activity is detected, all connections with a dead peer
334 are stopped and unrouted
335 .RB ( clear ),
336 put in the hold state
337 .RB ( hold )
338 or restarted
339 .RB ( restart ).
340 For IKEv1, the default is
341 .B none
342 which disables the active sending of R_U_THERE notifications.
343 Nevertheless pluto will always send the DPD Vendor ID during connection set up
344 in order to signal the readiness to act passively as a responder if the peer
345 wants to use DPD. For IKEv2,
346 .B none
347 does't make sense, since all messages are used to detect dead peers. If specified,
348 it has the same meaning as the default
349 .RB ( clear ).
350 .TP
351 .B dpddelay
352 defines the period time interval with which R_U_THERE messages/INFORMATIONAL
353 exchanges are sent to the peer. These are only sent if no other traffic is
354 received. In IKEv2, a value of 0 sends no additional INFORMATIONAL
355 messages and uses only standard messages (such as those to rekey) to detect
356 dead peers.
357 .TP
358 .B dpdtimeout
359 defines the timeout interval, after which all connections to a peer are deleted
360 in case of inactivity. This only applies to IKEv1, in IKEv2 the default
361 retransmission timeout applies, as every exchange is used to detect dead peers.
362 .TP
363 .B inactivity
364 defines the timeout interval, after which a CHILD_SA is closed if it did
365 not send or receive any traffic. Currently supported in IKEv2 connections only.
366 .TP
367 .B eap
368 defines the EAP type to propose as server if the client requests EAP
369 authentication. Currently supported values are
370 .B aka
371 for EAP-AKA,
372 .B gtc
373 for EAP-GTC,
374 .B md5
375 for EAP-MD5,
376 .B mschapv2
377 for EAP-MS-CHAPv2,
378 .B radius
379 for the EAP-RADIUS proxy and
380 .B sim
381 for EAP-SIM. Additionally, IANA assigned EAP method numbers are accepted, or a
382 definition in the form
383 .B eap=type-vendor
384 (e.g. eap=7-12345) can be used to specify vendor specific EAP types.
385 This parameter is deprecated in the favour of
386 .B leftauth.
388 To forward EAP authentication to a RADIUS server using the EAP-RADIUS plugin,
389 set
390 .BR eap=radius .
391 .TP
392 .B eap_identity
393 defines the identity the client uses to reply to a EAP Identity request.
394 If defined on the EAP server, the defined identity will be used as peer
395 identity during EAP authentication. The special value
396 .B %identity
397 uses the EAP Identity method to ask the client for an EAP identity. If not
398 defined, the IKEv2 identity will be used as EAP identity.
399 .TP
400 .B esp
401 comma-separated list of ESP encryption/authentication algorithms to be used
402 for the connection, e.g.
403 .BR 3des-md5 .
404 The notation is
405 .BR encryption-integrity-[dh-group] .
406 .br
407 If
408 .B dh-group
409 is specified, CHILD_SA setup and rekeying include a separate diffe hellman
410 exchange (IKEv2 only).
411 .TP
412 .B forceencaps
413 Force UDP encapsulation for ESP packets even if no NAT situation is detected.
414 This may help to surmount restrictive firewalls. In order to force the peer to
415 encapsulate packets, NAT detection payloads are faked (IKEv2 only).
416 .TP
417 .B ike
418 comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms
419 to be used, e.g.
420 .BR aes128-sha1-modp2048 .
421 The notation is
422 .BR encryption-integrity-dhgroup .
423 In IKEv2, multiple algorithms and proposals may be included, such as
424 .B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024.
425 .TP
426 .B ikelifetime
427 how long the keying channel of a connection (ISAKMP or IKE SA)
428 should last before being renegotiated.
429 .TP
430 .B installpolicy
431 decides whether IPsec policies are installed in the kernel by the IKEv2
432 charon daemon for a given connection. Allows peaceful cooperation e.g. with
433 the Mobile IPv6 daemon mip6d who wants to control the kernel policies.
434 Acceptable values are
435 .B yes
436 (the default) and
437 .BR no .
438 .TP
439 .B keyexchange
440 method of key exchange;
441 which protocol should be used to initialize the connection. Connections marked with
442 .B ikev1
443 are initiated with pluto, those marked with
444 .B ikev2
445 with charon. An incoming request from the remote peer is handled by the correct
446 daemon, unaffected from the
447 .B keyexchange
448 setting. The default value
449 .B ike
450 currently is a synonym for
451 .BR ikev1 .
452 .TP
453 .B keyingtries
454 how many attempts (a whole number or \fB%forever\fP) should be made to
455 negotiate a connection, or a replacement for one, before giving up
456 (default
457 .BR %forever ).
458 The value \fB%forever\fP
459 means 'never give up'.
460 Relevant only locally, other end need not agree on it.
461 .TP
462 .B keylife
463 synonym for
464 .BR lifetime .
465 .TP
466 .B left
467 (required)
468 the IP address of the left participant's public-network interface
469 or one of several magic values.
470 If it is
471 .BR %defaultroute ,
472 .B left
473 will be filled in automatically with the local address
474 of the default-route interface (as determined at IPsec startup time and
475 during configuration update).
476 Either
477 .B left
478 or
479 .B right
480 may be
481 .BR %defaultroute ,
482 but not both.
483 The prefix
484 .B  %
485 in front of a fully-qualified domain name or an IP address will implicitly set
486 .B leftallowany=yes.
487 If the domain name cannot be resolved into an IP address at IPsec startup or
488 update time then
489 .B left=%any
490 and
491 .B leftallowany=no
492 will be assumed.
494 In case of an IKEv2 connection, the value
495 .B %any
496 for the local endpoint signifies an address to be filled in (by automatic
497 keying) during negotiation. If the local peer initiates the connection setup
498 the routing table will be queried to determine the correct local IP address.
499 In case the local peer is responding to a connection setup then any IP address
500 that is assigned to a local interface will be accepted.
501 .br
502 Note that specifying
503 .B %any
504 for the local endpoint is not supported by the IKEv1 pluto daemon.
506 If
507 .B %any
508 is used for the remote endpoint it literally means any IP address.
510 Please note that with the usage of wildcards multiple connection descriptions
511 might match a given incoming connection attempt. The most specific description
512 is used in that case.
513 .TP
514 .B leftallowany
515 a modifier for
516 .B left
517 , making it behave as
518 .B %any
519 although a concrete IP address has been assigned.
520 Recommended for dynamic IP addresses that can be resolved by DynDNS at IPsec
521 startup or update time.
522 Acceptable values are
523 .B yes
524 and
525 .B no
526 (the default).
527 .TP
528 .B leftauth
529 Authentication method to use locally (left) or require from the remote (right)
530 side.
531 This parameter is supported in IKEv2 only. Acceptable values are
532 .B pubkey
533 for public key authentication (RSA/ECDSA),
534 .B psk
535 for pre-shared key authentication and
536 .B eap
537 to (require the) use of the Extensible Authentication Protocol. In the case
538 of
539 .B eap,
540 an optional EAP method can be appended. Currently defined methods are
541 .BR eap-aka ,
542 .BR eap-gtc ,
543 .BR eap-md5 ,
544 .BR eap-tls ,
545 .B eap-mschapv2
546 and
547 .BR eap-sim .
548 Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific
549 EAP methods are defined in the form
550 .B eap-type-vendor
551 .RB "(e.g. " eap-7-12345 ).
552 .TP
553 .B leftauth2
554 Same as
555 .BR leftauth ,
556 but defines an additional authentication exchange. IKEv2 supports multiple
557 authentication rounds using "Multiple Authentication Exchanges" defined
558 in RFC4739. This allows, for example, separated authentication
559 of host and user (IKEv2 only).
560 .TP
561 .B leftca
562 the distinguished name of a certificate authority which is required to
563 lie in the trust path going from the left participant's certificate up
564 to the root certification authority.
565 .TP
566 .B leftca2
567 Same as
568 .B leftca,
569 but for the second authentication round (IKEv2 only).
570 .TP
571 .B leftcert
572 the path to the left participant's X.509 certificate. The file can be encoded
573 either in PEM or DER format. OpenPGP certificates are supported as well.
574 Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
575 are accepted. By default
576 .B leftcert
577 sets
578 .B leftid
579 to the distinguished name of the certificate's subject and
580 .B leftca
581 to the distinguished name of the certificate's issuer.
582 The left participant's ID can be overriden by specifying a
583 .B leftid
584 value which must be certified by the certificate, though.
585 .TP
586 .B leftcert2
587 Same as
588 .B leftcert,
589 but for the second authentication round (IKEv2 only).
590 .TP
591 .B leftfirewall
592 whether the left participant is doing forwarding-firewalling
593 (including masquerading) using iptables for traffic from \fIleftsubnet\fR,
594 which should be turned off (for traffic to the other subnet)
595 once the connection is established;
596 acceptable values are
597 .B yes
598 and
599 .B no
600 (the default).
601 May not be used in the same connection description with
602 .BR leftupdown .
603 Implemented as a parameter to the default \fBipsec _updown\fR script.
604 See notes below.
605 Relevant only locally, other end need not agree on it.
607 If one or both security gateways are doing forwarding firewalling
608 (possibly including masquerading),
609 and this is specified using the firewall parameters,
610 tunnels established with IPsec are exempted from it
611 so that packets can flow unchanged through the tunnels.
612 (This means that all subnets connected in this manner must have
613 distinct, non-overlapping subnet address blocks.)
614 This is done by the default \fBipsec _updown\fR script (see
615 .IR pluto (8)).
617 In situations calling for more control,
618 it may be preferable for the user to supply his own
619 .I updown
620 script,
621 which makes the appropriate adjustments for his system.
622 .TP
623 .B leftgroups
624 a comma separated list of group names. If the
625 .B leftgroups
626 parameter is present then the peer must be a member of at least one
627 of the groups defined by the parameter. Group membership must be certified
628 by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts/\fP thas has
629 been issued to the peer by a trusted Authorization Authority stored in
630 \fI/etc/ipsec.d/aacerts/\fP.
631 .br
632 Attribute certificates are not supported in IKEv2 yet.
633 .TP
634 .B lefthostaccess
635 inserts a pair of INPUT and OUTPUT iptables rules using the default
636 \fBipsec _updown\fR script, thus allowing access to the host itself
637 in the case where the host's internal interface is part of the
638 negotiated client subnet.
639 Acceptable values are
640 .B yes
641 and
642 .B no
643 (the default).
644 .TP
645 .B leftid
646 how the left participant should be identified for authentication;
647 defaults to
648 .BR left .
649 Can be an IP address or a fully-qualified domain name preceded by
650 .B @
651 (which is used as a literal string and not resolved).
652 .TP
653 .B leftid2
654 identity to use for a second authentication for the left participant
655 (IKEv2 only); defaults to
656 .BR leftid .
657 .TP
658 .B leftikeport
659 UDP port the left participant uses for IKE communication. Currently supported in
660 IKEv2 connections only. If unspecified, port 500 is used with the port floating
661 to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port
662 different from the default additionally requires a socket implementation that
663 listens to this port.
664 .TP
665 .B leftnexthop
666 this parameter is usually not needed any more because the NETKEY IPsec stack
667 does not require explicit routing entries for the traffic to be tunneled. If
668 .B leftsourceip
669 is used with IKEv1 then
670 .B leftnexthop
671 must still be set in order for the source routes to work properly.
672 .TP
673 .B leftprotoport
674 restrict the traffic selector to a single protocol and/or port.
675 Examples:
676 .B leftprotoport=tcp/http
677 or
678 .B leftprotoport=6/80
679 or
680 .B leftprotoport=udp
681 .TP
682 .B leftrsasigkey
683 the left participant's
684 public key for RSA signature authentication,
685 in RFC 2537 format using
686 .IR ttodata (3)
687 encoding.
688 The magic value
689 .B %none
690 means the same as not specifying a value (useful to override a default).
691 The value
692 .B %cert
693 (the default)
694 means that the key is extracted from a certificate.
695 The identity used for the left participant
696 must be a specific host, not
697 .B %any
698 or another magic value.
699 .B Caution:
700 if two connection descriptions
701 specify different public keys for the same
702 .BR leftid ,
703 confusion and madness will ensue.
704 .TP
705 .B leftsendcert
706 Accepted values are
707 .B never
708 or
709 .BR no ,
710 .B always
711 or
712 .BR yes ,
713 and
714 .BR ifasked ,
715 the latter meaning that the peer must send a certificate request payload in
716 order to get a certificate in return.
717 .TP
718 .B leftsourceip
719 The internal source IP to use in a tunnel, also known as virtual IP. If the
720 value is one of the synonyms
721 .BR %modeconfig ,
722 .BR %modecfg ,
723 .BR %config ,
724 or
725 .BR %cfg ,
726 an address is requested from the peer. In IKEv2, a statically defined address
727 is also requested, since the server may change it.
728 .TP
729 .B rightsourceip
730 The internal source IP to use in a tunnel for the remote peer. If the
731 value is
732 .B %config
733 on the responder side, the initiator must propose an address which is then
734 echoed back. Also supported are address pools expressed as
735 \fInetwork\fB/\fInetmask\fR
736 or the use of an external IP address pool using %\fIpoolname\fR,
737 where \fIpoolname\fR is the name of the IP address pool used for the lookup.
738 .TP
739 .B leftsubnet
740 private subnet behind the left participant, expressed as
741 \fInetwork\fB/\fInetmask\fR;
742 if omitted, essentially assumed to be \fIleft\fB/32\fR,
743 signifying that the left end of the connection goes to the left participant
744 only. When using IKEv2, the configured subnet of the peers may differ, the
745 protocol narrows it to the greatest common subnet. Further, IKEv2 supports
746 multiple subnets separated by commas. IKEv1 only interprets the first subnet
747 of such a definition.
748 .TP
749 .B leftsubnetwithin
750 the peer can propose any subnet or single IP address that fits within the
751 range defined by
752 .BR leftsubnetwithin.
753 Not relevant for IKEv2, as subnets are narrowed.
754 .TP
755 .B leftupdown
756 what ``updown'' script to run to adjust routing and/or firewalling
757 when the status of the connection
758 changes (default
759 .BR "ipsec _updown" ).
760 May include positional parameters separated by white space
761 (although this requires enclosing the whole string in quotes);
762 including shell metacharacters is unwise.
763 See
764 .IR pluto (8)
765 for details.
766 Relevant only locally, other end need not agree on it. IKEv2 uses the updown
767 script to insert firewall rules only, since routing has been implemented
768 directly into charon.
769 .TP
770 .B lifebytes
771 the number of bytes transmitted over an IPsec SA before it expires (IKEv2
772 only).
773 .TP
774 .B lifepackets
775 the number of packets transmitted over an IPsec SA before it expires (IKEv2
776 only).
777 .TP
778 .B lifetime
779 how long a particular instance of a connection
780 (a set of encryption/authentication keys for user packets) should last,
781 from successful negotiation to expiry;
782 acceptable values are an integer optionally followed by
783 .BR s
784 (a time in seconds)
785 or a decimal number followed by
786 .BR m ,
787 .BR h ,
788 or
789 .B d
790 (a time
791 in minutes, hours, or days respectively)
792 (default
793 .BR 1h ,
794 maximum
795 .BR 24h ).
796 Normally, the connection is renegotiated (via the keying channel)
797 before it expires (see
798 .BR margintime ).
799 The two ends need not exactly agree on
800 .BR lifetime ,
801 although if they do not,
802 there will be some clutter of superseded connections on the end
803 which thinks the lifetime is longer.
804 .TP
805 .B marginbytes
806 how many bytes before IPsec SA expiry (see
807 .BR lifebytes )
808 should attempts to negotiate a replacement begin (IKEv2 only).
809 .TP
810 .B marginpackets
811 how many packets before IPsec SA expiry (see
812 .BR lifepackets )
813 should attempts to negotiate a replacement begin (IKEv2 only).
814 .TP
815 .B margintime
816 how long before connection expiry or keying-channel expiry
817 should attempts to
818 negotiate a replacement
819 begin; acceptable values as for
820 .B lifetime
821 (default
822 .BR 9m ).
823 Relevant only locally, other end need not agree on it.
824 .TP
825 .B mark
826 sets an XFRM mark of the form <value>[/<mask>] in the inbound and outbound
827 IPsec SAs and policies (IKEv2 only). If the mask is missing then a default
828 mask of
829 .B 0xffffffff
830 is assumed.
831 .TP
832 .B mark_in
833 sets an XFRM mark of the form <value>[/<mask>] in the inbound IPsec SA and policy
834 (IKEv2 only). If the mask is missing then a default mask of
835 .B 0xffffffff
836 is assumed.
837 .TP
838 .B mark_out
839 sets an XFRM mark of the form <value>[/<mask>] in the outbound IPsec SA and policy
840 (IKEv2 only). If the mask is missing then a default mask of
841 .B 0xffffffff
842 is assumed.
843 .TP
844 .B mobike
845 enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are
846 .B yes
847 (the default) and
848 .BR no .
849 If set to
850 .BR no ,
851 the IKEv2 charon daemon will not actively propose MOBIKE as initiator and
852 ignore the MOBIKE_SUPPORTED notify as responder.
853 .TP
854 .B modeconfig
855 defines which mode is used to assign a virtual IP.
856 Accepted values are
857 .B push
858 and
859 .B pull
860 (the default).
861 Currently relevant for IKEv1 only since IKEv2 always uses the configuration
862 payload in pull mode. Cisco VPN gateways usually operate in
863 .B push
864 mode.
865 .TP
866 .B pfs
867 whether Perfect Forward Secrecy of keys is desired on the connection's
868 keying channel
869 (with PFS, penetration of the key-exchange protocol
870 does not compromise keys negotiated earlier);
871 acceptable values are
872 .B yes
873 (the default)
874 and
875 .BR no.
876 IKEv2 always uses PFS for IKE_SA rekeying whereas for CHILD_SA rekeying
877 PFS is enforced by defining a Diffie-Hellman modp group in the
878 .B esp
879 parameter.
880 .TP
881 .B pfsgroup
882 defines a Diffie-Hellman group for perfect forward secrecy in IKEv1 Quick Mode
883 differing from the DH group used for IKEv1 Main Mode (IKEv1 only).
884 .TP
885 .B reauth
886 whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
887 reauthentication is always done. In IKEv2, a value of
888 .B no
889 rekeys without uninstalling the IPsec SAs, a value of
890 .B yes
891 (the default) creates a new IKE_SA from scratch and tries to recreate
892 all IPsec SAs.
893 .TP
894 .B rekey
895 whether a connection should be renegotiated when it is about to expire;
896 acceptable values are
897 .B yes
898 (the default)
899 and
900 .BR no .
901 The two ends need not agree, but while a value of
902 .B no
903 prevents pluto/charon from requesting renegotiation,
904 it does not prevent responding to renegotiation requested from the other end,
905 so
906 .B no
907 will be largely ineffective unless both ends agree on it.
908 .TP
909 .B rekeyfuzz
910 maximum percentage by which
911 .BR marginbytes ,
912 .B marginpackets
913 and
914 .B margintime
915 should be randomly increased to randomize rekeying intervals
916 (important for hosts with many connections);
917 acceptable values are an integer,
918 which may exceed 100,
919 followed by a `%'
920 (defaults to
921 .BR 100% ).
922 The value of
923 .BR marginTYPE ,
924 after this random increase,
925 must not exceed
926 .B lifeTYPE
927 (where TYPE is one of
928 .IR bytes ,
929 .I packets
930 or
931 .IR time ).
932 The value
933 .B 0%
934 will suppress randomization.
935 Relevant only locally, other end need not agree on it.
936 .TP
937 .B rekeymargin
938 synonym for
939 .BR margintime .
940 .TP
941 .B reqid
942 sets the reqid for a given connection to a pre-configured fixed value (IKEv2 only).
943 .TP
944 .B type
945 the type of the connection; currently the accepted values
946 are
947 .B tunnel
948 (the default)
949 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
950 .BR transport ,
951 signifying host-to-host transport mode;
952 .BR transport_proxy ,
953 signifying the special Mobile IPv6 transport proxy mode;
954 .BR passthrough ,
955 signifying that no IPsec processing should be done at all;
956 .BR drop ,
957 signifying that packets should be discarded; and
958 .BR reject ,
959 signifying that packets should be discarded and a diagnostic ICMP returned.
960 The IKEv2 daemon charon currently supports
961 .BR tunnel ,
962 .BR transport ,
963 and
964 .BR tunnel_proxy
965 connection types, only.
966 .TP
967 .B xauth
968 specifies the role in the XAUTH protocol if activated by
969 .B authby=xauthpsk
970 or
971 .B authby=xauthrsasig.
972 Accepted values are
973 .B server
974 and
975 .B client
976 (the default).
979 The following parameters are relevant to IKEv2 Mediation Extension
980 operation only.
981 .TP 14
982 .B mediation
983 whether this connection is a mediation connection, ie. whether this
984 connection is used to mediate other connections.  Mediation connections
985 create no child SA. Acceptable values are
986 .B no
987 (the default) and
988 .BR yes .
989 .TP
990 .B mediated_by
991 the name of the connection to mediate this connection through.  If given,
992 the connection will be mediated through the named mediation connection.
993 The mediation connection must set
994 .BR mediation=yes .
995 .TP
996 .B me_peerid
997 ID as which the peer is known to the mediation server, ie. which the other
998 end of this connection uses as its
999 .B leftid
1000 on its connection to the mediation server.  This is the ID we request the
1001 mediation server to mediate us with.  If
1002 .B me_peerid
1003 is not given, the
1004 .B rightid
1005 of this connection will be used as peer ID.
1008 This are optional sections that can be used to assign special
1009 parameters to a Certification Authority (CA).
1010 .TP 10
1011 .B auto
1012 currently can have either the value
1013 .B ignore
1014 or
1015 .B add
1016 .
1017 .TP
1018 .B cacert
1019 defines a path to the CA certificate either relative to
1020 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
1021 .TP
1022 .B crluri
1023 defines a CRL distribution point (ldap, http, or file URI)
1024 .TP
1025 .B crluri1
1026 synonym for
1027 .B crluri.
1028 .TP
1029 .B crluri2
1030 defines an alternative CRL distribution point (ldap, http, or file URI)
1031 .TP
1032 .B ldaphost
1033 defines an ldap host. Currently used by IKEv1 only.
1034 .TP
1035 .B ocspuri
1036 defines an OCSP URI.
1037 .TP
1038 .B ocspuri1
1039 synonym for
1040 .B ocspuri.
1041 .TP
1042 .B ocspuri2
1043 defines an alternative OCSP URI. Currently used by IKEv2 only.
1044 .TP
1045 .B certuribase
1046 defines the base URI for the Hash and URL feature supported by IKEv2.
1047 Instead of exchanging complete certificates, IKEv2 allows to send an URI
1048 that resolves to the DER encoded certificate. The certificate URIs are built
1049 by appending the SHA1 hash of the DER encoded certificates to this base URI.
1051 At present, the only
1052 .B config
1053 section known to the IPsec software is the one named
1054 .BR setup ,
1055 which contains information used when the software is being started.
1056 Here's an example:
1057 .PP
1058 .ne 8
1059 .nf
1060 .ft B
1061 .ta 1c
1062 config setup
1063         plutodebug=all
1064         crlcheckinterval=10m
1065         strictcrlpolicy=yes
1066 .ft
1067 .fi
1068 .PP
1069 Parameters are optional unless marked ``(required)''.
1070 The currently-accepted
1071 .I parameter
1072 names in a
1073 .B config
1074 .B setup
1075 section affecting both daemons are:
1076 .TP 14
1077 .B cachecrls
1078 certificate revocation lists (CRLs) fetched via http or ldap will be cached in
1079 \fI/etc/ipsec.d/crls/\fR under a unique file name derived from the certification
1080 authority's public key.
1081 Accepted values are
1082 .B yes
1083 and
1084 .B no
1085 (the default).
1086 .TP
1087 .B charonstart
1088 whether to start the IKEv2 Charon daemon or not.
1089 Accepted values are
1090 .B yes
1091 or
1092 .BR no .
1093 The default is
1094 .B yes
1095 if starter was compiled with IKEv2 support.
1096 .TP
1097 .B dumpdir
1098 in what directory should things started by \fBipsec starter\fR
1099 (notably the Pluto and Charon daemons) be allowed to dump core?
1100 The empty value (the default) means they are not
1101 allowed to.
1102 This feature is currently not yet supported by \fBipsec starter\fR.
1103 .TP
1104 .B plutostart
1105 whether to start the IKEv1 Pluto daemon or not.
1106 Accepted values are
1107 .B yes
1108 or
1109 .BR no .
1110 The default is
1111 .B yes
1112 if starter was compiled with IKEv1 support.
1113 .TP
1114 .B strictcrlpolicy
1115 defines if a fresh CRL must be available in order for the peer authentication based
1116 on RSA signatures to succeed.
1117 Accepted values are
1118 .B yes
1119 and
1120 .B no
1121 (the default).
1122 IKEv2 additionally recognizes
1123 .B ifuri
1124 which reverts to
1125 .B yes
1126 if at least one CRL URI is defined and to
1127 .B no
1128 if no URI is known.
1129 .TP
1130 .B uniqueids
1131 whether a particular participant ID should be kept unique,
1132 with any new (automatically keyed)
1133 connection using an ID from a different IP address
1134 deemed to replace all old ones using that ID;
1135 acceptable values are
1136 .B yes
1137 (the default)
1138 and
1139 .BR no .
1140 Participant IDs normally \fIare\fR unique,
1141 so a new (automatically-keyed) connection using the same ID is
1142 almost invariably intended to replace an old one.
1143 The IKEv2 daemon also accepts the value
1144 .B replace
1145 wich is identical to
1146 .B yes
1147 and the value
1148 .B keep
1149 to reject new IKE_SA setups and keep the duplicate established earlier.
1150 .PP
1151 The following
1152 .B config section
1153 parameters are used by the IKEv1 Pluto daemon only:
1154 .TP
1155 .B crlcheckinterval
1156 interval in seconds. CRL fetching is enabled if the value is greater than zero.
1157 Asynchronous, periodic checking for fresh CRLs is currently done by the
1158 IKEv1 Pluto daemon only.
1159 .TP
1160 .B keep_alive
1161 interval in seconds between NAT keep alive packets, the default being 20 seconds.
1162 .TP
1163 .B nat_traversal
1164 activates NAT traversal by accepting source ISAKMP ports different from udp/500 and
1165 being able of floating to udp/4500 if a NAT situation is detected.
1166 Accepted values are
1167 .B yes
1168 and
1169 .B no
1170 (the default).
1171 Used by IKEv1 only, NAT traversal always being active in IKEv2.
1172 .TP
1173 .B nocrsend
1174 no certificate request payloads will be sent.
1175 Accepted values are
1176 .B yes
1177 and
1178 .B no
1179 (the default).
1180 .TP
1181 .B pkcs11initargs
1182 non-standard argument string for PKCS#11 C_Initialize() function;
1183 required by NSS softoken.
1184 .TP
1185 .B pkcs11module
1186 defines the path to a dynamically loadable PKCS #11 library.
1187 .TP
1188 .B pkcs11keepstate
1189 PKCS #11 login sessions will be kept during the whole lifetime of the keying
1190 daemon. Useful with pin-pad smart card readers.
1191 Accepted values are
1192 .B yes
1193 and
1194 .B no
1195 (the default).
1196 .TP
1197 .B pkcs11proxy
1198 Pluto will act as a PKCS #11 proxy accessible via the whack interface.
1199 Accepted values are
1200 .B yes
1201 and
1202 .B no
1203 (the default).
1204 .TP
1205 .B plutodebug
1206 how much Pluto debugging output should be logged.
1207 An empty value,
1208 or the magic value
1209 .BR none ,
1210 means no debugging output (the default).
1211 The magic value
1212 .B all
1213 means full output.
1214 Otherwise only the specified types of output
1215 (a quoted list, names without the
1216 .B \-\-debug\-
1217 prefix,
1218 separated by white space) are enabled;
1219 for details on available debugging types, see
1220 .IR pluto (8).
1221 .TP
1222 .B plutostderrlog
1223 Pluto will not use syslog, but rather log to stderr, and redirect stderr
1224 to the argument file.
1225 .TP
1226 .B postpluto
1227 shell command to run after starting Pluto
1228 (e.g., to remove a decrypted copy of the
1229 .I ipsec.secrets
1230 file).
1231 It's run in a very simple way;
1232 complexities like I/O redirection are best hidden within a script.
1233 Any output is redirected for logging,
1234 so running interactive commands is difficult unless they use
1235 .I /dev/tty
1236 or equivalent for their interaction.
1237 Default is none.
1238 .TP
1239 .B prepluto
1240 shell command to run before starting Pluto
1241 (e.g., to decrypt an encrypted copy of the
1242 .I ipsec.secrets
1243 file).
1244 It's run in a very simple way;
1245 complexities like I/O redirection are best hidden within a script.
1246 Any output is redirected for logging,
1247 so running interactive commands is difficult unless they use
1248 .I /dev/tty
1249 or equivalent for their interaction.
1250 Default is none.
1251 .TP
1252 .B virtual_private
1253 defines private networks using a wildcard notation.
1254 .PP
1255 The following
1256 .B config section
1257 parameters are used by the IKEv2 Charon daemon only:
1258 .TP
1259 .B charondebug
1260 how much Charon debugging output should be logged.
1261 A comma separated list containing type level/pairs may
1262 be specified, e.g:
1263 .B dmn 3, ike 1, net -1.
1264 Acceptable values for types are
1265 .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib
1266 and the level is one of
1267 .B -1, 0, 1, 2, 3, 4
1268 (for silent, audit, control, controlmore, raw, private).
1269 .PP
1270 The following
1271 .B config section
1272 parameters only make sense if the KLIPS IPsec stack
1273 is used instead of the default NETKEY stack of the Linux 2.6 kernel:
1274 .TP
1275 .B fragicmp
1276 whether a tunnel's need to fragment a packet should be reported
1277 back with an ICMP message,
1278 in an attempt to make the sender lower his PMTU estimate;
1279 acceptable values are
1280 .B yes
1281 (the default)
1282 and
1283 .BR no .
1284 .TP
1285 .B hidetos
1286 whether a tunnel packet's TOS field should be set to
1287 .B 0
1288 rather than copied from the user packet inside;
1289 acceptable values are
1290 .B yes
1291 (the default)
1292 and
1293 .BR no
1294 .TP
1295 .B interfaces
1296 virtual and physical interfaces for IPsec to use:
1297 a single
1298 \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated
1299 by white space, or
1300 .BR %none .
1301 One of the pairs may be written as
1302 .BR %defaultroute ,
1303 which means: find the interface \fId\fR that the default route points to,
1304 and then act as if the value was ``\fBipsec0=\fId\fR''.
1305 .B %defaultroute
1306 is the default;
1307 .B %none
1308 must be used to denote no interfaces.
1309 .TP
1310 .B overridemtu
1311 value that the MTU of the ipsec\fIn\fR interface(s) should be set to,
1312 overriding IPsec's (large) default.
1313 .SH FILES
1314 .nf
1315 /etc/ipsec.conf
1316 /etc/ipsec.d/aacerts
1317 /etc/ipsec.d/acerts
1318 /etc/ipsec.d/cacerts
1319 /etc/ipsec.d/certs
1320 /etc/ipsec.d/crls
1323 ipsec(8), pluto(8), starter(8)
1325 Originally written for the FreeS/WAN project by Henry Spencer.
1326 Updated and extended for the strongSwan project <> by
1327 Tobias Brunner, Andreas Steffen and Martin Willi.
1328 .SH BUGS
1329 .PP
1330 If conns are to be added before DNS is available, \fBleft=\fP\fIFQDN\fP
1331 will fail.