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

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.