1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
5 <meta http-equiv="Content-Type" content="text/html">
6 <title>FreeS/WAN configuration</title>
8 content="Linux, IPsec, VPN, security, FreeSWAN, configuration">
11 Written by Sandy Harris for the Linux FreeS/WAN project
12 Freely distributable under the GNU General Public License
14 More information at www.freeswan.org
15 Feedback to users@lists.freeswan.org
18 RCS ID: $Id: config.html,v 1.65 2002/03/03 21:48:53 sandy Exp $
19 Last changed: $Date: 2002/03/03 21:48:53 $
20 Revision number: $Revision: 1.65 $
22 CVS revision numbers do not correspond to FreeS/WAN release numbers.
27 <h1><a name="setup">Configuration</a></h1>
29 <p>This section describes setting up and testing Linux FreeS/WAN.</p>
31 <p>This document is almost obsolete. It is being replaced by our new <a
32 href="quickstart.html">Quickstart Guide</a>. We recommend that most users use
35 <p>There are separate documents on <a href="testing.html">testbed
36 configurations</a> and <a href="performance.html">performance measurement</a>
37 which some users may want to consult along with this one. If you just want to
38 get a few connections up, this document should have everything you need.</p>
40 <p>Before attempting this, you should:</p>
42 <li>look at our <a href="intro.html">introduction</a> section. We assume
43 here that you understand concepts and terms described there.</li>
44 <li>ensure that FreeS/WAN is installed on your system. See these links:
46 <li><a href="install.html#testinstall">testing</a> whether FreeS/WAN is
48 <li>performing an <a href="install.html">installation</a></li>
53 <p>You also need to set up and test IP networking on all the machines you
54 plan to install FreeS/WAN on or to use in testing, before trying to set up
57 <h2><a name="example.simple">Our example networks</a></h2>
59 <p>In our examples, we describe a setup with three networks -- two that want
60 to talk to each other plus the Internet in the middle. The idea is to build
61 an encrypted tunnel across the Internet so the two networks can talk
64 <p>We'll call the two gateways East and West. We'll have a client machine on
65 each net: Sunrise in the East and Sunset in the West.</p>
66 <pre> Sunset==========West------------------East=========Sunrise
67 local net untrusted net local net</pre>
69 <p>Of course one does not always have a security gateway separate from the
70 client machine. It is also quite common to use IPsec on a network that looks
72 <pre> telecommuter's PC or
74 Sunset==========West------------------East
75 corporate LAN untrusted net</pre>
77 <p>We treat this setup as degenerate cases of the network-to-network link.
78 The East computer is a gateway for a one-client subnet, and it is also the
81 <p>Our goal here is to tell you how to set up the two gateways, East and
82 West. We assume your goal is to ensure that East and West encrypt all traffic
85 <p>More complicated network configurations are described later.</p>
87 <h2><a name="setupnet">Set up and test networking</a></h2>
89 <p>Before trying to get FreeS/WAN working, you should configure and test IP
90 networking on both gateways and on at least one client machine behind each of
91 them. <strong>IPsec cannot work without a working IP network beneath
94 <p>Many reported "FreeS/WAN problems" turn out to actually be problems with
95 routing or firewalling. If any actual IPsec problems turn up, you often
96 cannot even recognise them (much less debug them) unless the underlying
99 <p>If you need advice on this, your best sources are likely:</p>
102 href="http://www.linuxdoc.org/HOWTO/Net-HOWTO/index.html">Networking
104 <li>the <a href="http://www.linuxdoc.org/LDP/nag2/index.html">Network
105 Administrator's Guide</a>.</li>
107 href="http://netfilter.samba.org/unreliable-guides/networking-concepts-HOWTO/index.html">Linux
108 Networking-concepts HOWTO</a> from Rusty Russell, author of most of the
109 Linux firewalling code</li>
112 <p>See also our <a href="biblio.html">bibliography</a>.</p>
114 <p>Here is our network diagram again:</p>
115 <pre> Sunset==========West------------------East=========Sunrise
116 local net untrusted net local net</pre>
118 <p>The client machines, Sunrise and Sunset in our example, may have assigned
119 <a href="glossary.html#routable">routable</a> IP addresses, or they may be
120 using private <a href="glossary.html#non-routable">non-routable</a> addresses
121 (as defined in <a href="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</a>)
122 with the gateways doing <a href="glossary.html#masq">IP masquerade</a>. It
123 doesn't matter which, as long as whatever it is works correctly. Note,
124 however, that the two client subnets must have distinct addresses. You cannot
125 have them both masqueraded to the same range of RFC 1918 addresses.</p>
127 <p>You must have a working IP network before you try to add IPsec:</p>
129 <li>If Sunrise and Sunset have routable IP addresses, test that they can
130 ping each other.</li>
131 <li>If IP masquerading is in use, test as far as you can. Even with
132 masquerading on both ends, Sunset should be able to ping East and Sunrise
133 able to ping West.</li>
136 <p>It is not enough to just test that your gateways (East and West in the
137 example) can communicate. You need to test routing to the clients (Sunrise
138 and Sunset) as well.</p>
140 <p>If you want to run some service encapsulated in IP -- perhaps to use
141 Novell protocols encapsulated in IPX or to make Windows file sharing or NT
142 domains work across the IPsec tunnel -- then <em>please</em> build and test
143 what you need for that service on plain IP before trying it over IPsec. It
144 can be a real nightmare trying to debug such things when you don't know if
145 the problem is in IPsec, firewall rules, routing, or the configuration of the
146 service itself. Some advice on making such things work with IPsec is in our
147 <a href="interop.html#NTdomain">interoperation</a> section.</p>
149 <h3><a name="forward">Enabling packet forwarding</a></h3>
151 <p>Some systems turn off packet forwarding by default. This is the safe
152 default. You don't want systems forwarding packets in uncontrolled ways.</p>
154 <p>There are three places where you can enable or disable IP forwarding:</p>
156 <dt>in kernel configuration, before compiling the kernel</dt>
157 <dd>for FreeS/WAN use, forwarding must always be enabled here. If
158 forwarding is not compiled into your kernel, attempts to enable or use
160 <dt>in the standard boot scripts.</dt>
161 <dd>If your kernel has forwarding, you can have it turned on
162 automatically by the standard boot scripts. The exact method varies
163 from distribution to distribution:
165 <dt>Older Redhat</dt>
166 <dd>in the file <var>/etc/sysconfig/network</var>, set <var>
167 FORWARD_IPV4=yes</var></dd>
168 <dt>Redhat 6.x and 7.0</dt>
169 <dd>in the file <var>/etc/sysconfig/network</var>, set <var>
170 net.ipv4.ip_forward=1</var></dd>
171 <dt>Debian r2.2 systems (and most likely Debian r2.2 derived
173 <dd>in the file <var>/etc/network/options</var>, set <var>
174 ip_forward=yes</var></dd>
177 <dt>From the command line or your own scripts</dt>
179 <pre> echo "1" > /proc/sys/net/ipv4/ip_forward</pre>
180 You need root privileges to write to that file.</dd>
183 <p>A gateway machine needs forwarding enabled or it will not route packets
184 between the two networks it is attached to. The simplest way to ensure this
185 is to enable forwarding using your distribution's standard boot scripts. See
188 <p>A more conservative approach is to disable forwarding in your system
189 configuration, and only enable it after appropriate firewall rules and IPsec
190 tunnels are in place. This reduces the risk of something slipping past your
191 defenses before they are fully set up. On most systems, this can conveniently
192 be done by adding a line to <var>/etc/rc.d/rc.local</var>, which is usually
193 the last script run at boot time.</p>
195 <h3><a name="othersoft">Other software</a></h3>
197 <p>Configure and test any other software you will want to use for testing
198 once IPsec is up. For example, you might put an HTTP daemon on Sunset and a
199 browser on Sunrise. Make sure these work without IPsec.</p>
201 <p>If these tests fail, figure out why and fix it. <strong>Do not proceed
202 until it works.</strong></p>
204 <h2><a name="usersakey">Setting up RSA authentication keys</a></h2>
206 <p>To build a connection, the two gateway machines must be able to
207 authenticate each other. For FreeS/WAN, the default is <a
208 href="glossary.html#public">public key</a> authentication based on the <a
209 href="glossary.html#RSA">RSA</a> algorithm. IPsec does allow several other
210 authentication methods; using some of them with FreeS/WAN is discussed in our
211 <a href="adv_config.html#choose">advanced configuration</a> section.</p>
213 <p>This section covers setting up RSA keys. The example connections to follow
214 (VPN, road warrior and opportunistic) all use RSA.</p>
216 <h3><a name="rsa.basics">How RSA works</a></h3>
218 <p>RSA keys are created as matched pairs. Each pair includes:</p>
220 <li>a <strong>public key</strong> which need not be kept secure. Everyone
221 you plan to communicate with must be able to get a copy of this. It does
222 not matter if an enemy gets it as well.</li>
223 <li>a <strong>private key</strong> which must be kept secure. No-one but
224 you should have access to it.</li>
227 <p>For FreeS/WAN, both keys for your system are in the <a
228 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> file.
229 <strong>Maintaining security of this file is essential</strong> since it
230 holds your private key.</p>
232 <p>Public keys for the gateways you communicate with must be made available
233 to your gateway. There are several ways to do this:</p>
235 <li>arrange for the administrators of those gateways to place their public
236 keys in their <a href="glossary.html#DNS">DNS</a> records so your gateway
237 can look them up as required</li>
238 <li>collect the public keys for the gateways you talk to, and place them in
239 the connection descriptions for those gateways in <a
240 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</li>
241 <li>if you are using the X.509 <a href="web.html#patch">patches</a>,
242 collect X.509 certificates for the other gateways, and place them in the
243 appropriate file</li>
246 <p>The first two methods are described in more detail below. See the X.509
247 patch documentation for details of the third, if required.</p>
249 <p>Remember that public key systems are designed so that <strong>it does not
250 matter if an enemy knows the public keys</strong>. However, the
251 <strong>private keys must be scrupulously protected</strong>.</p>
253 <h3><a name="genrsakey">Generating an RSA key pair</a></h3>
255 <p>If you installed FreeS/WAN yourself, then the installation process has
256 already generated an RSA key pair for you and placed it in the <a
257 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> file. If not, then
258 you need to generate an RSA key pair (private and public).</p>
260 <p>If you have the common simple situation where:</p>
262 <li>the gateway needs only one RSA private key</li>
263 <li>the output of the <var>hostname</var> command is a suitable
267 <p>then you can just give these commands as root:</p>
268 <pre> ipsec newhostkey > /etc/ipsec.secrets
269 chmod 600 /etc/ipsec.secrets</pre>
271 <p>For other options, for example if you want to use different identities
272 with different partners, see the <a
273 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> and <a
274 href="manpage.d/ipsec_newhostkey.8.html">ipsec_newhostkey(8)</a> man
277 <p>Key generation may take some time, even on a fast system. Also, it needs a
278 lot of <a href="glossary.html#random">random numbers</a> so you may need to
279 switch consoles and do something like typing a lot of text or running
280 <nobr><var>du / > /dev/null</var></nobr>. These give <var>random(4)</var>
281 some inputs to work with.</p>
283 <p>The RSA keys we generate are suitable <strong>only</strong> for
284 authentication, not for encryption. IPsec uses them only for authentication.
285 See our <a href="ipsec.html">IPsec</a> section for details.</p>
287 <p>It is also possible to use keys in other formats, not generated by
288 FreeS/WAN. This may be necessary for interoperation with other IPsec
289 implementations. See our links to <a href="web.html#patch">patches</a> which
290 add support for keys generated by PGP or embedded in X.509 certificates.</p>
292 <h3><a name="keyexchange">Exchanging authentication keys</a></h3>
293 Once your gateway's key is in <a
294 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a>, the next step is
295 to send your public key to everyone you need to set up connections with and
296 collect their public keys. The other players will be:
299 <dd>each gateway administrator needs public keys for all the other
300 gateways his or her machine talks to</dd>
301 <dt>for a Road Warrior</dt>
302 <dd>the gateway needs public keys for all Warriors that connect to it,
303 and each Warrior needs the gateway public key</dd>
304 <dt>for opportunistic encryption</dt>
305 <dd>no explicit key exchange is needed, but you must put your public key
306 in DNS so others can find it when they need it</dd>
309 <p>You need to extract the public part in a suitable suitable format. This
311 href="manpage.d/ipsec_showhostkey.8.html">ipsec_showhostkey(8)</a> command.
312 For VPN or Road Warrior applications, use one of:</p>
313 <pre> ipsec showhostkey --left
314 ipsec showhostkey --right</pre>
316 <p>These two produce the key formatted for insertion in an <a
317 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file.</p>
319 <p>For opportunistic encryption, just use:</p>
320 <pre> ipsec showhostkey</pre>
321 This gives the key in a format suitable for use in DNS records.
323 <p>Public keys need not be protected as fanatically as private keys. They are
324 intended to be made public; the system is designed to work even if an enemy
325 knows all the public keys used. You can safely make them publicly accessible
326 -- for example, put a gateway key on a web page, make in available in DNS or
327 via finger(1) -- or transmit it with an insecure method such as email.
328 However, the recipient <em>must</em> be able to authenticate them, as
329 described in the next section.</p>
331 <h3><a name="pub.auth">Authenticating public key exchange</a></h3>
332 Authentication of public keys is critical. It does not matter if an enemy
333 knows your public keys, but <strong>if you can be tricked into trusting a
334 public key supplied by an enemy, you are in deep trouble</strong>.
336 <p>For example, consider the fellow who wants to communicate with his
337 mistress, keeping messages secret from his wife.</p>
339 <li>If the wife obtains the mistress' public key, that is not a problem. As
340 long as she does not get the private key, she can neither read things
341 sent to the mistress nor authenticate herself as the mistress.</li>
342 <li>If the mistress has any sense, she protects her private key carefully.
343 So long as she does that, and the husband encrypts his messages
344 correctly, there should be no (cryptographic!) problem.</li>
345 <li>Imagine that the wife is somewhat devious. She generates a
346 public/private key pair and sends the husband that public key, forging
347 the message to look as if it came from the mistress. Of course <em>this
348 fails if the husband has enough sense to check the key's validity</em>
349 before using it.</li>
350 <li>However, if the husband blindly <em>accepts that key without
351 verification</em>, it is <em>extremely</em> unlikely that he will be
352 pleased with the results.</li>
353 <li>If he accepts that key, the wife can read every message he sends to it.
354 The mistress cannot.</li>
355 <li>The wife can also pose as the mistress and send him whatever bogus
356 messages she likes. As long as he trusts that key, he will believe these
357 came from the mistress.</li>
360 <p>The minute he begins to trust a bogus key, the cryptography does not just
361 stop working for him. Instead, it becomes a powerful weapon against him.</p>
363 <p>You <strong>must authenticate any public keys received</strong> before
364 using them. For remote sites, the simplest method is to exchange them using
365 <a href="glossary.html#PGP">PGP</a>-signed email (taking appropriate steps to
366 authenticate the signing keys). Keys posted on the web or made available for
367 finger(1) should also be PGP-signed. Keys in DNS should be protected by <a
368 href="glossary.html#SDNS">DNS Security</a>. For nearby machines, a floppy
369 disk or trusted network is fine.</p>
371 <h3><a name="useRSA">Using RSA signatures for authentication</a></h3>
373 <p>For each system you will communicate with, you need an RSA public key and
374 an identifier associated with it. The identifiers go in the
375 <var>leftid=</var> and <var>rightid=</var> lines of connection descriptions
376 in <var>ipsec.conf(5)</var>. They are the names the systems use to identify
377 themselves during connection negotiation.</p>
379 <p>The syntax rules allow four types of identifier:</p>
381 <li>an IP address in dotted quad notation, four numbers separated by
382 periods (10.1.19.32).</li>
383 <li>a domain name, which will be resolved immediately
384 (bad.example.com).</li>
385 <li>a fully qualified domain name (FQDN) with a leading "@" to indicate
386 that it should not be resolved (@good.example.com)</li>
387 <li>user@FQDN (fred@example.com)</li>
390 <p><strong>We recommend that only the @FQDN form be used</strong> in most
391 applications. The other three forms have problems:</p>
393 <li>IP addresses make remarkably uninteresting names</li>
394 <li>Resolving a name to an IP address is not useful. Why pay the overheads
395 just to get something that, in this context, is less interesting than the
396 name you started with? Also, the attempt to resolve it may cause long
397 delays if DNS is down or may cause security problems if someone subverts
398 a DNS server which you rely on.</li>
399 <li>fred@example.com has no advantage over @fred.example.com</li>
402 <p>If your domain is example.com, the gateway identifiers you use should be
403 all be of the form "@<var>something</var>.example.com" with some convenient
404 string replacing <var>something</var>.</p>
406 <p>In order to facilitate distributing keys through DNS, we recommend
409 <li>names from non-existent domains</li>
410 <li>names from other people's domains</li>
411 <li>names which conflict with machine names in your domain</li>
415 <p>For example, if you have a server alice.example.com, then you should not
416 use "@alice.example.com" to identify Alice's laptop for IPsec.</p>
418 <p>One convenient scheme is to</p>
420 <dt>use DNS names for your gateways</dt>
421 <dd>their IPsec identifiers are things like @firewall.example.com or
422 @toronto.example.com</dd>
423 <dt>add a "road" label in the identifiers for your remote users ("Road
425 <dd>Alice's laptop uses the identifier @alice.road.example.com.</dd>
428 <h2><a name="basic.conf">The configuration file</a></h2>
430 <p>FreeS/WAN uses a configuration file, <a
431 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</p>
432 This section describes setting up the parts of that file that apply to all
435 <dt><var>config setup</var> section</dt>
436 <dd>describes machine configuration</dd>
437 <dt><var>conn default</var> section</dt>
438 <dd>default parameters which apply to all connections</dd>
441 <p>and gives an introduction to the parts of the file that specify the actual
442 connections. The following section covers setting up three common types of
443 connection, all using automatic keying with RSA authentication of the
446 <dt>conventional VPN</dt>
447 <dd>two security gateways, each with a known fixed IP address and with a
448 network of client machines behind it</dd>
449 <dt>Road Warrior</dt>
450 <dd>one player has a dynamically-assigned address</dd>
451 <dt>opportunistic encryption</dt>
452 <dd>the two machines have no prior knowledge of each other, but are set
453 up to secure connections whenever possible</dd>
456 <p>Setup is quite similar for each of these, but details differ.</p>
458 <p>Other types of connections are covered in later sections.</p>
460 <p>The easiest way to create a connection is by editing one of our examples.
461 Here we will use the one in the installation <a
462 href="manpage.d/ipsec.conf.5.html">ipsec.conf</a> file. You could also start
463 with one from our <a href="examples">doc/examples</a> file if one of those is
464 closer to what you need to do.</p>
466 <h3><a name="ipsec.conf.general">General comments on ipsec.conf</a></h3>
467 The <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file is divided
468 into sections, and the following rules apply:
470 <li>the '#' character marks a comment</li>
471 <li>the first uncommented line of a section must be at the margin, not
473 <li>all other non-comment lines of a section must be indented</li>
474 <li>blank lines separate sections</li>
475 <li>you cannot put a blank line within a section; use a lone '#'
479 <p>For more detail, see the <a href="manpage.d/ipsec.conf.5.html">man
482 <h4><a name="which">Which is which?</a></h4>
484 <p>The confguration file uses <var>left</var> and <var>right</var> to refer
485 to the two gateways involved in a connection, and has other parameters which
486 come in left/right pairs. For example, <var>leftsubnet</var> is the subnet
487 behind <var>left</var>.</p>
489 <p>Which gateway is <var>left</var> and which is <var>right</var> is
490 arbitrary, entirely up to you.</p>
492 <p>We suggest that you name connections by their ends. For example, name the
493 link between Fred and Susan's machines "fred-susan" or the link between your
494 Reno and Vancouver offices "reno-van". You can then let "left" refer to the
495 left half of the name, "fred" or "reno" in our examples, and "right" to the
498 <p>To simplify administration, we recommend that you use the same names in
499 the <var>ipsec.conf(5)</var> files on both ends. The name <var>reno</var>,
500 for example, should refer to the machine in Reno, no matter which city the
503 <p>Then when you copy the file from one machine to the other, the
504 <em>only</em> change you need to make on the second machine is changing the
505 <var>interfaces=</var> line to match the interface that machine uses for
508 <p>Of course the software does not actually require this. The names are just
509 arbitrary strings to it. If your administrator in Reno wants to refer to the
510 machines as "Phobos" and "Demios" while the Vancouver admin calls them
511 "George" and "Gracie", things should still work.</p>
513 <h3><a name="setup.conf">The setup section of ipsec.conf(5)</a></h3>
515 <p>The first section of <a
516 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> contains overall setup
517 parameters for IPsec, which apply to all connections. In our example file, it
519 <pre># basic configuration
521 # THIS SETTING MUST BE CORRECT or almost nothing will work;
522 # %defaultroute is okay for most simple cases.
523 interfaces=%defaultroute
524 # Debug-logging controls: "none" for (almost) none, "all" for lots.
527 # Use auto= parameters in conn descriptions to control startup actions.
530 # Close down old connection when new one using same ID shows up.
533 <p>The variables set here are:</p>
536 <dd>Tells the <a href="glossary.html#KLIPS">KLIPS</a> IPsec code in the
537 Linux kernel which network interface to use. The interfaces specified
538 here are the only ones this gateway machine will use to communicate
539 with other IPsec gateways. <strong>If this is not correct, nothing
541 <p>In many cases, the appropriate interface is just your default
542 connection to the world (the Internet, or your corporate network). In
543 these cases, you can use the default setting:</p>
545 <li>interfaces=%defaultroute</li>
547 <p>To check what FreeS/WAN sees as the default route, you can use the
548 command <var>ipsec showdefaults</var>. You may need to compare this
549 with the output from <var>route -n</var> to get a more complete
551 <p>In other cases, you can name one or more specific interfaces to be
552 used by FreeS/WAN. For example:</p>
554 <li>interfaces="ipsec0=eth0"</li>
555 <li>interfaces="ipsec0=eth0 ipsec1=ppp0"</li>
557 <p>Both tell KLIPS to use eth0 as ipsec0. The second one also supports
561 <li>Multiple tunnels do not require multiple interfaces. It is
562 possible, and even common, to have one ipsec interface carrying
563 traffic for many tunnels.</li>
564 <li>For PPP connections, you specify the virtual PPP interface (for
565 example <var>ppp0</var>) here, <strong>not</strong> the underlying
566 physical interface.</li>
568 <p>If you need to discover interface names, use the command:</p>
571 If you have PCMCIA or other interfaces that are not available at boot
572 time, special measures are required. See our <a
573 href="adv_config.html#dynamic">section</a> on that.</dd>
575 <dd>Debugging setting for the KLIPS kernel code</dd>
577 <dd>Debugging setting for the Pluto key and connection negotiation daemon.
578 <p><var>klipsdebug</var> and <var>plutodebug</var> can each be set to
579 "none" or to "all" in most circumstances. There are other options; see
580 the relevant man pages.</p>
583 <dd>List of connections to be automatically loaded into memory when Pluto
586 <dd>List of connections to be automatically negotiated when Pluto starts.
587 <p><var>plutoload</var> and <var>plutostart</var> can be quoted lists
588 of connection names, but are often set to <var>%search</var> as in our
589 example. Any connection with <var>auto=add</var> in its connection
590 definition is then loaded, and any connection with
591 <var>auto=start</var> is started.</p>
592 <p>In most cases, you want <var>plutostart=%search</var> here and
593 <var>auto=start</var> in your connection descriptions. That way when a
594 connection is broken, for example if one machine crashes or is taken
595 down for some reason, it will be reliably rebuilt. If only one end is
596 told to start the connection, then if the other end crashes, you may
597 lose the connection for a long time. The end that could rebuild does
598 not know it needs to.</p>
599 <p>The exception to the above is when you have many road warriors
600 connecting to a single gateway. Having the gateway trying to rebuild
601 tunnels to systems which are offline can waste considerable resources.
602 In this case, the gateway should have <var>auto=add</var> for all
603 connections, and let the remote systems start negotiations.</p>
606 <dd>Controls whether two connections with the same subnet on the remote
607 end are allowed. Normally this is set to <var>yes</var> so that when a
608 remote system disconnects and reconnects, Pluto will automatically take
609 the old connection down.</dd>
612 <h3><a name="conn.default">Connection defaults</a></h3>
614 <p>There is a special name <var>%default</var> that lets you define things
615 that apply to all connections.</p>
617 <p>You can also set general defaults here but override them later for
618 specific connections. If both the <var>%default</var> section and the actual
619 connection description set the same variable, then the connection description
620 takes precedence.</p>
622 <p>Our example file has:</p>
623 <pre># defaults for subsequent connection descriptions
625 # How persistent to be in (re)keying negotiations (0 means very).
627 # How to authenticate gateways
629 # Load all connection descriptions by default
630 # Some will override this with auto=start
633 <p>Variables set here are:</p>
636 <dd>How persistent to be in (re)keying negotiations (0 means very).
637 <p>For testing, you might wish to set this to some small number,
638 perhaps even to 1, to avoid wasting resources on incorrectly set up
639 connections. In production, it is often set to zero (retry forever).
640 Keeping the connection up is what machine resources are for, so if a
641 connection is down you might as well waste resources retrying as waste
642 them by sitting idle. Of course some caution should be exercised with
643 this, since it can waste network resources as well.</p>
645 <dt>authby=rsasig</dt>
646 <dd>authenticate gateways using RSA signatures. This is the preferred
647 method and is what we will use in this section's examples. An alternate
648 method is to use <a href="adv_config.html#prodsecrets">shared
651 <dd><strong>auto</strong>matically <strong>add</strong> connections
652 descriptions to Pluto's in-memory database at startup. This is required
653 before Pluto can recognise incoming requests for that connection, so we
654 suggest making it the default here.
655 <p>To actually start negotiations for a given connection, you need
656 <var>auto=start</var>. You could make that the default here or leave
657 <var>auto=add</var> as the default and override it where needed with
658 <var>auto=start</var> in individual connection descriptions.</p>
662 <p>Once you are finished testing, you can edit these defaults, adding
663 anything that is standard for all gateways in your organisation.</p>
665 <h3><a name="edit.conn">Editing a connection description</a></h3>
667 <p>Edit our example connection to match what you want to do. Rename it
668 appropriately for the connection you would like to build: "fred-susan",
669 "reno-van" or whatever. The name is the second string in the line that begins
670 with "conn", for example in:</p>
673 <p>The connection name is "snt" (<strong>s</strong>ub<strong>n</strong>et
674 <strong>t</strong>unnel) and to define another connection you make a copy
675 with a new name such as:</p>
676 <pre> conn reno-van</pre>
678 <p>A sample connection description is:</p>
680 # The network here looks like:
681 # leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
682 # If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
684 # left security gateway (public-network address)
686 # next hop to reach right
687 leftnexthop=10.44.55.66
688 # subnet behind left (omit if there is no subnet)
689 leftsubnet=172.16.0.0/24
690 # right s.g., subnet behind it, and next hop to reach left
692 rightnexthop=10.88.77.66
693 rightsubnet=192.168.0.0/24
696 <p>We omit here the variables we have shown as set in the default connection
697 above. All of them could also be set here. If they are set in both places,
698 settings here take precedence. Defaults are used only if the specific
699 connection description has no value set.</p>
701 <p>The network described above looks like this:</p>
702 <pre> subnet 172.16.0.0/24 =leftsubnet
708 interface 10.0.0.1 =left
710 interface 10.44.55.66 =leftnexthop
712 interface we don't know
716 interface we don't know
718 interface 10.88.77.66 =rightnexthop
720 interface 10.12.12.1 =right
721 right gateway machine
726 subnet 192.168.0.0/24 =rightsubnet</pre>
727 You need to edit the connection description, inserting appropriate IP
728 addresses and subnet descriptions so that it describes your network.
730 <p>The [whatever]s above indicate places where all that matters is
733 <li>in simple cases, the inside interface is directly connected to the
734 protected subnet and has an address on that subnet</li>
735 <li>in a large organisation, there might be several routers between gateway
738 It does not matter what is between the inside interface and the protected
739 subnet, as long as the gateway knows how to get packets to the subnet.
741 <p>You do not need to tell FreeS/WAN anything about the inside interfaces. In
742 fact, there is no parameter you could use to do that. What you do have to do
743 is make sure the gateway can route to its client subnet.</p>
745 <p>In most cases, you should use numeric IP addresses, not names, here. The
746 file syntax allows names to be used, but this creates an additional risk. If
747 someone can subvert the DNS service, then they can redirect packets whose
748 addresses are looked up via that service.</p>
750 <p>Many of the variables in this file come in pairs such as "leftsubnet: and
751 "rightsubnet", one for each end of the connection. The variables on the left
755 <dd>The gateway's external interface, the one it uses to talk to the
756 other gateway. This can be <var>left=%defaultroute</var>.</dd>
758 <dd>Where left should send packets whose destination is right, typically
759 the first router in the appropriate direction.
760 <p>This need not always be set.</p>
762 <li>If the two gateways are directly linked (packets can go from one
763 to the other without IP routing by any intermediate device) then
764 you need not set either <var>leftnexthop</var> or
765 <var>rightnexthop</var>.</li>
766 <li>a connection with <var>left=%defaultroute</var> or
767 <var>right=%defaultroute</var> must not have the corresponding
768 <var>nexthop</var> parameter set</li>
770 <p>However, <strong>in all other cases, you must provide nexthop
771 information</strong>. KLIPS (Kernel IP Security) bypasses the normal
772 routing machinery, so you must give KLIPS the information even though
773 routing already knows it.</p>
774 <p>(Yes, we know that design is not ideal, and we plan to change it.
775 See extensive discussions on the <a href="mail.html">mailing list</a>,
776 mostly with "routing" or "KLIPS 2" in the subject lines.)</p>
779 <dd>Addresses for the machines which left is protecting.
781 <li>Often something like 101.202.203.0/24 to indicate that a subnet
782 resides behind left. Often this subnet will be directly connected
783 to left, but this not necessary. The only requirement is that left
784 must be able to route to it.</li>
785 <li>If you omit the leftsubnet line, then left is both the security
786 gateway and the only client on that end.</li>
788 For some applications, you may want to create two connections, one to
789 protect traffic from the subnet behind left and another to protect
790 traffic from the left gateway itself. This takes two connection
791 descriptions. See <a href="adv_config.html#multitunnel">below</a>.</dd>
793 <dd>If the <var>conn setup</var> section has
794 <var>plutoload=%search</var>, then all connections marked
795 <var>auto=add</var> are loaded when Pluto starts.
796 <p>If the <var>conn setup</var> section has
797 <var>plutostart=%search</var>, then all connections marked
798 <var>auto=start</var> are started when Pluto starts.</p>
799 <p>Initially, we suggest using <var>auto=add</var> on all connections.
800 This lets you start them manually during testing. Once they are tested,
801 you can change many of them to <var>auto=start</var>.</p>
805 <p>For each left* parameter, there is a corresponding right* parameter.</p>
807 <p>Note that <em>a connection to a subnet behind left does not include left
808 itself</em>. The tunnel described above protects packets going <em>from one
809 subnet to the other</em>. It does not apply to packets which either begin or
810 end their journey on one of the gateways. If you need to protect those
811 packets, you must build separate tunnel descriptions for them.</p>
813 <p>It is a common error to attempt testing a subnet-to-subnet connection by
814 pinging from one of the gateways to the far end or vice versa. <strong>This
815 does not work</strong>, even if the connection is functioning perfectly,
816 because <em>traffic to or from the gateway itself is not sent on that
817 connection</em>. If you want to protect traffic originating or terminating on
818 the gateway, then you need a separate tunnel for that in addition to the
819 subnet's tunnel. See the section on <a
820 href="adv_config.html#multitunnel">multiple tunnels</a>.</p>
822 <h2><a name="examples">Example setups</a></h2>
824 <p>In this section we show examples of three common setups:</p>
826 <li>a VPN connection</li>
827 <li>road warrior support</li>
828 <li>opportunistic encryption</li>
831 <p>We use a, b, c ... to indicate components of IP addresses. Each letter is
832 some number in the range 0 to 255, inclusive.</p>
834 <p>For additional examples, see our <a href="examples">examples</a> file.</p>
836 <h3><a name="VPNex">VPN</a></h3>
837 For a site-to-site VPN, a simple network diagram looks like this:
838 <pre> Sunset==========West------------------East=========Sunrise
839 local net untrusted net local net</pre>
841 <p>which we describe in our config files as:</p>
842 <pre> leftsubnet === West------------------East=== rightsubnet
845 <p>In most cases, we also have to provide next hop information. A more
846 detailed diagram might look like this:<br>
847 (using a, b, c, ... to refer to arbitrary numbers 0 to 255)</p>
848 <pre> subnet a.b.c.0/24 =leftsubnet
849 | (head office has routable IP addresses)
852 interface e.f.g.h =left
853 | (external address outside a.b.c.0 subnet)
854 interface e.f.g.i =leftnexthop
856 interface we don't know
860 interface we don't know
862 interface j.k.l.m =rightnexthop
864 interface j.k.l.n =right
865 right gateway machine
866 interface 192.168.0.something
867 | (branch office uses private IP addresses)
868 subnet 192.168.0.0/24 =rightsubnet</pre>
870 <p>The <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file for the
871 above network would look like this (with RSA keys shortened for easy
873 <pre># basic configuration
875 interfaces="%defaultroute"
881 # defaults that apply to all connection descriptions
883 # How persistent to be in (re)keying negotiations (0 means very).
885 # How to authenticate gatways
888 # VPN connection for head office and branch office
890 # identity we use in authentication exchanges
891 leftid=@head.example.com
892 leftrsasigkey=0x175cffc641f...
893 # left security gateway (public-network address)
895 # next hop to reach right
897 # subnet behind left (omit if there is no subnet)
898 leftsubnet=a.b.c.0/24
899 # right s.g., subnet behind it, and next hop to reach left
900 rightid=@branch.example.com
901 rightrsasigkey=0xfc641fd6d9a24...
904 rightsubnet=192.168.0.0/24
906 # right is masquerading
907 # So you have three choices, none of them ideal
909 # uncomment this to use our default script
910 # which works only with ipfwadm(8) on 2.0 kernels
911 # or ipchains(8) on 2.2 in ipfwadm(8) emulation mode
914 # uncomment this and enter a name to write your own script
915 # to use all features of ipchains(8) on 2.2
916 # or to use iptables(8) on 2.4
917 # rightupdown=whatever_you_want_to_name_the_script
919 # if you uncomment neither and remove the rightsubnet= line
920 # then the tunnel terminates on the outside of your gateway
921 # and the masqueraded subnet is not visible to the remote
922 # subnet; they all think they're talking to the gateway
924 # try to start the connection
927 <p>For more on the use of the firewalling parameters --
928 <var>leftfirewall</var>, <var>rightfirewall</var>, <var>leftupdown</var> and
929 <var>rightupdown</var> -- see our <a href="firewall.html">IPsec and
930 firewalls</a> section.</p>
932 <p>The versions of this file at the two ends should be identical, except that
933 each must have an <var>interfaces=</var> line appropriate for the local
936 <h4><a name="route_or_not">Routable and non-routable addresses</a></h4>
938 <p>RFC 1918 reserves three groups of addresses for use on private
942 <li>172.16.0.0/12</li>
943 <li>192.168.0.0/16</li>
946 <p>Addresses in these ranges will never be assigned to anything on the
947 Internet. Many routers automatically drop any packet with one of these
948 addresses as either source or destination.</p>
950 <p>You can use FreeS/WAN to:</p>
952 <li>make such a network visible to remote clients. For example, with the
953 above description, any of the client machines on the
954 <var>leftsubnet</var> can talk to machines on
955 <var>rightsubnet=192.168.0.0/24</var>.</li>
956 <li>route between two such networks, using for example
957 <var>leftsubnet=192.168.1.0/24</var> and
958 <var>rightsubnet=192.168.0.0/24</var>.</li>
961 <p>If you do this, the non-routable addresses still do not appear on the
962 Internet. They are encapsulated inside IPsec packets which have the gateways'
963 external addresses (from the <var>left</var> and <var>right</var> parameters
964 of the connection description) in their headers.</p>
966 <p>Of course FreeS/WAN can also tunnel packets between subnets with normal
967 routable IP address.</p>
969 <h3><a name="roadex">Road Warrior</a></h3>
971 <p>For our purposes, a "road warrior" is any machine that does not have a
972 fixed IP address. This includes:</p>
974 <li>a traveller who might connect from anywhere</li>
975 <li>any machine that has a dynamic IP address -- nearly all dialup
976 connections and most DSL or cable modem connections, at least in North
978 <li>most home machines connecting to the office. If you have a home
979 firewall that is always left on and has a static IP address, then you can
980 use the <a href="#VPNex">VPN</a> configuration described above.
981 Otherwise, consider yourself a road warrior.</li>
984 <p>The configuration for road warrior support looks slightly different from a
985 VPN configuration. We cannot use the road warrior's IP address in the
986 configuration file since we don't know it, and we don't want to have our
987 server retrying connections to road warriors that are no longer online.</p>
989 <p>Some machines, such as home firewalls, may have a dynamic IP address and
990 have a protected subnet behind them. For this example, however, we assume the
991 Road Warrior is a standalone machine:</p>
992 <pre> telecommuter's PC or
994 Sunset==========West------------------East
995 corporate LAN untrusted net</pre>
997 <p>In more detail, the network looks like this:<br>
998 (using a, b, c, ... to refer to arbitrary numbers 0 to 255)</p>
999 <pre> subnet a.b.c.0/24 =leftsubnet
1000 | (head office has routable IP addresses)
1002 left gateway machine
1003 interface e.f.g.h =left
1004 | (external address outside a.b.c.0 subnet)
1005 interface e.f.g.i =leftnexthop
1010 interface with dynamic IP address
1011 road warrior machine</pre>
1013 <p>Here the <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> files on
1014 the two ends are slightly different. The one at the office might have exactly
1015 the same <var>config setup</var> and <var>conn %default</var> sections as in
1016 the VPN example.</p>
1017 <pre># basic configuration
1019 interfaces="%defaultroute"
1025 # defaults that apply to all connection descriptions
1027 # How persistent to be in (re)keying negotiations (0 means very).
1029 # How to authenticate gatways
1032 <p>Then add a description for the road warrior connection:</p>
1033 <pre># Connection for road warrior Fred
1035 # identity we use in authentication exchanges
1036 leftid=@head.example.com
1037 leftrsasigkey=0x175cffc641f...
1038 # left security gateway (public-network address)
1040 # next hop to reach right
1042 # subnet behind left (omit if there is no subnet)
1043 leftsubnet=a.b.c.0/24
1044 # accept any address for right
1046 # any address, provided authentication works
1047 rightid=@fred.road.example.com
1048 rightrsasigkey=0xd9a24765fe...
1050 # no subnet for a typical road warrior
1051 # it is possible, but usually not needed
1052 # so the rightsubnet= parameter is omitted
1054 # let the road warrior start the connection
1056 # override the default retry for road warriors
1057 # we don't want to retry if IP connectivity is gone
1060 <p>On the gateway end we use the values shown above:</p>
1062 <li><var>right=%any</var> so we have no preset idea of right's IP address
1063 and will accept whatever arrives on the packets</li>
1064 <li><var>auto=add</var> so we accept connections but don't initiate</li>
1065 <li><var>keyingtries=1</var> so we do not retry to excess when the partner
1066 disconnects or changes IP address</li>
1069 <p>The file on the road warrior end is nearly identical, except that it
1072 <li><var>interfaces=%defaultroute</var> to handle the dynamic IP
1074 <li><var>right=%defaultroute</var></li>
1075 <li><var>auto=start</var> to start the connection</li>
1076 <li><var>keyingtries=0</var> to try to maintain the connection</li>
1079 <p>Because we are using <var>right=%defaultroute</var>, we omit the
1080 <var>rightnexthop</var> parameter.</p>
1082 <p>Additional road warriors can be added as required. Each should have his or
1083 her own connection description with unique settings for <var>rightid</var>
1084 and <var>rightrsasigkey</var>.</p>
1086 <p>If necessary, a single road warrior can have multiple connections, all
1087 with the same <var>rightid</var> and <var>rightrsasigkey</var>, but with
1088 different values for <var>leftsubnet</var> to give access to different parts
1089 of the office network.</p>
1091 <p>Jean-Francois Nadeau's <a
1092 href="http://jixen.tripod.com/#Rw-Fwan-to-Fwan">Practical Configurations</a>
1093 document also has an example of using RSA authentication for road
1096 <h3><a name="oppex">Opportunistic encryption</a></h3>
1097 We use the term <a href="glossary.html">opportunistic encryption</a> for
1098 encryption which does not rely on any pre-arranged connection, hence does not
1099 require that the administrators of the two gateways involved communicate with
1100 each other (for example, to exchange keys) before their systems can create a
1103 <p>The idea is that each gateway check the destinations of outgoing packets,
1104 see if an encrypted connection is possible and, if so, take the opportuntity
1105 to encrypt. The opportunity will exist whenever the admins on both ends have
1106 set their systems up for opportunistic encryption.</p>
1108 <p>This makes encryption the default behaviour, and could greatly increase
1109 the overall security of the Internet if it were widely enough adopted. See
1112 <dt><a href="politics.html">history and politics</a></dt>
1113 <dd>for the reasons we want to do this</dd>
1114 <dt><a href="ipsec.html#traffic.resist">IPsec protocols</a></dt>
1115 <dd>for discussion of the general principle of encrypting as much as
1119 <p>The gateways must be able to authenticate each other for IPsec to be
1120 secure. For opportunistic encryption, we rely on the domain name system, <a
1121 href="glossary.html">DNS</a>, to provide the RSA keys needed for this
1122 authentication. Note, that currently this is not entirely secure because
1123 <strong>the DNS mechanism it relies on is not fully secure</strong>.
1124 Eventually, as <a href="glossary.html#SDNS">secure DNS</a> becomes widely
1125 deployed, this will change.</p>
1127 <h4><a name="opp.status">Status</a></h4>
1128 The team have been working on this for some time, and testing internally. The
1129 code is now ready for wider testing. We encourage everyone to try it.
1131 <p>The main documentation items so far are:</p>
1133 <li>an <a href="opportunism.howto">Opportunism HowTo</a> by Pluto
1134 programmer Hugh Redelmeier</li>
1135 <li>the project's internal <a href="opportunism.spec">opportunism design
1136 document</a> by Hugh and technical lead Henry Spencer.</li>
1138 href="http://www.ietf.org/internet-drafts/draft-richardson-ipsec-opportunistic-02.txt">Internet
1139 Draft</a> by Michael Richardson, Hugh and Henry. This is largely a
1140 rewrite of the internal document, a first step toward getting the
1141 protocol standardised so there can be multiple implementations of it.</li>
1143 I am playing catch up. HTML documentation so far is neither complete nor
1144 particularly clear. What I have so far is below.
1146 <p><strong>We do not yet recommend this code for production use</strong>. You
1147 should still protect your critical data with explicitly configured IPsec
1148 tunnels, rather than relying on opportunistic for everything at this
1151 <h4><a name="opp.config">ipsec.conf entries for opportunism</a></h4>
1153 <p>The relevant lines in the config file might look like this:</p>
1154 <pre>conn subnet-to-anyone # for our client subnet
1155 leftsubnet=10.42.42.0/24 # any single client in our subnet
1156 left=%defaultroute # our SG (defaults leftnexthop too)
1157 right=%opportunistic # anyone we can authenticate via DNS
1158 rekey=no # let unused connections die</pre>
1160 <p>The public key, in our format, must be in a KEY record of the appropriate
1161 DNS entry for this to work. We provide some <a
1162 href="background.html#dns.background">background information</a> on DNS in
1165 <p>Each opportunistic connection supports a single source/destination pair of
1166 IP addresses. There is no way to build an opportunistic connection for a
1167 larger subnet. Specifying a subnet in the connection description, as in the
1168 example above, just means that any host in that subnet may have opportunistic
1171 <h4><a name="dnskey">Putting IPsec information in DNS</a></h4>
1172 To set up for opportunistic encryption, you add some KEY and TXT records to
1173 your DNS data. Specifically:
1175 <li>each gateway must have a KEY record which other gateways can query to
1176 fetch its RSA authentication key</li>
1177 <li>any client whose communications are to be protected by a gateway must
1178 have a TXT record pointing to that machine as an authorised IPsec
1181 <a href="manpage.d/ipsec_showhostkey.8.html">ipsec_showhostkey(8)</a>
1182 provides the key in DNS record format. You will need to put it in the
1183 appropriate place in the DNS records.
1185 <p>To be more precise, quoting the Opportunism Design document:</p>
1186 <pre>For reference, the minimum set of DNS records needed to make
1187 this all work is either:
1189 1. TXT in Destination reverse map, identifying Responder
1190 and providing public key.
1191 2. KEY in Initiator reverse map, providing public key.
1192 3. TXT in Source reverse map, verifying relationship to
1197 1. TXT in Destination reverse map, identifying Responder.
1198 2. KEY in Responder reverse map, providing public key.
1199 3. KEY in Initiator reverse map, providing public key.
1200 4. TXT in Source reverse map, verifying relationship to
1203 Slight complications ensue for dynamic addresses, lack of
1204 control over reverse maps, etc.</pre>
1206 <h5><a name="dns.client">DNS records for client systems</a></h5>
1207 You must have control of the reverse maps for your client systems, or
1208 opportunistic IPsec cannot be made to work.
1210 <p>The client systems will be either Source or Destination, so they must
1212 <pre>1. TXT in Destination reverse map, identifying Responder
1213 and providing public key.
1215 3. TXT in Source reverse map, verifying relationship to
1220 1. TXT in Destination reverse map, identifying Responder.
1223 4. TXT in Source reverse map, verifying relationship to
1225 If you control the gateway's reverse map, example client records would look
1227 <pre>42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
1228 42.42.42.10.in-addr.arpa. IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"</pre>
1229 which can also be written as just:
1230 <pre>42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
1231 IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"</pre>
1232 This provides the IP address of the security gateway and the public key which
1233 the gateway will use to authenticate itself. This is the preferred method.
1235 <h5><a name="dns.gateway">DNS records for gateway systems</a></h5>
1236 The gateways will be either Initiator or Responder so they need:
1238 2. KEY in Initiator reverse map, providing public key.
1244 2. KEY in Responder reverse map, providing public key.
1245 3. KEY in Initiator reverse map, providing public key.
1248 <p>If you control the gateway's reverse map, you just add a KEY record there.
1249 That is all the gateway reverse map needs, whether it is working as Initiator
1252 <p>Here is an example, with many characters of the key itself left out:</p>
1253 <pre>40.30.20.10.in-addr.arpa. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8</pre>
1254 This allows lookups on the IP address of the gateway to retrieve the key.
1256 <h6>If you <em>don't</em> control the gateway's reverse map</h6>
1257 The approach must be different if you do not have control over the reverse
1258 map for your gateway. Perhaps your ISP controls that, and provides no way for
1259 you to put data into their maps. Without that, you cannot set your gateway up
1260 to respond to incoming opportunistic requests (short of changing ISPs, which
1261 you might consider).
1263 <p>However, suppose a friend over at example.org will let you put things in
1264 their maps. That will allow you to set your gateway up to handle
1265 opportunistic connections for which it is the initiator.</p>
1267 <p>You still need to be able to put data in the reverse map for your clients.
1268 However, that data is slightly different:</p>
1269 <pre>42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
1270 IN TXT "X-IPsec-Server(10)=something.example.org"</pre>
1271 Over at example.org, your friend puts these lines in the DNS data files:
1272 <pre>something.example.org. IN A 10.20.30.40
1273 something.example.org. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8</pre>
1274 Your gateway must identify itself in IKE as something.example.org, not as
1275 gateway.example.com. You set that up via <var>leftid=</var> or
1276 <var>rightid=</var> entries in <a
1277 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.
1279 <p>With this arrangement, the remote gateway receives an ID payload early in
1280 IKE with your (bogus) gateway name "something.example.org". Then it looks up
1281 that name to get the IP address and key for the gateway.</p>
1283 <h2><a name="config.fancy">Going beyond the examples</a></h2>
1284 The examples above each described a single connection. This section discusses
1285 some issues in going beyond that, dealing with more complicated networks.
1287 <p>If your network is simple enough that one of the examples had all you
1288 need, then you can skip ahead to <a href="#fw.basic">firewall setup</a>.</p>
1290 <h3><a name="handy">Simplifying ipsec.conf files</a></h3>
1292 <p>We provide several features in the syntax of the <a
1293 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file that are intended
1294 to simplify the work of managing complex multi-connection setups:</p>
1296 <li>a <var>conn %default</var> connection description for information
1297 common to all connections</li>
1298 <li><var>also=</var> lines allow a piece of a description to be defined in
1299 one place and used in several (the definition must be after all
1301 <li><var>include</var> directives allow information to be stored in
1302 separate files but used as part of the configuration</li>
1305 <p>These can be combined in whatever way suits your application. One example
1306 is this ipsec.conf file for a gateway supporting multiple road warriors, all
1307 using RSA authentication:</p>
1312 # set some defaults appropriate for the gateway
1313 # these should be changed or overridden on the road warriors
1314 keyingtries=1 # road warrior can retry, we shouldn't
1315 auto=add # default is to load, but not start
1316 # some parameters are common to all remote systems
1317 authby=rsasig # all connections use RSA authentication
1318 right=%any # accept from any address
1320 # pick up all remote system descriptions
1321 # uses shell wildcards
1322 include /etc/ipsec/remote.*.conn
1324 # left side of all connections is the same
1325 # define it after the descriptions which use it
1327 # left security gateway (public-network address)
1329 # next hop to reach right
1331 # subnet behind left (omit if there is no subnet)
1332 leftsubnet=a.b.c.0/24
1333 leftid=@gateway.example.org</pre>
1335 <p>On the left gateway, we can omit <var>leftrsasig</var>. That gateway uses
1336 the private key stored in <a
1337 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> and has no need
1338 for its own public key. Similarly, the road warriors need not have their own
1339 public keys in ipsec.conf(5), only the gateway's public key.</p>
1341 <p>The remote connection descriptions in <var>/etc/ipsec/remote.*.conn</var>
1342 need then have only a few lines each:</p>
1344 # pick up common info for all connections
1346 # identify the remote machine
1347 rightid=@myname.example.org
1348 rightrsasigkey=0xfc641fd6d9a24...</pre>
1350 <p>Be careful with the order of sections in ipsec.conf(5) and any included
1351 files. The parser requires that a definition comes after the <var>also=</var>
1352 line which uses it. In our example, the <var>include</var> inserts the files
1353 with the <var>also=leftstuff</var> lines before the definition of <var>conn
1354 leftstuff</var> so things are parsed in the correct order.</p>
1356 <p>The above method, using <var>conn leftstuff</var> and <var>also=</var>, is
1357 only one alternative. In simple cases, you can just put all the information
1358 about the left gateway in the <var>conn default</var> section instead and use
1359 no <var>also=</var> lines.</p>
1361 <h2><a name="fw.basic">Is there a firewall in play?</a></h2>
1363 <p>If firewall packet filtering is being done on either of the FreeS/WAN
1364 gateway machines, or on any machine on the path between them, then you will
1365 probably need to adjust the filters before FreeS/WAN can work. The filters
1368 <li>UDP packets between port 500 on one gateway and port 500 on the other,
1369 used by the automatic keying daemon Pluto.</li>
1370 <li>at least one of protocol 50 (ESP) and 51 (AH). Most applications want
1371 ESP since AH does only authentication, not encryption.</li>
1374 <p>For more detail, see our <a href="firewall.html">IPsec and firewalls</a>
1377 <h2><a name="testing">Testing the installation</a></h2>
1379 <p>This section covers testing connections once you have FreeS/WAN installed
1380 and your <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file set up.
1381 A separate <a href="testing.html">testing document</a> has more information
1384 <p>We assume all your connection descriptions use <var>auto=add</var> so that
1385 <a href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</a> loads the
1386 descriptions into its internal database at startup but does not attempt to
1387 start the connections until you tell it to.</p>
1389 <h3><a name="matching">Matching numbers</a></h3>
1391 <p>It is important that the numbers in your connection descriptions match the
1392 network configuration. FreeS/WAN is almost certain to fail if they do not.</p>
1394 <p>Suppose you are at the Reno office and your ipsec.conf file now has, among
1395 others, these lines:</p>
1397 interfaces="ipsec0=eth0"
1400 left=101.101.101.101
1401 right=202.202.202.202</pre>
1403 <p>When you tell FreeS/WAN to start the reno-van connection, it doesn't
1404 automagically know that it is in Reno, or that it is <var>left</var> in the
1405 configuration. It discovers that by comparing the IP address for ipsec0 (and,
1406 if it is set, for ipsec1) to the addresses for left and right. ipsec0
1407 inherits its address from the underlying device, eth0 in our example.</p>
1409 <p>So in our example, if eth0 has IP address 101.101.101.101 then ipsec0
1410 inherits that address, the correct match is found, and this FreeS/WAN
1411 discovers that it is <var>left</var>. (If no match is found, <a
1412 href="manpage.d/ipsec_pluto.8.html">Pluto</a> reports "unable to orient
1413 connection".) It then sets itself up with any other left* parameters in use
1414 -- some of <var>leftnexthop</var>, <var>leftsubnet</var>, and
1415 <var>leftid</var>.</p>
1417 <p>Once it has these parameters, FreeS/WAN sets things so that</p>
1419 <li>packets from leftsubnet addressed to rightsubnet are routed through a
1420 tunnel to right.</li>
1421 <li>packets for leftsubnet can be received on the tunnel and delivered.</li>
1424 <p>All should be well.</p>
1426 <p>Of course, there must also be interfaces and routes set up so that this
1427 machine can exchange IP packets both with the right gateway and with clients
1428 on leftsubnet. This is done with standard Linux utilities such as
1429 <var>ifconfig(8)</var> and <var>route(8)</var>. Also, things must be correct
1430 on right in Vancouver. It takes two to tunnel.</p>
1432 <p>A data mismatch anywhere in this configuration will cause FreeS/WAN to
1433 fail and to log various error messages. Depending on just how confused
1434 FreeS/WAN is and about what, the error messages may be somewhat confusing.
1435 See our <a href="trouble.html">troubleshooting</a> section and the FAQ
1436 section om <a href="faq.html#error">error messages</a> to get help
1437 interpreting them if required.</p>
1439 <p><em>We recommend double-checking for consistency here before starting
1440 actual tests.</em>.</p>
1442 <h3><a name="testsetup">Sanity checking</a></h3>
1444 <p>Reboot both gateways to get FreeS/WAN started. No connections are actually
1445 made yet, but the stage is set.</p>
1447 <p>Examine <var>/var/log/messages</var> for any signs of trouble.</p>
1449 <p>On both gateways, the following entries should now exist in the
1450 <var>/proc/net/</var> directory:</p>
1452 <li>ipsec_eroute</li>
1454 <li>ipsec_spigrp</li>
1455 <li>ipsec_spinew</li>
1456 <li>ipsec_tncfg</li>
1457 <li>ipsec_version</li>
1460 <p>and the IPsec interfaces should be attached on top of the specified
1461 physical interfaces. Confirm that with:</p>
1462 <pre> cat /proc/net/ipsec_tncfg</pre>
1464 <p>You should see at least device <var>ipsec0</var>, and each ipsec device
1465 should point to a physical device, eg. 'ipsec0 -> eth0 mtu=16260 ->
1468 <p>Routing connections through these ipsec pseudo-devices causes the data to
1469 be encrypted before being delivered to the underlying network interface. This
1470 can be done manually with our <a
1471 href="manpage.d/ipsec_eroute.8.html">eroute(8)</a> utility, but in most cases
1472 you do not need to use that utility directly. Just bring the connections up
1473 and down and the scripts call it as required.</p>
1475 <p>Don't be surprised when you cannot find <var>/dev/ipsec0</var> or
1476 <var>/dev/ipsec1</var>. They do not exist. Other network pseudo-devices such
1477 as <var>eth0</var> and <var>eth1</var> do not have entries in <var>/dev</var>
1478 either. In general, network devices do not need such entries.</p>
1480 <h3><a name="test">Starting a connection</a></h3>
1482 <p>On one gateway, start IPsec with:</p>
1483 <pre> ipsec auto --up <var>name</var></pre>
1485 <p>replacing <var>name</var> with the connection name you used in
1488 <p>For this to work, the connection description must already be loaded into
1489 Pluto's database, either via <var>auto=add</var> in the connection
1490 description or with an explicit <nobr><var>ipsec auto --add
1491 name</var></nobr>command.</p>
1493 <p>Note that to shut down a connection, you must do:</p>
1494 <pre> ipsec auto --down <var>name</var></pre>
1496 <p>on <em>both</em> gateway machines, even though you only start it from
1499 <p>If the <var>ipsec auto --up</var> command doesn't generate any errors,
1501 <pre> ipsec look</pre>
1503 <p>and see if the output looks something like this:</p>
1504 <pre>foo.spsystems.net Wed Nov 25 22:51:45 EST 1998
1505 -------------------------
1506 10.0.1.0/24 -> 11.0.1.0/24 => tun0x200@11.0.0.1 esp0x202@11.0.0.1
1507 -------------------------
1508 tun0x200@11.0.0.1 IPv4_Encapsulation: dir=out 10.0.0.1 -> 11.0.0.1
1509 esp0x203@10.0.0.1 3DES-MD5-96_Encryption: dir=in iv=0xc2cbca5ba42ffbb6 seq=0 bit=0x00000000 win=0 flags=0x0<>
1510 esp0x202@11.0.0.1 3DES-MD5-96_Encryption: dir=out iv=0xc2cbca5ba42ffbb6 seq=0 bit=0x00000000 win=0 flags=0x0<>
1511 Destination Gateway Genmask Flags MSS Window irtt Iface
1512 11.0.0.0 0.0.0.0 255.255.255.0 U 1500 0 0 eth1
1513 11.0.1.0 11.0.0.1 255.255.255.0 UG 1404 0 0 ipsec0</pre>
1515 <p>If it does, you're probably in business.</p>
1517 <p>This example shows:</p>
1518 <pre> a tunnel tun0x200 going to 11.0.0.1
1519 outgoing connection esp0x202
1520 incoming connection esp0x203</pre>
1522 <p>Both connections use <a href="glossary.html#ESP">ESP</a> with <a
1523 href="glossary.html#3DES">3DES</a> encryption and <a
1524 href="glossary.html#MD5">MD5</a> authentication.</p>
1526 <p>The routing is:</p>
1527 <pre> 11.0.0.0 via eth1 and the Internet
1528 11.0.1.0 via ipsec0 which encrypts and then sends to 11.0.0.1</pre>
1530 <p>This routes all traffic to the protected network 11.0.1.0/24 through an
1531 IPsec tunnel to the gateway 11.0.0.1.</p>
1533 <h3><a name="pingtest">Ping tests</a></h3>
1535 <p>If that works, test whether Sunrise can ping Sunset and vice versa. Our
1536 example setup again is:</p>
1537 <pre> Sunset==========West------------------East=========Sunrise
1538 local net untrusted net local net</pre>
1540 <p>There is no point in testing to or from the gateways themselves; the goal
1541 is to secure traffic between the subnets, not between the security gateways
1544 <p>In general, pings or other <strong>tests using the public interfaces of
1545 East and/or West are entirely useless</strong>. The IPsec tunnel is for
1546 packets between the two protected subnets and the outside interfaces are not
1547 on those subnets. Depending on your routing configuration, test packets sent
1548 via those interfaces will be:</p>
1550 <li>either transmitted in the clear, bypassing the tunnel,</li>
1551 <li>or discarded because there is no tunnel in place to handle them</li>
1554 <p>In either case, <strong>they tell you nothing about the
1555 tunnel</strong>.</p>
1557 <p>Sometimes it will be inconvenient to use the client machines (Sunrise and
1558 Sunset in our example) for testing. In these cases, use a command such as:</p>
1559 <pre> traceroute -i eth0 -f 20 192.168.7.1</pre>
1561 <p>where each of the interfaces specified (eth0 and 192.168.7.1 in the
1562 example) are <strong>on one of the protected subnets</strong>, eth0 being the
1563 local gateway's interface on that side and 192.168.7.1 the remote gateway's
1564 subnet interface. This forces the packets through the IPsec tunnel you want
1567 <p>For information on setting things up so that gateways can do IPsec to each
1568 other or to remote subnets, see <a
1569 href="adv_config.html#multitunnel">below</a>.</p>
1571 <p>If you have other software set up, test with it as well. Telnet from
1572 Sunrise to Sunset, browse a web server on the remote net and so on.</p>
1574 <h3><a name="tcpdump">Testing with tcpdump</a></h3>
1576 <p>To verify that all is working, run tcpdump(8) on a machine which can
1577 listen to the traffic between the gateways.</p>
1579 <p>This is most easily done from a third machine, rather than from one of the
1580 gateways. On the gateways you may see packets at intermediate stages of
1581 processing and the result may be confusing.</p>
1583 <p>If the results make no sense at all, or you see "bad physical medium"
1584 error messages, you probably have an outdated version of tcpdump(8) that does
1585 not handle IPsec at all. See this <a
1586 href="testing.html#tcpdump.test">discussion</a>.</p>
1588 <p>If packets look like total garbage, nothing recognizable, all is well.</p>
1589 See our document on <a href="testing.html#verify.crypt">testing</a> for more
1592 <h3><a name="conn.shutdown">Shutting down connections</a></h3>
1594 <p>To shut down a connection, you must do:</p>
1595 <pre> ipsec auto --down <var>name</var></pre>
1597 <p>on <em>both</em> gateway machines, even though you only start it from
1600 <p>Again, you can verify with the same commands. Repeat the ping test. Repeat
1601 the tcpdump test.</p>
1603 <p>If everything succeeds, congratulations. <strong>You now have a working
1604 Linux FreeS/WAN installation.</strong></p>
1606 <h2><a name="links.conf">What next?</a></h2>
1608 <p>At this point you should have a working FreeS/WAN setup. If not, you could
1609 go back and doublecheck various things above or try:</p>
1613 <li>our <a href="faq.html">FAQ</a></li>
1614 <li>our <a href="trouble.html">troubleshooting</a> section</li>
1615 <li>additional <a href="examples">configuration examples</a></li>
1618 <p>If all is well so far, you could go to:</p>
1620 <li>more detail on the <a href="ipsec.html">IPsec protocols</a></li>
1621 <li><a href="politics.html">history and politics of cryptography</a></li>
1622 <li><a href="adv_config.html">advanced configuration</a>, other ways to
1623 configure FreeS/WAN connections</li>
1624 <li><a href="interop.html">interoperating</a> with other IPsec
1625 implementations</li>
1628 <p>Of course you might just go off for a beverage or meal at this point as