f0363803be9237469b28d686477e7f89940bd8d6
[strongswan.git] / src / starter / ipsec.conf.5
1 .TH IPSEC.CONF 5 "20 Jan 2006"
2 .\" RCSID $Id: ipsec.conf.5,v 1.2 2006/01/22 15:33:46 as Exp $
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 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=10.11.11.1
162         leftsubnet=10.0.1.0/24
163         leftnexthop=172.16.55.66
164         right=192.168.22.1
165         rightsubnet=10.0.2.0/24
166         rightnexthop=172.16.88.99
167         keyingtries=%forever
168 .ft
169 .fi
170 .PP
171 A note on terminology: There are two kinds of communications going on:
172 transmission of user IP packets, and gateway-to-gateway negotiations for
173 keying, rekeying, and general control.
174 The path to control the connection is called 'ISAKMP SA' in IKEv1 and
175 'IKE SA' in the IKEv2 protocol. That what is beeing negotiated, the kernel
176 level data path, is called 'IPsec SA'.
177 strongSwan currently uses two separate keying daemons. Pluto handles
178 all IKEv1 connections, Charon is the new daemon supporting the IKEv2 protocol.
179 Charon does not support all keywords yet.
180 .PP
181 To avoid trivial editing of the configuration file to suit it to each system
182 involved in a connection,
183 connection specifications are written in terms of
184 .I left
185 and
186 .I right
187 participants,
188 rather than in terms of local and remote.
189 Which participant is considered
190 .I left
191 or
192 .I right
193 is arbitrary;
194 IPsec figures out which one it is being run on based on internal information.
195 This permits using identical connection specifications on both ends.
196 There are cases where there is no symmetry; a good convention is to
197 use
198 .I left
199 for the local side and
200 .I right
201 for the remote side (the first letters are a good mnemonic).
202 .PP
203 Many of the parameters relate to one participant or the other;
204 only the ones for
205 .I left
206 are listed here, but every parameter whose name begins with
207 .B left
208 has a
209 .B right
210 counterpart,
211 whose description is the same but with
212 .B left
213 and
214 .B right
215 reversed.
216 .PP
217 Parameters are optional unless marked '(required)'.
218 .SS "CONN PARAMETERS"
219 Unless otherwise noted, for a connection to work,
220 in general it is necessary for the two ends to agree exactly
221 on the values of these parameters.
222 .TP 14
223 .B type
224 the type of the connection; currently the accepted values
225 are
226 .B tunnel
227 (the default)
228 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
229 .BR transport ,
230 signifying host-to-host transport mode;
231 .BR passthrough ,
232 signifying that no IPsec processing should be done at all;
233 .BR drop ,
234 signifying that packets should be discarded; and
235 .BR reject ,
236 signifying that packets should be discarded and a diagnostic ICMP returned.
237 Charon currently supports only 
238 .BR tunnel
239 and
240 .BR transport
241 connection types.
242 .TP
243 .B left
244 (required)
245 the IP address of the left participant's public-network interface,
246 in any form accepted by
247 .IR ipsec_ttoaddr (3)
248 or one of several magic values.
249 If it is
250 .BR %defaultroute ,
251 and
252 the
253 .B config
254 .B setup
255 section's,
256 .B interfaces
257 specification contains
258 .BR %defaultroute,
259 .B left
260 will be filled in automatically with the local address
261 of the default-route interface (as determined at IPsec startup time);
262 this also overrides any value supplied for
263 .BR leftnexthop .
264 (Either
265 .B left
266 or
267 .B right
268 may be
269 .BR %defaultroute ,
270 but not both.)
271 The value
272 .B %any
273 signifies an address to be filled in (by automatic keying) during
274 negotiation.
275 .TP
276 .B leftsubnet
277 private subnet behind the left participant, expressed as
278 \fInetwork\fB/\fInetmask\fR
279 (actually, any form acceptable to
280 .IR ipsec_ttosubnet (3));
281 if omitted, essentially assumed to be \fIleft\fB/32\fR,
282 signifying that the left end of the connection goes to the left participant
283 only. When using IKEv2, the configured subnet of the peers may differ, the
284 protocol narrows it to the greates common subnet.
285 .TP
286 .B leftnexthop
287 next-hop gateway IP address for the left participant's connection
288 to the public network;
289 defaults to
290 .B %direct
291 (meaning
292 .IR right ).
293 If the value is to be overridden by the
294 .B left=%defaultroute
295 method (see above),
296 an explicit value must
297 .I not
298 be given.
299 If that method is not being used,
300 but
301 .B leftnexthop
302 is
303 .BR %defaultroute ,
304 and
305 .B interfaces=%defaultroute
306 is used in the
307 .B config
308 .B setup
309 section,
310 the next-hop gateway address of the default-route interface
311 will be used.
312 The magic value
313 .B %direct
314 signifies a value to be filled in (by automatic keying)
315 with the peer's address.
316 Relevant only locally, other end need not agree on it. Currently not supported
317 in IKEv2.
318 .TP
319 .B leftupdown
320 what ``updown'' script to run to adjust routing and/or firewalling
321 when the status of the connection
322 changes (default
323 .BR "ipsec _updown" ).
324 May include positional parameters separated by white space
325 (although this requires enclosing the whole string in quotes);
326 including shell metacharacters is unwise.
327 See
328 .IR ipsec_pluto (8)
329 for details.
330 Relevant only locally, other end need not agree on it. IKEv2 uses the updown
331 script to insert firewall rules only. Routing is not support and will be
332 implemented directly into Charon.
333 .TP
334 .B leftfirewall
335 whether the left participant is doing forwarding-firewalling
336 (including masquerading) for traffic from \fIleftsubnet\fR,
337 which should be turned off (for traffic to the other subnet)
338 once the connection is established;
339 acceptable values are
340 .B yes
341 and (the default)
342 .BR no .
343 May not be used in the same connection description with
344 .BR leftupdown .
345 Implemented as a parameter to the default
346 .I updown
347 script.
348 See notes below.
349 Relevant only locally, other end need not agree on it.
350
351 If one or both security gateways are doing forwarding firewalling
352 (possibly including masquerading),
353 and this is specified using the firewall parameters,
354 tunnels established with IPsec are exempted from it
355 so that packets can flow unchanged through the tunnels.
356 (This means that all subnets connected in this manner must have
357 distinct, non-overlapping subnet address blocks.)
358 This is done by the default
359 .I updown
360 script (see
361 .IR ipsec_pluto (8)).
362
363 In situations calling for more control,
364 it may be preferable for the user to supply his own
365 .I updown
366 script,
367 which makes the appropriate adjustments for his system.
368 .TP
369 .B auto
370 what operation, if any, should be done automatically at IPsec startup;
371 currently-accepted values are
372 .B add
373 ,
374 .B route
375 ,
376 .B start
377 and
378 .B ignore
379 .
380 .B add
381 loads a connection without starting it.
382 .B route
383 loads a connection and installs kernel traps. If traffic is detected between
384 .B leftsubnet
385 and
386 .B rightsubnet
387 , a connection is established.
388 .B start
389 loads a connection and brings it up immediatly.
390 .B ignore
391 ignores the connection. This is equal to delete a connection from the config
392 file. 
393 Relevant only locally, other end need not agree on it
394 (but in general, for an intended-to-be-permanent connection,
395 both ends should use
396 .B auto=start
397 to ensure that any reboot causes immediate renegotiation).
398 .TP
399 .B auth
400 whether authentication should be done as part of
401 ESP encryption, or separately using the AH protocol;
402 acceptable values are
403 .B esp
404 (the default) and
405 .BR ah .
406 The IKEv2 daemon currently supports only ESP.
407 .TP
408 .B authby
409 how the two security gateways should authenticate each other;
410 acceptable values are
411 .B secret
412 for shared secrets,
413 .B rsasig
414 for RSA digital signatures (the default),
415 .B secret|rsasig
416 for either, and
417 .B never
418 if negotiation is never to be attempted or accepted (useful for shunt-only conns).
419 Digital signatures are superior in every way to shared secrets. In IKEv2, the
420 two ends must not agree on this parameter, it is relevant for the own
421 authentication method only. IKEv2 additionally supports the value
422 .B eap,
423 which indicates an initiator to request EAP authentication. The EAP method to 
424 use is selected by the server (see
425 .B eap).
426 .TP
427 .B compress
428 whether IPComp compression of content is proposed on the connection
429 (link-level compression does not work on encrypted data,
430 so to be effective, compression must be done \fIbefore\fR encryption);
431 acceptable values are
432 .B yes
433 and
434 .B no
435 (the default). A value of
436 .B yes
437 causes IPsec to propose both compressed and uncompressed,
438 and prefer compressed.
439 A value of
440 .B no
441 prevents IPsec from proposing compression;
442 a proposal to compress will still be accepted.
443 IKEv2 does not support IP compression yet.
444 .TP
445 .B dpdaction
446 controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
447 R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2)
448 are periodically sent in order to check the
449 liveliness of the IPsec peer. The values
450 .B clear
451 and
452 .B hold
453 both activate DPD. If no activity is detected, all connections with a dead peer
454 are stopped and unrouted (
455 .B clear
456 ) or put in the hold state (
457 .B hold
458 ). For
459 .B IKEv1
460 , the default is
461 .B none
462 which disables the active sending of R_U_THERE notifications.
463 Nevertheless pluto will always send the DPD Vendor ID during connection set up
464 in order to signal the readiness to act passively as a responder if the peer
465 wants to use DPD. For
466 .B IKEv2, none
467 does't make sense, as all messages are used to detect dead peers. If specified,
468 it has the same meaning as the default (
469 .B clear
470 ).
471 .TP
472 .B dpddelay
473 defines the period time interval with which R_U_THERE messages/INFORMATIONAL
474 exchanges are sent to the peer. These are only sent if no other traffic is
475 received. In IKEv2, a value of 0 sends no additional INFORMATIONAL
476 messages and uses only standard messages (such as those to rekey) to detect
477 dead peers.
478 .TP
479 .B dpdtimeout
480 defines the timeout interval, after which all connections to a peer are deleted
481 in case of inactivity. This only applies to IKEv1, in IKEv2 the default
482 retransmission timeout applies, as every exchange is used to detect dead peers.
483 .TP
484 .B failureshunt
485 what to do with packets when negotiation fails.
486 The default is
487 .BR none :
488 no shunt;
489 .BR passthrough ,
490 .BR drop ,
491 and
492 .B reject
493 have the obvious meanings. Has no effect in IKEv2 yet.
494 .TP
495 .B ikelifetime
496 how long the keying channel of a connection ('ISAKMP/IKE SA')
497 should last before being renegotiated.
498 .TP
499 .B keyexchange
500 method of key exchange;
501 which protocol should be used to initialize the connection. Connections marked with
502 .B ikev1
503 are initiated with pluto, those marked with
504 .B ikev2
505 with charon. An incoming request from the remote peer is handled by the correct 
506 daemon, unaffected from the 
507 .B keyexchange
508 setting. The default value
509 .B ike
510 currently behaves exactly as
511 .B ikev1.
512 .TP
513 .B keyingtries
514 how many attempts (a whole number or \fB%forever\fP) should be made to
515 negotiate a connection, or a replacement for one, before giving up
516 (default
517 .BR %forever ).
518 The value \fB%forever\fP
519 means 'never give up'.
520 Relevant only locally, other end need not agree on it.
521 .TP
522 .B keylife
523 how long a particular instance of a connection
524 (a set of encryption/authentication keys for user packets) should last,
525 from successful negotiation to expiry;
526 acceptable values are an integer optionally followed by
527 .BR s
528 (a time in seconds)
529 or a decimal number followed by
530 .BR m ,
531 .BR h ,
532 or
533 .B d
534 (a time
535 in minutes, hours, or days respectively)
536 (default
537 .BR 1h ,
538 maximum
539 .BR 24h ).
540 Normally, the connection is renegotiated (via the keying channel)
541 before it expires.
542 The two ends need not exactly agree on
543 .BR keylife ,
544 although if they do not,
545 there will be some clutter of superseded connections on the end
546 which thinks the lifetime is longer.
547 .TP
548 .B leftca
549 the distinguished name of a certificate authority which is required to
550 lie in the trust path going from the left participant's certificate up
551 to the root certification authority. 
552 .TP
553 .B leftcert
554 the path to the left participant's X.509 certificate. The file can be coded either in
555 PEM or DER format. OpenPGP certificates are supported as well.
556 Both absolute paths or paths relative to
557 .B /etc/ipsec.d/certs
558 are accepted. By default
559 .B leftcert
560 sets 
561 .B leftid
562 to the distinguished name of the certificate's subject and
563 .B leftca
564 to the distinguished name of the certificate's issuer.
565 The left participant's ID can be overriden by specifying a
566 .B leftid
567 value which must be certified by the certificate, though.
568 .TP
569 .B leftgroups
570 a comma separated list of group names. If the
571 .B leftgroups
572 parameter is present then the peer must be a member of at least one
573 of the groups defined by the parameter. Group membership must be certified
574 by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts\fP thas has been
575 issued to the peer by a trusted Authorization Authority stored in
576 \fI/etc/ipsec.d/aacerts\fP. Attribute certificates are not supported in IKEv2 yet.
577 .TP
578 .B leftid
579 how
580 the left participant
581 should be identified for authentication;
582 defaults to
583 .BR left .
584 Can be an IP address (in any
585 .IR ipsec_ttoaddr (3)
586 syntax)
587 or a fully-qualified domain name preceded by
588 .B @
589 (which is used as a literal string and not resolved).
590 The magic value
591 .B %myid
592 stands for the current setting of \fImyid\fP.
593 This is set in \fBconfig setup\fP or by \fIipsec_whack\fP(8)), or, if not set,
594 it is the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
595 it is the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
596 .TP
597 .B leftsourceip
598 The internal source IP to use in a tunnel, also known as virtual IP. If the
599 value is
600 .B %modeconfig
601 or
602 .B %config,
603 an address is requested from the peer.
604 .TP
605 .B leftsubnetwithin
606 Not relevant for IKEv2, as subnets are narrowed.
607 .TP
608 .B pfs
609 whether Perfect Forward Secrecy of keys is desired on the connection's
610 keying channel
611 (with PFS, penetration of the key-exchange protocol
612 does not compromise keys negotiated earlier);
613 acceptable values are
614 .B yes
615 (the default)
616 and
617 .BR no
618 . IKEv2 always uses PFS for IKE_SA rekeying. PFS for rekeying IPsec SAs is
619 currently not supported.
620 .TP
621 .B rekey
622 whether a connection should be renegotiated when it is about to expire;
623 acceptable values are
624 .B yes
625 (the default)
626 and
627 .BR no .
628 The two ends need not agree,
629 but while a value of
630 .B no
631 prevents Pluto/Charon from requesting renegotiation,
632 it does not prevent responding to renegotiation requested from the other end,
633 so
634 .B no
635 will be largely ineffective unless both ends agree on it.
636 .TP
637 .B reauth
638 whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
639 reauthentication is always done. In IKEv2, a value of
640 .B no
641 rekeys without uninstalling the IPsec SAs, a value of
642 .B yes
643 (the default) creates a new IKE_SA from scratch and tries to recreate
644 all IPsec SAs.
645 .TP
646 .B rekeyfuzz
647 maximum percentage by which
648 .B rekeymargin
649 should be randomly increased to randomize rekeying intervals
650 (important for hosts with many connections);
651 acceptable values are an integer,
652 which may exceed 100,
653 followed by a `%'
654 (default set by
655 .IR ipsec_pluto (8),
656 currently
657 .BR 100% ).
658 The value of
659 .BR rekeymargin ,
660 after this random increase,
661 must not exceed
662 .BR keylife .
663 The value
664 .B 0%
665 will suppress time randomization.
666 Relevant only locally, other end need not agree on it.
667 .TP
668 .B rekeymargin
669 how long before connection expiry or keying-channel expiry
670 should attempts to
671 negotiate a replacement
672 begin; acceptable values as for
673 .B keylife
674 (default
675 .BR 9m ).
676 Relevant only locally, other end need not agree on it.
677 .TP
678 .B ike
679 IKE/ISAKMP SA encryption/authentication algorithm to be used, e.g.
680 .B aes128-sha1-modp2048
681 (encryption-integrity-dhgroup). In IKEv2, multiple algorithms and proposals
682 may be included, such as
683 .B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024.
684 .TP
685 .B esp
686 ESP encryption/authentication algorithm to be used
687 for the connection, e.g.
688 .B 3des-md5
689 (encryption-integrity-[dh-group]). If dh-group is specified, CHILD_SA setup
690 and rekeying include a separate diffe hellman exchange (IKEv2 only).
691 .TP
692 .B ah
693 AH authentication algorithm to be used
694 for the connection, e.g.
695 .B hmac-md5.
696 .SH "CA SECTIONS"
697 This are optional sections that can be used to assign special
698 parameters to a Certification Authority (CA). These parameters are not 
699 supported in IKEv2 yet.
700 .TP 10
701 .B auto
702 currently can have either the value
703 .B ignore
704 or
705 .B add
706
707 .TP
708 .B cacert
709 defines a path to the CA certificate either relative to 
710 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
711 .TP
712 .B crluri
713 defines a CRL distribution point (ldap, http, or file URI)
714 .TP
715 .B crluri2
716 defines an alternative CRL distribution point (ldap, http, or file URI)
717 .TP
718 .B ldaphost
719 defines an ldap host.
720 .TP
721 .B ocspuri
722 defines an OCSP URI.
723 .SH "CONFIG SECTIONS"
724 At present, the only
725 .B config
726 section known to the IPsec software is the one named
727 .BR setup ,
728 which contains information used when the software is being started
729 (see
730 .IR ipsec_setup (8)).
731 Here's an example:
732 .PP
733 .ne 8
734 .nf
735 .ft B
736 .ta 1c
737 config setup
738         interfaces="ipsec0=eth1 ipsec1=ppp0"
739         klipsdebug=none
740         plutodebug=all
741         manualstart=
742 .ft
743 .fi
744 .PP
745 Parameters are optional unless marked ``(required)''.
746 The currently-accepted
747 .I parameter
748 names in a
749 .B config
750 .B setup
751 section are:
752 .TP 14
753 .B myid
754 the identity to be used for
755 .BR %myid .
756 .B %myid
757 is used in the implicit policy group conns and can be used as
758 an identity in explicit conns.
759 If unspecified,
760 .B %myid
761 is set to the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
762 the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
763 An explicit value generally starts with ``\fB@\fP''.
764 .TP
765 .B interfaces
766 virtual and physical interfaces for IPsec to use:
767 a single
768 \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated
769 by white space, or
770 .BR %none .
771 One of the pairs may be written as
772 .BR %defaultroute ,
773 which means: find the interface \fId\fR that the default route points to,
774 and then act as if the value was ``\fBipsec0=\fId\fR''.
775 .B %defaultroute
776 is the default;
777 .B %none
778 must be used to denote no interfaces.
779 If
780 .B %defaultroute
781 is used (implicitly or explicitly)
782 information about the default route and its interface is noted for
783 use by
784 .IR ipsec_manual (8)
785 and
786 .IR ipsec_auto (8).)
787 .TP
788 .B forwardcontrol
789 whether
790 .I setup
791 should turn IP forwarding on
792 (if it's not already on) as IPsec is started,
793 and turn it off again (if it was off) as IPsec is stopped;
794 acceptable values are
795 .B yes
796 and (the default)
797 .BR no .
798 For this to have full effect, forwarding must be
799 disabled before the hardware interfaces are brought
800 up (e.g.,
801 .B "net.ipv4.ip_forward\ =\ 0"
802 in Red Hat 6.x
803 .IR /etc/sysctl.conf ),
804 because IPsec doesn't get control early enough to do that.
805 .TP
806 .B rp_filter
807 whether and how
808 .I setup
809 should adjust the reverse path filtering mechanism for the
810 physical devices to be used.
811 Values are \fB%unchanged\fP (to leave it alone)
812 or \fB0\fP, \fB1\fP, \fB2\fP (values to set it to).
813 \fI/proc/sys/net/ipv4/conf/PHYS/rp_filter\fP
814 is badly documented; it must be \fB0\fP in many cases
815 for ipsec to function.
816 The default value for the parameter is \fB0\fP.
817 .TP
818 .B syslog
819 the
820 .IR syslog (2)
821 ``facility'' name and priority to use for
822 startup/shutdown log messages,
823 default
824 .BR daemon.error .
825 .TP
826 .B plutodebug
827 how much Pluto debugging output should be logged.
828 An empty value,
829 or the magic value
830 .BR none ,
831 means no debugging output (the default).
832 The magic value
833 .B all
834 means full output.
835 Otherwise only the specified types of output
836 (a quoted list, names without the
837 .B \-\-debug\-
838 prefix,
839 separated by white space) are enabled;
840 for details on available debugging types, see
841 .IR ipsec_pluto (8).
842 .TP
843 .B charondebug
844 how much Charon debugging output should be logged.
845 A comma separated list containing type level/pairs may
846 be specified, e.g:
847 .B dmn 3, ike 1, net -1.
848 Acceptable values for types are
849 .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib
850 and the level is one of
851 .B -1, 0, 1, 2, 3, 4
852 (for silent, audit, control, controlmore, raw, private)
853 .TP
854 .B plutoopts
855 additional options to pass to pluto upon startup. See
856 .IR ipsec_pluto (8).
857 .TP
858 .B plutostderrlog
859 do not use syslog, but rather log to stderr, and direct stderr to the
860 argument file.
861 .TP
862 .B dumpdir
863 in what directory should things started by
864 .I setup
865 (notably the Pluto daemon) be allowed to
866 dump core?
867 The empty value (the default) means they are not
868 allowed to.
869 .TP
870 .B pluto
871 whether to start Pluto or not;
872 Values are
873 .B yes
874 (the default)
875 or
876 .B no
877 (useful only in special circumstances).
878 .TP
879 .B plutowait
880 should Pluto wait for each
881 negotiation attempt that is part of startup to
882 finish before proceeding with the next?
883 Values are
884 .B yes
885 or
886 .BR no
887 (the default).
888 .TP
889 .B prepluto
890 shell command to run before starting Pluto
891 (e.g., to decrypt an encrypted copy of the
892 .I ipsec.secrets
893 file).
894 It's run in a very simple way;
895 complexities like I/O redirection are best hidden within a script.
896 Any output is redirected for logging,
897 so running interactive commands is difficult unless they use
898 .I /dev/tty
899 or equivalent for their interaction.
900 Default is none.
901 .TP
902 .B postpluto
903 shell command to run after starting Pluto
904 (e.g., to remove a decrypted copy of the
905 .I ipsec.secrets
906 file).
907 It's run in a very simple way;
908 complexities like I/O redirection are best hidden within a script.
909 Any output is redirected for logging,
910 so running interactive commands is difficult unless they use
911 .I /dev/tty
912 or equivalent for their interaction.
913 Default is none.
914 .TP
915 .B fragicmp
916 whether a tunnel's need to fragment a packet should be reported
917 back with an ICMP message,
918 in an attempt to make the sender lower his PMTU estimate;
919 acceptable values are
920 .B yes
921 (the default)
922 and
923 .BR no .
924 .TP
925 .B hidetos
926 whether a tunnel packet's TOS field should be set to
927 .B 0
928 rather than copied from the user packet inside;
929 acceptable values are
930 .B yes
931 (the default)
932 and
933 .BR no .
934 .TP
935 .B uniqueids
936 whether a particular participant ID should be kept unique,
937 with any new (automatically keyed)
938 connection using an ID from a different IP address
939 deemed to replace all old ones using that ID;
940 acceptable values are
941 .B yes
942 (the default)
943 and
944 .BR no .
945 Participant IDs normally \fIare\fR unique,
946 so a new (automatically-keyed) connection using the same ID is
947 almost invariably intended to replace an old one.
948 .TP
949 .B overridemtu
950 value that the MTU of the ipsec\fIn\fR interface(s) should be set to,
951 overriding IPsec's (large) default.
952 This parameter is needed only in special situations.
953 .TP
954 .B nat_traversal
955 .TP
956 .B crlcheckinterval
957 .TP
958 .B strictcrlpolicy
959 .TP
960 .B pkcs11module
961 .TP
962 .B pkcs11keepstate
963
964 .SH CHOOSING A CONNECTION
965 .PP
966 When choosing a connection to apply to an outbound packet caught with a 
967 .BR %trap,
968 the system prefers the one with the most specific eroute that
969 includes the packet's source and destination IP addresses.
970 Source subnets are examined before destination subnets.
971 For initiating, only routed connections are considered. For responding,
972 unrouted but added connections are considered.
973 .PP
974 When choosing a connection to use to respond to a negotiation which
975 doesn't match an ordinary conn, an opportunistic connection
976 may be instantiated. Eventually, its instance will be /32 -> /32, but
977 for earlier stages of the negotiation, there will not be enough
978 information about the client subnets to complete the instantiation.
979 .SH FILES
980 .nf
981 /etc/ipsec.conf
982 /etc/ipsec.d/cacerts
983 /etc/ipsec.d/certs
984 /etc/ipsec.d/crls
985 /etc/ipsec.d/aacerts
986 /etc/ipsec.d/acerts
987
988 .SH SEE ALSO
989 ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8), ipsec_rsasigkey(8)
990 .SH HISTORY
991 Written  for  the  FreeS/WAN project
992 <http://www.freeswan.org>
993 by Henry Spencer.  Extended for the strongSwan project
994 <http://www.strongswan.org>
995 by Andreas Steffen. Updated to respect IKEv2 specific configuration
996 by Martin Willi.
997 .SH BUGS
998 .PP
999 When
1000 .B type
1001 or 
1002 .B failureshunt
1003 is set to
1004 .B drop
1005 or
1006 .BR reject,
1007 strongSwan blocks outbound packets using eroutes, but assumes inbound
1008 blocking is handled by the firewall. strongSwan offers firewall hooks 
1009 via an ``updown'' script.  However, the default 
1010 .B ipsec _updown
1011 provides no help in controlling a modern firewall.
1012 .PP
1013 Including attributes of the keying channel
1014 (authentication methods,
1015 .BR ikelifetime ,
1016 etc.)
1017 as an attribute of a connection,
1018 rather than of a participant pair, is dubious and incurs limitations.
1019 .PP
1020 .IR Ipsec_manual
1021 is not nearly as generous about the syntax of subnets,
1022 addresses, etc. as the usual strongSwan user interfaces.
1023 Four-component dotted-decimal must be used for all addresses.
1024 It
1025 .I is
1026 smart enough to translate bit-count netmasks to dotted-decimal form.
1027 .PP
1028 It would be good to have a line-continuation syntax,
1029 especially for the very long lines involved in
1030 RSA signature keys.
1031 .PP
1032 The ability to specify different identities,
1033 .BR authby ,
1034 and public keys for different automatic-keyed connections
1035 between the same participants is misleading;
1036 this doesn't work dependably because the identity of the participants
1037 is not known early enough.
1038 This is especially awkward for the ``Road Warrior'' case,
1039 where the remote IP address is specified as
1040 .BR 0.0.0.0 ,
1041 and that is considered to be the ``participant'' for such connections.
1042 .PP
1043 In principle it might be necessary to control MTU on an
1044 interface-by-interface basis,
1045 rather than with the single global override that
1046 .B overridemtu
1047 provides.
1048 .PP
1049 A number of features which \fIcould\fR be implemented in
1050 both manual and automatic keying
1051 actually are not yet implemented for manual keying.
1052 This is unlikely to be fixed any time soon.
1053 .PP
1054 If conns are to be added before DNS is available,
1055 \fBleft=\fP\fIFQDN\fP,
1056 \fBleftnextop=\fP\fIFQDN\fP,
1057 and
1058 .B leftrsasigkey=%dnsonload
1059 will fail.
1060 .IR ipsec_pluto (8)
1061 does not actually use the public key for our side of a conn but it
1062 isn't generally known at a add-time which side is ours (Road Warrior
1063 and Opportunistic conns are currently exceptions).
1064 .PP
1065 The \fBmyid\fP option does not affect explicit \fB ipsec auto \-\-add\fP or \fBipsec auto \-\-replace\fP commands for implicit conns.