1 Content-type: text/html
3 <HTML><HEAD><TITLE>Manpage of IPSEC.CONF</TITLE>
6 Section: File Formats (5)<BR>Updated: 14 June 2001<BR><A HREF="#index">Index</A>
7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
10 <A NAME="lbAB"> </A>
13 ipsec.conf - IPsec configuration and connections
14 <A NAME="lbAC"> </A>
21 specifies most configuration and control information for the
22 FreeS/WAN IPsec subsystem.
23 (The major exception is secrets for authentication;
25 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5).)
27 Its contents are not security-sensitive
30 manual keying is being done for more than just testing,
31 in which case the encryption/authentication keys in the
32 descriptions for the manually-keyed connections are very sensitive
33 (and those connection descriptions
34 are probably best kept in a separate file,
35 via the include facility described below).
38 The file is a text file, consisting of one or more
41 White space followed by
44 followed by anything to the end of the line
45 is a comment and is ignored,
46 as are empty lines which are not within a section.
52 and a file name, separated by white space,
53 is replaced by the contents of that file,
54 preceded and followed by empty lines.
55 If the file name is not a full pathname,
56 it is considered to be relative to the directory containing the
58 Such inclusions can be nested.
59 Only a single filename may be supplied, and it may not contain white space,
60 but it may include shell wildcards (see
61 <I><A HREF="sh.1.html">sh</A></I>(1));
72 The intention of the include facility is mostly to permit keeping
73 information on connections, or sets of connections,
74 separate from the main configuration file.
75 This permits such connection descriptions to be changed,
76 copied to the other security gateways involved, etc.,
77 without having to constantly extract them from the configuration
78 file and then insert them back into it.
82 parameter (described below) which permits splitting a single logical section
83 (e.g. a connection description) into several actual sections.
87 begins with a line of the form:
99 indicates what type of section follows, and
102 is an arbitrary name which distinguishes the section from others
104 (Names must start with a letter and may contain only
105 letters, digits, periods, underscores, and hyphens.)
106 All subsequent lines which begin with white space are part of the section;
107 comments within a section must begin with white space too.
108 There may be only one section of a given type with a given name.
111 Lines within the section are generally of the form
114 <I>parameter</I><B>=</B><I>value</I>
117 (note the mandatory preceding white space).
118 There can be white space on either side of the
121 Parameter names follow the same syntax as section names,
122 and are specific to a section type.
123 Unless otherwise explicitly specified,
124 no parameter name may appear more than once in a section.
130 stands for the system default value (if any) of the parameter,
131 i.e. it is roughly equivalent to omitting the parameter line entirely.
135 may contain white space only if the entire
138 is enclosed in double quotes (<B>"</B>);
142 cannot itself contain a double quote,
143 nor may it be continued across more than one line.
146 Numeric values are specified to be either an ``integer''
147 (a sequence of digits) or a ``decimal number''
148 (sequence of digits optionally followed by `.' and another sequence of digits).
151 There is currently one parameter which is available in any type of
157 the value is a section name;
158 the parameters of that section are appended to this section,
159 as if they had been written as part of it.
160 The specified section must exist, must follow the current one,
161 and must have the same section type.
162 (Nesting is permitted,
163 and there may be more than one
167 although it is forbidden to append the same section more than once.)
168 This allows, for example, keeping the encryption keys
169 for a connection in a separate file
170 from the rest of the description, by using both an
177 (Caution, see BUGS below for some restrictions.)
181 Parameter names beginning with
193 are reserved for user extensions and will never be assigned meanings
195 Parameters with such names must still observe the syntax rules
196 (limits on characters used in the name;
197 no white space in a non-quoted value;
198 no newlines or double quotes within the value).
199 All other as-yet-unused parameter names are reserved for future IPsec
206 specifies defaults for sections of the same type.
207 For each parameter in it,
208 any section of that type which does not have a parameter of the same name
209 gets a copy of the one from the
213 There may be multiple
216 sections of a given type,
217 but only one default may be supplied for any specific parameter name,
221 sections of a given type must precede all non-<B>%default</B>
223 sections of that type.
226 sections may not contain
232 Currently there are two types of section:
236 section specifies general configuration information for IPsec,
240 section specifies an IPsec connection.
241 <A NAME="lbAD"> </A>
242 <H2>CONN SECTIONS</H2>
248 <I>connection specification</I>,
250 defining a network connection to be made using IPsec.
251 The name given is arbitrary, and is used to identify the connection to
252 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8)
255 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8).
257 Here's a simple example:
265 leftsubnet=10.0.1.0/24
266 leftnexthop=172.16.55.66
268 rightsubnet=10.0.2.0/24
269 rightnexthop=172.16.88.99
270 keyingtries=0 # be very persistent
275 To avoid trivial editing of the configuration file to suit it to each system
276 involved in a connection,
277 connection specifications are written in terms of
284 rather than in terms of local and remote.
285 Which participant is considered
292 IPsec figures out which one it is being run on based on internal information.
293 This permits using identical connection specifications on both ends.
296 Many of the parameters relate to one participant or the other;
300 are listed here, but every parameter whose name begins with
307 whose description is the same but with
316 Parameters are optional unless marked ``(required)'';
317 a parameter required for manual keying need not be included for
318 a connection which will use only automatic keying, and vice versa.
319 <A NAME="lbAE"> </A>
320 <H3>CONN PARAMETERS: GENERAL</H3>
322 The following parameters are relevant to both automatic and manual keying.
327 the type of the connection; currently the accepted values
332 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
335 signifying host-to-host transport mode;
339 (supported only for manual keying),
340 signifying that no IPsec processing should be done at all
344 whether IPComp compression of content is desired on the connection
345 (link-level compression does not work on encrypted data,
346 so to be effective, compression must be done <I>before</I> encryption);
347 acceptable values are
358 the IP address of the left participant's public-network interface,
359 in any form accepted by
360 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3).
362 If it is the magic value
363 <B>%defaultroute</B>,
366 <B>interfaces=%defaultroute</B>
376 will be filled in automatically with the local address
377 of the default-route interface (as determined at IPsec startup time);
378 this also overrides any value supplied for
388 <B>%defaultroute</B>,
394 signifies an address to be filled in (by automatic keying) during
397 <B>%opportunistic</B>
405 are to be filled in (by automatic keying) from DNS data for
409 <DT><B>leftsubnet</B>
412 private subnet behind the left participant, expressed as
413 <I>network</I><B>/</B><I>netmask</I>
414 (actually, any form acceptable to
415 <I><A HREF="ipsec_ttosubnet.3.html">ipsec_ttosubnet</A></I>(3));
417 if omitted, essentially assumed to be <I>left</I><B>/32</B>,
418 signifying that the left end of the connection goes to the left participant only
419 <DT><B>leftnexthop</B>
422 next-hop gateway IP address for the left participant's connection
423 to the public network;
430 If the value is to be overridden by the
431 <B>left=%defaultroute</B>
434 an explicit value must
438 If that method is not being used,
443 <B>%defaultroute</B>,
446 <B>interfaces=%defaultroute</B>
454 the next-hop gateway address of the default-route interface
459 signifies a value to be filled in (by automatic keying)
460 with the peer's address.
461 <DT><B>leftupdown</B>
464 what ``updown'' script to run to adjust routing and/or firewalling
465 when the status of the connection
467 <B>ipsec _updown</B>).
469 May include positional parameters separated by white space
470 (although this requires enclosing the whole string in quotes);
471 including shell metacharacters is unwise.
473 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8)
476 <DT><B>leftfirewall</B>
479 whether the left participant is doing forwarding-firewalling
480 (including masquerading) for traffic from <I>leftsubnet</I>,
481 which should be turned off (for traffic to the other subnet)
482 once the connection is established;
483 acceptable values are
489 May not be used in the same connection description with
492 Implemented as a parameter to the default
499 If one or both security gateways are doing forwarding firewalling
500 (possibly including masquerading),
501 and this is specified using the firewall parameters,
502 tunnels established with IPsec are exempted from it
503 so that packets can flow unchanged through the tunnels.
504 (This means that all subnets connected in this manner must have
505 distinct, non-overlapping subnet address blocks.)
506 This is done by the default
510 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8)).
514 The implementation of this makes certain assumptions about firewall setup,
515 notably the use of the old
518 interface to the firewall.
519 In situations calling for more control,
520 it may be preferable for the user to supply his own
524 which makes the appropriate adjustments for his system.
525 <A NAME="lbAF"> </A>
526 <H3>CONN PARAMETERS: AUTOMATIC KEYING</H3>
528 The following parameters are relevant only to automatic keying,
529 and are ignored in manual keying.
531 <DT><B>keyexchange</B>
534 method of key exchange;
535 the default and currently the only accepted value is
541 what operation, if any, should be done automatically at IPsec startup;
542 currently-accepted values are
552 (signifying that plus an
559 (signifying that plus an
567 (also the default) (signifying no automatic startup operation).
568 This parameter is ignored unless the
574 configuration parameter is set suitably; see the
583 whether authentication should be done as part of
584 ESP encryption, or separately using the AH protocol;
585 acceptable values are
594 how the two security gateways should authenticate each other;
595 acceptable values are
598 for shared secrets (the default) and
601 for RSA digital signatures
607 should be identified for authentication;
611 Can be an IP address (in any
612 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3)
615 or a fully-qualified domain name preceded by
618 (which is used as a literal string and not resolved).
619 <DT><B>leftrsasigkey</B>
622 the left participant's
623 public key for RSA signature authentication,
624 in RFC 2537 format using
625 <I><A HREF="ipsec_ttodata.3.html">ipsec_ttodata</A></I>(3)
631 means to fetch it from DNS (at the time
632 the connection description is read from
636 The identity used for the left participant
637 must be a specific host, not
640 or another magic value.
643 if two connection descriptions
644 specify different public keys for the same
647 confusion and madness will ensue.
651 whether Perfect Forward Secrecy of keys is desired on the connection's
653 (with PFS, penetration of the key-exchange protocol
654 does not compromise keys negotiated earlier);
655 acceptable values are
665 how long a particular instance of a connection
666 (a set of encryption/authentication keys for user packets) should last,
667 from successful negotiation to expiry;
668 acceptable values are an integer optionally followed by
672 or a decimal number followed by
681 in minutes, hours, or days respectively)
688 Normally, the connection is renegotiated (via the keying channel)
690 <DT><B>rekeymargin</B>
693 how long before connection expiry should attempts to
694 negotiate a replacement
695 begin; acceptable values as for
704 maximum percentage by which
707 should be randomly increased to randomize rekeying intervals
708 (important for hosts with many connections);
709 acceptable values are an integer,
710 which may exceed 100,
713 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),
721 after this random increase,
728 will suppress time randomization.
729 <DT><B>keyingtries</B>
732 how many attempts (an integer) should be made to
733 negotiate a connection, or a replacement for one, before giving up
740 means ``never give up''
741 <DT><B>ikelifetime</B>
744 how long the keying channel of a connection (buzzphrase: ``ISAKMP SA'')
745 should last before being renegotiated;
746 acceptable values as for
750 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),
759 <A NAME="lbAG"> </A>
760 <H3>CONN PARAMETERS: MANUAL KEYING</H3>
762 The following parameters are relevant only to manual keying,
763 and are ignored in automatic keying.
765 connection must specify at least one of AH or ESP.
773 required for manual keying)
774 the SPI number to be used for the connection (see
775 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8));
777 must be of the form <B>0x</B><I>hex</I><B></B>,
781 is one or more hexadecimal digits
782 (note, it will generally be necessary to make
788 to be acceptable to KLIPS,
789 and use of SPIs in the range
790 <B>0x100</B>-<B>0xfff</B>
799 required for manual keying)
800 the base number for the SPIs to be used for the connection (see
801 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8));
803 must be of the form <B>0x</B><I>hex</I><B>0</B>,
807 is one or more hexadecimal digits
808 (note, it will generally be necessary to make
814 for the resulting SPIs
815 to be acceptable to KLIPS,
816 and use of numbers in the range
817 <B>0x100</B>-<B>0xff0</B>
823 ESP encryption/authentication algorithm to be used
824 for the connection, e.g.
827 (must be suitable as a value of
828 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
833 default is not to use ESP
838 (must be suitable as a value of
839 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
844 (may be specified separately for each direction using
849 <B>rightespenckey</B>
852 <DT><B>espauthkey</B>
855 ESP authentication key
856 (must be suitable as a value of
857 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
862 (may be specified separately for each direction using
863 <B>leftespauthkey</B>
867 <B>rightespauthkey</B>
870 <DT><B>espreplay_window</B>
873 ESP replay-window setting,
880 default, which turns off replay protection) to
883 relevant only if ESP authentication is being used
884 <DT><B>leftespspi</B>
887 SPI to be used for the leftward ESP SA, overriding
888 automatic assignment using
894 typically a hexadecimal number beginning with
900 AH authentication algorithm to be used
901 for the connection, e.g.
904 (must be suitable as a value of
905 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
910 default is not to use AH
917 is present) AH authentication key
918 (must be suitable as a value of
919 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
924 (may be specified separately for each direction using
932 <DT><B>ahreplay_window</B>
935 AH replay-window setting,
942 default, which turns off replay protection) to
948 SPI to be used for the leftward AH SA, overriding
949 automatic assignment using
955 typically a hexadecimal number beginning with
959 <A NAME="lbAH"> </A>
960 <H2>CONFIG SECTIONS</H2>
965 section known to the IPsec software is the one named
968 which contains information used when the software is being started
970 <I><A HREF="ipsec_setup.8.html">ipsec_setup</A></I>(8)).
979 interfaces="ipsec0=eth1 ipsec1=ppp0"
983 plutoload="snta sntb sntc sntd"
989 Parameters are optional unless marked ``(required)''.
990 The currently-accepted
1000 <DT><B>interfaces</B>
1004 virtual and physical interfaces for IPsec to use:
1006 <I>virtual</I><B>=</B><I>physical</I> pair, a (quoted!) list of pairs separated
1009 <B>%defaultroute</B>,
1011 which means to find the interface <I>d</I> that the default route points to,
1012 and then act as if the value was ``<B>ipsec0=</B><I>d</I>''.
1014 <B>%defaultroute</B>
1017 information about the default route and its interface is noted for
1019 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8)
1022 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8).)
1024 <DT><B>forwardcontrol</B>
1030 should turn IP forwarding on
1031 (if it's not already on) as IPsec is started,
1032 and turn it off again (if it was off) as IPsec is stopped;
1033 acceptable values are
1039 For this to have full effect, forwarding must be
1040 disabled before the hardware interfaces are brought
1042 <B>net.ipv4.ip_forward = 0</B>
1045 <I>/etc/sysctl.conf</I>),
1047 because IPsec doesn't get control early enough to do that.
1052 <I><A HREF="syslog.2.html">syslog</A></I>(2)
1054 ``facility'' name and priority to use for
1055 startup/shutdown log messages,
1057 <B>daemon.error</B>.
1059 <DT><B>klipsdebug</B>
1062 how much KLIPS debugging output should be logged.
1067 means no debugging output (the default).
1072 Otherwise only the specified types of output
1073 (a quoted list, names separated by white space) are enabled;
1074 for details on available debugging types, see
1075 <I><A HREF="ipsec_klipsdebug.8.html">ipsec_klipsdebug</A></I>(8).
1077 <DT><B>plutodebug</B>
1080 how much Pluto debugging output should be logged.
1085 means no debugging output (the default).
1090 Otherwise only the specified types of output
1091 (a quoted list, names without the
1095 separated by white space) are enabled;
1096 for details on available debugging types, see
1097 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8).
1102 in what directory should things started by
1105 (notably the Pluto daemon) be allowed to
1107 The empty value (the default) means they are not
1124 <B>dump=/var/tmp</B>.
1126 <DT><B>manualstart</B>
1129 which manually-keyed connections to set up at startup
1130 (empty, a name, or a quoted list of names separated by white space);
1132 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8).
1138 whether to start Pluto or not;
1146 (useful only in special circumstances).
1147 <DT><B>plutoload</B>
1150 which connections (by name) to load
1151 into Pluto's internal database at startup
1152 (empty, a name, or a quoted list of names separated by white space);
1154 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8)
1158 If the special value
1161 is used, all connections with
1170 <DT><B>plutostart</B>
1173 which connections (by name) to attempt to negotiate
1174 at startup (empty, a name, or a quoted
1175 list of names separated by white space);
1176 any such names which do not appear in
1179 are implicitly added to it.
1181 If the special value
1184 is used, all connections with
1191 and all connections with
1195 <DT><B>plutowait</B>
1198 should Pluto wait for each
1201 negotiation attempt to
1202 finish before proceeding with the next?
1210 <DT><B>plutobackgroundload</B>
1213 obsolete parameter, ignored, nominally specifying whether
1214 loading and starting of connections should be spun off as a background
1215 process to avoid startup delays.
1216 This is now always done.
1227 shell command to run before starting Pluto
1228 (e.g., to decrypt an encrypted copy of the
1229 <I>ipsec.secrets</I>
1232 It's run in a very simple way;
1233 complexities like I/O redirection are best hidden within a script.
1234 Any output is redirected for logging,
1235 so running interactive commands is difficult unless they use
1238 or equivalent for their interaction.
1240 <DT><B>postpluto</B>
1243 shell command to run after starting Pluto
1244 (e.g., to remove a decrypted copy of the
1245 <I>ipsec.secrets</I>
1248 It's run in a very simple way;
1249 complexities like I/O redirection are best hidden within a script.
1250 Any output is redirected for logging,
1251 so running interactive commands is difficult unless they use
1254 or equivalent for their interaction.
1259 whether a tunnel's need to fragment a packet should be reported
1260 back with an ICMP message,
1261 in an attempt to make the sender lower his PMTU estimate;
1262 acceptable values are
1269 <DT><B>packetdefault</B>
1272 what should be done with
1273 a packet which reaches KLIPS (via a route into a virtual interface)
1274 but does not match any eroute;
1275 acceptable values are
1278 (<I>insecure unless you really know what you're doing!!!</I>),
1288 but eventually it will send an ICMP notification back
1290 <DT><B>no_eroute_pass</B>
1293 obsolete parameter similar to
1294 <B>packetdefault</B>
1296 but with more limited functionality;
1298 <B>packetdefault</B>
1301 acceptable values are
1305 <B>packetdefault=pass</B>)
1311 <B>packetdefault=drop</B>)
1317 whether a tunnel packet's TOS field should be set to
1320 rather than copied from the user packet inside;
1321 acceptable values are
1328 <DT><B>uniqueids</B>
1331 whether a particular participant ID should be kept unique,
1332 with any new (automatically keyed)
1333 connection using an ID from a different IP address
1334 deemed to replace all old ones using that ID;
1335 acceptable values are
1342 <DT><B>overridemtu</B>
1345 value that the MTU of the ipsec<I>n</I> interface(s) should be set to,
1346 overriding IPsec's (large) default.
1347 This parameter is needed only in special situations.
1349 <A NAME="lbAI"> </A>
1353 <A NAME="lbAJ"> </A>
1356 <A HREF="ipsec.8.html">ipsec</A>(8), <A HREF="ipsec_ttoaddr.8.html">ipsec_ttoaddr</A>(8), <A HREF="ipsec_auto.8.html">ipsec_auto</A>(8), <A HREF="ipsec_manual.8.html">ipsec_manual</A>(8), <A HREF="ipsec_rsasigkey.8.html">ipsec_rsasigkey</A>(8)
1357 <A NAME="lbAK"> </A>
1360 Designed for the FreeS/WAN project
1361 <<A HREF="http://www.freeswan.org">http://www.freeswan.org</A>>
1363 <A NAME="lbAL"> </A>
1366 Including attributes of the keying channel
1367 (authentication methods,
1371 as an attribute of a connection,
1372 rather than of a participant pair, is dubious and incurs limitations.
1375 In general, the defaults often were chosen for backward compatibility
1376 and are less than ideal.
1387 is not nearly as generous about the syntax of subnets,
1388 addresses, etc. as the usual FreeS/WAN user interfaces.
1389 Four-component dotted-decimal must be used for all addresses.
1393 smart enough to translate bit-count netmasks to dotted-decimal form.
1396 It would be good to have a line-continuation syntax,
1397 especially for the very long lines involved in
1401 The ability to specify different identities,
1404 and public keys for different automatic-keyed connections
1405 between the same participants is misleading;
1406 this doesn't work dependably because the identity of the participants
1407 is not known early enough.
1408 This is especially awkward for the ``Road Warrior'' case,
1409 where the remote IP address is specified as
1412 and that is considered to be the ``participant'' for such connections.
1415 In principle it might be necessary to control MTU on an
1416 interface-by-interface basis,
1417 rather than with the single global override that
1424 <A NAME="index"> </A><H2>Index</H2>
1426 <DT><A HREF="#lbAB">NAME</A><DD>
1427 <DT><A HREF="#lbAC">DESCRIPTION</A><DD>
1428 <DT><A HREF="#lbAD">CONN SECTIONS</A><DD>
1430 <DT><A HREF="#lbAE">CONN PARAMETERS: GENERAL</A><DD>
1431 <DT><A HREF="#lbAF">CONN PARAMETERS: AUTOMATIC KEYING</A><DD>
1432 <DT><A HREF="#lbAG">CONN PARAMETERS: MANUAL KEYING</A><DD>
1434 <DT><A HREF="#lbAH">CONFIG SECTIONS</A><DD>
1435 <DT><A HREF="#lbAI">FILES</A><DD>
1436 <DT><A HREF="#lbAJ">SEE ALSO</A><DD>
1437 <DT><A HREF="#lbAK">HISTORY</A><DD>
1438 <DT><A HREF="#lbAL">BUGS</A><DD>
1441 This document was created by
1442 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
1443 using the manual pages.<BR>
1444 Time: 05:09:30 GMT, June 19, 2001