updated INSTALL to conform with autotools

added a short HACKING introduction

1 files changed, 121 insertions, 127 deletions

diff --git a/INSTALL b/INSTALL
index 40060d16a..020f1d193 100644
--- a/INSTALL
+++ b/INSTALL
@@ -6,176 +6,170 @@
 Contents
 --------
 
-   1. Required packages
-   2. Optional packages
-   2.1 libcurl
-   2.2 OpenLDAP
-   2.3 PKCS#11 smartcard library modules
-   3. Building and running strongSwan with a Linux 2.6 kernel
+   1.   Overview
+   2.   Required packages
+   3.   Optional packages
+   3.1   libcurl
+   3.2   OpenLDAP
+   3.3   PKCS#11 smartcard library modules
+   4.   Kernel configuration
+
+1.  Overview
+    --------
 
+    The strongSwan 4.x branch introduces a new build environment featuring
+    GNU autotools. This should simplify the build process and package 
+    maintenance.
+    First check for the availability of required packages on your system
+    (section 2.). You may want to include support for additional features, which
+    require other packages to be installed (section 3.).
+    To compile an extracted tarball, run the ./configure script first:
 
-1. Required packages
-   -----------------
+      ./configure
 
-   In order to be able to build strongSwan you'll need the GNU Multiprecision
-   Arithmetic Library (GMP) available from http://www.swox.com/gmp/.
+    You may want to specify some arguments listed in section 3., or see the
+    available options of the script using "./configure --help".
 
-   The libgmp library and the corresponding header file gmp.h are usually
-   included in the form of one or two packages in the major Linux
-   distributions (SuSE: gmp; Debian unstable:  libgmp3, libgmp3-dev).
+    After a successful run of the script, run
 
+      make
 
-2. Optional packages
-   -----------------
+    followed by
 
-2.1 libcurl
-    -------
+      make install
 
-   If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
-   from an HTTP server or as an alternative want to use the Online
-   Certificate Status Protocol (OCSP) then you will need the  libcurl library
-   available from http://curl.haxx.se/.
+    in the usual manner.
 
-   In order to keep the library as compact as possible for use with strongSwan
-   you can build libcurl from the sources with the optimized options
+    To check if your kernel fullfills the requirements, see section 4.
 
-       ./configure --prefix=<dir> --without-ssl \
-                   --disable-ldap --disable-telnet \
-                   --disable-dict --disable-gopher \
-                   --disable-debug \
-                   --enable-nonblocking --enable-thread
+    Next add your connections to "/etc/ipsec.conf" and your secrets to 
+    "/etc/ipsec.secrets". Connections that are to be negotiated by the new
+    IKEv2 charon keying daemon should be designated by "keyexchange=ikev2" and 
+    those by the IKEv1 pluto keying daemon either by "keyexchange=ikev1" or
+    the default "keyexchange=ike".
 
-   As an alternative you can use the ready-made packages included with your
-   favorite Linux distribution (SuSE: curl, curl-devel).
+    At last start strongSwan with
 
-   In order to activate the use of the libcurl library in strongSwan you must
-   set the USE_LIBCURL option in "Makefile.inc":
+      ipsec start
 
-       # include libcurl support (CRL fetching, OCSP and SCEP)
-       USE_LIBCURL?=true
 
-   Under Gentoo emerge strongSwan with
+2.  Required packages
+    -----------------
 
-       USE="curl -ssl" emerge strongswan
+    In order to be able to build strongSwan you'll need the GNU Multiprecision
+    Arithmetic Library (GMP) available from http://www.swox.com/gmp/. At least
+    version 4.1.5 of libgmp is required.
 
+    The libgmp library and the corresponding header file gmp.h are usually
+    included in the form of one or two packages in the major Linux
+    distributions (SuSE: gmp; Debian unstable:  libgmp3, libgmp3-dev).
 
-2.2 OpenLDAP
-    --------
 
-   If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
-   from an LDAP server  then you will need the libldap library available
-   from http://www.openldap.org/.
+3.  Optional packages
+    -----------------
 
