#########################################################################
#            Libreswan 3.X Release Notes
#########################################################################

Libreswan is an IPsec implementation for Linux. It has support for most 
of the extensions (RFC + IETF drafts) related to IPsec, including 
IKEv2, X.509 Digital Certificates, NAT Traversal, and many others.

Libreswan has been forked from Openswan 2.6.38, which was forked from
FreeS/WAN 1.99.

Download it from

    https://download.libreswan.org/
    ftp://ftp.libreswan.org/

#########################################################################
# REQUIREMENTS
#########################################################################

A recent Linux distribution based on either Kernel 2.4.x, 2.6.x or 3.x
are the currently supported platforms.

Most recent distributions have package support for libreswan.  Unless
a source based build is truly needed,  it is often best to use the pre-built
distributions packaged version.

There are a few packages required for Libreswan to compile from source:

For Debian/Ubuntu

	apt-get install libnss3-dev libnspr4-dev pkg-config libpam-dev \
		libcap-ng-dev libcap-ng-utils libselinux-dev \
		libcurl4-nss-dev libgmp3-dev flex bison gcc make \
		libunbound-dev libnss3-tools

	(there is no fipscheck library for these, set USE_FIPSCHECK=false)

For Fedora/RHEL/CentOS

	yum install nss-devel nspr-devel pkg-config pam-devel \
		libcap-ng-devel libselinux-devel \
		curl-devel gmp-devel flex bison gcc make \
		fipscheck-devel unbound-devel

Runtime requirements (usually already present on the system)

	iproute2, iptables, sed, awk, bash, cut and possible other tools

	(note: the busybox version of "ip" does not support 'ip xfrm', so
	       ensure you enable the iproute(2) package for busybox)

	python is used for "ipsec verify", which helps debugging problems

#########################################################################
# HOW TO INSTALL on Kernel 2.6 and higher
#########################################################################

NETKEY/XFRM (Native linux IPsec stack)
---------------------------------

To use Libreswan with the linux native (builtin) IPsec stack,  the
following steps should be all that are needed. Please use at least kernel
version 2.6.9, as prior versions of the kernel have serious bugs in the
native IPsec stack.  From the libreswan directory:

    make programs
    sudo make install

Note: The ipsec-tools package or setkey is not needed. Instead iproute2 >= 2.6.8
is required. Run 'ipsec verify' to determine if your system misses anything.
of the requirements.

KLIPS/KLIPSNG (Libreswan IPsec stack)
------------------------------------

To use the Libreswan KLIPS IPsec stack (ipsec0 devices) for Linux
Kernels 2.4 and higher, the following steps should work.  From the
libreswan directory:

    make programs
    make module
    sudo make module_install

This builds a module against the running kernel. To compile a module for
another kernel (for which the headers are installed), use:

    make KERNELSRC=/lib/modules/`uname -r`/build module 
    sudo make KERNELSRC=/lib/modules/`uname -r`/build module_install

For Linux 2.6 Kernels before 2.6.23, including 2.4 linux systems, the kernel
requires patching if NAT-T support or SAref tracking is required. Full kernel
source will be required as the kernel sources are being patched, built and
installed.  It is good practice to build and install an unpatched kernel
before starting to ensure the process is correct.  See your distribution
documentation on how to build and install a new kernel

    Determine the linux source directory,  for example /usr/src/linux on
    most full source installs.  It may also be /usr/src/linux-2.[46].X

    Add NAT-T support (if required).

        From the Libreswan source directory:

          make KERNELSRC=/usr/src/linux nattpatch | patch -d /usr/src/linux -p1

    Add SAref tracking support (if required).

        Premade patches for some distributions kernels can be found in
        patches/kernel/  It is recommended that kernel 2.6.32 or higher is
        used. Documentation on SAref/MAST can be found in docs/HACKING/Mast*
        and doc/klips/mast.xml. To understand what SAref tracking does, see
        doc/ipsecsaref.png and the overlapip= entry in the ipsec.conf man page.

        From the Libreswan source directory:

          make KERNELSRC=/usr/src/linux sarefpatch | patch -d /usr/src/linux -p1

    Add OCF HW offloading support

        For OCF HW offloading support, you need also need a patched kernel
        See: http://ocf-linux.sourceforge.net/ for more details.

    Build and install a new kernel

        See your distribution documentation on how to install a new kernel.
        It should be something similar to:

          cd /usr/src/linux
          make oldconfig
          make dep                    - this step is ignore on 2.6 systems)
          make bzImage install

    Build Libreswan

        From the Libreswan source directory:

            make programs
            make KERNELSRC=/usr/src/linux module
            sudo make KERNELSRC=/usr/src/linux install minstall

The Libreswan configuration file can select which ipsec stack to use at
runtime by using the "protostack=<klips|netkey|mast>" options in ipsec.conf.
See the ipsec.conf man page for more information on configuration options.

#########################################################################
# UPGRADING
#########################################################################

1. If you are upgrading from FreeS/WAN 1.x or Openswan 2.x to Libreswan 3.x,
   you might need to adjust your config files.  See 'man ipsec.conf.
   details on what has changed.

2. You can run 'make install' on top of your old version - it will not
   overwrite your your /etc/ipsec.* config files

#########################################################################
# SUPPORT
#########################################################################

Mailing Lists:

    https://lists.libreswan.org is home of the mailing lists

Wiki:

    https://libreswan.org is home to the Libreswan WIKI.  It has the most
    up to date documentation, interop guides and other related information.

IRC:

    Libreswan developers and users can be found on IRC, on #swan 
    irc.freenode.net.

#########################################################################
# BUGS
#########################################################################

Bugs with the package can be filed into our bug tracking system, at
https://bugs.libreswan.org

#########################################################################
# SECURITY HOLES
#########################################################################

All security vulnerabilities found that require public disclosure will
receive proper CVE tracking numbers (see http://mitre.org/) and co-ordinated
via the vendor-sec (or successor) mailing list. A complete list of known
security vulnerabilities is available at: https://www.libreswan.org/security/ 

#########################################################################
# DEVELOPMENT
#########################################################################

Those interested in the development, patches, beta releases of Libreswan
can join the development mailing list (http://lists.libreswan.org -
dev@lists.libreswan.org) or join the development team on IRC in #swan
on irc.freenode.net

For those who want to track things a bit more closely, the
commits@lists.libreswan.org mailinglist will mail all the commit messages.

#########################################################################
# DOCUMENTATION
#########################################################################

The most up to date docs are in the man pages and at https://libreswan.org/

The bulk of this software is under the GNU General Public License; see
LICENSE.  Some parts of it are not; see CREDITS for the details.
