Linux FreeS/WAN Setup

This document describes setting up Linux FreeS/WAN (Secure Wide Area Network), and intial testing to confirm it all works.

The distribution includes many other documents. See our index for a list.

Setting up a secure tunnel to create a VPN

The problem we are trying to solve is that of letting two networks communicate securely when the only connection between them is over a third network which they do not trust. The solution is to put a security gateway machine between each of the communicating networks and the untrusted network. The gateway machines encrypt packets entering the untrusted net and decrypt packets leaving it, creating a secure tunnel through it.

The result is called a VPN, a Virtual Private Network. If the cryptography is strong, the implementation is careful, and the administration of the gateways is competent, then one can reasonably trust the security of the tunnel. The two networks then behave like a single large private network, some of whose links are encrypted tunnels through untrusted nets.

Actual VPNs are often more complex. One organisation may have fifty branch offices, plus some suppliers and clients, with whom it needs to communicate securely. Another might have 5,000 stores, or 50,000 point-of-sale devices. Many VPNs need to handle travelling users, the "road warrior" connecting to home base from a laptop machine.

The untrusted network need not be the Internet. All the same issues arise on a corporate or institutional network whenever two departments want to communicate privately with each other.

Types of connection

A complication is that a secure connection cannot be created magically. There must be some mechanism which enables the gateways to reliably identify each other. Without this, they cannot sensibly trust each other and cannot create a genuinely secure link.

Any link they do create without some form of authentication will be vulnerable to a man-in-the-middle attack. If Alice and Bob are the people creating the connection, a villian who can re-route or intercept the packets can pose as Alice while talking to Bob and pose as Bob while talking to Alice. Alica and Bob then both talk to the man in the middle, thinking they are talking to each other, and the villain gets everything sent on the bogus "secure" connection.

There are several ways to build links securely, all of which exclude the man-in-the middle:

To get everything tested, we will build two connections in this document:
manually keyed
Tests the lower levels of FreeS/WAN without the complications of automatic mode. Note that what we build here is purely a test connection using well-known test keys, and is therefore completely insecure. Information on building secure manual mode connections for actual use is in the configuration document.
auto-keyed using shared secrets for authentication
Tests automatic mode in its simplest form. Please test your system by building these two connections before trying to configure other connections. If this is not done, troubleshooting becomes a great deal more difficult. Neither you nor we have time to waste solving avoidable problems.

Our example network

For our example, we assume that there are only three networks involved, two that want to talk to each other plus the Internet in the middle. The idea is to build an encrypted tunnel across the Internet so the two networks can talk securely. Once you have this working between two network gateways, extending it to three or more is straightforward.

We also assume here that all machines involved have known, fixed IP addresses. See our Configuration document for some information on supporting "road warriors".

In our example, we'll call the two gateways East and West. We'll have only one client machine on each net: Sunrise in the East and Sunset in the West.

A diagram:

              local net       untrusted net       local net

Our goal in this document is to tell you how to set up the two gateways, East and West. We assume your goal is to ensure that East and West encrypt all traffic between them, or at least all that your security policies require them to encrypt.

Configuration for a testbed network

Many users just want to get IPSEC installed on a few machines. They can skip this section.

Others may want to build a testbed network, for any of a number of reasons. For them, we have some suggstions.

The ideal test setup for IPSEC is something like:

	Sunset==========West-----eth0    eth1-----East=========Sunrise
              local net          test machine         local net
The test machine routes packets between the two gateways. This makes things more complicated than if you just connected the two gateway machines directly to each other, but it also makes your test setup much more like the environment you actually use IPSEC in. Those environments nearly always involve routing, and quite a few apparent IPSEC failures turn out to be problems with routing or with firewalls dropping packets. This approach lets you deal with those problems on your test setup.

Also, the test machine is in the ideal position to run diagnostic software (such as tcpdump) for checking IPSEC packets. Such software is likely to misbehave if run on the gateways themselves. It is designed to look into a normal IP stack and may become confused if you ask it to display data from a stack which has IPSEC in play.

