1 .TH IPSEC.CONF 5 "26 Nov 2001"
2 .\" RCSID $Id: ipsec.conf.5,v 1.79 2001/11/26 15:51:24 henry Exp $
4 ipsec.conf \- IPsec configuration and connections
9 specifies most configuration and control information for the
10 FreeS/WAN IPsec subsystem.
11 (The major exception is secrets for authentication;
13 .IR ipsec.secrets (5).)
14 Its contents are not security-sensitive
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).
23 The file is a text file, consisting of one or more
25 White space followed by
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.
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
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
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.
57 parameter (described below) which permits splitting a single logical section
58 (e.g. a connection description) into several actual sections.
61 begins with a line of the form:
68 indicates what type of section follows, and
70 is an arbitrary name which distinguishes the section from others
72 (Names must start with a letter and may contain only
73 letters, digits, periods, underscores, and hyphens.)
74 All subsequent non-empty lines
75 which begin with white space are part of the section;
76 comments within a section must begin with white space too.
77 There may be only one section of a given type with a given name.
79 Lines within the section are generally of the form
81 \ \ \ \ \ \fIparameter\fB=\fIvalue\fR
83 (note the mandatory preceding white space).
84 There can be white space on either side of the
86 Parameter names follow the same syntax as section names,
87 and are specific to a section type.
88 Unless otherwise explicitly specified,
89 no parameter name may appear more than once in a section.
93 stands for the system default value (if any) of the parameter,
94 i.e. it is roughly equivalent to omitting the parameter line entirely.
97 may contain white space only if the entire
99 is enclosed in double quotes (\fB"\fR);
102 cannot itself contain a double quote,
103 nor may it be continued across more than one line.
105 Numeric values are specified to be either an ``integer''
106 (a sequence of digits) or a ``decimal number''
107 (sequence of digits optionally followed by `.' and another sequence of digits).
109 There is currently one parameter which is available in any type of
113 the value is a section name;
114 the parameters of that section are appended to this section,
115 as if they had been written as part of it.
116 The specified section must exist, must follow the current one,
117 and must have the same section type.
118 (Nesting is permitted,
119 and there may be more than one
122 although it is forbidden to append the same section more than once.)
123 This allows, for example, keeping the encryption keys
124 for a connection in a separate file
125 from the rest of the description, by using both an
130 (Caution, see BUGS below for some restrictions.)
132 Parameter names beginning with
140 are reserved for user extensions and will never be assigned meanings
142 Parameters with such names must still observe the syntax rules
143 (limits on characters used in the name;
144 no white space in a non-quoted value;
145 no newlines or double quotes within the value).
146 All other as-yet-unused parameter names are reserved for future IPsec
151 specifies defaults for sections of the same type.
152 For each parameter in it,
153 any section of that type which does not have a parameter of the same name
154 gets a copy of the one from the
157 There may be multiple
159 sections of a given type,
160 but only one default may be supplied for any specific parameter name,
163 sections of a given type must precede all non-\c
165 sections of that type.
167 sections may not contain
171 Currently there are two types of section:
174 section specifies general configuration information for IPsec,
177 section specifies an IPsec connection.
182 .IR "connection specification" ,
183 defining a network connection to be made using IPsec.
184 The name given is arbitrary, and is used to identify the connection to
187 .IR ipsec_manual (8).
188 Here's a simple example:
196 leftsubnet=10.0.1.0/24
197 leftnexthop=172.16.55.66
199 rightsubnet=10.0.2.0/24
200 rightnexthop=172.16.88.99
201 keyingtries=0 # be very persistent
205 A note on terminology...
206 In automatic keying, there are two kinds of communications going on:
207 transmission of user IP packets, and gateway-to-gateway negotiations for
208 keying, rekeying, and general control.
209 The data path (a set of ``IPsec SAs'') used for user packets is herein
210 referred to as the ``connection'';
211 the path used for negotiations (built with ``ISAKMP SAs'') is referred to as
212 the ``keying channel''.
214 To avoid trivial editing of the configuration file to suit it to each system
215 involved in a connection,
216 connection specifications are written in terms of
221 rather than in terms of local and remote.
222 Which participant is considered
227 IPsec figures out which one it is being run on based on internal information.
228 This permits using identical connection specifications on both ends.
230 Many of the parameters relate to one participant or the other;
233 are listed here, but every parameter whose name begins with
238 whose description is the same but with
244 Parameters are optional unless marked ``(required)'';
245 a parameter required for manual keying need not be included for
246 a connection which will use only automatic keying, and vice versa.
247 .SS "CONN PARAMETERS: GENERAL"
248 The following parameters are relevant to both automatic and manual keying.
249 Unless otherwise noted,
250 for a connection to work,
251 in general it is necessary for the two ends to agree exactly
252 on the values of these parameters.
255 the type of the connection; currently the accepted values
259 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
261 signifying host-to-host transport mode;
264 (supported only for manual keying),
265 signifying that no IPsec processing should be done at all
269 the IP address of the left participant's public-network interface,
270 in any form accepted by
271 .IR ipsec_ttoaddr (3).
272 If it is the magic value
275 .B interfaces=%defaultroute
281 will be filled in automatically with the local address
282 of the default-route interface (as determined at IPsec startup time);
283 this also overrides any value supplied for
294 signifies an address to be filled in (by automatic keying) during
302 are to be filled in (by automatic keying) from DNS data for
307 private subnet behind the left participant, expressed as
308 \fInetwork\fB/\fInetmask\fR
309 (actually, any form acceptable to
310 .IR ipsec_ttosubnet (3));
311 if omitted, essentially assumed to be \fIleft\fB/32\fR,
312 signifying that the left end of the connection goes to the left participant only
315 next-hop gateway IP address for the left participant's connection
316 to the public network;
321 If the value is to be overridden by the
322 .B left=%defaultroute
324 an explicit value must
327 If that method is not being used,
333 .B interfaces=%defaultroute
338 the next-hop gateway address of the default-route interface
342 signifies a value to be filled in (by automatic keying)
343 with the peer's address.
344 Relevant only locally, other end need not agree on it.
347 what ``updown'' script to run to adjust routing and/or firewalling
348 when the status of the connection
350 .BR "ipsec _updown" ).
351 May include positional parameters separated by white space
352 (although this requires enclosing the whole string in quotes);
353 including shell metacharacters is unwise.
357 Relevant only locally, other end need not agree on it.
360 whether the left participant is doing forwarding-firewalling
361 (including masquerading) for traffic from \fIleftsubnet\fR,
362 which should be turned off (for traffic to the other subnet)
363 once the connection is established;
364 acceptable values are
368 May not be used in the same connection description with
370 Implemented as a parameter to the default
374 Relevant only locally, other end need not agree on it.
376 If one or both security gateways are doing forwarding firewalling
377 (possibly including masquerading),
378 and this is specified using the firewall parameters,
379 tunnels established with IPsec are exempted from it
380 so that packets can flow unchanged through the tunnels.
381 (This means that all subnets connected in this manner must have
382 distinct, non-overlapping subnet address blocks.)
383 This is done by the default
386 .IR ipsec_pluto (8)).
388 The implementation of this makes certain assumptions about firewall setup,
389 notably the use of the old
391 interface to the firewall.
392 In situations calling for more control,
393 it may be preferable for the user to supply his own
396 which makes the appropriate adjustments for his system.
397 .SS "CONN PARAMETERS: AUTOMATIC KEYING"
398 The following parameters are relevant only to automatic keying,
399 and are ignored in manual keying.
400 Unless otherwise noted,
401 for a connection to work,
402 in general it is necessary for the two ends to agree exactly
403 on the values of these parameters.
406 method of key exchange;
407 the default and currently the only accepted value is
411 what operation, if any, should be done automatically at IPsec startup;
412 currently-accepted values are
418 (signifying that plus an
422 (signifying that plus an
427 (also the default) (signifying no automatic startup operation).
428 This parameter is ignored unless the
432 configuration parameter is set suitably; see the
436 Relevant only locally, other end need not agree on it
437 (but in general, for an intended-to-be-permanent connection,
440 to ensure that any reboot causes immediate renegotiation).
443 whether authentication should be done as part of
444 ESP encryption, or separately using the AH protocol;
445 acceptable values are
451 how the two security gateways should authenticate each other;
452 acceptable values are
454 for shared secrets (the default) and
456 for RSA digital signatures
461 should be identified for authentication;
464 Can be an IP address (in any
465 .IR ipsec_ttoaddr (3)
467 or a fully-qualified domain name preceded by
469 (which is used as a literal string and not resolved).
472 the left participant's
473 public key for RSA signature authentication,
474 in RFC 2537 format using
475 .IR ipsec_ttodata (3)
479 means to fetch it from DNS (at the time
480 the connection description is read from
483 The identity used for the left participant
484 must be a specific host, not
486 or another magic value.
488 if two connection descriptions
489 specify different public keys for the same
491 confusion and madness will ensue.
494 whether Perfect Forward Secrecy of keys is desired on the connection's
496 (with PFS, penetration of the key-exchange protocol
497 does not compromise keys negotiated earlier);
498 acceptable values are
505 how long a particular instance of a connection
506 (a set of encryption/authentication keys for user packets) should last,
507 from successful negotiation to expiry;
508 acceptable values are an integer optionally followed by
511 or a decimal number followed by
517 in minutes, hours, or days respectively)
522 Normally, the connection is renegotiated (via the keying channel)
524 The two ends need not exactly agree on
526 although if they do not,
527 there will be some clutter of superseded connections on the end
528 which thinks the lifetime is longer.
531 whether a connection should be renegotiated when it is about to expire;
532 acceptable values are
537 The two ends need not agree,
540 prevents Pluto from requesting renegotiation,
541 it does not prevent responding to renegotiation requested from the other end,
544 will be largely ineffective unless both ends agree on it.
547 how long before connection expiry or keying-channel expiry
549 negotiate a replacement
550 begin; acceptable values as for
554 Relevant only locally, other end need not agree on it.
557 maximum percentage by which
559 should be randomly increased to randomize rekeying intervals
560 (important for hosts with many connections);
561 acceptable values are an integer,
562 which may exceed 100,
570 after this random increase,
575 will suppress time randomization.
576 Relevant only locally, other end need not agree on it.
579 how many attempts (an integer) should be made to
580 negotiate a connection, or a replacement for one, before giving up
585 means ``never give up''
586 Relevant only locally, other end need not agree on it.
589 how long the keying channel of a connection (buzzphrase: ``ISAKMP SA'')
590 should last before being renegotiated;
591 acceptable values as for
599 The two-ends-disagree case is similar to that of
603 whether IPComp compression of content is desired on the connection
604 (link-level compression does not work on encrypted data,
605 so to be effective, compression must be done \fIbefore\fR encryption);
606 acceptable values are
611 The two ends need not agree.
615 IPsec will neither propose nor accept compression.
618 causes IPsec to propose both compressed and uncompressed,
619 and prefer compressed.
621 .B disablearrivalcheck
622 whether KLIPS's normal tunnel-exit check
623 (that a packet emerging from a tunnel has plausible addresses in its header)
625 acceptable values are
627 (the backward-compatible default)
630 Relevant only locally, other end need not agree on it.
631 .SS "CONN PARAMETERS: MANUAL KEYING"
632 The following parameters are relevant only to manual keying,
633 and are ignored in automatic keying.
634 Unless otherwise noted,
635 for a connection to work,
636 in general it is necessary for the two ends to agree exactly
637 on the values of these parameters.
639 connection must specify at least one of AH or ESP.
644 required for manual keying)
645 the SPI number to be used for the connection (see
646 .IR ipsec_manual (8));
647 must be of the form \fB0x\fIhex\fB\fR,
650 is one or more hexadecimal digits
651 (note, it will generally be necessary to make
655 to be acceptable to KLIPS,
656 and use of SPIs in the range
663 required for manual keying)
664 the base number for the SPIs to be used for the connection (see
665 .IR ipsec_manual (8));
666 must be of the form \fB0x\fIhex\fB0\fR,
669 is one or more hexadecimal digits
670 (note, it will generally be necessary to make
674 for the resulting SPIs
675 to be acceptable to KLIPS,
676 and use of numbers in the range
681 ESP encryption/authentication algorithm to be used
682 for the connection, e.g.
684 (must be suitable as a value of
688 default is not to use ESP
692 (must be suitable as a value of
696 (may be specified separately for each direction using
704 ESP authentication key
705 (must be suitable as a value of
709 (may be specified separately for each direction using
717 ESP replay-window setting,
722 default, which turns off replay protection) to
724 relevant only if ESP authentication is being used
727 SPI to be used for the leftward ESP SA, overriding
728 automatic assignment using
732 typically a hexadecimal number beginning with
736 AH authentication algorithm to be used
737 for the connection, e.g.
739 (must be suitable as a value of
743 default is not to use AH
748 is present) AH authentication key
749 (must be suitable as a value of
753 (may be specified separately for each direction using
761 AH replay-window setting,
766 default, which turns off replay protection) to
770 SPI to be used for the leftward AH SA, overriding
771 automatic assignment using
775 typically a hexadecimal number beginning with
777 .SH "CONFIG SECTIONS"
780 section known to the IPsec software is the one named
782 which contains information used when the software is being started
784 .IR ipsec_setup (8)).
792 interfaces="ipsec0=eth1 ipsec1=ppp0"
796 plutoload="snta sntb sntc sntd"
801 Parameters are optional unless marked ``(required)''.
802 The currently-accepted
811 virtual and physical interfaces for IPsec to use:
813 \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated
817 which means to find the interface \fId\fR that the default route points to,
818 and then act as if the value was ``\fBipsec0=\fId\fR''.
822 information about the default route and its interface is noted for
831 should turn IP forwarding on
832 (if it's not already on) as IPsec is started,
833 and turn it off again (if it was off) as IPsec is stopped;
834 acceptable values are
838 For this to have full effect, forwarding must be
839 disabled before the hardware interfaces are brought
841 .B "net.ipv4.ip_forward\ =\ 0"
843 .IR /etc/sysctl.conf ),
844 because IPsec doesn't get control early enough to do that.
849 ``facility'' name and priority to use for
850 startup/shutdown log messages,
855 how much KLIPS debugging output should be logged.
859 means no debugging output (the default).
863 Otherwise only the specified types of output
864 (a quoted list, names separated by white space) are enabled;
865 for details on available debugging types, see
866 .IR ipsec_klipsdebug (8).
869 how much Pluto debugging output should be logged.
873 means no debugging output (the default).
877 Otherwise only the specified types of output
878 (a quoted list, names without the
881 separated by white space) are enabled;
882 for details on available debugging types, see
886 in what directory should things started by
888 (notably the Pluto daemon) be allowed to
890 The empty value (the default) means they are not
905 which manually-keyed connections to set up at startup
906 (empty, a name, or a quoted list of names separated by white space);
908 .IR ipsec_manual (8).
912 whether to start Pluto or not;
918 (useful only in special circumstances).
921 which connections (by name) to load
922 into Pluto's internal database at startup
923 (empty, a name, or a quoted list of names separated by white space);
930 is used, all connections with
938 which connections (by name) to attempt to negotiate
939 at startup (empty, a name, or a quoted
940 list of names separated by white space);
941 any such names which do not appear in
943 are implicitly added to it.
947 is used, all connections with
952 and all connections with
957 should Pluto wait for each
959 negotiation attempt to
960 finish before proceeding with the next?
967 .B plutobackgroundload
968 obsolete parameter, ignored, nominally specifying whether
969 loading and starting of connections should be spun off as a background
970 process to avoid startup delays.
971 This is now always done.
979 shell command to run before starting Pluto
980 (e.g., to decrypt an encrypted copy of the
983 It's run in a very simple way;
984 complexities like I/O redirection are best hidden within a script.
985 Any output is redirected for logging,
986 so running interactive commands is difficult unless they use
988 or equivalent for their interaction.
992 shell command to run after starting Pluto
993 (e.g., to remove a decrypted copy of the
996 It's run in a very simple way;
997 complexities like I/O redirection are best hidden within a script.
998 Any output is redirected for logging,
999 so running interactive commands is difficult unless they use
1001 or equivalent for their interaction.
1005 whether a tunnel's need to fragment a packet should be reported
1006 back with an ICMP message,
1007 in an attempt to make the sender lower his PMTU estimate;
1008 acceptable values are
1015 what should be done with
1016 a packet which reaches KLIPS (via a route into a virtual interface)
1017 but does not match any eroute;
1018 acceptable values are
1020 (\fIinsecure unless you really know what you're doing!!!\fR),
1027 but eventually it will send an ICMP notification back
1031 obsolete parameter similar to
1033 but with more limited functionality;
1037 acceptable values are
1040 .BR packetdefault=pass )
1044 .BR packetdefault=drop )
1048 whether a tunnel packet's TOS field should be set to
1050 rather than copied from the user packet inside;
1051 acceptable values are
1058 whether a particular participant ID should be kept unique,
1059 with any new (automatically keyed)
1060 connection using an ID from a different IP address
1061 deemed to replace all old ones using that ID;
1062 acceptable values are
1069 value that the MTU of the ipsec\fIn\fR interface(s) should be set to,
1070 overriding IPsec's (large) default.
1071 This parameter is needed only in special situations.
1072 .SH "RECOMMENDED CONFIGURATION"
1073 Certain parameters are now strongly-recommended defaults,
1074 but cannot (yet) be made system defaults due to backward compatibility.
1075 They \fIare\fR supplied as ``boilerplate'' in the sample
1077 file which is put in place as part of a new FreeS/WAN install.
1083 .B plutoload=%search
1085 .B plutostart=%search
1086 In practice, it is preferable to use the
1088 parameter to control whether a particular
1089 connection is added or started automatically.
1092 Participant IDs normally \fIare\fR unique,
1093 so a new (automatically-keyed) connection using the same ID is
1094 almost invariably intended to replace an old one.
1098 parameters (mostly for automatic keying, as manual keying seldom sees
1102 Unlimited retries are normally appropriate for VPN connections.
1103 Finite values may be needed for Road Warrior and other more-ephemeral
1105 but the fixed small default is pretty much useless.
1107 .B disablearrivalcheck=no
1108 Tunnel-exit checks improve security and do not break any normal configuration.
1111 Digital signatures are superior in every way to shared secrets.
1113 .B leftrsasigkey=%dns
1115 .B rightrsasigkey=%dns
1116 Fetching public keys from DNS is generally more convenient
1117 than having to preconfigure them in configuration files.
1121 ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8), ipsec_rsasigkey(8)
1123 Designed for the FreeS/WAN project
1124 <http://www.freeswan.org>
1127 Including attributes of the keying channel
1128 (authentication methods,
1131 as an attribute of a connection,
1132 rather than of a participant pair, is dubious and incurs limitations.
1134 In general, the defaults often were chosen for backward compatibility
1135 and are less than ideal.
1142 is not nearly as generous about the syntax of subnets,
1143 addresses, etc. as the usual FreeS/WAN user interfaces.
1144 Four-component dotted-decimal must be used for all addresses.
1147 smart enough to translate bit-count netmasks to dotted-decimal form.
1149 It would be good to have a line-continuation syntax,
1150 especially for the very long lines involved in
1153 The ability to specify different identities,
1155 and public keys for different automatic-keyed connections
1156 between the same participants is misleading;
1157 this doesn't work dependably because the identity of the participants
1158 is not known early enough.
1159 This is especially awkward for the ``Road Warrior'' case,
1160 where the remote IP address is specified as
1162 and that is considered to be the ``participant'' for such connections.
1164 In principle it might be necessary to control MTU on an
1165 interface-by-interface basis,
1166 rather than with the single global override that
1170 A number of features which \fIcould\fR be implemented in
1171 both manual and automatic keying
1172 actually are not yet implemented for manual keying.
1173 This is unlikely to be fixed any time soon.
OSDN Git Service