-    OpenLDAP is usually included  with your Linux distribution. You will need
-   both the run-time and development environments (SuSE: openldap2,
-   openldap2-devel).
+3.1 libcurl
+    -------
+
+    If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
+    from an HTTP server or as an alternative want to use the Online
+    Certificate Status Protocol (OCSP) then you will need the  libcurl library
+    available from http://curl.haxx.se/.
+
+    In order to keep the library as compact as possible for use with strongSwan
+    you can build libcurl from the sources with the optimized options
 
-   In order to activate the use of the libldap library in strongSwan you must
-   set the USE_LDAP option in "Makefile.inc":
+       ./configure --prefix=<dir> --without-ssl \
+                   --disable-ldap --disable-telnet \
+                   --disable-dict --disable-gopher \
+                   --disable-debug \
+                   --enable-nonblocking --enable-thread
+
+    As an alternative you can use the ready-made packages included with your
+    favorite Linux distribution (SuSE: curl, curl-devel).
 
-       # include LDAP support (CRL fetching)
-       USE_LDAP?=true
+    In order to activate the use of the libcurl library in strongSwan you must
+    enable the ./configure switch:
 
-   Depending upon whether your LDAP server understands the V3 (preferred) or
-   V2 LDAP protocol, uncomment one ot the two following lines:
+       ./configure [...] --enable-http
 
-       # Uncomment to enable dynamic CRL fetching using LDAP V3
-       LDAP_VERSION=3
-       # Uncomment to enable dynamic CRL fetching using LDAP V2
-       #LDAP_VERSION=2
 
-   The latest OpenLDAP releases use the LDAP V3 protocol, whereas older
-   versions require LDAP V2.
+3.2 OpenLDAP
+    --------
 
-   Under Gentoo emerge strongSwan with
+    If you intend to dynamically fetch Certificate Revocation Lists (CRLs)
+    from an LDAP server then you will need the libldap library available
+    from http://www.openldap.org/.
 
-       USE="ldap -ssl" emerge strongswan
+    OpenLDAP is usually included  with your Linux distribution. You will need
+    both the run-time and development environments (SuSE: openldap2,
+    openldap2-devel).
 
+    In order to activate the use of the libldap library in strongSwan you must
+    enable the ./configure switch:
 
-2.3 PKCS#11 smartcard library modules
-    ---------------------------------
+       ./configure [...] --enable-ldap
 
-   If you want to securely store your X.509 certificates and private RSA keys
-   on a smart card or a USB crypto token then you will need a PKCS #11 library 
-   for the smart card of your choice. The OpenSC PKCS#11 library (use
-   versions >= 0.9.4) available from http://www.opensc.org/ supports quite a
-   selection of cards and tokens (e.g. Aladdin eToken Pro32k, Schlumberger
-   Cryptoflex e-gate, Oberthur AuthentIC,  etc.) but requires that a PKCS#15
-   directory structure be present on the smart card. But in principle
-   any other PKCS#11 library could be used since the PKCS#11 API hides the
-   internal data representation on the card.
-
-   For USB crypto token support you must add the OpenCT driver library
-   (version >= 0.6.2) from the OpenSC site, whereas for serial smartcard
-   readers you'll need the pcsc-lite library and the matching driver from the
-   M.U.S.C.L.E project http://www.linuxnet.com/ .
-
-   In order to activate the PKCS#11-based smartcard support in strongSwan
-   you must set the USE_SMARTCARD option in "Makefile.inc":
-
-       #include PKCS11-based smartcard support
-       USE_SMARTCARD?=true
-
-   During compilation no externel smart card libraries must be present.
-   strongSwan directly references a copy of the standard RSAREF pkcs11.h
-   header files stored in the pluto/rsaref sub directory. During compile
-   time a pathname to a default PKCS#11 dynamical library can be specified
-   in "Makefile.inc" 
-
-      # Uncomment this line if using OpenSC <= 0.9.6
-      # PKCS11_DEFAULT_LIB=\"/usr/lib/pkcs11/opensc-pkcs11.so\"
-      # Uncomment tis line if using OpenSC >= 0.10.0
-        PKCS11_DEFAULT_LIB=\"usr/lib/opensc-pkcs11.so\"
-
-   This default path to the easily-obtainable OpenSC library module can be
-   simply overridden during run-time by specifying an alternative path in
-   ipsec.conf pointing to any dynamic PKCS#11 library of your choice.
-
-   config setup
-          pkcs11module="/usr/lib/xyz-pkcs11.so"
+    LDAP Protocl version 2 is not supported anymore, --enable-ldap uses always
+    version 3 of the LDAP protocol
 
