added charondebug config parameter to set debug level at startup
[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 .I unless
16 manual keying is being done for more than just testing,
17 in which case the encryption/authentication keys in the
18 descriptions for the manually-keyed connections are very sensitive
19 (and those connection descriptions
20 are probably best kept in a separate file,
21 via the include facility described below).
22 .PP
23 The file is a text file, consisting of one or more
24 .IR sections .
25 White space followed by
26 .B #
27 followed by anything to the end of the line
28 is a comment and is ignored,
29 as are empty lines which are not within a section.
30 .PP
31 A line which contains
32 .B include
33 and a file name, separated by white space,
34 is replaced by the contents of that file,
35 preceded and followed by empty lines.
36 If the file name is not a full pathname,
37 it is considered to be relative to the directory containing the
38 including file.
39 Such inclusions can be nested.
40 Only a single filename may be supplied, and it may not contain white space,
41 but it may include shell wildcards (see
42 .IR sh (1));
43 for example:
44 .PP
45 .B include
46 .B "ipsec.*.conf"
47 .PP
48 The intention of the include facility is mostly to permit keeping
49 information on connections, or sets of connections,
50 separate from the main configuration file.
51 This permits such connection descriptions to be changed,
52 copied to the other security gateways involved, etc.,
53 without having to constantly extract them from the configuration
54 file and then insert them back into it.
55 Note also the
56 .B also
57 parameter (described below) which permits splitting a single logical
58 section (e.g. a connection description) into several actual sections.
59 .PP
60 The first significant line of the file must specify the version
61 of this specification that it conforms to:
62 .PP
63 \fBversion 2\fP
64 .PP
65 A section
66 begins with a line of the form:
67 .PP
68 .I type
69 .I name
70 .PP
71 where
72 .I type
73 indicates what type of section follows, and
74 .I name
75 is an arbitrary name which distinguishes the section from others
76 of the same type.
77 (Names must start with a letter and may contain only
78 letters, digits, periods, underscores, and hyphens.)
79 All subsequent non-empty lines
80 which begin with white space are part of the section;
81 comments within a section must begin with white space too.
82 There may be only one section of a given type with a given name.
83 .PP
84 Lines within the section are generally of the form
85 .PP
86 \ \ \ \ \ \fIparameter\fB=\fIvalue\fR
87 .PP
88 (note the mandatory preceding white space).
89 There can be white space on either side of the
90 .BR = .
91 Parameter names follow the same syntax as section names,
92 and are specific to a section type.
93 Unless otherwise explicitly specified,
94 no parameter name may appear more than once in a section.
95 .PP
96 An empty
97 .I value
98 stands for the system default value (if any) of the parameter,
99 i.e. it is roughly equivalent to omitting the parameter line entirely.
100 A
101 .I value
102 may contain white space only if the entire
103 .I value
104 is enclosed in double quotes (\fB"\fR);
105 a
106 .I value
107 cannot itself contain a double quote,
108 nor may it be continued across more than one line.
109 .PP
110 Numeric values are specified to be either an ``integer''
111 (a sequence of digits) or a ``decimal number''
112 (sequence of digits optionally followed by `.' and another sequence of digits).
113 .PP
114 There is currently one parameter which is available in any type of
115 section:
116 .TP
117 .B also
118 the value is a section name;
119 the parameters of that section are appended to this section,
120 as if they had been written as part of it.
121 The specified section must exist, must follow the current one,
122 and must have the same section type.
123 (Nesting is permitted,
124 and there may be more than one
125 .B also
126 in a single section,
127 although it is forbidden to append the same section more than once.)
128 This allows, for example, keeping the encryption keys
129 for a connection in a separate file
130 from the rest of the description, by using both an
131 .B also
132 parameter and an
133 .B include
134 line.
135 .PP
136 Parameter names beginning with
137 .B x-
138 (or
139 .BR X- ,
140 or
141 .BR x_ ,
142 or
143 .BR X_ )
144 are reserved for user extensions and will never be assigned meanings
145 by IPsec.
146 Parameters with such names must still observe the syntax rules
147 (limits on characters used in the name;
148 no white space in a non-quoted value;
149 no newlines or double quotes within the value).
150 All other as-yet-unused parameter names are reserved for future IPsec
151 improvements.
152 .PP
153 A section with name
154 .B %default
155 specifies defaults for sections of the same type.
156 For each parameter in it,
157 any section of that type which does not have a parameter of the same name
158 gets a copy of the one from the
159 .B %default
160 section.
161 There may be multiple
162 .B %default
163 sections of a given type,
164 but only one default may be supplied for any specific parameter name,
165 and all
166 .B %default
167 sections of a given type must precede all non-\c
168 .B %default
169 sections of that type.
170 .B %default
171 sections may not contain the
172 .B also
173 parameter.
174 .PP
175 Currently there are three types of sections:
176 a
177 .B config
178 section specifies general configuration information for IPsec, a
179 .B conn
180 section specifies an IPsec connection, while a
181 .B ca
182 section specifies special properties a certification authority.
183 .SH "CONN SECTIONS"
184 A
185 .B conn
186 section contains a
187 .IR "connection specification" ,
188 defining a network connection to be made using IPsec.
189 The name given is arbitrary, and is used to identify the connection to
190 .IR ipsec_auto (8)
191 and
192 .IR ipsec_manual (8).
193 Here's a simple example:
194 .PP
195 .ne 10
196 .nf
197 .ft B
198 .ta 1c
199 conn snt
200         left=10.11.11.1
201         leftsubnet=10.0.1.0/24
202         leftnexthop=172.16.55.66
203         right=192.168.22.1
204         rightsubnet=10.0.2.0/24
205         rightnexthop=172.16.88.99
206         keyingtries=%forever
207 .ft
208 .fi
209 .PP
210 A note on terminology...
211 In automatic keying, there are two kinds of communications going on:
212 transmission of user IP packets, and gateway-to-gateway negotiations for
213 keying, rekeying, and general control.
214 The data path (a set of ``IPsec SAs'') used for user packets is herein
215 referred to as the ``connection'';
216 the path used for negotiations (built with ``ISAKMP SAs'') is referred to as
217 the ``keying channel''.
218 .PP
219 To avoid trivial editing of the configuration file to suit it to each system
220 involved in a connection,
221 connection specifications are written in terms of
222 .I left
223 and
224 .I right
225 participants,
226 rather than in terms of local and remote.
227 Which participant is considered
228 .I left
229 or
230 .I right
231 is arbitrary;
232 IPsec figures out which one it is being run on based on internal information.
233 This permits using identical connection specifications on both ends.
234 There are cases where there is no symmetry; a good convention is to
235 use
236 .I left
237 for the local side and
238 .I right
239 for the remote side (the first letters are a good mnemonic).
240 .PP
241 Many of the parameters relate to one participant or the other;
242 only the ones for
243 .I left
244 are listed here, but every parameter whose name begins with
245 .B left
246 has a
247 .B right
248 counterpart,
249 whose description is the same but with
250 .B left
251 and
252 .B right
253 reversed.
254 .PP
255 Parameters are optional unless marked ``(required)'';
256 a parameter required for manual keying need not be included for
257 a connection which will use only automatic keying, and vice versa.
258 .SS "CONN PARAMETERS:  GENERAL"
259 The following parameters are relevant to both automatic and manual keying.
260 Unless otherwise noted,
261 for a connection to work,
262 in general it is necessary for the two ends to agree exactly
263 on the values of these parameters.
264 .TP 14
265 .B type
266 the type of the connection; currently the accepted values
267 are
268 .B tunnel
269 (the default)
270 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
271 .BR transport ,
272 signifying host-to-host transport mode;
273 .BR passthrough ,
274 signifying that no IPsec processing should be done at all;
275 .BR drop ,
276 signifying that packets should be discarded; and
277 .BR reject ,
278 signifying that packets should be discarded and a diagnostic ICMP returned.
279 .TP
280 .B left
281 (required)
282 the IP address of the left participant's public-network interface,
283 in any form accepted by
284 .IR ipsec_ttoaddr (3)
285 or one of several magic values.
286 If it is
287 .BR %defaultroute ,
288 and
289 the
290 .B config
291 .B setup
292 section's,
293 .B interfaces
294 specification contains
295 .BR %defaultroute,
296 .B left
297 will be filled in automatically with the local address
298 of the default-route interface (as determined at IPsec startup time);
299 this also overrides any value supplied for
300 .BR leftnexthop .
301 (Either
302 .B left
303 or
304 .B right
305 may be
306 .BR %defaultroute ,
307 but not both.)
308 The value
309 .B %any
310 signifies an address to be filled in (by automatic keying) during
311 negotiation.
312 The value
313 .B %opportunistic
314 signifies that both
315 .B left
316 and
317 .B leftnexthop
318 are to be filled in (by automatic keying) from DNS data for
319 .BR left 's
320 client.
321 The values
322 .B %group
323 and
324 .B %opportunisticgroup
325 makes this a policy group conn: one that will be instantiated
326 into a regular or opportunistic conn for each CIDR block listed in the
327 policy group file with the same name as the conn.
328 .TP
329 .B leftsubnet
330 private subnet behind the left participant, expressed as
331 \fInetwork\fB/\fInetmask\fR
332 (actually, any form acceptable to
333 .IR ipsec_ttosubnet (3));
334 if omitted, essentially assumed to be \fIleft\fB/32\fR,
335 signifying that the left end of the connection goes to the left participant only
336 .TP
337 .B leftnexthop
338 next-hop gateway IP address for the left participant's connection
339 to the public network;
340 defaults to
341 .B %direct
342 (meaning
343 .IR right ).
344 If the value is to be overridden by the
345 .B left=%defaultroute
346 method (see above),
347 an explicit value must
348 .I not
349 be given.
350 If that method is not being used,
351 but
352 .B leftnexthop
353 is
354 .BR %defaultroute ,
355 and
356 .B interfaces=%defaultroute
357 is used in the
358 .B config
359 .B setup
360 section,
361 the next-hop gateway address of the default-route interface
362 will be used.
363 The magic value
364 .B %direct
365 signifies a value to be filled in (by automatic keying)
366 with the peer's address.
367 Relevant only locally, other end need not agree on it.
368 .TP
369 .B leftupdown
370 what ``updown'' script to run to adjust routing and/or firewalling
371 when the status of the connection
372 changes (default
373 .BR "ipsec _updown" ).
374 May include positional parameters separated by white space
375 (although this requires enclosing the whole string in quotes);
376 including shell metacharacters is unwise.
377 See
378 .IR ipsec_pluto (8)
379 for details.
380 Relevant only locally, other end need not agree on it.
381 .TP
382 .B leftfirewall
383 whether the left participant is doing forwarding-firewalling
384 (including masquerading) for traffic from \fIleftsubnet\fR,
385 which should be turned off (for traffic to the other subnet)
386 once the connection is established;
387 acceptable values are
388 .B yes
389 and (the default)
390 .BR no .
391 May not be used in the same connection description with
392 .BR leftupdown .
393 Implemented as a parameter to the default
394 .I updown
395 script.
396 See notes below.
397 Relevant only locally, other end need not agree on it.
398 .PP
399 If one or both security gateways are doing forwarding firewalling
400 (possibly including masquerading),
401 and this is specified using the firewall parameters,
402 tunnels established with IPsec are exempted from it
403 so that packets can flow unchanged through the tunnels.
404 (This means that all subnets connected in this manner must have
405 distinct, non-overlapping subnet address blocks.)
406 This is done by the default
407 .I updown
408 script (see
409 .IR ipsec_pluto (8)).
410 .PP
411 The implementation of this makes certain assumptions about firewall setup,
412 notably the use of the old
413 .I ipfwadm
414 interface to the firewall.
415 In situations calling for more control,
416 it may be preferable for the user to supply his own
417 .I updown
418 script,
419 which makes the appropriate adjustments for his system.
420 .SS "CONN PARAMETERS:  AUTOMATIC KEYING"
421 The following parameters are relevant only to automatic keying,
422 and are ignored in manual keying.
423 Unless otherwise noted,
424 for a connection to work,
425 in general it is necessary for the two ends to agree exactly
426 on the values of these parameters.
427 .TP 14
428 .B auto
429 what operation, if any, should be done automatically at IPsec startup;
430 currently-accepted values are
431 .B add
432 (signifying an
433 .B ipsec auto
434 .BR \-\-add ),
435 .B route
436 (signifying that plus an
437 .B ipsec auto
438 .BR \-\-route ),
439 .B start
440 (signifying that plus an
441 .B ipsec auto
442 .BR \-\-up ),
443 .B manual
444 (signifying an
445 .B ipsec
446 .B manual
447 .BR \-\-up ),
448 and
449 .B ignore
450 (also the default) (signifying no automatic startup operation).
451 See the
452 .B config
453 .B setup
454 discussion below.
455 Relevant only locally, other end need not agree on it
456 (but in general, for an intended-to-be-permanent connection,
457 both ends should use
458 .B auto=start
459 to ensure that any reboot causes immediate renegotiation).
460 .TP
461 .B auth
462 whether authentication should be done as part of
463 ESP encryption, or separately using the AH protocol;
464 acceptable values are
465 .B esp
466 (the default) and
467 .BR ah .
468 .TP
469 .B authby
470 how the two security gateways should authenticate each other;
471 acceptable values are
472 .B secret
473 for shared secrets,
474 .B rsasig
475 for RSA digital signatures (the default),
476 .B secret|rsasig
477 for either, and
478 .B never
479 if negotiation is never to be attempted or accepted (useful for shunt-only conns).
480 Digital signatures are superior in every way to shared secrets.
481 .TP
482 .B compress
483 whether IPComp compression of content is proposed on the connection
484 (link-level compression does not work on encrypted data,
485 so to be effective, compression must be done \fIbefore\fR encryption);
486 acceptable values are
487 .B yes
488 and
489 .B no
490 (the default).
491 The two ends need not agree.
492 A value of
493 .B yes
494 causes IPsec to propose both compressed and uncompressed,
495 and prefer compressed.
496 A value of
497 .B no
498 prevents IPsec from proposing compression;
499 a proposal to compress will still be accepted.
500 .TP
501 .B dpdaction
502 controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
503 R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2)
504 are periodically sent in order to check the
505 liveliness of the IPsec peer. The values
506 .B clear
507 and
508 .B hold
509 both activate DPD. If no activity is detected, all connections with a dead peer
510 are stopped and unrouted (
511 .B clear
512 ) or put in the hold state (
513 .B hold
514 ). For
515 .B IKEv1
516 , the default is
517 .B none
518 which disables the active sending of R_U_THERE notifications.
519 Nevertheless pluto will always send the DPD Vendor ID during connection set up
520 in order to signal the readiness to act passively as a responder if the peer
521 wants to use DPD. For
522 .B IKEv2, none
523 does't make sense, as all messages are used to detect dead peers. If specified,
524 it has the same meaning as the default (
525 .B clear
526 ).
527 .TP
528 .B dpddelay
529 defines the period time interval with which R_U_THERE messages/INFORMATIONAL
530 exchanges are sent to the peer. These are only sent if no other traffic is
531 received. In IKEv2, a value of 0 sends no additional INFORMATIONAL
532 messages and uses only standard messages (such as those to rekey) to detect
533 dead peers.
534 .TP
535 .B dpdtimeout
536 defines the timeout interval, after which all connections to a peer are deleted
537 in case of inactivity. This only applies to IKEv1, in IKEv2 the default
538 retransmission timeout applies, as every exchange is used to detect dead peers.
539 .TP
540 .B failureshunt
541 what to do with packets when negotiation fails.
542 The default is
543 .BR none :
544 no shunt;
545 .BR passthrough ,
546 .BR drop ,
547 and
548 .B reject
549 have the obvious meanings.
550 .TP
551 .B ikelifetime
552 how long the keying channel of a connection (buzzphrase:  ``ISAKMP SA'')
553 should last before being renegotiated.
554 .TP
555 .B keyexchange
556 method of key exchange;
557 which protocol should be used to initialize the connection. Connections marked with
558 .B ikev1
559 are initiated with pluto, those marked with
560 .B ikev2
561 with charon. An incoming request from the remote peer is handled by the correct 
562 daemon, unaffected from the 
563 .B keyexchange
564 setting. The default value
565 .B ike
566 currently behaves exactly as
567 .B ikev1.
568 .TP
569 .B keylife
570 (default set by
571 .IR ipsec_pluto (8),
572 currently
573 .BR 3h ,
574 maximum
575 .BR 24h ).
576 The two-ends-disagree case is similar to that of
577 .BR keylife .
578 .TP
579 .B keyingtries
580 how many attempts (a whole number or \fB%forever\fP) should be made to
581 negotiate a connection, or a replacement for one, before giving up
582 (default
583 .BR %forever ).
584 The value \fB%forever\fP
585 means ``never give up'' (obsolete: this can be written \fB0\fP).
586 Relevant only locally, other end need not agree on it.
587 .TP
588 .B keylife
589 how long a particular instance of a connection
590 (a set of encryption/authentication keys for user packets) should last,
591 from successful negotiation to expiry;
592 acceptable values are an integer optionally followed by
593 .BR s
594 (a time in seconds)
595 or a decimal number followed by
596 .BR m ,
597 .BR h ,
598 or
599 .B d
600 (a time
601 in minutes, hours, or days respectively)
602 (default
603 .BR 1h ,
604 maximum
605 .BR 24h ).
606 Normally, the connection is renegotiated (via the keying channel)
607 before it expires.
608 The two ends need not exactly agree on
609 .BR keylife ,
610 although if they do not,
611 there will be some clutter of superseded connections on the end
612 which thinks the lifetime is longer.
613 .TP
614 .B leftca
615 the distinguished name of a certificate authority which is required to
616 lie in the trust path going from the left participant's certificate up
617 to the root certification authority. 
618 .TP
619 .B leftcert
620 the path to the left participant's X.509 certificate. The file can be coded either in
621 PEM or DER format. OpenPGP certificates are supported as well.
622 Both absolute paths or paths relative to
623 .B /etc/ipsec.d/certs
624 are accepted. By default
625 .B leftcert
626 sets 
627 .B leftid
628 to the distinguished name of the certificate's subject and
629 .B leftca
630 to the distinguished name of the certificate's issuer.
631 The left participant's ID can be overriden by specifying a
632 .B leftid
633 value which must be certified by the certificate, though.
634 .TP
635 .B leftgroups
636 a comma separated list of group names. If the
637 .B leftgroups
638 parameter is present then the peer must be a member of at least one
639 of the groups defined by the parameter. Group membership must be certified
640 by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts\fP thas has been
641 issued to the peer by a trusted Authorization Authority stored in
642 \fI/etc/ipsec.d/aacerts\fP.
643 .TP
644 .B leftid
645 how
646 the left participant
647 should be identified for authentication;
648 defaults to
649 .BR left .
650 Can be an IP address (in any
651 .IR ipsec_ttoaddr (3)
652 syntax)
653 or a fully-qualified domain name preceded by
654 .B @
655 (which is used as a literal string and not resolved).
656 The magic value
657 .B %myid
658 stands for the current setting of \fImyid\fP.
659 This is set in \fBconfig setup\fP or by \fIipsec_whack\fP(8)), or, if not set,
660 it is the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
661 it is the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
662 .TP
663 .B leftrsasigkey
664 the left participant's
665 public key for RSA signature authentication,
666 in RFC 2537 format using
667 .IR ipsec_ttodata (3)
668 encoding.
669 The magic value
670 .B %none
671 means the same as not specifying a value (useful to override a default).
672 The value
673 .B %cert
674 (the default)
675 means that the key is extracted from a certificate.
676 The value
677 .B %dnsondemand
678 means the key is to be fetched from DNS at the time it is needed.
679 The value
680 .B %dnsonload
681 means the key is to be fetched from DNS at the time
682 the connection description is read from
683 .IR ipsec.conf ;
684 currently this will be treated as
685 .B %none
686 if
687 .B right=%any
688 or
689 .BR right=%opportunistic .
690 The value
691 .B %dns
692 is currently treated as
693 .B %dnsonload
694 but will change to
695 .B %dnsondemand
696 in the future.
697 The identity used for the left participant
698 must be a specific host, not
699 .B %any
700 or another magic value.
701 .B Caution:
702 if two connection descriptions
703 specify different public keys for the same
704 .BR leftid ,
705 confusion and madness will ensue.
706 .TP
707 .B leftrsasigkey2
708 if present, a second public key.
709 Either key can authenticate the signature, allowing for key rollover.
710 .TP
711 .B leftsourceip
712 .TP
713 .B leftsubnetwithin
714 .TP
715 .B pfs
716 whether Perfect Forward Secrecy of keys is desired on the connection's
717 keying channel
718 (with PFS, penetration of the key-exchange protocol
719 does not compromise keys negotiated earlier);
720 acceptable values are
721 .B yes
722 (the default)
723 and
724 .BR no .
725 .TP
726 .B rekey
727 whether a connection should be renegotiated when it is about to expire;
728 acceptable values are
729 .B yes
730 (the default)
731 and
732 .BR no .
733 The two ends need not agree,
734 but while a value of
735 .B no
736 prevents Pluto from requesting renegotiation,
737 it does not prevent responding to renegotiation requested from the other end,
738 so
739 .B no
740 will be largely ineffective unless both ends agree on it.
741 .TP
742 .B rekeyfuzz
743 maximum percentage by which
744 .B rekeymargin
745 should be randomly increased to randomize rekeying intervals
746 (important for hosts with many connections);
747 acceptable values are an integer,
748 which may exceed 100,
749 followed by a `%'
750 (default set by
751 .IR ipsec_pluto (8),
752 currently
753 .BR 100% ).
754 The value of
755 .BR rekeymargin ,
756 after this random increase,
757 must not exceed
758 .BR keylife .
759 The value
760 .B 0%
761 will suppress time randomization.
762 Relevant only locally, other end need not agree on it.
763 .TP
764 .B rekeymargin
765 how long before connection expiry or keying-channel expiry
766 should attempts to
767 negotiate a replacement
768 begin; acceptable values as for
769 .B keylife
770 (default
771 .BR 9m ).
772 Relevant only locally, other end need not agree on it.
773 .SS "CONN PARAMETERS:  MANUAL KEYING"
774 The following parameters are relevant only to manual keying,
775 and are ignored in automatic keying.
776 Unless otherwise noted,
777 for a connection to work,
778 in general it is necessary for the two ends to agree exactly
779 on the values of these parameters.
780 A manually-keyed
781 connection must specify at least one of AH or ESP.
782 .TP 14
783 .B spi
784 (this or
785 .B spibase
786 required for manual keying)
787 the SPI number to be used for the connection (see
788 .IR ipsec_manual (8));
789 must be of the form \fB0x\fIhex\fB\fR,
790 where
791 .I hex
792 is one or more hexadecimal digits
793 (note, it will generally be necessary to make
794 .I spi
795 at least
796 .B 0x100
797 to be acceptable to KLIPS,
798 and use of SPIs in the range
799 .BR 0x100 - 0xfff
800 is recommended)
801 .TP 14
802 .B spibase
803 (this or
804 .B spi
805 required for manual keying)
806 the base number for the SPIs to be used for the connection (see
807 .IR ipsec_manual (8));
808 must be of the form \fB0x\fIhex\fB0\fR,
809 where
810 .I hex
811 is one or more hexadecimal digits
812 (note, it will generally be necessary to make
813 .I spibase
814 at least
815 .B 0x100
816 for the resulting SPIs
817 to be acceptable to KLIPS,
818 and use of numbers in the range
819 .BR 0x100 - 0xff0
820 is recommended)
821 .TP
822 .B esp
823 ESP encryption/authentication algorithm to be used
824 for the connection, e.g.
825 .B 3des-md5-96
826 (must be suitable as a value of
827 .IR ipsec_spi (8)'s
828 .B \-\-esp
829 option);
830 default is not to use ESP
831 .TP
832 .B espenckey
833 ESP encryption key
834 (must be suitable as a value of
835 .IR ipsec_spi (8)'s
836 .B \-\-enckey
837 option)
838 (may be specified separately for each direction using
839 .B leftespenckey
840 (leftward SA)
841 and
842 .B rightespenckey
843 parameters)
844 .TP
845 .B espauthkey
846 ESP authentication key
847 (must be suitable as a value of
848 .IR ipsec_spi (8)'s
849 .B \-\-authkey
850 option)
851 (may be specified separately for each direction using
852 .B leftespauthkey
853 (leftward SA)
854 and
855 .B rightespauthkey
856 parameters)
857 .TP
858 .B espreplay_window
859 ESP replay-window setting,
860 an integer from
861 .B 0
862 (the
863 .IR ipsec_manual
864 default, which turns off replay protection) to
865 .BR 64 ;
866 relevant only if ESP authentication is being used
867 .TP
868 .B leftespspi
869 SPI to be used for the leftward ESP SA, overriding
870 automatic assignment using
871 .B spi
872 or
873 .BR spibase ;
874 typically a hexadecimal number beginning with
875 .B 0x
876 .TP
877 .B ah
878 AH authentication algorithm to be used
879 for the connection, e.g.
880 .B hmac-md5-96
881 (must be suitable as a value of
882 .IR ipsec_spi (8)'s
883 .B \-\-ah
884 option);
885 default is not to use AH
886 .TP
887 .B ahkey
888 (required if
889 .B ah
890 is present) AH authentication key
891 (must be suitable as a value of
892 .IR ipsec_spi (8)'s
893 .B \-\-authkey
894 option)
895 (may be specified separately for each direction using
896 .B leftahkey
897 (leftward SA)
898 and
899 .B rightahkey
900 parameters)
901 .TP
902 .B ahreplay_window
903 AH replay-window setting,
904 an integer from
905 .B 0
906 (the
907 .I ipsec_manual
908 default, which turns off replay protection) to
909 .B 64
910 .TP
911 .B leftahspi
912 SPI to be used for the leftward AH SA, overriding
913 automatic assignment using
914 .B spi
915 or
916 .BR spibase ;
917 typically a hexadecimal number beginning with
918 .B 0x
919 .SH "CA SECTIONS"
920 This are optional sections that can be used to assign special
921 parameters to a Certification Authority (CA).
922 .TP 10
923 .B auto
924 currently can have either the value
925 .B ignore
926 or
927 .B add
928
929 .TP
930 .B cacert
931 defines a path to the CA certificate either relative to 
932 \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
933 .TP
934 .B crluri
935 defines a CRL distribution point (ldap, http, or file URI)
936 .TP
937 .B crluri2
938 defines an alternative CRL distribution point (ldap, http, or file URI)
939 .TP
940 .B ldaphost
941 defines an ldap host.
942 .TP
943 .B ocspuri
944 defines an OCSP URI.
945 .SH "CONFIG SECTIONS"
946 At present, the only
947 .B config
948 section known to the IPsec software is the one named
949 .BR setup ,
950 which contains information used when the software is being started
951 (see
952 .IR ipsec_setup (8)).
953 Here's an example:
954 .PP
955 .ne 8
956 .nf
957 .ft B
958 .ta 1c
959 config setup
960         interfaces="ipsec0=eth1 ipsec1=ppp0"
961         klipsdebug=none
962         plutodebug=all
963         manualstart=
964 .ft
965 .fi
966 .PP
967 Parameters are optional unless marked ``(required)''.
968 The currently-accepted
969 .I parameter
970 names in a
971 .B config
972 .B setup
973 section are:
974 .TP 14
975 .B myid
976 the identity to be used for
977 .BR %myid .
978 .B %myid
979 is used in the implicit policy group conns and can be used as
980 an identity in explicit conns.
981 If unspecified,
982 .B %myid
983 is set to the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
984 the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
985 An explicit value generally starts with ``\fB@\fP''.
986 .TP
987 .B interfaces
988 virtual and physical interfaces for IPsec to use:
989 a single
990 \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated
991 by white space, or
992 .BR %none .
993 One of the pairs may be written as
994 .BR %defaultroute ,
995 which means: find the interface \fId\fR that the default route points to,
996 and then act as if the value was ``\fBipsec0=\fId\fR''.
997 .B %defaultroute
998 is the default;
999 .B %none
1000 must be used to denote no interfaces.
1001 If
1002 .B %defaultroute
1003 is used (implicitly or explicitly)
1004 information about the default route and its interface is noted for
1005 use by
1006 .IR ipsec_manual (8)
1007 and
1008 .IR ipsec_auto (8).)
1009 .TP
1010 .B forwardcontrol
1011 whether
1012 .I setup
1013 should turn IP forwarding on
1014 (if it's not already on) as IPsec is started,
1015 and turn it off again (if it was off) as IPsec is stopped;
1016 acceptable values are
1017 .B yes
1018 and (the default)
1019 .BR no .
1020 For this to have full effect, forwarding must be
1021 disabled before the hardware interfaces are brought
1022 up (e.g.,
1023 .B "net.ipv4.ip_forward\ =\ 0"
1024 in Red Hat 6.x
1025 .IR /etc/sysctl.conf ),
1026 because IPsec doesn't get control early enough to do that.
1027 .TP
1028 .B rp_filter
1029 whether and how
1030 .I setup
1031 should adjust the reverse path filtering mechanism for the
1032 physical devices to be used.
1033 Values are \fB%unchanged\fP (to leave it alone)
1034 or \fB0\fP, \fB1\fP, \fB2\fP (values to set it to).
1035 \fI/proc/sys/net/ipv4/conf/PHYS/rp_filter\fP
1036 is badly documented; it must be \fB0\fP in many cases
1037 for ipsec to function.
1038 The default value for the parameter is \fB0\fP.
1039 .TP
1040 .B syslog
1041 the
1042 .IR syslog (2)
1043 ``facility'' name and priority to use for
1044 startup/shutdown log messages,
1045 default
1046 .BR daemon.error .
1047 .TP
1048 .B klipsdebug
1049 how much KLIPS debugging output should be logged.
1050 An empty value,
1051 or the magic value
1052 .BR none ,
1053 means no debugging output (the default).
1054 The magic value
1055 .B all
1056 means full output.
1057 Otherwise only the specified types of output
1058 (a quoted list, names separated by white space) are enabled;
1059 for details on available debugging types, see
1060 .IR ipsec_klipsdebug (8).
1061 .TP
1062 .B plutodebug
1063 how much Pluto debugging output should be logged.
1064 An empty value,
1065 or the magic value
1066 .BR none ,
1067 means no debugging output (the default).
1068 The magic value
1069 .B all
1070 means full output.
1071 Otherwise only the specified types of output
1072 (a quoted list, names without the
1073 .B \-\-debug\-
1074 prefix,
1075 separated by white space) are enabled;
1076 for details on available debugging types, see
1077 .IR ipsec_pluto (8).
1078 .TP
1079 .B charondebug
1080 how much Charon debugging output should be logged.
1081 A comma separated list containing type level/pairs may
1082 be specified, e.g:
1083 .B dmn 3, ike 1, net -1.
1084 Acceptable values for types are
1085 .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib
1086 and the level is one of
1087 .B -1, 0, 1, 2, 3, 4
1088 (for silent, audit, control, controlmore, raw, private)
1089 .TP
1090 .B plutoopts
1091 additional options to pass to pluto upon startup. See
1092 .IR ipsec_pluto (8).
1093 .TP
1094 .B plutostderrlog
1095 do not use syslog, but rather log to stderr, and direct stderr to the
1096 argument file.
1097 .TP
1098 .B dumpdir
1099 in what directory should things started by
1100 .I setup
1101 (notably the Pluto daemon) be allowed to
1102 dump core?
1103 The empty value (the default) means they are not
1104 allowed to.
1105 .TP
1106 .B manualstart
1107 which manually-keyed connections to set up at startup
1108 (empty, a name, or a quoted list of names separated by white space);
1109 see
1110 .IR ipsec_manual (8).
1111 Default is none.
1112 .TP
1113 .B pluto
1114 whether to start Pluto or not;
1115 Values are
1116 .B yes
1117 (the default)
1118 or
1119 .B no
1120 (useful only in special circumstances).
1121 .TP
1122 .B plutowait
1123 should Pluto wait for each
1124 negotiation attempt that is part of startup to
1125 finish before proceeding with the next?
1126 Values are
1127 .B yes
1128 or
1129 .BR no
1130 (the default).
1131 .TP
1132 .B prepluto
1133 shell command to run before starting Pluto
1134 (e.g., to decrypt an encrypted copy of the
1135 .I ipsec.secrets
1136 file).
1137 It's run in a very simple way;
1138 complexities like I/O redirection are best hidden within a script.
1139 Any output is redirected for logging,
1140 so running interactive commands is difficult unless they use
1141 .I /dev/tty
1142 or equivalent for their interaction.
1143 Default is none.
1144 .TP
1145 .B postpluto
1146 shell command to run after starting Pluto
1147 (e.g., to remove a decrypted copy of the
1148 .I ipsec.secrets
1149 file).
1150 It's run in a very simple way;
1151 complexities like I/O redirection are best hidden within a script.
1152 Any output is redirected for logging,
1153 so running interactive commands is difficult unless they use
1154 .I /dev/tty
1155 or equivalent for their interaction.
1156 Default is none.
1157 .TP
1158 .B fragicmp
1159 whether a tunnel's need to fragment a packet should be reported
1160 back with an ICMP message,
1161 in an attempt to make the sender lower his PMTU estimate;
1162 acceptable values are
1163 .B yes
1164 (the default)
1165 and
1166 .BR no .
1167 .TP
1168 .B hidetos
1169 whether a tunnel packet's TOS field should be set to
1170 .B 0
1171 rather than copied from the user packet inside;
1172 acceptable values are
1173 .B yes
1174 (the default)
1175 and
1176 .BR no .
1177 .TP
1178 .B uniqueids
1179 whether a particular participant ID should be kept unique,
1180 with any new (automatically keyed)
1181 connection using an ID from a different IP address
1182 deemed to replace all old ones using that ID;
1183 acceptable values are
1184 .B yes
1185 (the default)
1186 and
1187 .BR no .
1188 Participant IDs normally \fIare\fR unique,
1189 so a new (automatically-keyed) connection using the same ID is
1190 almost invariably intended to replace an old one.
1191 .TP
1192 .B overridemtu
1193 value that the MTU of the ipsec\fIn\fR interface(s) should be set to,
1194 overriding IPsec's (large) default.
1195 This parameter is needed only in special situations.
1196 .TP
1197 .B nat_traversal
1198 .TP
1199 .B crlcheckinterval
1200 .TP
1201 .B strictcrlpolicy
1202 .TP
1203 .B pkcs11module
1204 .TP
1205 .B pkcs11keepstate
1206
1207 .SH CHOOSING A CONNECTION
1208 .PP
1209 When choosing a connection to apply to an outbound packet caught with a 
1210 .BR %trap,
1211 the system prefers the one with the most specific eroute that
1212 includes the packet's source and destination IP addresses.
1213 Source subnets are examined before destination subnets.
1214 For initiating, only routed connections are considered. For responding,
1215 unrouted but added connections are considered.
1216 .PP
1217 When choosing a connection to use to respond to a negotiation which
1218 doesn't match an ordinary conn, an opportunistic connection
1219 may be instantiated. Eventually, its instance will be /32 -> /32, but
1220 for earlier stages of the negotiation, there will not be enough
1221 information about the client subnets to complete the instantiation.
1222 .SH FILES
1223 .nf
1224 /etc/ipsec.conf
1225 /etc/ipsec.d/cacerts
1226 /etc/ipsec.d/certs
1227 /etc/ipsec.d/crls
1228 /etc/ipsec.d/aacerts
1229 /etc/ipsec.d/acerts
1230
1231 .SH SEE ALSO
1232 ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8), ipsec_rsasigkey(8)
1233 .SH HISTORY
1234 Written  for  the  FreeS/WAN project
1235 <http://www.freeswan.org>
1236 by Henry Spencer.  Extended for the strongSwan project
1237 <http://www.strongswan.org>
1238 by Andreas Steffen.
1239 .SH BUGS
1240 .PP
1241 When
1242 .B type
1243 or 
1244 .B failureshunt
1245 is set to
1246 .B drop
1247 or
1248 .BR reject,
1249 strongSwan blocks outbound packets using eroutes, but assumes inbound
1250 blocking is handled by the firewall. strongSwan offers firewall hooks 
1251 via an ``updown'' script.  However, the default 
1252 .B ipsec _updown
1253 provides no help in controlling a modern firewall.
1254 .PP
1255 Including attributes of the keying channel
1256 (authentication methods,
1257 .BR ikelifetime ,
1258 etc.)
1259 as an attribute of a connection,
1260 rather than of a participant pair, is dubious and incurs limitations.
1261 .PP
1262 .IR Ipsec_manual
1263 is not nearly as generous about the syntax of subnets,
1264 addresses, etc. as the usual strongSwan user interfaces.
1265 Four-component dotted-decimal must be used for all addresses.
1266 It
1267 .I is
1268 smart enough to translate bit-count netmasks to dotted-decimal form.
1269 .PP
1270 It would be good to have a line-continuation syntax,
1271 especially for the very long lines involved in
1272 RSA signature keys.
1273 .PP
1274 The ability to specify different identities,
1275 .BR authby ,
1276 and public keys for different automatic-keyed connections
1277 between the same participants is misleading;
1278 this doesn't work dependably because the identity of the participants
1279 is not known early enough.
1280 This is especially awkward for the ``Road Warrior'' case,
1281 where the remote IP address is specified as
1282 .BR 0.0.0.0 ,
1283 and that is considered to be the ``participant'' for such connections.
1284 .PP
1285 In principle it might be necessary to control MTU on an
1286 interface-by-interface basis,
1287 rather than with the single global override that
1288 .B overridemtu
1289 provides.
1290 .PP
1291 A number of features which \fIcould\fR be implemented in
1292 both manual and automatic keying
1293 actually are not yet implemented for manual keying.
1294 This is unlikely to be fixed any time soon.
1295 .PP
1296 If conns are to be added before DNS is available,
1297 \fBleft=\fP\fIFQDN\fP,
1298 \fBleftnextop=\fP\fIFQDN\fP,
1299 and
1300 .B leftrsasigkey=%dnsonload
1301 will fail.
1302 .IR ipsec_pluto (8)
1303 does not actually use the public key for our side of a conn but it
1304 isn't generally known at a add-time which side is ours (Road Warrior
1305 and Opportunistic conns are currently exceptions).
1306 .PP
1307 The \fBmyid\fP option does not affect explicit \fB ipsec auto \-\-add\fP or \fBipsec auto \-\-replace\fP commands for implicit conns.