3 <meta http-equiv="Content-Type" content="text/html">
4 <title>Quick FreeS/WAN installation and configuration</title>
6 content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart">
9 Written by Sandy Harris for the Linux FreeS/WAN project
10 Freely distributable under the GNU General Public License
12 More information at www.freeswan.org
13 Feedback to users@lists.freeswan.org
16 RCS ID: $Id: quickstart.html,v 1.22 2002/03/25 19:10:04 sandy Exp $
17 Last changed: $Date: 2002/03/25 19:10:04 $
18 Revision number: $Revision: 1.22 $
20 CVS revision numbers do not correspond to FreeS/WAN release numbers.
25 <h1><a name="quick_guide">FreeS/WAN quick start guide</a></h1>
27 <p>This is a quick guide to</p>
29 <li><a href="#easy.install">getting FreeS/WAN installed</a> from a
30 distribution CD or RPMs</li>
31 <li><a href="#enable">enabling FreeS/WAN</a></li>
32 <li><a href="#gen_rsa">generating RSA public keys</a> for your system</li>
35 <p>and then setting up some common configurations:</p>
37 <li><a href="#opp.setup">opportunistic encryption</a>
39 <li>a system which can initiate all the encryption it needs</li>
40 <li>a system which also accepts incoming requests for secure
42 <li>a gateway providing services for a number of clients</li>
45 <li><a href="#roadies">"road warrior" remote access</a> to a network
47 <li>"road warrior" machine setup</li>
48 <li>network gateway setup</li>
51 <li><a href="#gate.VPN">network-to-network VPN</a></li>
54 <p>This should cover everything you need to set up</p>
56 <li>a laptop machine</li>
57 <li>a standalone home PC</li>
58 <li>a home office firewall/gateway</li>
59 <li>a simple gateway for a small company or branch office</li>
62 <p>More complex requirements are covered elsewhere:</p>
64 <li><a href="install.html">installing from source</a></li>
65 <li><a href="adv_config.html">advanced configuration</a></li>
66 <li><a href="interop.html">interoperation</a> with other IPsec
70 <p>However, <strong>please read this quick start section first</strong>,
71 before tackling the others.</p>
73 <h2><a name="easy.install">Easy installation</a></h2>
75 <p>There are two easy ways to install FreeS/WAN:</p>
77 <li>Some Linux distributions, <a href="intro.html#distwith">listed in the
78 introduction</a>, ship with FreeS/WAN included.
79 <p>If you are using one of them, just include FreeS/WAN in the choices
80 you make during installation, or add it to your configuration later using
81 the distribution's tools.</p>
83 <li>RPM (Redhat Package Manager) packages built for your distribution may
84 be available for download. If they are, then the installation is quite
86 <p>Sources for RPM packages of FreeS/WAN are:</p>
88 <li><a href="http://rpms.steamballoon.com/freeswan/">Steamballoon</a>,
89 the helpful folks who developed the RPM tools in our distribution</li>
90 <li><a href="ftp://ftp.xs4all.nl/pub/crypto/freeswan">FreeS/WAN FTP
91 site</a> (At time of writing, no RPMs are there yet.)</li>
92 <li>one of the FreeS/WAN <a href="intro.html#sites">mirrors</a> listed
93 in the introduction (not yet)</li>
97 <li><strong>you should not trust RPMs from a source you do not
99 <li>you should <strong>run <var>rpm --checksig</var> before trusting
100 any RPM</strong>. Checking the public key signature gives you
101 assurance that the RPM you install was not changed after they signed
103 <li>the <strong>RPMs must exactly match your system</strong>. For
104 example, an RPM built for Redhat 7.1 should not be used on 7.2.</li>
105 <li>the <strong>kernel RPM must be correct for your hardware</strong>.
106 For example, a kernel compiled for an AMD Athlon will not run
107 correctly on an Intel-based system.</li>
109 <p>You need to download at least two RPMs:</p>
111 <li>FreeS/WAN utilities</li>
112 <li>a kernel that includes FreeS/WAN code</li>
114 The FreeS/WAN version number in the two should match.
115 <p>You do not need the kernel header and kernel source RPMs to install
117 href="http://www.edwards.af.mil/history/docs_html/tidbits/murphy's_law.html">Murphy's
118 Law</a> suggests you should download them so that the kernel source and
119 headers on your system match the kernel actually in use.</p>
120 <p>Once you have them, install the RPMs with <var>rpm -i</var> commands.
121 You will need to be root to install the kernel.</p>
125 <p>If your distribution does not include FreeS/WAN and no RPMs are available,
126 see our <a href="install.html">installation from source</a> document.</p>
128 <h2><a name="enable">Enabling FreeS/WAN</a><a></a></h2>
130 <p>Once you have FreeS/WAN on the system, ensure that it is enabled:</p>
132 <dt>Set your boot loader to get the system booting with the new kernel.</dt>
133 <dd>On many systems, you do this by editing lilo.conf(5) and running
135 href="http://www.linuxdoc.org/HOWTO/mini/LILO.html">LILO
137 <dd>On other systems, you might use grub(8). See the <a
138 href="http://www.gnu.org/software/grub/">GRUB homepage</a>.</dd>
139 <dt>Enable ipsec in your boot scripts.</dt>
140 <dd>Typically, this is done with chkconfig(8). If this is unfamiliar
141 territory, see the <a
142 href="http://www.linuxdoc.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">Power-up
143 to Bash Prompt</a> HowTo.
144 <p>Our script is installed as <var>/etc/rc.d/init.d/ipsec</var> and
145 chkconfig(8)creates links to it in the <var>/etc/rc.d/rc[1-6].d
146 </var>directories.</p>
150 <h2><a name="testinstall">Testing to see if install succeeded</a></h2>
152 <p>To check that you have a sucessful install, you can reboot and check (by
153 watching messages during boot or by looking at them later with dmesg(8))
156 <li>the kernel reports the right version. If not, you are likely still
157 running your old kernel. Check your lilo.conf(5) file and the
158 installation directory (defined in the kernel make file, often /boot but
159 the default is /), then rerun lilo(8).</li>
160 <li>KLIPS initialisation messages appear</li>
161 <li>Pluto reports that it is starting</li>
164 <p>You can also try the commands:</p>
166 <li><var>ipsec --version</var>, to test whether /usr/local/bin is in your
167 path so you can use IPsec administration commands</li>
168 <li><var>ipsec whack --status</var>, using <a
169 href="manpage.d/ipsec_whack.8.html">ipsec_whack(8)</a> to ask Pluto for
170 status information</li>
173 <p>Of course any status information at this point should be uninteresting
174 since you have not yet configured connections.</p>
176 <p>That's it. FreeS/WAN is installed.</p>
178 <h2><a name="gen_rsa">Creating an RSA key</a></h2>
180 <p>The next step is to generate an <a href="glossary.html#RSA">RSA</a> key
181 for your machine. These keys are used for machine-to-machine <a
182 href="glossary.html#authentication">authentication</a> in IPsec negotiations.
183 Any system which will be the endpoint of an IPsec tunnel must have one.</p>
185 <p>RSA is a <a href="glossary.html#public">public key</a> cryptographic
186 technique. Keys are created as matched pairs. Each pair includes:</p>
188 <li>a <strong>public key</strong> which need not be kept secure. Everyone
189 you plan to communicate with must be able to get a copy of this. It does
190 not matter if an enemy gets it as well.</li>
191 <li>a <strong>private key</strong> which must be kept secure. No-one but
192 you should have access to it.</li>
195 <p>For FreeS/WAN, both keys for your system are in the <a
196 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> file.
197 <strong>Maintaining security of this file is essential</strong> since it
198 holds your private key.</p>
200 <p>To generate your key pair, give these commands as root:</p>
201 <pre> ipsec newhostkey --output /etc/ipsec.secrets
202 chmod 600 /etc/ipsec.secrets</pre>
204 <p>Key generation may take some time, even on a fast system. Also, it needs a
205 lot of <a href="glossary.html#random">random numbers</a> so you may need to
206 switch consoles and do something like typing a lot of text or running
207 <nobr><var>du / > /dev/null</var></nobr>. These give <var>random(4)</var>
208 some inputs to work with.</p>
210 <p>The RSA keys we generate are suitable <strong>only</strong> for
211 authentication, not for encryption. IPsec uses them only for authentication.
212 See our <a href="ipsec.html">IPsec</a> section for details.</p>
214 <h2><a name="opp.setup">Setting up opportunistic encryption</a></h2>
216 <p><a href="glossary.html#carpediem">Opportunistic encryption</a> makes some
217 aspects of the setup and administration of IPsec easier.</p>
219 <p>For opportunistic encryption, <strong>you do not need to communicate with
220 the administrator of a site before establishing secure communications to that
221 site</strong>. In particular, you do not have to send them your keys or
222 collect and authenticate theirs. All you have to do is set up your end
223 correctly and from there on, everything is automatic.</p>
225 <p>One of the major goals of the FreeS/WAN project is to get opportunistic
226 encryption widely enough deployed that a "FAX effect" comes into play.
227 Neither a FAX machine nor opportunistic encryption is of much value if there
228 are only a few installed, but both become much more useful as the installed
231 <p>Widespread deployment of opportunistic encryption appears to be our best
232 hope for making the Internet more secure. See discussion in our <a
233 href="intro.html#opp.intro">introduction</a>.</p>
235 <h3><a name="opp.client">Initiate-only opportunistic encryption</a></h3>
237 <p>In this section, we treat the simplest case of opportunistic
240 <li>there will be <strong>no incoming connection requests</strong>; you can
241 initiate all the IPsec connections you ever need</li>
242 <li><strong>only one machine is visible</strong> on your end of the
243 connection (though there may be a hidden <a
244 href="glossary.html#NAT.gloss">NAT</a> network behind it.)</li>
245 <li>for IPsec purposes, that one IP address is both the gateway and the
249 <p>This would apply to a standalone machine, or to a home gateway with some
250 invisible <a href="glossary.html#NAT.gloss">NAT</a> clients.</p>
252 <p>Given the above conditions, you can set up opportunistic encryption
253 without having access to the <a href="glossary.html#reverse">DNS reverse
254 map</a> for your machine. The following sections cover situations where one
255 or more of the above restrictions do not apply.</p>
257 <p>There are two steps:</p>
259 <li>set your system up for opportunistic encryption</li>
260 <li>put your public key in <a href="glossary.html#DNS">DNS</a></li>
263 <p>Once this is done, your system will automatically encrypt whenever it
266 <h4><a name="config.opp.client">ipsec.conf(5) for initiate-only
269 <p>The <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file for this
271 <pre># general IPsec setup
273 # Use the default interface
274 interfaces=%defaultroute
275 # Use auto= parameters in conn descriptions to control startup actions.
279 # defaults for subsequent connection descriptions
281 # How to authenticate gateways
284 # load connection description into Pluto's database
285 # so it can respond if another gatway initiates
286 # individual connection descriptions may override this
289 # description for opportunistic connections
291 also=our_stuff # our system details, stored below
292 right=%opportunistic # anyone we can authenticate
293 rightrsasigkey=%dns # look up their key in DNS
294 auto=route # set up for opportunistic
295 rekey=no # let unused connections die
297 # description of our system
298 # included in other connection descriptions via also= lines
299 # must come after the lines that use it
301 # all connections should use our default route
302 # also controls the source address on IPsec packets
304 # our identity for IPsec negotiations
305 # must match what is in DNS and ipsec.secrets(5)
306 leftid=@xy.example.com</pre>
308 <p>The last line above is the only one that you need to edit for your system.
309 All the rest is identical for any standalone machine doing opportunistic
312 <p>The @ sign in the <var>leftid=</var> line indicates that this machine
313 should not attempt to look up that name. Others will, to get our public key,
314 but we don't need to..</p>
316 <p>There is no need to provide any keys in this file. Your private key is in
317 <a href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> and, for
318 opportunistic encryption, the public keys for remote gateways are all looked
321 <p>Also note that the <var>left</var> and <var>right</var> designations here
322 are arbitrary. You could reverse them above with no problems.</p>
324 <h4><a name="dns.txt.client">Initiate-only DNS key</a></h4>
326 <p>You need to put your system's RSA public key in a <a
327 href="glossary.html#DNS">DNS</a> record so that systems you communicate with
330 <h5>Find a helpful DNS administrator</h5>
332 <p>You need the co-operation of a DNS administrator somewhere for this, to
333 place a KEY record so that you can use a name in some domain he or she
334 controls. This need not be either the domain you get your IP address from or
335 a domain that points to your system.</p>
337 <p>For example, a reverse lookup on the IP address for a home gateway might
338 give 123.adsl.kalamazoo.example.net, and a forward lookup for
339 example.dyndns.org might point to that gateway. You could use either of these
340 names as your ID for IPsec purposes, if the admins at either example.net or
341 dyndns.org co-operate.</p>
343 <p>If not, you can use any domain whose DNS administrator is willing to help
344 out. You do not need an A record (address record, associating your chosen
345 name with an address) in that domain, only a KEY record.</p>
347 <h5>Generate a KEY record</h5>
349 <p>You can generate a DNS KEY record containing your system's public key with
351 <pre> ipsec showhostkey</pre>
352 The result should look like this (with the key data trimmed down for clarity):
353 <pre> ; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000
354 xy.example.com. IN KEY 0x4200 4 1 AQOF8tZ2...+buFuFn/</pre>
356 <p>The name here is taken from <a
357 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a>. If it is not what
358 you want, edit that file to correct it, then run <var>ipsec showhostkey</var>
361 <p>The name must also match what you used for <var>leftid=</var> in <a
362 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</p>
364 <p>Give this record to the DNS administrator, for insertion into the zone
365 file of the domain.</p>
367 <h4><a name="firewall.standalone">Firewalling for a standalone system</a></h4>
369 <p>Firewall rules on a standalone system doing IPsec -- opportunistic, "road
370 warrior" remote access, or both -- can be very simple.</p>
372 <p>The first step is to allow IPsec packets (IKE on UDP port 500 plus ESP,
373 protocol 50) in and out of your gateway. A script to set up iptables(8) rules
375 <pre># edit this line to match the interface you use as default route
376 # ppp0 is correct for many modem, DSL or cable connections
377 # but perhaps not for you
383 iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT
384 iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
385 # ESP encrypton and authentication
386 iptables -A INPUT -p 50 -i $world -j ACCEPT
387 iptables -A OUTPUT -p 50 -o $world -j ACCEPT</pre>
389 <p>Optionally, you could restrict this, allowing these packets only to and
390 from a list of known gateways.</p>
392 <p>A second firewalling step -- access controls built into the IPsec
393 protocols -- is automatically applied:</p>
395 <dt><a href="glossary.html#Pluto">Pluto</a> -- the FreeS/WAN keying daemon
396 -- deals with the IKE packets.</dt>
397 <dd>Pluto authenticates its partners during the IKE negotiation, and
398 drops negotiation if authentication fails.</dd>
399 <dt><a href="glossary.html#KLIPS">KLIPS</a> -- the FreeS/WAN kernel
400 component -- handles the ESP packets.</dt>
402 <dt>KLIPS drops outgoing packets</dt>
403 <dd>if they are routed to IPsec, but no tunnel has been negotiated
405 <dt>KLIPS drops incoming unencrypted packets</dt>
406 <dd>if source and destination addresses match a tunnel; the packets
407 should have been encrypted</dd>
408 <dt>KLIPS drops incoming encrypted packets</dt>
409 <dd>if source and destination address do not match the negotiated
410 parameters of the tunnel that delivers them</dd>
411 <dd>if packet-level authentication fails</dd>
416 <p>These errors are logged. See our <a
417 href="trouble.html">troubleshooting</a> document for details.</p>
419 <p>Optionally, you can add a third step using whatever additional firewall
420 rules are required for your situation. These rules can recognise packets
421 emerging from IPsec. They are marked as arriving on an interface such as
422 <var>ipsec0</var>, rather than <var>eth0</var>, <var>ppp0</var> or whatever.
423 For example, in an iptables(8) rule set, you would use:</p>
425 <dt><var>-i ipsec+</var></dt>
426 <dd>to specify packets arriving on any ipsec device</dd>
427 <dt><var>-o ipsec+</var></dt>
428 <dd>to specify packets leaving via any ipsec device</dd>
431 <p>It is therefore straightforward to apply whatever additional filtering you
432 like to these packets.</p>
434 <h4>Testing opportunistic connections</h4>
436 <p>To check that opportunistic encryption is working, point a browser to
437 <var><a href="http://oetest.freeswan.org">oetest.freeswan.org</a></var>, a
438 host we have set up to do opportunistic encryption for testing. A link there
439 will tell you whether or not you have an encrypted connection.</p>
441 <p>If using a browser is inconvenient, take these steps:</p>
443 <li>ping <var>oetest.freeswan.org</var></li>
444 <li>ping some site that does not yet have opportunistic encryption</li>
445 <li>run <var>ipsec look</var></li>
448 <p>You should see a tunnel to the opportunistic host.</p>
450 <p>When FreeS/WAN cannot set up an opportunistic connection, and no explicit
451 tunnel has been configured, its default is to allow the traffic through in
452 the clear. For the non-opportunistic host, you should see a %pass eroute
453 (IPsec route), the FreeS/WAN mechanism that implements that default.</p>
455 <h3><a name="opp.incoming">Accepting incoming requests for opportunistic
458 <p>If you need to let others inititiate encrypted connections to your system
459 -- for example, if you run services on your machine and want remote clients
460 to be able to access them securely -- then you need to do a bit more.</p>
462 <p>There are two steps in the setup.</p>
464 <li>setting up <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a></li>
465 <li>setting up the DNS entries to support it</li>
468 <p>Both need to be a little different than in the initiate-only case.</p>
470 <p>For incoming connections, you are not the initiator so you cannot use the
471 first message to tell the other end the identity you wish to use. You must be
472 able to handle having the other end identify you by IP address. In many
473 cases, that will be all the remote gateway knows.</p>
475 <h4><a name="incoming.opp.conf">ipsec.conf(5) to accept incoming
476 opportunistic</a></h4>
478 <p>Only one change is need in the <a
479 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file. You use an IP
480 address instead of a name as your identity. For example, with the address
481 1.2.3.4, the section describing your system becomes:</p>
482 <pre># description of our system
483 # included in other connection descriptions via also= lines
484 # must come after the lines that use it
486 # all connections should use our default route
487 # also controls the source address on IPsec packets
489 # our identity for IPsec negotiations
490 # must match what is in DNS and ipsec.secrets(5)
493 <p>You must make a matching change in <a
494 href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a>, so that the
495 identifier for your secret key is also "1.2.3.4".</p>
497 <h4><a name="incoming.opp.dns">DNS for incoming opportunistic
500 <p>To accept incoming connections, you need to put a KEY record in the DNS <a
501 href="glossary.html#reverse">reverse map</a> for your gateway. The initiator
502 will not always know your gateway's name. It must be possible to look up the
503 key knowing only the IP address.</p>
505 <p>The record you need looks like this:</p>
506 <pre> ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
507 4.3.2.1.in-addr.arpa. IN KEY 0x4200 4 1 AQOF8tZ2...+buFuFn/</pre>
509 <p>Generate a record with <nobr><var>ipsec showhostkey</var></nobr>, and then
510 edit it to insert the IP address.</p>
512 <p>As always, IP addresses in the reverse map are written backwards. In the
513 above example, the gateway IP address is 1.2.3.4.</p>
515 <h4><a name="incoming.opp.firewall">Firewalling incoming opportunistic
518 <p>The basic firewalling for IPsec does not change when you support incoming
519 connections as well as connections you initiate. You must still allow IKE
520 (UDP port 500) and ESP (protocol 50) packets to and from your machine, as in
521 the rules given <a href="#firewall.standalone">above</a>.</p>
523 <p>However, there are additional security concerns when you allow incoming
524 opportunistic connections. This creates an additional path to your machine,
525 so you need to check your rules to see that this does not provide a means for
526 EvilDoers to bypass protections you have set up on other paths.</p>
528 <p>In particular, look at any rules you have that depend on interfaces, rules
529 using <var>-i ppp+</var>, <var>-o eth1</var> or similar expressions. You may
530 need analogous rules for your <var>ipsec</var> interfaces.</p>
532 <h3><a name="opp.gate">An opportunistic gateway</a></h3>
534 <p>Next we expand from a standalone system (which protects only its own
535 traffic) to a gateway (which protects traffic for other systems).</p>
537 <p>There is one special case in which gateway configuration is quite simple
538 -- if all the machines behind the gateway are hidden from the Internet. We
539 describe that first, then go on to describe gateways for visible clients.</p>
541 <h4><a name="simple.NAT">NAT for hidden clients</a></h4>
543 <p>If your gateway uses <a href="glossary.html#NAT.gloss">NAT</a> to allow
544 machines to access the Internet without having their own <a
545 href="glossary.html">routable</a> IP addresses, then from the point of view
546 of anyone else on the Internet:</p>
548 <li>the systems behind the gateway are completely hidden</li>
549 <li>only one machine with one IP address is visible</li>
550 <li>the gateway appears to be a standalone system</li>
553 <p>For purposes of IPsec across the Internet, your gateway can be treated as
554 a standalone machine. Consequently,</p>
556 <li>your <strong>ipsec.conf(5) file needs no changes</strong> to support
557 the NAT. It can be identical to what you would use on a standalone system
558 -- either initiate-only or with incoming connection support -- as shown
560 <li>the firewall rules for your Internet interface can be identical to
561 those for a standalone system, as above</li>
562 <li>the only thing you must change are the firewall rules that control
563 forwarding to the NAT network</li>
566 <p>For a more detailed discussion of NAT, see our <a
567 href="background.html#nat.background">background</a> section.</p>
569 <h4><a name="gate.real">Gateway for visible clients</a></h4>
571 <p>Many gateways will need to support client systems which have routable
572 addresses and are visible to the Internet. This involves:</p>
574 <li>adding a connection description in <a
575 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a></li>
576 <li>adding a DNS record for each client, pointing to the gateway</li>
579 <h4><a name="gate.opp.conf">ipsec.conf(5) for an opportunistic
582 <p>You need only make a few additions to in the ipsec.conf(5) file:</p>
584 <li>keep the connection description for the gateway itself</li>
585 <li>add another one for its clients</li>
586 <li>in that connection, specify the clients in a <var>leftsubnet=</var>
590 <p>The additions to the ipsec.conf(5) file might be:</p>
591 <pre># opportunistic connections for client systems
592 # our gateway will build opportunistic tunnels on behalf of any
593 # machine in the specified subnet
594 conn subnet-to-anyone
595 also=gate_stuff # our system details, stored below
596 also=public_subnet # subnet description, below
597 auto=route # set up for opportunistic
598 right=%opportunistic # anyone we can authenticate via DNS
599 rekey=no # let unused connections die
601 # description of the subnet this gateway encrypts for
602 # numbers used here are arbitrary, just for example
604 leftsubnet=42.42.42.0/24 </pre>
606 <p>There is one small thing to be careful of here. An <var>also=</var> line
607 must appear in the file before the conn it references, so the first section
608 above must appear before <var>conn gate_stuff</var>.</p>
610 <h5>Supporting additional subnets</h5>
612 <p>If required, a gateway can easily provide this service for more than one
613 subnet. You just add a connection description and a subnet description for
614 each. For example, leaving everything else above unchanged, you could add
616 <pre># opportunistic connections for additional systems
617 conn second-to-anyone
618 also=gate_stuff # our system details, stored below
619 also=second_subnet # subnet description, below
620 right=%opportunistic # anyone we can authenticate via DNS
621 rekey=no # let unused connections die
623 # description of a second subnet this gateway encrypts for
624 # numbers used here are arbitrary, just for example
626 leftsubnet=101.102.103.0/24 </pre>
628 <p>again, you need a little care so that <var>also=</var> lines always come
629 before the sections they reference.</p>
631 <p>The subnets used in these descriptions need not correspond to physical
632 subnets. This is discussed in more detail in our <a
633 href="adv_config.html">advanced configuration</a> document.</p>
635 <h4><a name="gate.opp.dns">DNS entries for an opportunistic gateway</a></h4>
637 <p>We assume you already have a KEY record in the <a
638 href="glossary.html#reverse">reverse map</a> so your gateway can accept
639 incoming connections as described <a href="#incoming.opp.dns">above</a>.</p>
641 <p>For the gateway to provide an opportunistic encryption service for other
642 systems, it must be possible for the initiator of an IPsec connection to:</p>
644 <li>discover the gateway's address, knowing only the endpoint that packets
646 <li>verify that the gateway is authorised to encrypt for that endpoint</li>
649 <p>This is done by adding a TXT record to the reverse map for the endpoint.
650 The record (with key shortened) looks like this:</p>
651 <pre> ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
652 IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"</pre>
654 <p>This record must be generated on the gateway so it can get the key from <a
655 href="ipsec.secrets.5.html">ipsec.secrets(5)</a>. The command is:</p>
656 <pre> ipsec showhostkey --txt 1.2.3.4</pre>
658 <p>You must supply the gateway IP address on the command line.</p>
660 <p>One of these records is required in the reverse map for each system using
661 this gateway for opportunistic IPsec. You insert it in the reverse map part
662 of the zone file right after the line for that system's IP address, so part
663 of the file might look like this:</p>
664 <pre> 1.42.42.42.in-addr.arpa. IN PTR arthur.example.com
665 ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
666 IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
667 2.42.42.42.in-addr.arpa. IN PTR ford.example.com
668 ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
669 IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
670 3.42.42.42.in-addr.arpa. IN PTR trillian.example.com
671 ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
672 IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"</pre>
674 <p>You need one TXT record per client, but the TXT records can all be
677 <h4>Firewalling for gateways</h4>
679 <p>On a gateway, the IPsec-related firewall rules applied for input and
680 output on the Internet side are exactly as shown above. A gateway exchanges
681 exactly the same things -- UDP 500 packets and IPsec packets -- with other
682 gateways that a standalone system does, so it can use exactly the same
683 firewall rules as a standalone system would.</p>
685 <p>However, on a gateway there are additional things to do:</p>
687 <li>you have other interfaces and need rules for them</li>
688 <li>packets emerging from ipsec processing must be correctly forwarded</li>
691 <p>You need additional rules to handle these things. For example, adding some
692 rules to the set shown above we get:</p>
693 <pre># edit this line to match the interface you use as default route
694 # ppp0 is correct for many modem, DSL or cable connections
695 # but perhaps not for you
698 # edit these lines to describe your internal subnet and interface
699 localnet=42.42.42.0/24
705 iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT
706 iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
707 # ESP encrypton and authentication
708 iptables -A INPUT -p 50 -i $world -j ACCEPT
709 iptables -A OUTPUT -p 50 -o $world -j ACCEPT
711 # packet forwarding for an IPsec gateway
712 # simplest possible rules
713 $ forward everything, with no attempt to filter
715 # handle packets emerging from IPsec
716 # ipsec+ means any of ipsec0, ipsec1, ...
717 iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT
718 # simple rule for outbound packets
719 # let local net send anything
720 # IPsec will encrypt some of it
721 iptables -A FORWARD -s $localnet -i $internal -j ACCEPT </pre>
723 <p>On a production gateway, you would no doubt need tighter rules than the
724 above. For details, see:</p>
726 <li><a href="http://www.netfilter.org/documentation/">netfilter
727 documentation</a></li>
730 <li>Cheswick and Bellovin, <a
731 href="biblio.html#firewall.book">Firewalls and Internet
733 <li>Zeigler <a href="biblio.html#Zeigler">Linux Firewalls</a>,</li>
736 <li><a href="firewall.html">our firewalls document</a></li>
737 <li><a href="web.html#firewall.web">our firewall links</a></li>
740 <h2><a name="roadies">"Road Warrior" remote access</a></h2>
742 <p>A common requirement is for pre-configured connections between a specfic
743 network and some set of remote machines. For example, an office network will
744 often need to provide remote access services for:</p>
746 <li>employees' or contractors' home offices (standalone machine or firewall
747 plus client machines)</li>
748 <li>travelling employees</li>
751 <p>We refer to the remote machines as "Road Warriors". For purposes of IPsec,
752 anyone with a <a href="glossary.html#dynamic">dynamic IP address</a> is a
755 <p>Of course, if both the warrior and the gateway at the office are set up
756 for opportunistic encryption, then you may not need the pre-configured
757 connection. Here we assume that you do need it. For example:</p>
759 <li>a corporate security policy might require explicitly-configured
760 connections for some applications</li>
761 <li>either end might be using a product which does not yet support
762 opportunistic encryption</li>
765 <p>This section has three sub-sections:</p>
767 <li>exchanging the information required to build explicitly configured
769 <li>setup on the "Road Warrior" end</li>
770 <li>setup on the gateway end</li>
773 <p>On either end, the opportunistic setup is unaffected by this. You leave it
774 in place so both systems can continue to do opportunistic encryption with
775 everyone but each other.</p>
777 <h3><a name="info.ex">Information exchange</a></h3>
779 <p>To set up an explicitly configured connection, you need some information
780 about the system on the other end.</p>
782 <p>Connection descriptions use <var>left </var>and <var>right</var> to
783 designate the two ends. We adopt the convention that, from the gateway's
784 point of view left=local and right=remote.</p>
786 <p>The gateway administrator needs to know some things about each Road
789 <li>the system's public key</li>
790 <li>the ID that system uses in IPsec negotiation</li>
793 <p>To get this information, in a format suitable for insertion directly into
794 the gateway's <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file,
795 issue this command on the Warrior machine:</p>
796 <pre> ipsec showhostkey --right</pre>
798 <p>The output should look like this (with the key shortened for easy
800 <pre> rightid=@xy.example.com
801 rightrsasigkey=0s1LgR7/oUM...</pre>
803 <p>The Road Warrior needs to know:</p>
805 <li>the gateway's public key</li>
806 <li>the ID the gateway uses in IPsec negotiation</li>
809 <p>which can be generated by running <var>ipsec showhostkey --left</var> on
810 the gateway. Each Warrior must also know:</p>
812 <li>the IP address of the gateway</li>
813 <li>the subnet to which an IPsec tunnel provides access</li>
816 <p>This information should be provided in a convenient format, ready for
817 insertion in the Warrior's <a
818 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file. For example:</p>
820 leftsubnet=42.42.42.0/24
821 leftid=@gateway.example.com
822 leftrsasigkey=0s1LgR7/oUM...</pre>
824 <p>The gateway administrator typically needs to generate this only once. The
825 same file can be given to all Warriors.</p>
827 <p>Of course it is also possible to provide different versions (in
828 particular, access to differnet subnets) to different groups of Warriors. See
829 our <a href="adv_config.html">advanced configuration</a> document.</p>
831 <h3><a name="rw.client">Setup on the Road Warrior machine</a></h3>
833 <p>To set up a Road Warrior machine, we start from the opportunistic
834 imitiator setup shown <a href="#opp.client">above</a>.</p>
836 <p>We need to add a connection description for the pre-configured tunnel.
837 Since we want to be right in that description, we reverse the opportunistic
838 description so we are right there too.</p>
840 <h4>Connection description for a pre-configured tunnel</h4>
842 <p>We insert the new connection description before the <var>conn
843 our_stuff</var> section, so that it can use an <var>also=</var> line
844 referring to that section.</p>
845 <pre># description for opportunistic connections
846 # reversed from previous example
848 also=our_stuff # our system details, stored below
849 left=%opportunistic # anyone we can authenticate
850 leftrsasigkey=%dns # look up their key in DNS
851 auto=route # set up for opportunistic
852 rekey=no # let unused connections die
854 # pre-configured link to office network
855 # added for this example
857 also=our_stuff # our system details, stored below
859 # information obtained from office system admin
860 # goes to the right of the = signs in these lines
861 # values shown here are just for example
863 left=1.2.3.4 # gateway IP address
864 lefttsubnet=42.42.42.0/24 # the office network
865 leftid=@gateway.example.com
866 # real keys are much longer than shown here
867 leftrsasigkey=0s1LgR7/oUM...
869 # description of our system
870 # included in other connection descriptions via also= lines
871 # must come after the lines that use it
872 # reversed from previous example
874 # all connections should use our default route
875 # also controls the source address on IPsec packets
877 # our identity for IPsec negotiations
878 # must match what is in DNS and ipsec.secrets(5)
879 righttid=@xy.example.com</pre>
881 <p>Everything else remains as it was when we had only opportunistic
884 <p>We could easily add more connections as required, perhaps one each for his
885 office, her office, the kid's school, ... The file would grow longer, but
886 nothing already in the file would need to change.</p>
888 <h3><a name="gate.road">Road Warrior support on an office gateway</a></h3>
890 <p>Adding road warrior support so people can connect remotely to your office
891 network is straightforward.</p>
893 <p>We start from the opportunistic gateway setup shown <a
894 href="#opp.gate">above</a>.</p>
896 <h4>Putting connection descriptions in separate files</h4>
898 <p>You could put a complete connection description for each Warrior in your
899 <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file, but this makes
900 for a rather unmanageable file if you have many Warriors.</p>
902 <p>Instead, we suggest you give each warrior its own file, choosing some
903 directory and naming convention that suits your system and style.</p>
905 <p>For this example, we use the directory <var>/etc/ipsec.road</var> and use
906 filenames based on IPsec ID, so the Warrior using ID
907 <var>xy.example.com</var> gets a file named <var>xy.conf</var>.</p>
909 <p>Using such files, you need add only one line to <a
910 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>. With our naming
911 convention, the line is:</p>
912 <pre> include /etc/ipsec.road/*.conf</pre>
914 <p>FreeS/WAN will then read all those files and behave as if they were part
915 of the ipsec.conf(5) file.</p>
917 <p>This needs to come before the <var>conn gate_stuff</var> section, so that
918 the Warriors' connection descriptions can use <var>also=gate_stuff</var>. A
919 convenient place for the line is right after the <var>conn %default</var>
922 <p>Each of the Road Warrior files then contains a connection description for
923 that Warrior. For example:</p>
924 <pre># connection description for Road Warrior "xy"
926 # use the gateway description in ipsec.conf(5)
928 # allow connection attempt from any address
929 # attempt fails if caller cannot authenticate
931 # authentication information
932 rightid=@xy.example.com
933 rightrsasigkey=0s1LgR7/oUM...</pre>
935 <p>With this technique, it becomes fairly simple to administer a gateway that
936 supports many Road Warriors. For example:</p>
938 <p>To add a new user, simply add a suitable file.</p>
940 <p>To disable an account -- for example if a key is compromised -- first
941 remove the file, then take any existing connection down with:</p>
942 <pre> ipsec auto --down <var>connection</var></pre>
943 and delete it from Pluto's internal database with:
944 <pre> ipsec auto --delete <var>connection</var></pre>
946 <p>If you have many users, it would be worthwhile to write scripts to
947 automate such tasks.</p>
949 <h2><a name="net2net">Network-to-network VPN</a></h2>
951 <p>Often it is useful to have explicitly configured IPsec tunnels between
952 different offices of an organisation, or between organisations that have
955 <p>Of course, if both offices are set up for opportunistic encryption and the
956 security policies in place allow you to use that, explicitly configured
957 tunnels become unnecessary. However, this will not always be the case.</p>
959 <h3><a name="gate.VPN">Gateway setup for net-to-net</a></h3>
961 <p>Adding up a network-to-network tunnel does not require any change to the
962 opportunistic or Road warrior parts of your <a
963 href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>. You can keep those
964 parts exactly as shown above.</p>
966 <p>Of course, a network-to-network tunnel requires its own connection
967 description, so you have to add that. There are two ways to do this.</p>
969 <dt>identical connection description on the two ends</dt>
970 <dd>needs to specify more detail so the machine can figure out which end
972 <dt>slightly different descriptions on the two ends</dt>
973 <dd>needs less detail, but you need to manage two descriptions</dd>
976 <p>Choose whichever is more convenient to administer in your environment.</p>
978 <h4>A connection description that works on either end</h4>
980 <p>Here is a network-to-network tunnel description from our <a
981 href="example">examples</a> file:</p>
983 # The network here looks like:
984 # leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
985 # If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
987 # left security gateway (public-network address)
989 # next hop to reach right
990 leftnexthop=10.44.55.66
991 # subnet behind left (omit if there is no subnet)
992 leftsubnet=172.16.0.0/24
993 # right s.g., subnet behind it, and next hop to reach left
995 rightnexthop=10.88.77.66
996 rightsubnet=192.168.0.0/24
999 <p>If you give an explicit IP address for <var>left</var> (and
1000 <var>left</var> and <var>right</var> are not directly connected), then you
1001 <strong>must</strong> specify <var>leftnexthop</var> (the router which
1002 <var>left</var> sends packets to in order to get them delivered to
1003 <var>right</var>). Similarly, you may need to specify <var>rightnexthop</var>
1006 <p>The <var>*nexthop</var> parameters are needed because of an unfortunate
1007 interaction between FreeS/WAN and the kernel routing code. They will be
1008 eliminated in a future release, but perhaps not soon. We know they should go,
1009 but getting them out is not a simple problem.</p>
1011 <p>This description can be generated on either machine and simply inserted in
1012 the ipsec.conf(5) file on the other. No change is required or desired.</p>
1014 <h4>Using slightly different descriptions</h4>
1016 <p>Provided both machines do IPsec over the interface that is their default
1017 route to the Internet (a common case, but by no means the only one) you can
1018 simplify the description somewhat.</p>
1020 <p>When using <var>left=%defaultroute</var>, you do not need to specify
1021 <var>leftnexthop</var>. <var>left</var> does not need to know
1022 <var>rightnexthop</var> either, so on <var>left</var> the connection
1023 description can be:</p>
1025 # left security gateway (public-network address)
1027 # subnet behind left (omit if there is no subnet)
1028 leftsubnet=172.16.0.0/24
1029 # right s.g., subnet behind it
1031 rightsubnet=192.168.0.0/24
1034 <p>On <var>right</var> it is:</p>
1036 # left security gateway (public-network address)
1038 # subnet behind left (omit if there is no subnet)
1039 leftsubnet=172.16.0.0/24
1040 # right s.g., subnet behind it
1042 rightsubnet=192.168.0.0/24
1047 <p>At this point, we have covered setup for opportunistic encryption and for
1048 simple cases of Road warrior and VPN connections. You have several choices
1049 for what to look at next:</p>
1051 <li>more <a href="adv_config.html">advanced configuration</a></li>
1052 <li><a href="firewall.html">FreeS/WAN and firewalls</a></li>
1053 <li>more detail on the <a href="ipsec.html">IPsec protocols</a></li>