1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
4 <TITLE> Introduction to FreeS/WAN</TITLE>
5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
8 <A HREF="toc.html">Contents</a>
9 <A HREF="intro.html">Previous</a>
10 <A HREF="config.html">Next</a>
12 <H1><A name="install">Installing FreeS/WAN</A></H1>
13 <H2><A name="who.install">Who needs to perform an installation?</A></H2>
14 <P> Some Linux distributions, <A href="intro.html#distwith">listed in
15 the introduction</A>, ship with FreeS/WAN included. If you are using
16 one of them, you need not perform a FreeS/WAN installation. That should
17 all be done for you already. All you have to do is:</P>
19 <LI>include FreeS/WAN in your installation choices, or add it to your
20 configuration later</LI>
21 <LI>if you install kernel source, be sure to use a version which
22 includes the FreeS/WAN patches. This should be available from your CDs
23 or from the web site for your distribution.</LI>
25 <P>Users of such distributions can skip ahead to our section on <A href="config.html">
26 setting up</A> FreeS/WAN.</P>
27 <P> Unfortunately, due to <A href="politics.html#exlaw">export laws</A>
28 restricting distribution of strong cryptography, not all distributions
29 include FreeS/WAN. Moreover, the standard kernel does not include the
30 kernel parts of FreeS/WAN. Many people will need to install FreeS/WAN,
31 including patching and rebuilding their kernel.</P>
32 <H2><A name="re-install">Re-installs</A></H2>
33 If this is the first FreeS/WAN install on this machine, skip this
35 <P> The scripts are designed so that a re-install -- to upgrade to a
36 later FreeS/WAN version or to a later kernel version -- can be done in
37 exactly the same way as an original install. </P>
38 <P> The scripts know enough, for example, not to apply the same kernel
39 patch twice and not to overwrite your <VAR>ipsec.conf</VAR> or <VAR>
40 ipsec.secrets</VAR> files. However, they will overwrite the _updown
41 script. If you have modified that, save your version under another name
42 before doing the install. </P>
43 <P> Also, they may not always work exactly as designed. Check the <A href="../BUGS">
44 BUGS</A> file for any caveats in the current version. </P>
46 <DT>to install a new version of FreeS/WAN, with your current kernel</DT>
47 <DD> Download and untar the new FreeS/WAN. Since kernel source has
48 already been installed and configured, you can skip a few steps in the
49 procedure below. Go to <A href="#building">Building FreeS/WAN</A>, and
50 follow normal FreeS/WAN procedures from there. </DD>
51 <DT>to install a new kernel, on a machine which already has FreeS/WAN
53 <DD> Download and untar the new kernel source. Since this kernel is not
54 yet configured, that is the next thing to do.Go to <A href="#kconfig">
55 Kernel configuration</A>, and follow normal FreeS/WAN procedures from
57 <DT>to upgrade both kernel and FreeS/WAN</DT>
58 <DD> You need both new kernel source and new FreeS/WAN source. Follow
59 the full FreeS/WAN install procedure. </DD>
61 <H2><A name="before">Before starting the install</A></H2>
62 <P>Configure, compile, install, and test a Linux kernel, without
64 <P> If you have not done this before, you will need to read the <A href="http://metalab.unc.edu/LDP/HOWTO/Kernel-HOWTO.html">
66 <H3><A name="choosek">Choosing a kernel</A></H3>
67 <H4><A name="2.2">2.2.19 for many users</A></H4>
68 <P> Many users can continue to run kernels from the 2.2 series of Linux
69 production <A href="glossary.html#kernel">kernels</A>. </P>
70 <P> At time of writing (June 2001), the latest version is 2.2.19. If
71 you are going to use a 2.2 kernel, we <STRONG>strongly recommend 2.2.19</STRONG>
74 <LI>It has a number of small security fixes not found in earlier
76 <LI>There have been changes in some kernel file formats that make it
77 difficult to compile a current FreeS/WAN with earlier kernels. </LI>
79 If you really need to use an older 2.2.x kernel for some reason, see
80 the note in the FreeS/WAN 1.91 release <A href="../CHANGES">CHANGES</A>
81 file for a workaround for the compile difficulty, and the <A href="mail.html">
82 mailing list archives</A> for more details if needed.
83 <H4><A name="2.4">2.4.x is possible</A></H4>
84 The new 2.4 series of kernels began in January 2001 and are currently
85 (early June) at 2.4.5. FreeS/WAN is known to work on 2.4.5.
86 <P> 2.4 has new firewalling code called <A href="http://netfilter.kernelnotes.org/unreliable-guides/index.html">
87 netfilter</A>. This may provide good reasons to move to 2.4, especially
88 on for gateway machines. </P>
89 <H4><A name="2.0">2.0.x should still work</A></H4>
90 <P> In the older 2.0.x kernel series, we no longer support versions
91 earlier than 2.0.38. 2.0.38 has fixes for a number of small
92 security-related glitches, worth having on a security gateway machine.
93 FreeS/WAN has been tested on 2.0.39, and does work there.</P>
94 <P> Recent versions of FreeS/WAN are not heavily tested on 2.0 kernels.
95 Most of both the development team and the user community are on 2.2, or
97 <P> We are likely to drop 2.0 support entirely if some problem crops up
98 that would mean retaining it required significant work from our team. </P>
99 <H4><A name="devkernel">Development kernels</A></H4>
100 Development kernels are a separate series, work-in-progress versions
101 for use by kernel developers. By convention, production kernels have an
102 even second digit in the version number (2.0, 2.2, 2.4) and development
103 kernels have an odd digit there (2.1, 2.3, 2.5).
104 <P> At time of writing, no more 2.3 kernels are being produced and the
105 2.5 series has not been started yet, so just now development kernels
106 are not an issue. No doubt a 2.5 series will be started in the next few
108 <P><STRONG> Development kernels are not intended for production use</STRONG>
109 . They change often and include new code which has not yet been
110 thoroughly tested. <STRONG>This regularly breaks things, including
111 FreeS/WAN</STRONG>. The FreeS/WAN team does not have the resources to
112 chase the moving target; our priority is developing FreeS/WAN on stable
113 kernels. If you encounter a problem on a development kernel, please
114 solve it (you are a developer, aren't you?) and send us a patch. Of
115 course, we will happily discuss problems and solutions on the <A href="mail.html">
116 mailing list</A>, but we are unlikely to do much work on actually
117 implementing a solution. </P>
118 <P> Fortunately we have a user who regularly fixes problems with
119 FreeS/WAN on development kernels (merci, Marc), and we do fix some
120 ourselves. FreeS/WAN often works just fine on a development kernel;
121 it's just that there's no guarantee. </P>
122 <P> If you are going to test FreeS/WAN with a development kernel, we
123 recommend you <STRONG>use our latest snapshot</STRONG>. This is the
124 FreeS/WAN version most likely to have the patches required to work on a
125 recent development kernel. The released version of FreeS/WAN is likely
126 to be out of date for your purposes.</P>
127 <H3><A name="getkernel">Things you must have installed</A></H3>
128 <P> If you have a CD distribution of Linux, it should include
129 everything you need. </P>
130 <H4><A " name="tool.lib">Tools and libraries</A></H4>
131 Use your distribution's tools to load:
135 <LI>a GNU C compiler (gcc or egcs)</LI>
136 <LI>assembler and linker for your architecture (the bin86 package on
138 <LI>miscellaneous development tools such as make(1) and patch(1)</LI>
141 <LI>libraries, both headers and object modules
143 <LI>standard compiler libraries such as glibc</LI>
144 <LI>the GMP (<STRONG>G</STRONG>NU <STRONG>M</STRONG>ulti-<STRONG>P</STRONG>
145 recision) library, required for Pluto's public key calculations. </LI>
146 <LI>ncurses library if you want to use menuconfig (recommended)</LI>
150 <P> There are some <STRONG>common slips</STRONG> worth avoiding here: </P>
152 <LI>not installing the GMP library. Pluto will not compile without it.
153 See the FreeS/WAN FAQ for <A href="faq.html#gmp.h_missing">more detail</A>
155 <LI>not installing patch(1). Our scripts need it to apply our patches
158 <H4><A name="kernel.">Kernel source code</A></H4>
159 You need the source code for the kernel because you must patch and
160 re-compile it to install FreeS/WAN. There are several places you can
163 <LI>off your distribution CDs </LI>
164 <LI>from your ditribution vendor's website </LI>
165 <LI>from kernel.org </LI>
167 <H5><A name="kernel.cd">Kernel from CD</A></H5>
168 You can install the kernel from your distribution CD. It may be in two
171 <LI>kernel source</LI>
172 <LI>kernel headers</LI>
174 However, if your CD is not recent, it may have an older kernel, in
175 which case we suggest getting more recent kernel source from the net.
176 <H5>Vendor kernels</H5>
177 <P> All the major distribution vendors provide kernel source. See for
180 <LI>Red Hat's list of <A href="http://www.redhat.com/mirrors.html">
181 mirror sites</A></LI>
182 <LI>SuSE's <A href="http://www.suse.com/us/support/download/index.html">
183 download page</A></LI>
185 <P> Using a kernel from your distribution vendor may save you some
187 <P> Different distributions put the kernel in different places
188 (/vmlinuz, /boot/vmlinuz, /boot/vmlinuz-2.2.15 ...) and set lilo (the <STRONG>
189 Li</STRONG>nux <STRONG>lo</STRONG>ader) up differently. With a kernel
190 from your distribution vendor, everything should work right. With
191 other combinations, a newly compiled kernel may be installed in one
192 place while lilo is looking in another. You can of course adjust the
193 kernel Makefile and/or /etc/lilo.conf to solve this problem, but we
194 suggest just avoiding it.</P>
195 <P> Also, distributions vendors may include patches or drivers which
196 are not part of the standard kernel. If you install a standard kernel,
197 you must either do without those features or download those patches
198 and add them yourself.</P>
199 <H5>Kernels from kernel.org</H5>
200 For kernels direct from Linus, without any distribution vendor's
201 modifications, see the <A href="http://www.kernel.org/mirrors/">
202 kernel.org</A> mirror list, or go directly to <NOBR><VAR>
203 ftp.<country>.kernel.org</VAR>,</NOBR> with the appropriate two-letter
204 country code inserted.
205 <H4>Once you've found a kernel</H4>
206 <P> Once you have found suitable kernel source, choose a mirror that is
207 close to you and bookmark it.</P>
208 <P> Kernel source normally resides in <VAR>/usr/src/linux</VAR>,
209 whether you load it from a distribution CD or download a tar file into <VAR>
210 /usr/src</VAR> and untar it there. Unless you both have unusual
211 requirements and know exactly what you're doing, we recommend you put
213 <H3><A NAME="2_3_3">Getting FreeS/WAN</A></H3>
214 <P> You can download FreeS/WAN from our <A href="ftp://ftp.xs4all.nl/pub/crypto/freeswan/">
215 primary site</A> or one of our <A href="intro.html#sites">mirrors</A>. </P>
216 <P> Put the tarfile under <VAR>/usr/src</VAR> and untar it there. The
217 command to use is: </P>
219 <LI>tar -xzf freeswan*.gz </LI>
221 <P> This will give you a directory <VAR>/usr/src/freeswan<version></VAR>
223 <P>Note that <STRONG>these methods don't work:</STRONG></P>
225 <LI>putting freeswan under <VAR>/usr/src/linux</VAR>. The links become
227 <LI>untarring in one place, then using <VAR>cp -R</VAR> to move it
228 where you want it. Some necessary symbolic links are not copied.</LI>
230 <H3><A name="kconfig">Kernel configuration</A></H3>
231 <P> The gateway kernel must be configured before FreeS/WAN is added
232 because some of our utilities rely on the results of configuration. </P>
233 <P><STRONG> Note for Redhat 7.1 users</STRONG>: If you are using the
234 Redhat-supplied kernel, then you <STRONG>must do a <NOBR><VAR>make
235 mrproper</VAR></NOBR></STRONG> command before starting the kernel
236 configuration. This prevents some unpleasant interactions between
237 Redhat's config and our patches. </P>
238 <P> On some distributions, you can get the configuration files for the
239 vendor's standard kernel(s) off the CD, and use that. This allows you
240 to skip this step; you need not configure the kernel if the vendor has <EM>
241 and you have the vendor's config file installed</EM>. Here is a mailing
242 list message describing the procedure for Redhat: </P>
244 Subject: Re: [Users] Do I need to recompile kernel 2.2.17-14?
245 Date: Wed, 6 Jun 2001 08:38:38 -0500
246 From: "Corey J. Steele" <csteele@mtron.com>
248 if you install the corresponding kernel-source-*.rpm, you can actually find
249 the config file used to build that kernel in /usr/src/linux/Configs, just
250 copy the one you want to use (based solely on architecture) to
251 /usr/src/linux/.config, and proceed! It should work.
253 If you have ever configured the kernel yourself on this machine, you
254 can also skip this step.
255 <P> If the kernel has not been configured, do that now. This is done by
256 giving one of the following commands in <VAR>/usr/src/linux</VAR>:</P>
259 <DD>command-line interface</DD>
260 <DT>make menuconfig</DT>
261 <DD>text menus (requires curses(3) libraries)</DD>
262 <DT>make xconfig</DT>
263 <DD>using the X window system (requires X, not recommended for
266 <P> Any of these wiil do the job. If you have no established
267 preference, we suggest trying <VAR>menuconfig</VAR>.</P>
268 <P> For more information on configuring your kernel, see our <A href="kernel.html">
269 section</A> on that topic.</P>
270 <H3><A name="inst-test">Install and test a kernel before adding
272 <P> You should compile, install and test the kernels as you have
273 configured them, so that you have a known stable starting point. The
274 series of commands involved is usually something like:</P>
276 <DT>make menuconfig</DT>
277 <DD>choose kernel options, set up a kernel for your machine</DD>
279 <DD>find <STRONG>dep</STRONG>endencies between files</DD>
280 <DT>make bzImage</DT>
281 <DD>build a loadable kernel image, compressed with bzip(1)</DD>
282 <DT>make install</DT>
284 <DT>make modules</DT>
285 <DD>build modules which can be added to a running kernel</DD>
286 <DT>make modules_install</DT>
287 <DD>install them</DD>
289 <DD>ensure that the boot loader sees your changes</DD>
291 <P> Doing this first means that if there is a problem after you add
292 FreeS/WAN, tracking it down is <EM>much</EM> simpler.</P>
293 <P> If you need advice on this process, or general Linux background
294 information, try our <A href="web.html#linux.link">Linux web references</A>
295 . The most directly relevant document is the <A href="http://metalab.unc.edu/LDP/HOWTO/Kernel-HOWTO.html">
296 Kernel HowTo</A>.</P>
297 <H2><A name="building">Building and installing the software</A></H2>
298 <P> There are several ways to build and install the software. All
299 require that you have kernel source, correctly configured for your
300 machine, as a starting point. If you don't have that yet, see the <A href="#before">
301 previous section</A></P>
302 <P> Whatever method you choose, it will do all of the following: </P>
304 <LI>add FreeS/WAN code to the kernel
306 <LI>insert patches into standard kernel code to provide an interface</LI>
307 <LI>add additional files which use that interface</LI>
310 <LI>re-configure and re-compile the kernel to activate that code</LI>
311 <LI>install the new kernel</LI>
312 <LI>build the non-kernel FreeS/WAN programs and install them
314 <LI><A href="manpage.d/ipsec.8.html">ipsec(8)</A> in <VAR>
315 /usr/local/sbin</VAR></LI>
316 <LI>others in <VAR>/usr/local/lib/ipsec</VAR></LI>
319 <LI>install FreeS/WAN <A href="manpages.html">man pages</A> under <VAR>
320 /usr/local/man</VAR></LI>
321 <LI>create the configuration file <A href="manpage.d/ipsec.conf.5.html">
322 ipsec.conf(5)</A>. Editing this file to configure your IPSEC gateway
323 is described in the <A href="config.html">next section</A>.</LI>
324 <LI>create an RSA public/private key pair for your system and place it
325 in <A href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</A></LI>
326 <LI>install the initialisation script <VAR>/etc/rc.d/init.d/ipsec</VAR></LI>
327 <LI>create links to that script from the <VAR>/etc/rc.d/rc[0-6].d</VAR>
328 directories so that each run level starts or stops IPSEC. (If the
329 previous sentence makes no sense to you, try the <A href="http://www.linuxdoc.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">
330 From Power-up to Bash Prompt HowTo</A>).</LI>
332 <P> You can do the whole install with two commands (recommended in most
333 cases) or get into as much of the detail as you like.</P>
334 <H3><A name="allbut">Everything but kernel installation</A></H3>
335 <P> To do everything except install the new kernel, <VAR>cd</VAR> into
336 the freeswan directory and become root. Give <STRONG>any one</STRONG>
337 of the following commands:</P>
340 <DD>Uses FreeS/WAN's default settings for some kernel configuration
341 options. Leaves all other options unchanged from your last kernel
344 <DD>Invokes <VAR>config</VAR> so you can configure the kernel from the
347 <DD>Invokes <VAR>menuconfig</VAR> so you can configure the kernel with
348 text-mode menus.</DD>
350 <DD>Invokes <VAR>xconfig</VAR> so you can configure the kernel in an X
353 <P> You must <STRONG>save the new configuration even if you make no
354 changes</STRONG>. This ensures that the FreeS/WAN changes are actually
355 seen by the system.</P>
356 <P> Our scripts save the output of <VAR>make</VAR> commands they call
357 in files with names like <VAR>out.kbuild</VAR> or <VAR>out.kinstall</VAR>
358 . The last command of each script checks the appropriate <VAR>out.*</VAR>
359 file for error messages.</P>
361 <LI>If the last output you see is <VAR>make</VAR> saying it is calling
362 our <VAR> errcheck</VAR> script, then all is well. There were no errors.</LI>
363 <LI>If not, an error has occurred. Check the appropriate <VAR>out.*</VAR>
364 file for details.</LI>
366 <P> For the above commands, the error files are <VAR>out.kpatch</VAR>
367 and <VAR>out.kbuild</VAR>. </P>
368 <P> These scripts automatically build an <A href="glossary.html#RSA">RSA</A>
369 authentication key pair (a public key and the matching private key)
370 for you, and put the result in <VAR>/etc/ipsec.secrets</VAR>. For
371 information on using RSA authentication, see our <A href="config.html">
372 configuration section</A>. Here, we need only note that generating the
373 key uses random(4) quite heavily and if random(4) runs out of
374 randomness, <STRONG>it will block until it has enough input</STRONG>.
375 You may need to provide input by moving the mouse around a lot, or
376 going to another window and typing random characters, or using some
377 command such as <VAR>du -s /usr</VAR> to generate disk activity.</P>
378 <H3><A name="newk">Installing the new kernel</A></H3>
379 <P>To install the kernel the easy way, just give this command in the
380 FreeS/WAN directory:</P>
382 <DT>make kinstall</DT>
383 <DD>Installs the new kernel and, if required, the modules to go with
384 it. Errors, if any, are reported in <VAR>out.kinstall</VAR></DD>
386 <P> Using <VAR>make kinstall</VAR> from the FreeS/WAN directory is
387 equivalent to giving the following sequence of commands in <VAR>
388 /usr/src/linux</VAR>:</P>
391 <LI>make install</LI>
392 <LI>make modules</LI>
393 <LI>make modules_install</LI>
395 <P>If you prefer that sequence, use it instead.</P>
396 <P> If you have some unusual setup such that the above sequence of
397 commands won't work on your system, then our <VAR>make kinstall</VAR>
398 will not work either. Use whatever method does work on your system.
399 See our <A href="impl.notes">implementation notes</A> file for
400 additional information that may help in such situations.</P>
402 <H3><A NAME="2_4_3">Make sure Lilo knows about the new kernel</A></H3>
403 <P> Check your lilo.conf(5) file to ensure it points to the right
404 kernel, then run lilo(8) to read lilo.conf(5) and set up the bootloader.</P>
405 <H2><A name="testinstall">Testing to see if install succeeded</A></H2>
406 <P> To check that you have a sucessful install, you can reboot and
407 check (by watching messages during boot or by looking at them later
408 with dmesg(8)) that:</P>
410 <LI>the kernel reports the right version. If not, you are likely still
411 running your old kernel. Check your lilo.conf(5) file and the
412 installation directory (defined in the kernel make file, often /boot
413 but the default is /), then rerun lilo(8).</LI>
414 <LI>KLIPS initialisation messages appear</LI>
415 <LI>Pluto reports that it is starting</LI>
417 <P>You can also try the commands:</P>
419 <LI><VAR>ipsec --version</VAR>, to test whether /usr/local/bin is in
420 your path so you can use IPSEC administration commands</LI>
421 <LI><VAR>ipsec whack --status</VAR>, using <A href="manpage.d#ipsec_whack.8.html">
422 ipsec_whack(8)</A> to ask Pluto for status information</LI>
424 <P> Of course any status information at this point should be
425 uninteresting since you have not yet configured connections.</P>
426 <H2><A NAME="2_6">Where to go from here</A></H2>
427 <P>See the following section for information on <A href="config.html">
428 configuring connections</A>.</P>
429 <P>Alternately, you might want to look at background material on the <A href="ipsec.html">
430 protocols used</A> before trying configuration.</P>
432 <A HREF="toc.html">Contents</a>
433 <A HREF="intro.html">Previous</a>
434 <A HREF="config.html">Next</a>