]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
1 | <html> |
2 | <head> | |
3 | <meta http-equiv="Content-Type" content="text/html"> | |
4 | <title>Quick FreeS/WAN installation and configuration</title> | |
5 | <meta name="keywords" | |
6 | content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart"> | |
7 | <!-- | |
8 | ||
9 | Written by Sandy Harris for the Linux FreeS/WAN project | |
10 | Revised by Claudia Schmeing for same | |
11 | Freely distributable under the GNU General Public License | |
12 | ||
13 | More information at www.freeswan.org | |
14 | Feedback to users@lists.freeswan.org | |
15 | ||
16 | CVS information: | |
17 | RCS ID: $Id: quickstart.html,v 1.1 2004/03/15 20:35:24 as Exp $ | |
18 | Last changed: $Date: 2004/03/15 20:35:24 $ | |
19 | Revision number: $Revision: 1.1 $ | |
20 | ||
21 | CVS revision numbers do not correspond to FreeS/WAN release numbers. | |
22 | --> | |
23 | </head> | |
24 | <BODY> | |
25 | <H1><A name="quickstart">Quickstart Guide to Opportunistic Encryption</A></H1> | |
26 | <A name="quick_guide"></A> | |
27 | ||
28 | <H2><A name="opp.setup">Purpose</A></H2> | |
29 | ||
30 | <P>This page will get you started using Linux FreeS/WAN with opportunistic | |
31 | encryption (OE). OE enables you to set up IPsec tunnels | |
32 | without co-ordinating with another | |
33 | site administrator, and without hand configuring each tunnel. | |
34 | If enough sites support OE, a "FAX effect" occurs, and | |
35 | many of us can communicate without eavesdroppers.</P> | |
36 | ||
37 | <H3>OE "flag day"</H3> | |
38 | ||
39 | <P>As of FreeS/WAN 2.01, OE uses DNS TXT resource records (RRs) | |
40 | only (rather than TXT with KEY). | |
41 | This change causes a | |
42 | <a href="http://jargon.watson-net.com/jargon.asp?w=flag+day">"flag day"</a>. | |
43 | Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may require | |
44 | additional resource records, as detailed in our | |
45 | <a href="upgrading.html#upgrading.flagday">upgrading document</a>. | |
46 | OE setup instructions here are for 2.02 or later.</P> | |
47 | ||
48 | ||
49 | <H2><A name="opp.dns">Requirements</A></H2> | |
50 | ||
51 | <P>To set up opportunistic encryption, you will need:</P> | |
52 | <UL> | |
53 | <LI>a Linux box. For OE to the public Internet, this box must NOT | |
54 | be behind <A HREF="glossary.html#NAT.gloss">Network Address Translation</A> | |
55 | (NAT).</LI> | |
56 | <LI>to install Linux FreeS/WAN 2.02 or later</LI> | |
57 | <LI>either control over your reverse DNS (for full opportunism) or | |
58 | the ability to write to some forward domain (for initiator-only). | |
59 | <A HREF="http://www.fdns.net">This free DNS service</A> explicitly | |
60 | supports forward TXT records for FreeS/WAN use.</LI> | |
61 | <LI>(for full opportunism) a static IP</LI> | |
62 | </UL> | |
63 | ||
64 | <P>Note: Currently, only Linux FreeS/WAN supports opportunistic | |
65 | encryption.</P> | |
66 | ||
67 | <H2><A name="easy.install">RPM install</A></H2> | |
68 | ||
69 | <P>Our instructions are for a recent Red Hat with a 2.4-series stock or | |
70 | Red Hat updated kernel. For other ways to install, see our | |
71 | <A href="install.html#install">install document</A>.</P> | |
72 | ||
73 | ||
74 | <H3>Download RPMs</H3> | |
75 | ||
76 | <P>If we have prebuilt RPMs for your Red Hat system, | |
77 | this command will get them: | |
78 | </P> | |
79 | ||
80 | <PRE> ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*</PRE> | |
81 | ||
82 | <P>If that fails, you will need to try <A HREF="install.html">another install | |
83 | method</A>. | |
84 | Our kernel modules | |
85 | <B>will only work on the Red Hat kernel they were built for</B>, | |
86 | since they are very sensitive to small changes in the kernel.</P> | |
87 | ||
88 | <P>If it succeeds, you will have userland tools, a kernel module, and an | |
89 | RPM signing key:</P> | |
90 | ||
91 | <PRE> freeswan-module-2.04_2.4.20_20.9-0.i386.rpm | |
92 | freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm | |
93 | freeswan-rpmsign.asc</PRE> | |
94 | ||
95 | ||
96 | <H3>Check signatures</H3> | |
97 | ||
98 | <P>If you're running RedHat 8.x or later, import the RPM signing key into the | |
99 | RPM database:</P> | |
100 | <PRE> rpm --import freeswan-rpmsign.asc</PRE> | |
101 | ||
102 | <P>For RedHat 7.x systems, you'll need to add it to your | |
103 | <A HREF="glossary.html#PGP">PGP</A> keyring:</P> | |
104 | <PRE> pgp -ka freeswan-rpmsign.asc</PRE> | |
105 | ||
106 | <P>Check the digital signatures on both RPMs using:</P> | |
107 | <PRE> rpm --checksig freeswan*.rpm </PRE> | |
108 | ||
109 | <P>You should see that these signatures are good:</P> | |
110 | <PRE> freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK | |
111 | freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK</PRE> | |
112 | ||
113 | ||
114 | <H3>Install the RPMs</H3> | |
115 | ||
116 | <P>Become root:</P> | |
117 | <PRE> su</PRE> | |
118 | ||
119 | <P>Install your RPMs with:<P> | |
120 | <PRE> rpm -ivh freeswan*.rpm</PRE> | |
121 | ||
122 | <P>If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with that | |
123 | command, see | |
124 | <A HREF="upgrading.html#upgrading.rpms">this note</A>.</P> | |
125 | ||
126 | <P>Then, start FreeS/WAN:</P> | |
127 | <PRE> service ipsec start</PRE> | |
128 | ||
129 | ||
130 | <H3><A name="testinstall">Test</A></H3> | |
131 | <P>To check that you have a successful install, run:</P> | |
132 | <PRE> ipsec verify</PRE> | |
133 | ||
134 | <P>You should see as part of the <var>verify</var> output:</P> | |
135 | <PRE> | |
136 | Checking your system to see if IPsec got installed and started correctly | |
137 | Version check and ipsec on-path [OK] | |
138 | Checking for KLIPS support in kernel [OK] | |
139 | Checking for RSA private key (/etc/ipsec.secrets) [OK] | |
140 | Checking that pluto is running [OK] | |
141 | ...</PRE> | |
142 | ||
143 | <P>If any of these first four checks fails, see our | |
144 | <A href="trouble.html#install.check">troubleshooting guide</A>. | |
145 | </P> | |
146 | ||
147 | <H2><A name="opp.setups.list">Our Opportunistic Setups</A></H2> | |
148 | <H3>Full or partial opportunism?</H3> | |
149 | <P>Determine the best form of opportunism your system can support.</P> | |
150 | <UL> | |
151 | <LI>For <A HREF="#opp.incoming">full opportunism</A>, you'll need a static | |
152 | IP and and either control over your reverse DNS or an ISP | |
153 | that can add the required TXT record for you.</LI> | |
154 | <LI>If you have a dynamic IP, and/or write access to forward DNS only, | |
155 | you can do <A HREF="#opp.client">initiate-only opportunism</A></LI> | |
156 | <LI>To protect traffic bound for real IPs behind your gateway, use | |
157 | <A HREF="adv_config.html#opp.gate">this form of full opportunism</A>.</LI> | |
158 | </UL> | |
159 | ||
160 | <H2><A name="opp.client">Initiate-only setup</A></H2> | |
161 | ||
162 | <H3>Restrictions</H3> | |
163 | <P>When you set up initiate-only Opportunistic Encryption (iOE):</P> | |
164 | <UL> | |
165 | <LI>there will be <STRONG> no incoming connection requests</STRONG>; you | |
166 | can initiate all the IPsec connections you need.</LI> | |
167 | <LI><STRONG>only one machine is visible</STRONG> on your end of the | |
168 | connection.</LI> | |
169 | <LI>iOE also protects traffic on behalf of | |
170 | <A HREF="glossary.html#NAT.gloss">NATted</A> hosts behind the iOE box.</LI> | |
171 | </UL> | |
172 | <P>You cannot network a group of initiator-only machines if none | |
173 | of these is capable of responding to OE. If one is capable of responding, | |
174 | you may be able to create a hub topology using routing.</P> | |
175 | ||
176 | ||
177 | <H3><A name="forward.dns">Create and publish a forward DNS record</A></H3> | |
178 | ||
179 | <H4>Find a domain you can use</H4> | |
180 | ||
181 | <P>Find a DNS forward domain (e.g. example.com) where you can publish your key. | |
182 | You'll need access to the DNS zone files for that domain. | |
183 | This is common for a domain you own. Some free DNS providers, | |
184 | such as <A HREF="http://www.fdns.net">this one</A>, also provide | |
185 | this service.</P> | |
186 | ||
187 | <P>Dynamic IP users take note: the domain where you place your key | |
188 | need not be associated with the IP address for your system, | |
189 | or even with your system's usual hostname.</P> | |
190 | ||
191 | <H4>Choose your ID</H4> | |
192 | ||
193 | <P>Choose a name within that domain which you will use to identify your | |
194 | machine. It's convenient if this can be the same as your hostname:</P> | |
195 | <PRE> [root@xy root]# hostname --fqdn | |
196 | xy.example.com</PRE> | |
197 | <P>This name in FQDN (fully-qualified domain name) | |
198 | format will be your ID, for DNS key lookup and IPsec | |
199 | negotiation.</P> | |
200 | ||
201 | ||
202 | <H4>Create a forward TXT record</H4> | |
203 | ||
204 | <P>Generate a forward TXT record containing your system's public key | |
205 | with a command like:</P> | |
206 | <PRE> ipsec showhostkey --txt @xy.example.com</PRE> | |
207 | <P>using your chosen ID in place of | |
208 | xy.example.com. | |
209 | This command takes the contents of | |
210 | /etc/ipsec.secrets and reformats it into something usable by ISC's BIND. | |
211 | The result should look like this (with the key data trimmed down for | |
212 | clarity):</P> | |
213 | <PRE> | |
214 | ; RSA 2192 bits xy.example.com Thu Jan 2 12:41:44 2003 | |
215 | IN TXT "X-IPsec-Server(10)=@xy.example.com" | |
216 | "AQOF8tZ2... ...+buFuFn/" | |
217 | </PRE> | |
218 | ||
219 | ||
220 | <H4>Publish the forward TXT record</H4> | |
221 | ||
222 | <P>Insert the record into DNS, or have a system adminstrator do it | |
223 | for you. It may take up to 48 hours for the record to propagate, but | |
224 | it's usually much quicker.</P> | |
225 | ||
226 | <H3>Test that your key has been published</H3> | |
227 | ||
228 | <P>Check your DNS work</P> | |
229 | ||
230 | <PRE> ipsec verify --host xy.example.com</PRE> | |
231 | ||
232 | <P>As part of the <var>verify</var> output, you ought to see something | |
233 | like:</P> | |
234 | ||
235 | <PRE> ... | |
236 | Looking for TXT in forward map: xy.example.com [OK] | |
237 | ...</PRE> | |
238 | ||
239 | <P>For this type of opportunism, only the forward test is relevant; | |
240 | you can ignore the tests designed to find reverse records.</P> | |
241 | ||
242 | ||
243 | <H3>Configure, if necessary</H3> | |
244 | ||
245 | <P> | |
246 | If your ID is the same as your hostname, | |
247 | you're ready to go. | |
248 | FreeS/WAN will use its | |
249 | <A HREF="policygroups.html">built-in connections</A> to create | |
250 | your iOE functionality. | |
251 | </P> | |
252 | ||
253 | <P>If you have chosen a different ID, you must tell FreeS/WAN about it via | |
254 | <A HREF="manpage.d/ipsec.conf.5.html"><VAR>ipsec.conf</VAR></A>: | |
255 | ||
256 | <PRE> config setup | |
257 | myid=@myname.freedns.example.com</PRE> | |
258 | ||
259 | <P>and restart FreeS/WAN: | |
260 | </P> | |
261 | <PRE> service ipsec restart</PRE> | |
262 | <P>The new ID will be applied to the built-in connections.</P> | |
263 | ||
264 | <P>Note: you can create more complex iOE configurations as explained in our | |
265 | <A HREF="policygroups.html#policygroups">policy groups document</A>, or | |
266 | disable OE using | |
267 | <A HREF="policygroups.html#disable_policygroups">these instructions</A>.</P> | |
268 | ||
269 | ||
270 | <H3>Test</H3> | |
271 | <P>That's it! <A HREF="#opp.test">Test your connections</A>.</P> | |
272 | ||
273 | <A name="opp.incoming"></A><H2>Full Opportunism</H2> | |
274 | ||
275 | <P>Full opportunism | |
276 | allows you to initiate and receive opportunistic connections on your | |
277 | machine.</P> | |
278 | ||
279 | <A name="incoming.opp.dns"></A><H3>Put a TXT record in a Forward Domain</H3> | |
280 | ||
281 | <P>To set up full opportunism, first | |
282 | <A HREF="#forward.dns">set up a forward TXT record</A> as for | |
283 | <A HREF="#opp.client">initiator-only OE</A>, using | |
284 | an ID (for example, your hostname) that resolves to your IP. Do not | |
285 | configure <VAR>/etc/ipsec.conf</VAR>, but continue with the | |
286 | instructions for full opportunism, below. | |
287 | </P> | |
288 | ||
289 | <P>Note that this forward record is not currently necessary for full OE, | |
290 | but will facilitate future features.</P> | |
291 | ||
292 | ||
293 | <A name="incoming.opp.dns"></A><H3>Put a TXT record in Reverse DNS</H3> | |
294 | ||
295 | <P>You must be able to publish your DNS RR directly in the reverse domain. | |
296 | FreeS/WAN will not follow a PTR which appears in the reverse, since | |
297 | a second lookup at connection start time is too costly.</P> | |
298 | ||
299 | ||
300 | <H4>Create a Reverse DNS TXT record</H4> | |
301 | ||
302 | <P>This record serves to publicize your FreeS/WAN public key. In | |
303 | addition, it lets others know that this machine can receive opportunistic | |
304 | connections, and asserts that the machine is authorized to encrypt on | |
305 | its own behalf.</P> | |
306 | ||
307 | <P>Use the command:</P> | |
308 | <PRE> ipsec showhostkey --txt 192.0.2.11</PRE> | |
309 | <P>where you replace 192.0.2.11 with your public IP.</P> | |
310 | ||
311 | <P>The record (with key shortened) looks like:</P> | |
312 | <PRE> ; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 | |
313 | IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"</PRE> | |
314 | ||
315 | ||
316 | <H4>Publish your TXT record</H4> | |
317 | ||
318 | <P>Send these records to your ISP, to be published in your IP's reverse map. | |
319 | It may take up to 48 hours for these to propagate, but usually takes | |
320 | much less time.</P> | |
321 | ||
322 | ||
323 | <H3>Test your DNS record</H3> | |
324 | ||
325 | <P>Check your DNS work with</P> | |
326 | ||
327 | <PRE> ipsec verify --host xy.example.com</PRE> | |
328 | ||
329 | <P>As part of the <var>verify</var> output, you ought to see something like:</P> | |
330 | ||
331 | <PRE> ... | |
332 | Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK] | |
333 | ...</PRE> | |
334 | ||
335 | <P>which indicates that you've passed the reverse-map test.</P> | |
336 | ||
337 | <H3>No Configuration Needed</H3> | |
338 | ||
339 | <P>FreeS/WAN 2.x ships with full OE enabled, so you don't need to configure | |
340 | anything. | |
341 | To enable OE out of the box, FreeS/WAN 2.x uses the policy group | |
342 | <VAR>private-or-clear</VAR>, | |
343 | which creates IPsec connections if possible (using OE if needed), | |
344 | and allows traffic in the clear otherwise. You can create more complex | |
345 | OE configurations as described in our | |
346 | <A HREF="policygroups.html#policygroups">policy groups document</A>, or | |
347 | disable OE using | |
348 | <A HREF="policygroups.html#disable_policygroups">these instructions</A>.</P> | |
349 | ||
350 | <P>If you've previously configured for initiator-only opportunism, remove | |
351 | <VAR>myid=</VAR> from <VAR>config setup</VAR>, so that peer FreeS/WANs | |
352 | will look up your key by IP. Restart FreeS/WAN so that your change will | |
353 | take effect, with</P> | |
354 | ||
355 | <PRE> service ipsec restart</PRE> | |
356 | ||
357 | ||
358 | <H3>Consider Firewalling</H3> | |
359 | ||
360 | <P>If you are running a default install of RedHat 8.x, take note: you will | |
361 | need to alter your iptables rule setup to allow IPSec traffic through your | |
362 | firewall. See <A HREF="firewall.html#simple.rules">our firewall document</A> | |
363 | for sample <VAR>iptables</VAR> rules.</P> | |
364 | ||
365 | ||
366 | <H3>Test</H3> | |
367 | ||
368 | <P>That's it. Now, <A HREF="#opp.test">test your connection</A>. | |
369 | ||
370 | ||
371 | ||
372 | ||
373 | <H3>Test</H3> | |
374 | ||
375 | <P>Instructions are in the next section.</P> | |
376 | ||
377 | ||
378 | <H2><A NAME="opp.test">Testing opportunistic connections</A></H2> | |
379 | ||
380 | <P>Be sure IPsec is running. You can see whether it is with:</P> | |
381 | <PRE> ipsec setup status</PRE> | |
382 | <P>If need be, you can restart it with:</P> | |
383 | <PRE> service ipsec restart</PRE> | |
384 | ||
385 | <P>Load a FreeS/WAN test website from the host on which you're running | |
386 | FreeS/WAN. Note: the feds may be watching these sites. Type one of:<P> | |
387 | <PRE> links oetest.freeswan.org</PRE> | |
388 | <PRE> links oetest.freeswan.nl</PRE> | |
389 | <!--<PRE> links oetest.freeswan.ca</PRE>--> | |
390 | ||
391 | <P>A positive result looks like this:</P> | |
392 | ||
393 | <PRE> | |
394 | You seem to be connecting from: 192.0.2.11 which DNS says is: | |
395 | gateway.example.com | |
396 | _________________________________________________________________ | |
397 | ||
398 | Status E-route | |
399 | OE enabled 16 192.139.46.73/32 -> 192.0.2.11/32 => | |
400 | tun0x2097@192.0.2.11 | |
401 | OE enabled 176 192.139.46.77/32 -> 192.0.2.11/32 => | |
402 | tun0x208a@192.0.2.11 | |
403 | </PRE> | |
404 | ||
405 | <P>If you see this, congratulations! Your OE host or gateway will now encrypt | |
406 | its own traffic whenever it can. For more OE tests, please see our | |
407 | <A HREF="testing.html#test.oe">testing document</A>. If you have difficulty, | |
408 | see our <A HREF="#oe.trouble">OE troubleshooting tips</A>. | |
409 | </P> | |
410 | ||
411 | ||
412 | ||
413 | <H2>Now what?</H2> | |
414 | ||
415 | <P>Please see our <A HREF="policygroups.html">policy groups document</A> | |
416 | for more ways to set up Opportunistic Encryption.</P> | |
417 | ||
418 | <P>You may also wish to make some <A HREF="config.html"> | |
419 | pre-configured connections</A>. | |
420 | </P> | |
421 | ||
422 | <H2>Notes</H2> | |
423 | ||
424 | <UL> | |
425 | <LI>We assume some facts about your system in order to make Opportunistic | |
426 | Encryption easier to configure. For example, we assume that you wish | |
427 | to have FreeS/WAN secure your default interface.</LI> | |
428 | <LI>You may change this, and other settings, by altering the | |
429 | <VAR>config setup</VAR> section in | |
430 | <VAR>/etc/ipsec.conf</VAR>. | |
431 | </LI> | |
432 | <LI>Note that the built-in connections used to build policy groups do | |
433 | not inherit from <VAR>conn default</VAR>.</LI> | |
434 | <!-- | |
435 | <LI>If you do not define your local identity | |
436 | (eg. <VAR>leftid</VAR>), this will be the IP address of your default | |
437 | FreeS/WAN interface. | |
438 | --> | |
439 | <LI> | |
440 | If you fail to define your local identity and | |
441 | do not fill in your reverse DNS entry, you will not be able to use OE.</LI> | |
442 | </UL> | |
443 | ||
444 | <A NAME="oe.trouble"></A><H2>Troubleshooting OE</H2> | |
445 | ||
446 | <P>See the OE troubleshooting hints in our | |
447 | <A HREF="trouble.html#oe.trouble">troubleshooting guide</A>. | |
448 | </P> | |
449 | ||
450 | <A NAME="oe.known-issues"></A><H2>Known Issues</H2> | |
451 | ||
452 | <P>Please see | |
453 | <A HREF="opportunism.known-issues">this list</A> of known issues | |
454 | with Opportunistic Encryption.</P> | |
455 | ||
456 | ||
457 | </BODY> | |
458 | </HTML> |