-   Under Gentoo emerge strongSwan with
 
-       USE="smartcard usb -pam -X" emerge strongswan
+3.3 PKCS#11 smartcard library modules
+    ---------------------------------
 
+    If you want to securely store your X.509 certificates and private RSA keys
+    on a smart card or a USB crypto token then you will need a PKCS #11 library 
+    for the smart card of your choice. The OpenSC PKCS#11 library (use
+    versions >= 0.9.4) available from http://www.opensc.org/ supports quite a
+    selection of cards and tokens (e.g. Aladdin eToken Pro32k, Schlumberger
+    Cryptoflex e-gate, Oberthur AuthentIC,  etc.) but requires that a PKCS#15
+    directory structure be present on the smart card. But in principle
+    any other PKCS#11 library could be used since the PKCS#11 API hides the
+    internal data representation on the card.
 
+    For USB crypto token support you must add the OpenCT driver library
+    (version >= 0.6.2) from the OpenSC site, whereas for serial smartcard
+    readers you'll need the pcsc-lite library and the matching driver from the
+    M.U.S.C.L.E project http://www.linuxnet.com/ .
 
-3. Building and running strongSwan with a Linux 2.6 kernel
-   -------------------------------------------------------
+    In order to activate the PKCS#11-based smartcard support in strongSwan
+    you must enable the smartcard ./configure switch:
 
-   * Because the Linux 2.6 kernel comes with a built-in native IPsec stack,
-     you won't need to build the strongSwan kernel modules. Please make sure 
-     that the the following Linux 2.6 IPsec kernel modules are available:
+       ./configure [...] --enable-smartcard
 
-         o af_key
-         o ah4
-         o esp4
-         o ipcomp
-         o xfrm_user
-         o xfrm4_tunnel
+    During compilation no externel smart card libraries must be present.
+    strongSwan directly references a copy of the standard RSAREF pkcs11.h
+    header files stored in the pluto/rsaref sub directory. During compile
+    time a pathname to a default PKCS#11 dynamical library can be specified
+    with a ./configure flag:
 
-     Also the built-in kernel Cryptoapi modules with selected encryption and 
-     hash algorithms should be available.
+      ./configure --enable-smartcard --with-default-pkcs11=/path/to/lib.so
 
-   * First select any desired compile options in "Makefile.inc" (see section 2.
-     Optional packages). Then in the  strongwan-4.x.x  top directory type
+    This default path to the easily-obtainable OpenSC library module can be
+    simply overridden during run-time by specifying an alternative path in
+    ipsec.conf pointing to any dynamic PKCS#11 library of your choice.
 
-         make
+    config setup
+          pkcs11module="/usr/lib/xyz-pkcs11.so"
 
-     followed by
 
-         make install
+4.  Kernel configuration
+    --------------------
 
-   * Next add your connections to "/etc/ipsec.conf" and your secrets to 
-     "/etc/ipsec.secrets". Connections that are to be negotiated by the new
-     IKEv2 charon keying daemon should be designated by "keyexchange=ikev2" and 
-     those by the IKEv1 pluto keying daemon either by "keyexchange=ikev1" or
-     the default "keyexchange=ike".
+    The strongSwan 4.x series currently support only 2.6 kernels and its
+    nativ IPsec stack. Please make sure that the the following IPsec kernel
+    modules are available:
 
-   * At last start strongSwan with
+      o af_key
+      o ah4
+      o esp4
+      o ipcomp
+      o xfrm_user
+      o xfrm4_tunnel
 
-         ipsec start
+    These may be build into the kernel or as modules. Modules get loaded
+    automatically at strongSwan startup.
 
------------------------------------------------------------------------------
+    Also the built-in kernel Cryptoapi modules with selected encryption and
+    hash algorithms should be available.
 
-This file is RCSID $Id: INSTALL,v 1.9 2006/05/01 16:02:37 as Exp $