[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

2. Installing the CIPE software package

The CIPE software package is available via the WWW from
http://sites.inka.de/~bigred/devel/cipe.html. It is distributed in a tar.gz file, currently about 138k in size. After unpacking the distribution, run the configure script, possibly specifying options there. Then run make.

2.1 Prerequisites  What you need before installing.
2.2 Protocols and ciphers  Important compile-time options to select.
2.3 Advanced compiling  Configuring the compile for different targets.
2.4 Installation  Compiling and installing the software.
2.5 Compilation errors  If something goes wrong.
2.6 Running CIPE  Running the software.


2.1 Prerequisites

CIPE runs under Linux 2.0.* since 2.0.12, 2.1.* since about 2.1.103, 2.2.*, 2.3.* since 2.3.48, 2.4.*, and 2.6.*. It was developed for the i386 architecture; other architectures should work.

Make sure you have the complete source tree of the running kernel installed (usually in `/usr/src/linux'). The version and configuration of the kernel sources must match the kernel on which it will run exactly, or else you risk building a module which crashes. You also have to use the same compiler version than the one with which the kernel was compiled. After reconfiguring and rebuilding the kernel, don't forget to rebuild the CIPE module too. (This applies to all externally compiled modules.) Enabling "versioned symbols" on the kernel is strongly recommended, because it protects against version skew between kernel and modules.

The kernel needs "IP Forwarding/Gatewaying" enabled in the configuration for 2.0 kernels. Make sure to enable IP forwarding with
 
echo 1 > /proc/sys/net/ipv4/ip_forward
on system boot with 2.2 or later and recent 2.0 kernels. The urandom device must be available.

For kernels that have it (i.e. 2.4.22 upwards or 2.6), the option "CRC32 functions" under "Library routines" should be enabled.

A suited version of the module utilities (modprobe and friends) needs to be installed. When in doubt, consult the documentation in the kernel source.

The PKCIPE tool needs the OpenSSL package, version 0.9.6 or later. If this is not available, the rest of the CIPE package can still be compiled and installed as usual.

Since version 1.3, CIPE uses an autoconf-generated configure script to configure its Makefiles. This script takes the following parameters on the command line. All of the parameters have defaults which should suffice for a simple installation.

`--with-linux=dir'
Path to the Linux source tree (e.g., `/usr/src/linux'). Using an include tree without complete source is no longer supported, as newer Linux versions need the kernel's build infrastructure. `Makefile' parameters are also used.
`--with-obj=dir'
Path to the Linux compile tree. When the Linux kernel has been compiled in a separate object directory (possible since Linux 2.6), this parameter has to be given in addition to --with-linux.
`--with-ssl-includes=dir'
Path to the OpenSSL includes, if the script can not find it.
`--with-ssl-libs=dir'
Path to the OpenSSL libraries, if the script can not find it.
`--enable-protocol=n'
Use encapsulation protocol `n'. The supported values in CIPE 1.5 are 3 and 4. See section 2.2 Protocols and ciphers, for how to choose the right one. The default is 3.
`--enable-cryptoapi'
Use the new cryptographic API of Linux 2.4.22 or later or 2.6.
`--disable-debug'
Disable debugging code in kernel module. Not really useful.
`--disable-dyndev'
Disable dynamic device allocation. Not really useful.
`--enable-logfacility=x'
Set syslog facility for ciped and pkcipe (default and usually right is LOG_DAEMON).
`--disable-asm'
Disable use of assembler code. Not really useful.
`--enable-name=n'
Set a name suffix for the compilation directory.
`--enable-bug-compatible'
Use old, broken interpretation of keys. See section 3.3 Incompatibility of keys to older CIPE versions.
`--disable-send-config'
Do not send configuration information to the peer. This is normally sent on startup to help diagnose mismatches, but it is sent unencrypted, which may be unwanted.
`--disable-pkcipe'
Do not compile and install the PKCIPE tool.

The script then looks for certain parameters (like whether compiling for an SMP system) in the kernel headers, and it creates a new directory named like 2.2.6-i386-cb in which compilation of the module and daemon will take place. (This would be for Linux 2.2.6 on i386, protocol 3 [the "c"], Blowfish [the "b"].)

The PKCIPE tool and some library components are built in their source directories, they do not depend on configuration (in theory; unfortunately pkcipe is still tied to the particular ciped in use, but this is going to be fixed).


2.2 Protocols and ciphers

CIPE supports different versions of the encryption protocol, which in turn can be used with different ciphers (encryption algorithms). Which one is used is chosen at compile time with arguments to the configure script.

As of CIPE 1.5, the following options are possible:

Protocol version 3: This is the default protocol and recommended for most use. It is described in detail in this document. See section 6.1 The CIPE protocol. The device works as an IP-only point-to-point device much like with SLIP or PPP.

Protocol version 4: This protocol uses the same data format as protocol version 3, except that the packets transmitted contain an Ethernet-compatible link-level header. With this it is possible to run payload protocols other than IP, and particularly it is possible to make the CIPE device part of an Ethernet bridge. The disadvantage is that the packets get larger than with protocol 3. It may be necessary to set the MAC address using the `hwaddr' option to make it unique across the VPN. With this protocol, the device has a subnet mask and broadcast address which can be set with appropriate options.

Blowfish: This is the default encryption algorithm, used with a 128 bit key.

IDEA: An alternate encryption algorithm with a 128 bit key. This algorithm is patented and may need a licence for commercial use. It is no longer included in the CIPE package, but can (in theory) be used via the cryptographic API.

Since CIPE 1.4, the built-in Blowfish is available in generic C and i386 assembler implementations. The assembler versions are used where possible.

With CIPE 1.6 it is possible to use the cryptographic API in Linux 2.4.22 or later and 2.6 and use the modularized ciphers. In this case, the module and daemon are named like cipc and ciped-c (note the lack of the last letter indicating the builtin cipher). The cipher actually used can be specified as a configuration parameter, defaulting to blowfish-internal which gives the old builtin Blowfish algorithm. Note that this version is not compatible with the kernel Blowfish module, because blowfish-internal is originally coded little-endian (real Blowfish is big-endian) and remains so for compatibility with older versions.

Ciphers with a block or IV size other than 64 bits are not supported.


2.3 Advanced compiling

The use of a separate object directory means it is possible to compile CIPE for separate targets in the same directory. An example would be a machine running different kernels for testing, etc. In that case you would have kernel directories like `/usr/src/linux-2.0.36', `/usr/src/linux-2.2.6', and so on. Running configure --with-linux=/usr/src/linux-2.0.36 and after that configure --with-linux=/usr/src/linux-2.2.6 leaves two directories 2.0.36-i386-cb and 2.2.6-i386-cb. You can run make in each of the object directories separately.

Another common case is a setup where one central box compiles kernels for different machines. You can rename CIPE's compilation directories with the --enable-name option, perhaps name them after the target machine:
 
./configure --with-linux=/usr/src/linux-2.2.6-bigbox \
            --enable-name=bigbox
make -C 2.2.6-i386-cb-bigbox
./configure --with-linux=/usr/src/linux-2.2.6-satellite \
            --enable-name=satellite
make -C 2.2.6-i386-cb-satellite
./configure --with-linux=/mounts/srv1/linux-2.2.5-small \
            --enable-name=laptop
make -C 2.2.5-i386-cb-laptop

In the same way distribution maintainers could prepare a set of differently configured CIPE modules (IDEA vs. Blowfish) for one target. The names of the module and driver are chosen so that different configurations can coexist on one target. See section 2.6.1 Program Names.

Note that real cross-compilation is not possible for now, because the configure script always assumes the CPU architecture of the system where it runs.


2.4 Installation

A simple make command compiles everything. Compiler warnings should not occur. Do make install as root to install the software components in their final location. These are a kernel module, named according to the protocol version and encryption algorithm selected, and the driver program, which is (since CIPE 1.3) also named after the protocol version and encryption algorithm. See section 2.6.1 Program Names. The Makefiles accept the semi-standard options BINDIR, MODDIR, INFODIR to specify where the stuff gets installed.

If PKCIPE was compiled, make install also installs the pkcipe program and a helper rsa-keygen, sets up the necessary directories and generates a host key if none is already there. See section 4. The PKCIPE tool.

You need to create a directory `/etc/cipe' which contains at least two files, `options' and `ip-up'. You can copy the files from the `samples' directory in the distribution here, and edit them to suit your needs. See section 3. Configuration of the CIPE software.


2.5 Compilation errors

There is a known problem in that the various 2.0.30 and 2.0.31 pre-releases disagree on whether they have a certain feature (SO_BINDTODEVICE), and detecting this version dependency via the version number is not foolproof. Apparently, since 2.0.32, this problem is resolved. If output.c doesn't compile under 2.0.*, change the line
 
#ifdef SO_BINDTODEVICE
to #if 1 or #if 0 as needed.

A similar problem exists in the 2.3.99 pre-releases, where the name part of the net_device structure has changed. If an error occurs during compilation of `device.c' under 2.3.99pre-n, change the conditional definition of HAVE_DEVNAME_ARRAY in `cipe.h' to #if 1 or #if 0 as needed. Since the 2.4.0 test releases this problem is resolved.


2.6 Running CIPE

Once installed, the CIPE software is run by loading the module and running the ciped daemon.

2.6.1 Program Names  How the components of CIPE are named.
2.6.2 Loading the module  Loading the kernel module.
2.6.3 Running the ciped daemon  Running the daemon.


2.6.1 Program Names

The module name is cip followed by the protocol version as a letter and the first letter of the encryption algorithm. E.g. cipcb for version 3 (i.e. "c"), Blowfish (the default). The device names which this module manages are the module name followed by a number, e.g. cipcb0.

Since CIPE 1.3, the daemon program is named ciped- followed by the protocol and encryption letters, likewise. E.g. ciped-cb. Where this manual refers to ciped, assume the real name as given here.

The configuration parameters of kernel module and daemon must match (the module checks this), but the daemon does not depend (at least not in theory) on the kernel version. The naming scheme is chosen so that all possible modules and daemons on one machine can coexist.

The pkcipe program is designed to be independent from the configuration. However, currently it can only handle one version of ciped (i.e. one protocol and cipher version). This will be fixed in future versions.


2.6.2 Loading the module

The kernel module is loaded into the kernel via the command
 
modprobe modulename parameter=value...

The CIPE module accepts the following additional parameters:

cipe_debug=(number)
Set the debugging level. The file `cipe.h' defines different debugging levels which are ORed. Set this to 0 if you don't need debugging output. Debugging output is emitted via kernel messages, which means it usually winds up in the syslog somewhere.
cipe_maxdev=(number)
Set the number of channels this module manages. E.g. with cipe_maxdev=4 the devices cipcb0 through cipcb3 are available. Maximum is 9999 Since CIPE 1.2, there is no need to set this, since channels are allocated dynamically.

The module can be autoloaded via kerneld/kmod. Advanced users will recognize the following options in `/etc/conf.modules' necessary to make it work correctly:
 
alias cipcb0 cipcb
options cipcb cipe_debug=0
Note: with dynamic device allocation, aliasing any device other than cipcb0 is pointless and autoloading only works when the requesting application is ciped (not ifconfig etc.) This is a limitation inherent in dynamic device allocation.


2.6.3 Running the ciped daemon

The ciped daemon must be run as root. (Do not make it setuid.) It takes as command line arguments an optional `-o file' parameter specifying an options file followed by any number of individual option arguments. See section 3.1 Specifying options.

Except in debugging mode, the daemon puts itself in the background and uses syslog(3) for logging messages. Normal operation causes no log messages except for errors and a notice when the daemon terminates.

Shutting down (with ifconfig(8)) a CIPE device terminates its ciped process, and vice-versa terminating a ciped closes the device. When a device is closed, its configuration parameters including all keys and statistics are erased. (This is different from earlier CIPE versions!) ciped does not keep any keys in memory.

When the device comes up, ciped spawns `/etc/cipe/ip-up' with the parameters described in the sample version. It waits for completion of this script before data can be sent over the device and before it goes into the background. The script is called with standard input, output and error to `/dev/null'. It typically sets routes and does some logging. Since CIPE 1.4, the script is called with all options (except key) in environment variables named after the option.

Likewise, when a CIPE device goes down, `/etc/cipe/ip-down' is invoked. ciped itself logs the interface statistics when closing.

ciped will terminate when an error occurs. This includes a "connection refused" message from the peer, to be able to detect non-working peers. This default error handling implies that no data may be sent over a link unless both ends are up and running, or the first one to come up will go down again immediately. In particular, the "ping" command in the sample `ip-up' should not be activated on both ends of a link. This behaviour can be customized. See section 3.6 Error handling in ciped, for more details.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Olaf Titz on August, 4 2004 using texi2html