OSDN Git Service

2013.10.24
[uclinux-h8/uClinux-dist.git] / freeswan / doc / install.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2 <HTML>
3 <HEAD>
4 <TITLE> Introduction to FreeS/WAN</TITLE>
5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
6 </HEAD>
7 <BODY>
8 <A HREF="toc.html">Contents</a>
9 <A HREF="intro.html">Previous</a>
10 <A HREF="config.html">Next</a>
11 <HR>
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>
18 <UL>
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>
24 </UL>
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 
34 section. 
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>
45 <DL>
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 
52 installed</DT>
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 
56 there. </DD>
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>
60 </DL>
61 <H2><A name="before">Before starting the install</A></H2>
62 <P>Configure, compile, install, and test a Linux kernel, without 
63 FreeS/WAN.</P>
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">
65 Kernel HowTo</A>.</P>
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>
72  since: </P>
73 <UL>
74 <LI>It has a number of small security fixes not found in earlier 
75 kernels. </LI>
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>
78 </UL>
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 
96 even 2.4, by now.</P>
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 
107 months. </P>
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:
132 <UL>
133 <LI>tools 
134 <UL>
135 <LI>a GNU C compiler (gcc or egcs)</LI>
136 <LI>assembler and linker for your architecture (the bin86 package on 
137 PCs)</LI>
138 <LI>miscellaneous development tools such as make(1) and patch(1)</LI>
139 </UL>
140 </LI>
141 <LI>libraries, both headers and object modules 
142 <UL>
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>
147 </UL>
148 </LI>
149 </UL>
150 <P> There are some <STRONG>common slips</STRONG> worth avoiding here: </P>
151 <UL>
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>
154  if required. </LI>
155 <LI>not installing patch(1). Our scripts need it to apply our patches 
156 to the kernel. </LI>
157 </UL>
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 
161 get this: 
162 <UL>
163 <LI>off your distribution CDs </LI>
164 <LI>from your ditribution vendor's website </LI>
165 <LI>from kernel.org </LI>
166 </UL>
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 
169 packages. 
170 <UL>
171 <LI>kernel source</LI>
172 <LI>kernel headers</LI>
173 </UL>
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 
178 example:</P>
179 <UL>
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>
184 </UL>
185 <P> Using a kernel from your distribution vendor may save you some 
186 annoyance later.</P>
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.&lt;country&gt;.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 
212 it there.</P>
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>
218 <UL>
219 <LI>tar -xzf freeswan*.gz </LI>
220 </UL>
221 <P> This will give you a directory <VAR>/usr/src/freeswan&lt;version&gt;</VAR>
222 .</P>
223 <P>Note that <STRONG>these methods don't work:</STRONG></P>
224 <UL>
225 <LI>putting freeswan under <VAR>/usr/src/linux</VAR>. The links become 
226 confused.</LI>
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>
229 </UL>
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>
243 <PRE>
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: &quot;Corey J. Steele&quot; &lt;csteele@mtron.com&gt;
247
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.
252 </PRE>
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>
257 <DL>
258 <DT>make config</DT>
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 
264  gateways)</DD>
265 </DL>
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 
271 FreeS/WAN</A></H3>
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>
275 <DL>
276 <DT>make menuconfig</DT>
277 <DD>choose kernel options, set up a kernel for your machine</DD>
278 <DT>make dep</DT>
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>
283 <DD>install it</DD>
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>
288 <DT>lilo</DT>
289 <DD>ensure that the boot loader sees your changes</DD>
290 </DL>
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>
303 <UL>
304 <LI>add FreeS/WAN code to the kernel 
305 <UL>
306 <LI>insert patches into standard kernel code to provide an  interface</LI>
307 <LI>add additional files which use that interface</LI>
308 </UL>
309 </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 
313 <UL>
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>
317 </UL>
318 </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>
331 </UL>
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>
338 <DL>
339 <DT>make oldgo</DT>
340 <DD>Uses FreeS/WAN's default settings for some kernel configuration 
341  options. Leaves all other options unchanged from your last kernel 
342  configuration.</DD>
343 <DT>make ogo</DT>
344 <DD>Invokes <VAR>config</VAR> so you can configure the kernel from the 
345  command line.</DD>
346 <DT>make menugo</DT>
347 <DD>Invokes <VAR>menuconfig</VAR> so you can configure the kernel with 
348  text-mode menus.</DD>
349 <DT>make xgo</DT>
350 <DD>Invokes <VAR>xconfig</VAR> so you can configure the kernel in an X 
351  window.</DD>
352 </DL>
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>
360 <UL>
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>
365 </UL>
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>
381 <DL>
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>
385 </DL>
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>
389 <UL>
390 <LI>make</LI>
391 <LI>make install</LI>
392 <LI>make modules</LI>
393 <LI>make modules_install</LI>
394 </UL>
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>
401 <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>
409 <UL>
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>
416 </UL>
417 <P>You can also try the commands:</P>
418 <UL>
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>
423 </UL>
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>
431 <HR>
432 <A HREF="toc.html">Contents</a>
433 <A HREF="intro.html">Previous</a>
434 <A HREF="config.html">Next</a>
435 </BODY>
436 </HTML>