added support for transport mode and (experimental!) BEET mode
[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.
422 .TP
423 .B compress
424 whether IPComp compression of content is proposed on the connection
425 (link-level compression does not work on encrypted data,
426 so to be effective, compression must be done \fIbefore\fR encryption);
427 acceptable values are
428 .B yes
429 and
430 .B no
431 (the default). A value of
432 .B yes
433 causes IPsec to propose both compressed and uncompressed,
434 and prefer compressed.
435 A value of
436 .B no
437 prevents IPsec from proposing compression;
438 a proposal to compress will still be accepted.
439 IKEv2 does not support IP compression yet.
440 .TP
441 .B dpdaction
442 controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
443 R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2)
444 are periodically sent in order to check the
445 liveliness of the IPsec peer. The values
446 .B clear
447 and
448 .B hold
449 both activate DPD. If no activity is detected, all connections with a dead peer
450 are stopped and unrouted (
451 .B clear
452 ) or put in the hold state (
453 .B hold
454 ). For
455 .B IKEv1
456 , the default is
457 .B none
458 which disables the active sending of R_U_THERE notifications.
459 Nevertheless pluto will always send the DPD Vendor ID during connection set up
460 in order to signal the readiness to act passively as a responder if the peer
461 wants to use DPD. For
462 .B IKEv2, none
463 does't make sense, as all messages are used to detect dead peers. If specified,
464 it has the same meaning as the default (
465 .B clear
466 ).
467 .TP
468 .B dpddelay
469 defines the period time interval with which R_U_THERE messages/INFORMATIONAL
470 exchanges are sent to the peer. These are only sent if no other traffic is
471 received. In IKEv2, a value of 0 sends no additional INFORMATIONAL
472 messages and uses only standard messages (such as those to rekey) to detect
473 dead peers.
474 .TP
475 .B dpdtimeout
476 defines the timeout interval, after which all connections to a peer are deleted
477 in case of inactivity. This only applies to IKEv1, in IKEv2 the default
478 retransmission timeout applies, as every exchange is used to detect dead peers.
479 .TP
480 .B failureshunt
481 what to do with packets when negotiation fails.
482 The default is
483 .BR none :
484 no shunt;
485 .BR passthrough ,
486 .BR drop ,
487 and
488 .B reject
489 have the obvious meanings. Has no effect in IKEv2 yet.
490 .TP
491 .B ikelifetime
492 how long the keying channel of a connection ('ISAKMP/IKE SA')
493 should last before being renegotiated.
494 .TP
495 .B keyexchange
496 method of key exchange;
497 which protocol should be used to initialize the connection. Connections marked with
498 .B ikev1
499 are initiated with pluto, those marked with
500 .B ikev2
501 with charon. An incoming request from the remote peer is handled by the correct 
502 daemon, unaffected from the 
503 .B keyexchange
504 setting. The default value
505 .B ike
506 currently behaves exactly as
507 .B ikev1.
508 .TP
509 .B keyingtries
510 how many attempts (a whole number or \fB%forever\fP) should be made to
511 negotiate a connection, or a replacement for one, before giving up
512 (default
513 .BR %forever ).
514 The value \fB%forever\fP
515 means 'never give up'.
516 Relevant only locally, other end need not agree on it.
517 .TP
518 .B keylife
519 how long a particular instance of a connection
520 (a set of encryption/authentication keys for user packets) should last,
521 from successful negotiation to expiry;
522 acceptable values are an integer optionally followed by
523 .BR s
524 (a time in seconds)
525 or a decimal number followed by
526 .BR m ,
527 .BR h ,
528 or
529 .B d
530 (a time
531 in minutes, hours, or days respectively)
532 (default
533 .BR 1h ,
534 maximum
535 .BR 24h ).
536 Normally, the connection is renegotiated (via the keying channel)
537 before it expires.
538 The two ends need not exactly agree on
539 .BR keylife ,
540 although if they do not,
541 there will be some clutter of superseded connections on the end
542 which thinks the lifetime is longer.
543 .TP
544 .B leftca
545 the distinguished name of a certificate authority which is required to
546 lie in the trust path going from the left participant's certificate up
547 to the root certification authority. 
548 .TP
549 .B leftcert
550 the path to the left participant's X.509 certificate. The file can be coded either in
551 PEM or DER format. OpenPGP certificates are supported as well.
552 Both absolute paths or paths relative to
553 .B /etc/ipsec.d/certs
554 are accepted. By default
555 .B leftcert
556 sets 
557 .B leftid
558 to the distinguished name of the certificate's subject and
559 .B leftca
560 to the distinguished name of the certificate's issuer.
561 The left participant's ID can be overriden by specifying a
562 .B leftid
563 value which must be certified by the certificate, though.
564 .TP
565 .B leftgroups
566 a comma separated list of group names. If the
567 .B leftgroups
568 parameter is present then the peer must be a member of at least one
569 of the groups defined by the parameter. Group membership must be certified
570 by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts\fP thas has been
571 issued to the peer by a trusted Authorization Authority stored in
572 \fI/etc/ipsec.d/aacerts\fP. Attribute certificates are not supported in IKEv2 yet.
573 .TP
574 .B leftid
575 how
576 the left participant
577 should be identified for authentication;
578 defaults to
579 .BR left .
580 Can be an IP address (in any
581 .IR ipsec_ttoaddr (3)
582 syntax)
583 or a fully-qualified domain name preceded by
584 .B @
585 (which is used as a literal string and not resolved).
586 The magic value
587 .B %myid
588 stands for the current setting of \fImyid\fP.
589 This is set in \fBconfig setup\fP or by \fIipsec_whack\fP(8)), or, if not set,
590 it is the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
591 it is the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
592 .TP
593 .B leftsourceip
594 Not supported in IKEv2 yet.
595 .TP
596 .B leftsubnetwithin
597 Not relevant for IKEv2, as subnets are narrowed.
598 .TP
599 .B pfs
600 whether Perfect Forward Secrecy of keys is desired on the connection's
601 keying channel
602 (with PFS, penetration of the key-exchange protocol
603 does not compromise keys negotiated earlier);
604 acceptable values are
605 .B yes
606 (the default)
607 and
608 .BR no
609 . IKEv2 always uses PFS for IKE_SA rekeying. PFS for rekeying IPsec SAs is
610 currently not supported.
611 .TP
612 .B rekey
613 whether a connection should be renegotiated when it is about to expire;
614 acceptable values are
615 .B yes
616 (the default)
617 and
618 .BR no .
619 The two ends need not agree,
620 but while a value of
621 .B no
622 prevents Pluto/Charon from requesting renegotiation,
623 it does not prevent responding to renegotiation requested from the other end,
624 so
625 .B no
626 will be largely ineffective unless both ends agree on it.
627 .TP
628 .B reauth
629 whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
630 reauthentication is always done. In IKEv2, a value of
631 .B no
632 rekeys without uninstalling the IPsec SAs, a value of
633 .B yes
634 (the default) creates a new IKE_SA from scratch and tries to recreate
635 all IPsec SAs.
636 .TP
637 .B rekeyfuzz
638 maximum percentage by which
639 .B rekeymargin
640 should be randomly increased to randomize rekeying intervals
641 (important for hosts with many connections);
642 acceptable values are an integer,
643 which may exceed 100,
644 followed by a `%'
645 (default set by
646 .IR ipsec_pluto (8),
647 currently
648 .BR 100% ).
649 The value of
650 .BR rekeymargin ,
651 after this random increase,
652 must not exceed
653 .BR keylife .
654 The value
655 .B 0%
656 will suppress time randomization.
657 Relevant only locally, other end need not agree on it.
658 .TP
659 .B rekeymargin
660 how long before connection expiry or keying-channel expiry
661 should attempts to
662 negotiate a replacement
663 begin; acceptable values as for
664 .B keylife
665 (default
666 .BR 9m ).
667 Relevant only locally, other end need not agree on it.
668 .TP
669 .B ike
670 IKE/ISAKMP SA encryption/authentication algorithm to be used, e.g.
671 .B aes128-sha1-modp2048
672 (encryption-integrity-dhgroup).
673 .TP
674 .B esp
675 ESP encryption/authentication algorithm to be used
676 for the connection, e.g.
677 .B 3des-md5
678 (encryption-integrity).
679 .TP
680 .B ah
681 AH authentication algorithm to be used
682 for the connection, e.g.
683 .B hmac-md5.
684 .SH "CA SECTIONS"
685 This are optional sections that can be used to assign special
686 parameters to a Certification Authority (CA). These parameters are not 
687 supported in IKEv2 yet.
688 .TP 10
689 .B auto
690 currently can have either the value
691 .B ignore
692 or
693 .B add
694
695 .TP
696 .B cacert
697 defines a path to the CA certificate either relative to 
698 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
699 .TP
700 .B crluri
701 defines a CRL distribution point (ldap, http, or file URI)
702 .TP
703 .B crluri2
704 defines an alternative CRL distribution point (ldap, http, or file URI)
705 .TP
706 .B ldaphost
707 defines an ldap host.
708 .TP
709 .B ocspuri
710 defines an OCSP URI.
711 .SH "CONFIG SECTIONS"
712 At present, the only
713 .B config
714 section known to the IPsec software is the one named
715 .BR setup ,
716 which contains information used when the software is being started
717 (see
718 .IR ipsec_setup (8)).
719 Here's an example:
720 .PP
721 .ne 8
722 .nf
723 .ft B
724 .ta 1c
725 config setup
726         interfaces="ipsec0=eth1 ipsec1=ppp0"
727         klipsdebug=none
728         plutodebug=all
729         manualstart=
730 .ft
731 .fi
732 .PP
733 Parameters are optional unless marked ``(required)''.
734 The currently-accepted
735 .I parameter
736 names in a
737 .B config
738 .B setup
739 section are:
740 .TP 14
741 .B myid
742 the identity to be used for
743 .BR %myid .
744 .B %myid
745 is used in the implicit policy group conns and can be used as
746 an identity in explicit conns.
747 If unspecified,
748 .B %myid
749 is set to the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
750 the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
751 An explicit value generally starts with ``\fB@\fP''.
752 .TP
753 .B interfaces
754 virtual and physical interfaces for IPsec to use:
755 a single
756 \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated
757 by white space, or
758 .BR %none .
759 One of the pairs may be written as
760 .BR %defaultroute ,
761 which means: find the interface \fId\fR that the default route points to,
762 and then act as if the value was ``\fBipsec0=\fId\fR''.
763 .B %defaultroute
764 is the default;
765 .B %none
766 must be used to denote no interfaces.
767 If
768 .B %defaultroute
769 is used (implicitly or explicitly)
770 information about the default route and its interface is noted for
771 use by
772 .IR ipsec_manual (8)
773 and
774 .IR ipsec_auto (8).)
775 .TP
776 .B forwardcontrol
777 whether
778 .I setup
779 should turn IP forwarding on
780 (if it's not already on) as IPsec is started,
781 and turn it off again (if it was off) as IPsec is stopped;
782 acceptable values are
783 .B yes
784 and (the default)
785 .BR no .
786 For this to have full effect, forwarding must be
787 disabled before the hardware interfaces are brought
788 up (e.g.,
789 .B "net.ipv4.ip_forward\ =\ 0"
790 in Red Hat 6.x
791 .IR /etc/sysctl.conf ),
792 because IPsec doesn't get control early enough to do that.
793 .TP
794 .B rp_filter
795 whether and how
796 .I setup
797 should adjust the reverse path filtering mechanism for the
798 physical devices to be used.
799 Values are \fB%unchanged\fP (to leave it alone)
800 or \fB0\fP, \fB1\fP, \fB2\fP (values to set it to).
801 \fI/proc/sys/net/ipv4/conf/PHYS/rp_filter\fP
802 is badly documented; it must be \fB0\fP in many cases
803 for ipsec to function.
804 The default value for the parameter is \fB0\fP.
805 .TP
806 .B syslog
807 the
808 .IR syslog (2)
809 ``facility'' name and priority to use for
810 startup/shutdown log messages,
811 default
812 .BR daemon.error .
813 .TP
814 .B plutodebug
815 how much Pluto debugging output should be logged.
816 An empty value,
817 or the magic value
818 .BR none ,
819 means no debugging output (the default).
820 The magic value
821 .B all
822 means full output.
823 Otherwise only the specified types of output
824 (a quoted list, names without the
825 .B \-\-debug\-
826 prefix,
827 separated by white space) are enabled;
828 for details on available debugging types, see
829 .IR ipsec_pluto (8).
830 .TP
831 .B charondebug
832 how much Charon debugging output should be logged.
833 A comma separated list containing type level/pairs may
834 be specified, e.g:
835 .B dmn 3, ike 1, net -1.
836 Acceptable values for types are
837 .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib
838 and the level is one of
839 .B -1, 0, 1, 2, 3, 4
840 (for silent, audit, control, controlmore, raw, private)
841 .TP
842 .B plutoopts
843 additional options to pass to pluto upon startup. See
844 .IR ipsec_pluto (8).
845 .TP
846 .B plutostderrlog
847 do not use syslog, but rather log to stderr, and direct stderr to the
848 argument file.
849 .TP
850 .B dumpdir
851 in what directory should things started by
852 .I setup
853 (notably the Pluto daemon) be allowed to
854 dump core?
855 The empty value (the default) means they are not
856 allowed to.
857 .TP
858 .B pluto
859 whether to start Pluto or not;
860 Values are
861 .B yes
862 (the default)
863 or
864 .B no
865 (useful only in special circumstances).
866 .TP
867 .B plutowait
868 should Pluto wait for each
869 negotiation attempt that is part of startup to
870 finish before proceeding with the next?
871 Values are
872 .B yes
873 or
874 .BR no
875 (the default).
876 .TP
877 .B prepluto
878 shell command to run before starting Pluto
879 (e.g., to decrypt an encrypted copy of the
880 .I ipsec.secrets
881 file).
882 It's run in a very simple way;
883 complexities like I/O redirection are best hidden within a script.
884 Any output is redirected for logging,
885 so running interactive commands is difficult unless they use
886 .I /dev/tty
887 or equivalent for their interaction.
888 Default is none.
889 .TP
890 .B postpluto
891 shell command to run after starting Pluto
892 (e.g., to remove a decrypted copy of the
893 .I ipsec.secrets
894 file).
895 It's run in a very simple way;
896 complexities like I/O redirection are best hidden within a script.
897 Any output is redirected for logging,
898 so running interactive commands is difficult unless they use
899 .I /dev/tty
900 or equivalent for their interaction.
901 Default is none.
902 .TP
903 .B fragicmp
904 whether a tunnel's need to fragment a packet should be reported
905 back with an ICMP message,
906 in an attempt to make the sender lower his PMTU estimate;
907 acceptable values are
908 .B yes
909 (the default)
910 and
911 .BR no .
912 .TP
913 .B hidetos
914 whether a tunnel packet's TOS field should be set to
915 .B 0
916 rather than copied from the user packet inside;
917 acceptable values are
918 .B yes
919 (the default)
920 and
921 .BR no .
922 .TP
923 .B uniqueids
924 whether a particular participant ID should be kept unique,
925 with any new (automatically keyed)
926 connection using an ID from a different IP address
927 deemed to replace all old ones using that ID;
928 acceptable values are
929 .B yes
930 (the default)
931 and
932 .BR no .
933 Participant IDs normally \fIare\fR unique,
934 so a new (automatically-keyed) connection using the same ID is
935 almost invariably intended to replace an old one.
936 .TP
937 .B overridemtu
938 value that the MTU of the ipsec\fIn\fR interface(s) should be set to,
939 overriding IPsec's (large) default.
940 This parameter is needed only in special situations.
941 .TP
942 .B nat_traversal
943 .TP
944 .B crlcheckinterval
945 .TP
946 .B strictcrlpolicy
947 .TP
948 .B pkcs11module
949 .TP
950 .B pkcs11keepstate
951
952 .SH CHOOSING A CONNECTION
953 .PP
954 When choosing a connection to apply to an outbound packet caught with a 
955 .BR %trap,
956 the system prefers the one with the most specific eroute that
957 includes the packet's source and destination IP addresses.
958 Source subnets are examined before destination subnets.
959 For initiating, only routed connections are considered. For responding,
960 unrouted but added connections are considered.
961 .PP
962 When choosing a connection to use to respond to a negotiation which
963 doesn't match an ordinary conn, an opportunistic connection
964 may be instantiated. Eventually, its instance will be /32 -> /32, but
965 for earlier stages of the negotiation, there will not be enough
966 information about the client subnets to complete the instantiation.
967 .SH FILES
968 .nf
969 /etc/ipsec.conf
970 /etc/ipsec.d/cacerts
971 /etc/ipsec.d/certs
972 /etc/ipsec.d/crls
973 /etc/ipsec.d/aacerts
974 /etc/ipsec.d/acerts
975
976 .SH SEE ALSO
977 ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8), ipsec_rsasigkey(8)
978 .SH HISTORY
979 Written  for  the  FreeS/WAN project
980 <http://www.freeswan.org>
981 by Henry Spencer.  Extended for the strongSwan project
982 <http://www.strongswan.org>
983 by Andreas Steffen. Update to respect IKEv2 specific configuration
984 by Martin Willi.
985 .SH BUGS
986 .PP
987 When
988 .B type
989 or 
990 .B failureshunt
991 is set to
992 .B drop
993 or
994 .BR reject,
995 strongSwan blocks outbound packets using eroutes, but assumes inbound
996 blocking is handled by the firewall. strongSwan offers firewall hooks 
997 via an ``updown'' script.  However, the default 
998 .B ipsec _updown
999 provides no help in controlling a modern firewall.
1000 .PP
1001 Including attributes of the keying channel
1002 (authentication methods,
1003 .BR ikelifetime ,
1004 etc.)
1005 as an attribute of a connection,
1006 rather than of a participant pair, is dubious and incurs limitations.
1007 .PP
1008 .IR Ipsec_manual
1009 is not nearly as generous about the syntax of subnets,
1010 addresses, etc. as the usual strongSwan user interfaces.
1011 Four-component dotted-decimal must be used for all addresses.
1012 It
1013 .I is
1014 smart enough to translate bit-count netmasks to dotted-decimal form.
1015 .PP
1016 It would be good to have a line-continuation syntax,
1017 especially for the very long lines involved in
1018 RSA signature keys.
1019 .PP
1020 The ability to specify different identities,
1021 .BR authby ,
1022 and public keys for different automatic-keyed connections
1023 between the same participants is misleading;
1024 this doesn't work dependably because the identity of the participants
1025 is not known early enough.
1026 This is especially awkward for the ``Road Warrior'' case,
1027 where the remote IP address is specified as
1028 .BR 0.0.0.0 ,
1029 and that is considered to be the ``participant'' for such connections.
1030 .PP
1031 In principle it might be necessary to control MTU on an
1032 interface-by-interface basis,
1033 rather than with the single global override that
1034 .B overridemtu
1035 provides.
1036 .PP
1037 A number of features which \fIcould\fR be implemented in
1038 both manual and automatic keying
1039 actually are not yet implemented for manual keying.
1040 This is unlikely to be fixed any time soon.
1041 .PP
1042 If conns are to be added before DNS is available,
1043 \fBleft=\fP\fIFQDN\fP,
1044 \fBleftnextop=\fP\fIFQDN\fP,
1045 and
1046 .B leftrsasigkey=%dnsonload
1047 will fail.
1048 .IR ipsec_pluto (8)
1049 does not actually use the public key for our side of a conn but it
1050 isn't generally known at a add-time which side is ours (Road Warrior
1051 and Opportunistic conns are currently exceptions).
1052 .PP
1053 The \fBmyid\fP option does not affect explicit \fB ipsec auto \-\-add\fP or \fBipsec auto \-\-replace\fP commands for implicit conns.