updated man-page for left/rightsourceip
[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. In IKEv2, a defined address is requested,
604 but the server may change it. If the server does not support it, the address
605 is enforced. 
606 .TP
607 .B leftsourceip
608 The internal source IP to use in a tunnel for the remote peer. If the
609 value is
610 .B %config
611 on the responder side, the initiator must propose a address which is then echoed
612 back.
613 .TP
614 .B leftsubnetwithin
615 Not relevant for IKEv2, as subnets are narrowed.
616 .TP
617 .B pfs
618 whether Perfect Forward Secrecy of keys is desired on the connection's
619 keying channel
620 (with PFS, penetration of the key-exchange protocol
621 does not compromise keys negotiated earlier);
622 acceptable values are
623 .B yes
624 (the default)
625 and
626 .BR no
627 . IKEv2 always uses PFS for IKE_SA rekeying. PFS for rekeying IPsec SAs is
628 currently not supported.
629 .TP
630 .B rekey
631 whether a connection should be renegotiated when it is about to expire;
632 acceptable values are
633 .B yes
634 (the default)
635 and
636 .BR no .
637 The two ends need not agree,
638 but while a value of
639 .B no
640 prevents Pluto/Charon from requesting renegotiation,
641 it does not prevent responding to renegotiation requested from the other end,
642 so
643 .B no
644 will be largely ineffective unless both ends agree on it.
645 .TP
646 .B reauth
647 whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
648 reauthentication is always done. In IKEv2, a value of
649 .B no
650 rekeys without uninstalling the IPsec SAs, a value of
651 .B yes
652 (the default) creates a new IKE_SA from scratch and tries to recreate
653 all IPsec SAs.
654 .TP
655 .B rekeyfuzz
656 maximum percentage by which
657 .B rekeymargin
658 should be randomly increased to randomize rekeying intervals
659 (important for hosts with many connections);
660 acceptable values are an integer,
661 which may exceed 100,
662 followed by a `%'
663 (default set by
664 .IR ipsec_pluto (8),
665 currently
666 .BR 100% ).
667 The value of
668 .BR rekeymargin ,
669 after this random increase,
670 must not exceed
671 .BR keylife .
672 The value
673 .B 0%
674 will suppress time randomization.
675 Relevant only locally, other end need not agree on it.
676 .TP
677 .B rekeymargin
678 how long before connection expiry or keying-channel expiry
679 should attempts to
680 negotiate a replacement
681 begin; acceptable values as for
682 .B keylife
683 (default
684 .BR 9m ).
685 Relevant only locally, other end need not agree on it.
686 .TP
687 .B ike
688 IKE/ISAKMP SA encryption/authentication algorithm to be used, e.g.
689 .B aes128-sha1-modp2048
690 (encryption-integrity-dhgroup). In IKEv2, multiple algorithms and proposals
691 may be included, such as
692 .B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024.
693 .TP
694 .B esp
695 ESP encryption/authentication algorithm to be used
696 for the connection, e.g.
697 .B 3des-md5
698 (encryption-integrity-[dh-group]). If dh-group is specified, CHILD_SA setup
699 and rekeying include a separate diffe hellman exchange (IKEv2 only).
700 .TP
701 .B ah
702 AH authentication algorithm to be used
703 for the connection, e.g.
704 .B hmac-md5.
705 .SH "CA SECTIONS"
706 This are optional sections that can be used to assign special
707 parameters to a Certification Authority (CA). These parameters are not 
708 supported in IKEv2 yet.
709 .TP 10
710 .B auto
711 currently can have either the value
712 .B ignore
713 or
714 .B add
715
716 .TP
717 .B cacert
718 defines a path to the CA certificate either relative to 
719 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
720 .TP
721 .B crluri
722 defines a CRL distribution point (ldap, http, or file URI)
723 .TP
724 .B crluri2
725 defines an alternative CRL distribution point (ldap, http, or file URI)
726 .TP
727 .B ldaphost
728 defines an ldap host.
729 .TP
730 .B ocspuri
731 defines an OCSP URI.
732 .SH "CONFIG SECTIONS"
733 At present, the only
734 .B config
735 section known to the IPsec software is the one named
736 .BR setup ,
737 which contains information used when the software is being started
738 (see
739 .IR ipsec_setup (8)).
740 Here's an example:
741 .PP
742 .ne 8
743 .nf
744 .ft B
745 .ta 1c
746 config setup
747         interfaces="ipsec0=eth1 ipsec1=ppp0"
748         klipsdebug=none
749         plutodebug=all
750         manualstart=
751 .ft
752 .fi
753 .PP
754 Parameters are optional unless marked ``(required)''.
755 The currently-accepted
756 .I parameter
757 names in a
758 .B config
759 .B setup
760 section are:
761 .TP 14
762 .B myid
763 the identity to be used for
764 .BR %myid .
765 .B %myid
766 is used in the implicit policy group conns and can be used as
767 an identity in explicit conns.
768 If unspecified,
769 .B %myid
770 is set to the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
771 the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
772 An explicit value generally starts with ``\fB@\fP''.
773 .TP
774 .B interfaces
775 virtual and physical interfaces for IPsec to use:
776 a single
777 \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated
778 by white space, or
779 .BR %none .
780 One of the pairs may be written as
781 .BR %defaultroute ,
782 which means: find the interface \fId\fR that the default route points to,
783 and then act as if the value was ``\fBipsec0=\fId\fR''.
784 .B %defaultroute
785 is the default;
786 .B %none
787 must be used to denote no interfaces.
788 If
789 .B %defaultroute
790 is used (implicitly or explicitly)
791 information about the default route and its interface is noted for
792 use by
793 .IR ipsec_manual (8)
794 and
795 .IR ipsec_auto (8).)
796 .TP
797 .B forwardcontrol
798 whether
799 .I setup
800 should turn IP forwarding on
801 (if it's not already on) as IPsec is started,
802 and turn it off again (if it was off) as IPsec is stopped;
803 acceptable values are
804 .B yes
805 and (the default)
806 .BR no .
807 For this to have full effect, forwarding must be
808 disabled before the hardware interfaces are brought
809 up (e.g.,
810 .B "net.ipv4.ip_forward\ =\ 0"
811 in Red Hat 6.x
812 .IR /etc/sysctl.conf ),
813 because IPsec doesn't get control early enough to do that.
814 .TP
815 .B rp_filter
816 whether and how
817 .I setup
818 should adjust the reverse path filtering mechanism for the
819 physical devices to be used.
820 Values are \fB%unchanged\fP (to leave it alone)
821 or \fB0\fP, \fB1\fP, \fB2\fP (values to set it to).
822 \fI/proc/sys/net/ipv4/conf/PHYS/rp_filter\fP
823 is badly documented; it must be \fB0\fP in many cases
824 for ipsec to function.
825 The default value for the parameter is \fB0\fP.
826 .TP
827 .B syslog
828 the
829 .IR syslog (2)
830 ``facility'' name and priority to use for
831 startup/shutdown log messages,
832 default
833 .BR daemon.error .
834 .TP
835 .B plutodebug
836 how much Pluto debugging output should be logged.
837 An empty value,
838 or the magic value
839 .BR none ,
840 means no debugging output (the default).
841 The magic value
842 .B all
843 means full output.
844 Otherwise only the specified types of output
845 (a quoted list, names without the
846 .B \-\-debug\-
847 prefix,
848 separated by white space) are enabled;
849 for details on available debugging types, see
850 .IR ipsec_pluto (8).
851 .TP
852 .B charondebug
853 how much Charon debugging output should be logged.
854 A comma separated list containing type level/pairs may
855 be specified, e.g:
856 .B dmn 3, ike 1, net -1.
857 Acceptable values for types are
858 .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib
859 and the level is one of
860 .B -1, 0, 1, 2, 3, 4
861 (for silent, audit, control, controlmore, raw, private)
862 .TP
863 .B plutoopts
864 additional options to pass to pluto upon startup. See
865 .IR ipsec_pluto (8).
866 .TP
867 .B plutostderrlog
868 do not use syslog, but rather log to stderr, and direct stderr to the
869 argument file.
870 .TP
871 .B dumpdir
872 in what directory should things started by
873 .I setup
874 (notably the Pluto daemon) be allowed to
875 dump core?
876 The empty value (the default) means they are not
877 allowed to.
878 .TP
879 .B pluto
880 whether to start Pluto or not;
881 Values are
882 .B yes
883 (the default)
884 or
885 .B no
886 (useful only in special circumstances).
887 .TP
888 .B plutowait
889 should Pluto wait for each
890 negotiation attempt that is part of startup to
891 finish before proceeding with the next?
892 Values are
893 .B yes
894 or
895 .BR no
896 (the default).
897 .TP
898 .B prepluto
899 shell command to run before starting Pluto
900 (e.g., to decrypt an encrypted copy of the
901 .I ipsec.secrets
902 file).
903 It's run in a very simple way;
904 complexities like I/O redirection are best hidden within a script.
905 Any output is redirected for logging,
906 so running interactive commands is difficult unless they use
907 .I /dev/tty
908 or equivalent for their interaction.
909 Default is none.
910 .TP
911 .B postpluto
912 shell command to run after starting Pluto
913 (e.g., to remove a decrypted copy of the
914 .I ipsec.secrets
915 file).
916 It's run in a very simple way;
917 complexities like I/O redirection are best hidden within a script.
918 Any output is redirected for logging,
919 so running interactive commands is difficult unless they use
920 .I /dev/tty
921 or equivalent for their interaction.
922 Default is none.
923 .TP
924 .B fragicmp
925 whether a tunnel's need to fragment a packet should be reported
926 back with an ICMP message,
927 in an attempt to make the sender lower his PMTU estimate;
928 acceptable values are
929 .B yes
930 (the default)
931 and
932 .BR no .
933 .TP
934 .B hidetos
935 whether a tunnel packet's TOS field should be set to
936 .B 0
937 rather than copied from the user packet inside;
938 acceptable values are
939 .B yes
940 (the default)
941 and
942 .BR no .
943 .TP
944 .B uniqueids
945 whether a particular participant ID should be kept unique,
946 with any new (automatically keyed)
947 connection using an ID from a different IP address
948 deemed to replace all old ones using that ID;
949 acceptable values are
950 .B yes
951 (the default)
952 and
953 .BR no .
954 Participant IDs normally \fIare\fR unique,
955 so a new (automatically-keyed) connection using the same ID is
956 almost invariably intended to replace an old one.
957 .TP
958 .B overridemtu
959 value that the MTU of the ipsec\fIn\fR interface(s) should be set to,
960 overriding IPsec's (large) default.
961 This parameter is needed only in special situations.
962 .TP
963 .B nat_traversal
964 .TP
965 .B crlcheckinterval
966 .TP
967 .B strictcrlpolicy
968 .TP
969 .B pkcs11module
970 .TP
971 .B pkcs11keepstate
972
973 .SH CHOOSING A CONNECTION
974 .PP
975 When choosing a connection to apply to an outbound packet caught with a 
976 .BR %trap,
977 the system prefers the one with the most specific eroute that
978 includes the packet's source and destination IP addresses.
979 Source subnets are examined before destination subnets.
980 For initiating, only routed connections are considered. For responding,
981 unrouted but added connections are considered.
982 .PP
983 When choosing a connection to use to respond to a negotiation which
984 doesn't match an ordinary conn, an opportunistic connection
985 may be instantiated. Eventually, its instance will be /32 -> /32, but
986 for earlier stages of the negotiation, there will not be enough
987 information about the client subnets to complete the instantiation.
988 .SH FILES
989 .nf
990 /etc/ipsec.conf
991 /etc/ipsec.d/cacerts
992 /etc/ipsec.d/certs
993 /etc/ipsec.d/crls
994 /etc/ipsec.d/aacerts
995 /etc/ipsec.d/acerts
996
997 .SH SEE ALSO
998 ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8), ipsec_rsasigkey(8)
999 .SH HISTORY
1000 Written  for  the  FreeS/WAN project
1001 <http://www.freeswan.org>
1002 by Henry Spencer.  Extended for the strongSwan project
1003 <http://www.strongswan.org>
1004 by Andreas Steffen. Updated to respect IKEv2 specific configuration
1005 by Martin Willi.
1006 .SH BUGS
1007 .PP
1008 When
1009 .B type
1010 or 
1011 .B failureshunt
1012 is set to
1013 .B drop
1014 or
1015 .BR reject,
1016 strongSwan blocks outbound packets using eroutes, but assumes inbound
1017 blocking is handled by the firewall. strongSwan offers firewall hooks 
1018 via an ``updown'' script.  However, the default 
1019 .B ipsec _updown
1020 provides no help in controlling a modern firewall.
1021 .PP
1022 Including attributes of the keying channel
1023 (authentication methods,
1024 .BR ikelifetime ,
1025 etc.)
1026 as an attribute of a connection,
1027 rather than of a participant pair, is dubious and incurs limitations.
1028 .PP
1029 .IR Ipsec_manual
1030 is not nearly as generous about the syntax of subnets,
1031 addresses, etc. as the usual strongSwan user interfaces.
1032 Four-component dotted-decimal must be used for all addresses.
1033 It
1034 .I is
1035 smart enough to translate bit-count netmasks to dotted-decimal form.
1036 .PP
1037 It would be good to have a line-continuation syntax,
1038 especially for the very long lines involved in
1039 RSA signature keys.
1040 .PP
1041 The ability to specify different identities,
1042 .BR authby ,
1043 and public keys for different automatic-keyed connections
1044 between the same participants is misleading;
1045 this doesn't work dependably because the identity of the participants
1046 is not known early enough.
1047 This is especially awkward for the ``Road Warrior'' case,
1048 where the remote IP address is specified as
1049 .BR 0.0.0.0 ,
1050 and that is considered to be the ``participant'' for such connections.
1051 .PP
1052 In principle it might be necessary to control MTU on an
1053 interface-by-interface basis,
1054 rather than with the single global override that
1055 .B overridemtu
1056 provides.
1057 .PP
1058 A number of features which \fIcould\fR be implemented in
1059 both manual and automatic keying
1060 actually are not yet implemented for manual keying.
1061 This is unlikely to be fixed any time soon.
1062 .PP
1063 If conns are to be added before DNS is available,
1064 \fBleft=\fP\fIFQDN\fP,
1065 \fBleftnextop=\fP\fIFQDN\fP,
1066 and
1067 .B leftrsasigkey=%dnsonload
1068 will fail.
1069 .IR ipsec_pluto (8)
1070 does not actually use the public key for our side of a conn but it
1071 isn't generally known at a add-time which side is ours (Road Warrior
1072 and Opportunistic conns are currently exceptions).
1073 .PP
1074 The \fBmyid\fP option does not affect explicit \fB ipsec auto \-\-add\fP or \fBipsec auto \-\-replace\fP commands for implicit conns.