SuSE 6.3 and 6.4

Recent European version of the SuSE distribution ship with FreeS/WAN included. If you are using one of them, you need not download kernel source and FreeS/WAN code, then apply our kernel patches and install the rest of FreeS/WAN. That should all be done for you already. All you have to do is:

  • include FreeS/WAN in your installation choices, or add it later with YaST
  • if you install kernel source, be sure to use a version which includes the FreeS/WAN patches. This should be available from your CDs or from the SuSE web site.
Here, users of such SuSE releases can skip ahead to our section on editing configuration files.

Installation steps

    Before starting the install

  1. Configure, compile, install, test and back up Linux kernels on both gateways, without FreeS/WAN.

    Choosing a kernel

    Most users should run the latest production version of the Linux kernel. At time of writing (mid-June 2000), that is 2.2.16.

    In the older 2.0.x kernel series, we no longer support versions earlier than 2.0.38. 2.0.38 has fixes for a number of small security-related glitches, worth having on a security gateway machine.

    We do not recommend the 2.3 series of development kernels for production use. If you are going to try FreeS/WAN on a 2.3.x kernel, use the latest 2.3 release and our latest code snapshot. The rapid change in these kernel versions regularly breaks things. Fortunately we have a user who almost equally regularly fixes them, and we fix some ourselves. However you will often need the latest patches, so use our latest snapshot.

    Our code does run on (at least the Intel architecture version of) the 2.4-test1 kernel, but we would recommend this only for experimentation, not for actual use. We have not, at time of writing, tried it on or patched it for the test1-ac?? series of modified test kernels. If anyone does try other 2.4-test kernels, either newer or non-Intel versions, we would like to hear of it on the mailing list.

    For information on other CPU architectures see our Implementation Notes file and our Compatibility document.

    Getting kernel source

    There are many sources on the net for Linux kernels. All the major distribution vendors provide them. See for example: For kernels direct from Linus, without any distribution vendor's modifications, see the mirror list, or go directly to ftp.<your country>, with the appropriate two-letter country code inserted.

    For any of these, choose a mirror that is close to you and bookmark it.

    Using a kernel from your distribution vendor may save you some annoyance later.

    • Different distributions put the kernel in different places (/vmlinuz, /boot/vmlinuz, /boot/vmlinuz-2.2.15 ...) and set lilo (the Linux loader) up differently. With a kernel from your distribution vendor, everything should work right. With other combinations, a newly compiled kernel may be installed in one place while lilo is looking in another. You can of course adjust the kernel Makefile and/or /etc/lilo.conf to solve this problem, but we suggest just avoiding it.
    • Also, distributions vendors may include patches or drivers which are not part of the standard kernel. If you install a standard kernel, you must either do without those features or download those patches and add them yourself.

    Kernel source normally resides in /usr/src/linux, whether you load it from a distribution CD or download a tar file into /usr/src and untar it there.

    We suggest the same procedure for FreeS/WAN. Put the tarfile under /usr/src. You will get a directory /usr/src/freeswan<version> when you untar.

    Note that these methods don't work:

    • putting freeswan under /usr/src/linux. The links become confused.
    • untarring in one place, then cp -R to move it where you want it. Some necessary symbolic links are not copied.

    Kernel configuration

    You need to configure the gateway kernels because some of our utilities rely on the results of configuration. This is done by giving one of the following commands in /usr/src/linux:

    make config
    command-line interface
    make menuconfig
    text menus
    make xconfig
    using the X window system

    Any of these wiil do the job. If you have no established preference, we suggest trying menuconfig.

    Install and test a kernel before adding FreeS/WAN

    You should compile, install and test the kernels as you have configured them, so that you have a known stable starting point. Then if there is a problem after you add FreeS/WAN, tracking it down is much simpler.

    If you need advice on this process, or general Linux background information, try our list of Linux web references. The most directly relevant document is the Kernel HOWTO. We also provide a file of notes on kernel installation.

  2. Configure and test IP networking on both gateways and on at least one client machine behind each of them.

    If you need advice on this, your best sources are likely the Net-3 Networking Howto and the Network Administrator's Guide.

    Here is our network diagram again:

                  local net       untrusted net       local net

    The client machines, Sunrise and Sunset in our example, may have assigned routable IP addresses, or they may be using private non-routable addresses (as defined in RFC 1918) with the gateways doing IP masquerade. It doesn't matter which, as long as whatever it is works correctly.

    Note, however, that the two subnets must have distinct addresses. You cannot have them both masqueraded to the same range of RFC 1918 addresses.

    • If Sunrise and Sunset have routable IP addresses, test that they can ping each other.
    • If IP masquerading is in use, test as far as you can. For example, if Sunset is masqueraded behind West then Sunrise cannot ping Sunset but should be able to ping West. Whether Sunset can ping Sunrise, assuming Sunrise is not masqueraded, would depend on whether West's rules let ICMP packets through. If not, you should adjust those rules.

    In any case, it is not enough to just test that East and West can communicate.

    Note that Redhat turns off packet forwarding by default, even for kernels in which it has been enabled. To turn it on:

    • Temporarily, use the following command as root:
               echo "1" > /proc/sys/net/ipv4/ip_forward
    • Permanently, edit the file /etc/sysconfig/network
      Change the FORWARD_IPV4 line to read:
    A gateway machine needs forwarding enabled or it will not route packets between the two networks it is attached to.

    Configure and test any other software you will want to use for testing once IPSEC is up. For example, you might put an HTTP daemon on Sunset and a browser on Sunrise. Make sure these work without IPSEC.

    If these tests fail, figure out why and fix it.
    Do not proceed until it works.

    Building the software

  3. Did you do the steps listed above? If not, please go back and do them now. Doing them first makes troubleshooting any problems you may encounter later much easier.

  4. Build and install FreeS/WAN.

    There are several ways to do this. All of them:

    All of our scripts save the output of make commands they call in files wth names like out.kbuild or out.kinstall. The last command of each script checks the appropriate out.* file for error messages.

    • If the last output you see is make saying it is calling our errcheck script, then all is well. There were no errors.
    • If not, an error has occurred. Check the appropriate out.* file for details.

    You can do the whole install with two commands (recommended in most cases) or get into as much of the detail as you like.

    We provide the command make kinstall to install the kernel. Using this from the FreeS/WAN directory is equivalent to giving the following sequence of commands in /usr/src/linux:

    • make
    • make install
    • make modules
    • make modules_install
    If you have some unusual setup such that the above sequence of commands won't work on your system, then do not use make kinstall. Install the kernel your way.

    The simplest way

    cd into the freeswan directory and become root. Give these two commands:

    make oldgo
    Does everything except install the new kernel
    Uses FreeS/WAN's default settings for some kernel configuration options.
    Leaves all other options unchanged from your last kernel configuration.
    make kinstall
    Installs the new kernel and, if required, the modules to go with it.

    Configuring the kernel yourself

    cd into the freeswan directory and become root. As above, you will give only two commands.

    Choose the first command from:

    make ogo
    If you prefer config for configuring a kernel.
    make menugo
    If you prefer menuconfig for configuring a kernel.
    make xgo
    If you prefer xconfig for configuring a kernel.

    These do everything except install the new kernel. The difference from make oldgo is that they give you a chance to configure the new kernel with your preferred tool. You should save the new configuration even if you make no changes. This ensures that the FreeS/WAN changes are actually seen by the system.

    The second command is just:

    make kinstall
    Installs the new kernel and, if required, the modules to go with it.

    Doing it step-by-step

    If you prefer a number of smaller steps, handling all the details yourself, see our
    implementation notes file.

    Configuration files

  5. Pick one machine on which you will edit the two files:

    Editing these two files is how you configure IPSEC connections. Here we will set up two test connections, one for ipsec_manual(8) and one for ipsec_auto(8).

    As with most things on any Unix-like system, most parts of Linux FreeS/WAN are documented in online manual pages. We provide a list of FreeS/WAN man pages, with links to HTML versions of them. The man page describing these files are:

    You can read them either in HTML using the links above or with the man(1) command.

    You may also want to look at manual pages for ipsec_manual(8) and ipsec_auto(8) which document the two types of connections you will set up here, and at our example configurations file.

    Types of connection

    We currently support two types of connections, started with commands such as:
    	ipsec manual --start name
    	ipsec auto --up name
    The difference is in how they are keyed.
    Manually keyed connections
    use keys stored in ipsec.conf.
    Automatically keyed connections
    use keys automatically generated by the Pluto key negotiation daemon. The key negotiation protocol, IKE, must authenticate the other system. (It is vulnerable to a man-in-the-middle attack if used without authentication.) We currently support two authentication methods:

    Here we will set up test connections in both manual mode and automatic mode.

    For actual use, the steps involved would be:

    • edit connection information used by both modes, in ipsec.conf
    • add keys for manual mode (if used), in ipsec.conf
    • add secrets used for authentication during key negotiation, in ipsec.secrets
      • either secrets shared between machines
      • or a private key for your machine
    Here we will use pre-set data for manual mode keys and for shared secrets. This lets us test after performing only the first step above, making sure we can build IPSEC connections before trying to secure them.

    Note, however, that these test connections will be entirely insecure. Testing is easier if everyone uses the same key, but these keys are utterly useless for security since any attacker with a grain of sense can be expected to discover them.

    The setup section of ipsec.conf(5)

    The first section of ipsec.conf(5) contains overall setup parameters for IPSEC, which apply to all connections. In our example file, it is:

    # basic configuration
    config setup
    	# THIS SETTING MUST BE CORRECT or almost nothing will work;
    	# %defaultroute is okay for most simple cases.
    	# Debug-logging controls:  "none" for (almost) none, "all" for lots.
    	# Use auto= parameters in conn descriptions to control startup actions.
    The variables set here are:

    Tells the KLIPS IPSEC code in the Linux kernel which network interface to use.

    In many cases, the appropriate interface is just your default connection to the world (the Internet, or your corporate network). In these cases, you can use the default setting:

    • interfaces=%defaultroute

    In other cases, you can name one or more specific interfaces to be used by FreeS/WAN. For example:

    • interfaces="ipsec0=eth0"
    • interfaces="ipsec0=eth0 ipsec1=ppp0"
    Both tell KLIPS to use eth0 as ipsec0. The second one also supports IPSEC over PPP.

    Note that multiple tunnels do not require multiple interfaces. It is possible, and even common, to have one ipsec interface carrying traffic for many tunnels.

    The interfaces specified here are the only ones this gateway machine can use to communicate with other IPSEC gateways. If this is not correct, nothing works.

    If you need to discover interface names, use the command:

    If you have PCMCIA or other interfaces that are not available at boot time, special measures are required. See our Configuration document.

    Debugging setting for the KLIPS kernel code
    Debugging setting for the Pluto key and connection negotiation daemon.

    klipsdebug and plutodebug can each be set to "none" or to "all" in most circumstances. There are other options; see the relevant man pages.

    List of connections to be automatically loaded into memory when Pluto starts.
    List of connections to be automatically negotiated when Pluto starts.

    plutoload and plutostart can be quoted lists of connection names, but are often set to %search as in our example. Any connection with auto=add in its connection definition is then loaded, and any connection with auto=start is started.

    In most cases, you want plutostart=%search here and auto=start in your connection descriptions. That way when a connection is broken, for example if one machine crashes or is taken down for some reason, it will be reliably rebuilt. If only one end is told to start the connection, then if the other end crashes, you may lose the connection for a long time. The end that could rebuild does not know it needs to.

    The exception to the above is when you have many road warriors connecting to a single gateway. Having the gateway trying to rebuild tunnels to systems which are offline can waste considerable resources. In this case, the gateway should have auto=load for all connections, and let the remote systems start negotiations.

    Editing connections in ipsec.conf(5)

  6. The easiest way to create a connection is by editing one of our examples. Here we will use the one in the installation ipsec.conf file. You could also start with one from our doc/examples file if one of those is closer to what you need to do.
    Connection defaults
    There is a special name %default that lets you define things that apply to all connections. e.g. our example file has:
    # defaults for subsequent connection descriptions
    conn %default
    	# How persistent to be in (re)keying negotiations (0 means very).
    	# Parameters for manual-keying testing (DON'T USE OPERATIONALLY).
    You cannot set the auto parameter here. That must be done individually for each connection.

    Variables set here are:

    How persistent to be in (re)keying negotiations (0 means very).

    For testing, you might wish to set this to some small number, perhaps even to 1, to avoid wasting resources on incorrectly set up connections. In production, it is often set to zero (retry forever); keeping the connection up is what machine resources are for.

    A number needed by the manual keying code. Any 3-digit hex number will do, but if you have more than one manual connection then spi must be different for each connection.
    Options for ESP (Encapsulated Security Payload), the usual IPSEC encryption mode. Settings here are for encryption using triple DES and authentication using MD5. Note that encryption without authentication should not be used; it is insecure.
    Key for ESP encryption. Here, a 192-bit hex number for triple DES.
    Key for ESP authentication. Here, a 128-bit hex number for MD5.

    Note that the keys we supply here are intended only for testing. For real use, you should go to automatic keying. If that is not possible, create your own keys for manual mode and keep them secret. See the configuration document for details.

    Once you are finished testing, you should edit these defaults:

    • delete the test keys or comment them out with # characters
    • add anything that is standard for all gateways in your organisation
    Note, however, that putting auto=start in the default connection description to get all connections started automatically does not work. Nor does using auto=load here.

    Editing a connection description
    Edit our example connection to match what you want to do. Rename it appropriately for the connection you would like to build: "fred-susan", "reno-van" or whatever. The name is the second string in the line that begins with "conn", for example in:
    	conn snt
    The connection name is "snt" and to define another connection you make a copy with a new name such as:
    	conn reno-van
    A sample connection description is:
    # sample tunnel (manually or automatically keyed)
    # "(manual)" means relevant only to manual keying, "(auto)" only to automatic.
    # For manual keying, we use ESP for both encryption and authentication, the
    # simplest and often the best method.
    # The network here looks like:
    #   leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
    # If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
    conn sample
    	# left security gateway (public-network address)
    	# next hop to reach right
    	# subnet behind left (omit if there is no subnet)
    	# right s.g., subnet behind it, and next hop to reach left
    We omit here the variables we have shown as set in the default connection above. All of them could also be set here. If they are set in both places, settings here take precedence. Defaults are used only if the specific connection description has no value set.

    The network described above looks like this:

             subnet              =leftsubnet
             interface 172.16.0.something
                left gateway machine
             interface                =left
             interface             =leftnexthop
             interface we don't know
             interface we don't know
             interface             =rightnexthop
             interface              =right
                right gateway machine
             interface 192.168.0.something
             subnet             =rightsubnet
    You need to edit the connection description, inserting appropriate IP addresses and subnet descriptions so that it describes your network.

    In most cases, you should use numeric IP addresses, not names, here. The file syntax allows names to be used, but this creates an additional risk. If someone can subvert the DNS service, then they can redirect packets whose addresses are looked up via that service.

    Many of the variables in this file come in pairs such as "leftsubnet: and "rightsubnet", one for each end of the connection. The variables on the left side are:

    The gateway's external interface, the one it uses to talk to the other gateway.
    Where left should send packets whose destination is right, typically the first router in the appropriate direction.

    This need not always be set.

    • If the two gateways are directly linked (packets can go from one to the other without IP routing by any intermediate device) then you need not set either leftnexthop or rightnexthop.
    • a gateway with interfaces=%defaultroute does not need a nexthop set for it
    However, in all other cases, you must provide nexthop information. KLIPS (Kernel IP Security) bypasses the normal routing machinery, so you must give KLIPS the information even though routing already knows it.

    (Yes, we know that design is not ideal, and we plan to change it. See extensive discussions on the mailing list, mostly with "routing" in the subject lines.)

    Addresses for the machines which left is protecting.
    • Often something like to indicate that a subnet resides behind left. This gives a tunnel mode connection.
    • If you omit this parameter (or set it to left's address and add a /32 netmask), then left is both the security gateway and the only client on that end.
    • For some applications, you may want to do both. In that case, create two connections, one to protect traffic from the subnet behind left and another to protect traffic from the left gateway itself.
    Note that a connection to a subnet behind left, such as 101.202.303.0/24, does not include left itself. It is a common error to attempt testing such a connection by pinging from left to the far end or vice versa. This does not work, even if the connection is functioning perfectly, since traffic to or from left itself is not sent on that connection. If you want to protect traffic originating or terminating on left, you need a separate tunnel for that in addition to the subnet's tunnel. Setting up such additional tunnels is discussed in our configuration document.
    Set to "yes" if there is a firewall in play that supresses forwarding, for example if a subnet behind left uses non-routable addresses and left does IP masquerade for them. For more detail, see our FreeS/WAN and firewalls document.
    If the conn setup section has plutoload=%search, then all connections marked auto=add are loaded when Pluto starts.

    If the conn setup section has plutostart=%search, then all connections marked auto=start are started when Pluto starts.

    For each left* parameter, there is a corresponding right* parameter.

    The tunnel described protects packets going from one subnet to the other. Note that it does not apply to packets which either begin or end their journey on one of the gateways. If you need to protect those packets, you must build separate tunnel descriptions for them. See the section on multiple tunnels in the configuration document.

    Which is which?

    Which security gateway is "left" and which is "right" is arbitrary.

    We suggest that you name connections by their ends. For example, name the link between Fred and Susan's machines "fred-susan" or the link between your Reno and Vancouver offices "reno-van". You can then let "left" refer to the left half of the name, "fred" or "reno" in our examples, and "right" to the other half.

    Note that the names should be the same in the ipsec.conf files on both ends. The name "reno", for example, refers to the machine in Reno, no matter which city the file is in, and if "reno" is "left" in the reno-van description in Reno, then "reno" is "left" in that description on the Vancouver machine as well. When you copy the file from one machine to the other, the only change you should make on the second machine is changing the interfaces= line to match the interface the second machine uses for IPSEC. In the simple case where both machines have interfaces=%defaulroute, no change at all is required.

    Putting secrets in ipsec.secrets(5)

    This file stores the secrets used to authenticate communication for the Diffie-Hellman key exchange in the IKE protocol.

    Each line has the IP addresses of the two gateways plus the secret. It should look something like this:	"jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"
    Note that the quotes are required. You can use any character string as your secret. For security, it should be both long and extremely hard to guess.

    For details, see the ipsec.secrets(5) man page.

    You want the same secret on the two gateways used, so you create a line with that secret and the two gateway IP addresses.

    The installation process supplies an example secret, useful only for testing. You should change it for production use.

  7. Copy the two files:

    • ipsec.conf
    • ipsec.secrets

    to the other gateway machine by some secure means.

    Don't just FTP or mail these files! It is vital that the keys (if any) in ipsec.conf and the secrets in ipsec.secrets remain secret. An attacker who knew those could easily have all the data on your "secure" connection. Carry the files on a floppy, and lock the floppy in a good safe or erase it extremely thoroughly afterward. Or use PGP or SSH to make the transfer.

    Note also that those files should be owned by root. ipsec.secrets should have permissions rw-------.

    If ipsec.conf contains keys, then it too should have permissions rw-------. In production use, it will not normally contain keys. You would either have keys automatically generated or, if using manual keying in production, you would keep the keys in separate files.

    Note that ipsec.conf is installed with permissions rw-r--r--. If you plan to use manually keyed connections for anything more than initial testing, you must:

    • either change permissions to rw-------
    • or store keys separately in secure files and access them via include statements in ipsec.conf. See our configuration document.

    Setting up interfaces

  8. For now, these files don't have to be changed much. They should be identical on the two gateways, except that each gateway must have the correct interfaces setting in its copy of ipsec.conf(5). This is in the file section labelled by the line config setup.

    For now, all you need to do in the overall config setup section of the file is set interfaces. We cover other options in our Configuration document. When you go to three or more gateways, however, you should ensure that distribution of keys and secrets is kept to a minimum. If Reno, Vancouver and Munich offices all communicate, there is no reason to give Reno keys to the Vancouver-Munich tunnel, for example.

    Matching numbers

    It is important that the numbers here match the network configuration. Suppose you are at the Reno office and your ipsec.conf file now has, among others, these lines:
    config setup
    conn reno-van
    When you tell FreeS/WAN to start the reno-van connection, it doesn't automagically know that it is in Reno, or that it is "left" in the configuration. It discovers that by comparing the IP address for ipsec0 (and, if it is set, for ipsec1) to the addresses for left and right. ipsec0 inherits its address from the underlying device, eth0 in our example.

    So in our example, if eth0 has IP address then ipsec0 inherits that address, the correct match is found, and this FreeS/WAN discovers that it is left. It then sets itself up with the other left* parameters

    The next hop on the path from left to right. In many applications this will be a router at left's ISP. For an IPSEC gateway to a departmental LAN, the next hop might be a router on the corporate LAN.
    Subnet address for clients behind left, with netmask. Often something like:
    This can be omitted if there is no subnet, if left is acting as its own gateway.
    Set to yes if left is masquerading for its clients.
    Once it has these parameters, FreeS/WAN sets things so that
    • packets from leftsubnet addressed to rightsubnet are routed through a tunnel to right.
    • Packets for leftsubnet can be received on the tunnel and delivered.
    All should be well.

    Of course, there must also be an interface and routes set up so that this machine can exchange non-IPSEC packets with clients on leftsubnet. This is done with standard Linux utilities such as ifconfig(8) and route(8). Also, things must be correct on right in Vancouver; it takes two to tunnel.

    A data mismatch anywhere in this configuration will cause FreeS/WAN to fail and to log various error messages. Depending on just how confused FreeS/WAN is and about what, the error messages may be somewhat confusing. See our troubleshooting file to get help interpreting them if required.

    We recommend double-checking for consistency here before continuing.

    Testing the installation

  9. Reboot both gateways to get FreeS/WAN started. No connections are actually made yet, but the stage is set.

    Examine /var/log/messages for any signs of trouble.

    On both gateways, the following entries should now exist in the /proc/net/ directory:

    • ipsec_eroute
    • ipsec_spi
    • ipsec_spigrp
    • ipsec_spinew
    • ipsec_tncfg
    • ipsec_version

    and the IPSEC interfaces should be attached on top of the specified physical interfaces. Confirm that with:

    	cat /proc/net/ipsec_tncfg

    You should see at least device ipsec0, and each ipsec device should point to a physical device, eg. 'ipsec0 -> eth0 mtu=16260 -> 1500'. Routing connections through this pseudo-device with our eroute(8) utility causes the data to be encrypted before being delivered to the underlying network interface.

    Minor confusion sometimes arises when people find that /dev/ipsec0, and /dev/ipsec1 are not visible with 'ls'. This is as it should be. Other network pseudo-devices such as eth0 and eth1 do not have entries in /dev either. In general, network devices do not need such entries.

    Manually keyed test

    The initial tests should be done with manually keyed connections. This lets you test the lower-level parts of Linux FreeS/WAN (mainly the KLIPS code which you've added to your kernel) while bypassing the higher-level parts. We will get to those once we're sure the low level works right.

  10. On one gateway, start IPSEC with:

    	ipsec manual --up name
    replacing name with the connection name you used in ipsec.conf(5).

    If it doesn't generate any errors, do

    	ipsec look

    and see if the output looks something like this: Wed Nov 25 22:51:45 EST 1998
    ------------------------- -> => tun0x200@ esp0x202@
    tun0x200@ IPv4_Encapsulation: dir=out ->
    esp0x203@ 3DES-MD5-96_Encryption: dir=in  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
    esp0x202@ 3DES-MD5-96_Encryption: dir=out  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
    Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface   U      1500 0          0 eth1   UG     1404 0          0 ipsec0

    If it does, you're probably in business.

    This example shows:

    	a tunnel              tun0x200 going to
    	outgoing connection   esp0x202
    	incoming connection   esp0x203
    Both connections use ESP with 3DES encryption and MD5 authentication.

    The routing is:    via eth1 and the Internet    via ipsec0 which encrypts and then sends to
    This routes all traffic to the protected network through an IPSEC tunnel to the gateway

  11. A manual connection must be set up on both ends to work. So give the same commands:
    	ipsec manual --up name
    	ipsec look

    on the other gateway and look for similar results.

  12. If that works, test whether Sunrise can ping Sunset and vice versa. Our example setup again is:

                  local net       untrusted net       local net

    It is not enough to just test that East can ping West; the goal is to secure traffic between the subnets, not between the security gateways themselves.

    In general, pings or other tests using the public interfaces of East and/or West are entirely useless. The IPSEC tunnel is for packets between the two protected subnets and the outside interfaces are not on those subnets. Depending on your routing configuration, test packets sent via those interfaces will be:

    • either transmitted in the clear, bypassing the tunnel,
    • or discarded because there is no tunnel in place to handle them
    In either case, they tell you nothing about the tunnel.

    Sometimes it will be inconvenient to use the client machines (Sunrise and Sunset in our example) for testing. In these cases, use a command such as:

         traceroute -i eth0 -f 20
    where each of the interfaces specified (eth0 and in the example) are on one of the protected subnets, eth0 being the local gateway's interface on that side and the remote gateway's subnet interface. This forces the packets through the IPSEC tunnel you want to test.

    For information on setting things up so that gateways can do IPSEC to each other or to remote subnets, see our configuration document.

    If you have other software set up, test with it as well. Telnet from Sunrise to Sunset, browse a web server on the remote net and so on.

    Testing with tcpdump

  13. To verify that all is working, run tcpdump(8) on a machine which can listen to the traffic between the gateways.

    This really has to be done from a third machine, not from one of the gateways. On the gateways you'll see packets at intermediate stages of processing and the result will be confusing. Also, both tcpdump(8) and nmap(8) use the libpcap library. That library does not recognise ipsec? devices and will generate "bad physical medium" error messages if you try to use it with them.

    The packets should, except for some of the header information, be utterly unintelligible. The output of good encryption looks exactly like random noise.

    You can put recognizable data in the ping packets with something like:

    	ping -p feedfacedeadbeef
    "feedfacedeadbeef" is a legal hexadecimal pattern that is easy to pick out of hex dumps.

    For many other protocols, you need to check if you have encrypted data or ASCII text. Encrypted data has approximately equal frequencies for all 256 possible characters. ASCII text has most characters in the printable range 0x20-0x7f, a few control characters less than 0x20, and none at all in the range 0x80-0xff.

    0x20, space, is a good character to look for. In normal English text space occurs about once in seven characters, versus about once in 256 for random or encrypted data. You can put long sequences of spaces in your data and look for 0x20202020 in output, but this is not usually necessary.

    If packets look like total garbage, nothing recognizable, all is well.

    Testing Automatic connections

  14. Do
    	ipsec manual --down name
    on both gateways. This shuts down the named tunnel. You can verify with the same commands used to check it was up:
    	ps -ax
    	ipsec look

  15. Now, do
    	ipsec auto --add name
    on both gateway machines. Then do:
    	ipsec auto --up name
    on one gateway. The first command adds the information on this connection to Pluto's database. The second makes the connection active.

    Note that to shut down a connection, you must do:

    	ipsec auto --down name
    on both gateway machines, even though you only start it from one.

    Again, you can verify with the same commands.

    Repeat the ping test. Repeat the tcpdump test.

    If everything succeeds, congratulations.

    You now have a working Linux FreeS/WAN installation.

    For information on configuring the system for production use, see our Configuration document.

Click below to go to: