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

3. Configuration of the CIPE software

3.1 Specifying options  How CIPE gets its parameters.
3.2 List of all parameters  All valid and needed parameters.
3.3 Incompatibility of keys to older CIPE versions  An incompatibility between Version 1.4 and earlier.
3.4 Working with SOCKS  Routing with CIPE over a SOCKS5 relayer.
3.5 Dynamic carrier addresses  How to deal with dynamic IP address assignment.
3.6 Error handling in ciped  How ciped deals with errors.


3.1 Specifying options

All configuration parameters are processed by the ciped daemon. It takes parameters from

  1. the default options file (`/etc/cipe/options'),
  2. an options file specified as `-o file' on the command line,
  3. single options given on the command line,

in that order. Which means, parameters on the command line override those from files, and parameters from an explicit options file override those from the default options file.

Options are one of the types: boolean, integer, string, IP address, IP address with port number. Booleans are default false and specifying them as option makes them true. IP addresses are given as dot-quad notation or domain names which can be resolved using gethostbyname(3). UDP or TCP addresses are given as ip:port, where the port is a number or a name resolvable by getservbyname(3).

The syntax for specifying options is name=value on the command line, and name value (one option per line, no continuations, escapes, quoting etc.) in the options file.

For security reasons, options files must be given as absolute paths, and they and all their parent directories must be owned by root and not writable by group or other, and the options file itself must be even not readable by group or other (because it may contain secret keys).


3.2 List of all parameters

(Req=Required parameter)

Name Type Req
device String no Name of the CIPE device. If not given, the system picks a free one.
debug Bool Don't go background, use stderr instead of syslog. (Independent of the kernel driver debug option.)
cipher String no Name of encryption algorithm to use. Defaults to "blowfish" (built-in).
ipaddr IP yes IP address of the CIPE device.
ptpaddr IP (yes) IP address of the peer device (i.e. the CIPE device on the other end). For protocol 3.
mask IP no Netmask of the CIPE device. For protocol 4.
bcast IP no Broadcast address of the CIPE device. For protocol 4.
mtu Int no Device MTU (default: ethernet standard MTU minus all necessary headers)
metric Int no Device metric (not sure if this is used anywhere...)
cttl Int no Carrier TTL value. If not specified or 0, use the payload packet's TTL. Default recommendation is 64.
me UDP no Our carrier UDP address. If either IP or port are not given, the system picks one and reports it via `ip-up'.
peer UDP yes The other end's carrier UDP address.
key String (yes) The link key. For security reasons, the key has to be set via an options file, subject to the restrictions described above. The key should be 128 bits in hexadecimal encoding. (To generate such a beast from random, try ps -auxw | md5sum.)
nokey Bool Don't encrypt at all, just encapsulate in UDP. Only with this option, key is not needed.
socks TCP no Address (port required!) of the SOCKS5 server. See section 3.4 Working with SOCKS.
tokxc Int no Timeout (seconds) for key exchange. Default: 10.
tokey Int no Dynamic key lifetime. Default: 600 (10 minutes).
ipup String no Script to run instead of `/etc/cipe/ip-up'.
ipdown String no Script to run instead of `/etc/cipe/ip-down'.
arg String no Argument to supply to `ip-up', `ip-down'.
maxerr Int no Maximum number of errors before ciped exits. See section 3.6 Error handling in ciped.
stayalive Bool Do not exit on errors; just invoke ip-down and wait until the connection comes up again, then invoke ip-up. NOTE: the piddir option should be used in this case instead of writing PID files from ip-up.
piddir String no Directory to write pid-files to. PID files are named like the device, with .pid appended. If not specified, pid files are not written.
tokxts Int no Key exchange timestamp timeout. Default: 0 (no timestamps). Set this to 10 to prevent key exchange replay attacks, but only if the peer runs CIPE 1.4.6 or later and both system clocks are reasonably synchronized.
ping Int no Frequency (in seconds) for keep-alive pings. Default is don't send any pings. The "ping" used here is internal to CIPE, not ICMP ping.
toping Int no Timeout for pings. If no answer is received on a keep-alive ping in this time, it counts as an error, See section 3.6 Error handling in ciped. Default is no check for answers.
dynip Bool Assume the carrier is on a dynamic IP address. See section 3.5 Dynamic carrier addresses.
hwaddr String no Set the dummy MAC address used in Ethernet mode (protocol 4).
ifconfig Bool Require an external ifconfig call to configure the interface.
checksum Bool Use checksummed UDP carrier packets. Only necessary if the network does not like unchecksummed packets.
ignoredf Bool Ignore the DF bit on IP packets and allow the encapsulated packet to be fragmented.
forcemtu Bool Disable PMTU and use device MTU.


3.3 Incompatibility of keys to older CIPE versions

Versions of CIPE before 1.4.0 have a bug in the way the key option is interpreted. It is supposed to be a 128-bit hexadecimal number. However, earlier versions interpret the digits `a' through `f' as equal to `1' through `6'. This reduces the effective key space from 16^32 (32 hex digits) to 10^32 (32 decimal digits), or 109 bits. Worse, it introduces bias in the distribution of bit patterns in the effective key.

This bug needed to be fixed as soon as it was found. Unfortunately the fix means that old and new versions of ciped will read the same key parameter differently, in other words: keys are not compatible between 1.4.0 and older when they contain any non-decimal digits.

The solution to make them work again is either to upgrade both ends at once (recommended), or generate new keys which consist only of decimal digits. A possible method to generate such a key is
 
(ps aux|md5sum; ps alx|md5sum) | tr -cd 0-9

Alternatively, the 1.4 or newer package can be given the option `--enable-bug-compatible' to configure to use the old broken key parser.


3.4 Working with SOCKS

With the socks option, CIPE uses a SOCKS5 server for sending and receiving the encrypted data. Since this is UDP, SOCKS4 (which doesn't support UDP) can not be used. SOCKS5 has a number of authentication methods. CIPE can use either no authentication or Username/Password. (3) Username and password are taken from the environment variables SOCKS5_USER and SOCKS5_PASSWD.

The SOCKS server is free to pick any IP address, or at least any port number, as it sees fit. Thus using SOCKS implies a dynamic carrier address. See section 3.5 Dynamic carrier addresses.

The implementation is not based on a SOCKS library, don't attempt to link ciped with it.

ciped periodically checks whether the SOCKS server has closed the control connection. If the SOCKS server goes down, there is no way to recover without restarting the client (in this case, ciped). This is a limitation in the SOCKS5 protocol. See section 3.6 Error handling in ciped.


3.5 Dynamic carrier addresses

CIPE can handle dynamically changing carrier addresses. This is subject to certain restrictions, however.

When a link is already established, one end must notice when the other end's carrier address changes. CIPE versions since 0.5.1 do this automatically.

When one end of the link is on a real dynamic IP address (dial-up device), it must notice when its own carrier address changes. This requires Linux 2.2 or higher, CIPE version 1.4.0 or higher and the `dynip' option set.

The trickiest part with using dynamic carrier addresses is finding out the peer address before the link is established. Each CIPE needs to know the IP address and UDP port number to send packets to. Normally this is set with the `peer' option. As soon as a valid packet is received the driver recognizes the peer address automatically.

With one static and one dynamic (or SOCKS) end, this is fairly easy. Just make sure the dynamic end has the right `peer' option, and (only!) the dynamic end has the ping in the example `ip-up' activated. The ping will ensure that the dynamic end tells the static end its carrier address as soon as possible. The static end should use a dummy `peer' which does not respond to packets normally(4) and the option `maxerr=-1'. The link is initiated by the dynamic end.

Whether a link between two dynamic carriers is possible depends on the situation. It must be possible for one end to tell the other end its current address in some way outside of CIPE, and it should be possible to initiate an immediate restart of ciped this way. As of CIPE 1.5, the recommended way to do this is the PKCIPE program. See section 4. The PKCIPE tool.

The `ip-up' script is always given the correct address in the me environment variable. For dynamic addresses this is the current address and for SOCKS this is the address of the SOCKS relayer.

In such a configuration, both ends should use `maxerr=-1' and the initiating end should use the ping.

See section 5.4 Connection modes, for an overview on the different sorts of dynamic addresses and how they can be handled.


3.6 Error handling in ciped

When the remote ciped is down or not available, the local ciped will get a "connection refused" error. Older versions always exited on this error. This has proven impractical in some situations, so an extra option has been added: maxerr determines how many network errors ciped will tolerate before exiting. This counter is reset when the connection proves OK (more precisely: when a key exchange packet is received). The default for maxerr is 8, like the non-changeable default in version 0.5.1. A value of -1 will cause ciped to ignore any network errors. In this case, it can only be brought down manually.

If keep-alive pings are enabled, a failure to respond to a ping counts as one error in this picture. This means that for maxerr=5 and ping=60, a dead link will take ciped down after five minutes.

Error handling for SOCKS is independent of this option, however. When an error occurs on the SOCKS control connection (e.g., the SOCKS server goes down), ciped will exit. This behaviour is mandated by the SOCKS5 protocol.


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

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