doc/src/quickstart.html

   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 &quot;FAX effect&quot; 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  &quot;X-IPsec-Server(10)=192.0.2.11&quot; &quot; AQOF8tZ2...+buFuFn/&quot;</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>