|[ << ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
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
How ciped deals with errors.
All configuration parameters are processed by the
It takes parameters from
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
or TCP addresses are given as
ip:port, where the port is a number
or a name resolvable by
The syntax for specifying options is
name=value on the command
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).
|String||no||Name of the CIPE device. If not given, the system picks a free one.|
|Bool||Don't go background, use stderr instead of syslog. (Independent of the kernel driver debug option.)|
|String||no||Name of encryption algorithm to use. Defaults to "blowfish" (built-in).|
|IP||yes||IP address of the CIPE device.|
|IP||(yes)||IP address of the peer device (i.e. the CIPE device on the other end). For protocol 3.|
|IP||no||Netmask of the CIPE device. For protocol 4.|
|IP||no||Broadcast address of the CIPE device. For protocol 4.|
|Int||no||Device MTU (default: ethernet standard MTU minus all necessary headers)|
|Int||no||Device metric (not sure if this is used anywhere...)|
|Int||no||Carrier TTL value. If not specified or 0, use the payload packet's TTL. Default recommendation is 64.|
|UDP||no||Our carrier UDP address. If either IP or port are not given, the system picks one and reports it via `ip-up'.|
|UDP||yes||The other end's carrier UDP address.|
|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 |
|Bool|| Don't encrypt at all, just encapsulate in UDP. Only with this option,
|TCP||no||Address (port required!) of the SOCKS5 server. See section 3.4 Working with SOCKS.|
|Int||no||Timeout (seconds) for key exchange. Default: 10.|
|Int||no||Dynamic key lifetime. Default: 600 (10 minutes).|
|String||no||Script to run instead of `/etc/cipe/ip-up'.|
|String||no||Script to run instead of `/etc/cipe/ip-down'.|
|String||no||Argument to supply to `ip-up', `ip-down'.|
|Int||no|| Maximum number of errors before ciped exits. See section 3.6 Error handling in |
|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.|
|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.|
|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.|
|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.|
|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 |
|Bool||Assume the carrier is on a dynamic IP address. See section 3.5 Dynamic carrier addresses.|
|String||no||Set the dummy MAC address used in Ethernet mode (protocol 4).|
|Bool|| Require an external |
|Bool||Use checksummed UDP carrier packets. Only necessary if the network does not like unchecksummed packets.|
|Bool||Ignore the DF bit on IP packets and allow the encapsulated packet to be fragmented.|
|Bool||Disable PMTU and use device MTU.|
Versions of CIPE before 1.4.0 have a bug in the way the
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
(32 hex digits) to
(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
to use the old
broken key parser.
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.
Username and password are taken from the environment variables
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
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,
is a limitation in the SOCKS5 protocol. See section 3.6 Error handling in
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
See section 5.4 Connection modes, for an overview on the different sorts of dynamic addresses and how they can be handled.
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:
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
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
ciped will exit. This behaviour is mandated by the
|[ << ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|