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