Once installed, the CIPE software is run by loading the module andrunning the @command{ciped} daemon.@menu* Program Names::       How the components of CIPE are named.* insmod::              Loading the kernel module.* ciped::               Running the daemon.@end menu@node  Program Names, insmod, Run, Run@subsection        Program Names@cindex module name@cindex device namesThe module name is @code{cip} followed by the protocol version as aletter and the first letter of the encryption algorithm. E.g.@:@code{cipcb} for version 3 (i.e. "c"), Blowfish (the default). Thedevice names which this module manages are the module name followed by anumber, e.g.@: @code{cipcb0}.@cindex daemon nameSince CIPE 1.3, the daemon program is named @code{ciped-} followed bythe protocol and encryption letters, likewise. E.g.@: @code{ciped-cb}.Where this manual refers to @command{ciped}, assume the real name as givenhere.The configuration parameters of kernel module and daemon must match (themodule checks this), but the daemon does not depend (at least not intheory) on the kernel version. The naming scheme is chosen so that allpossible modules and daemons on one machine can coexist.The @code{pkcipe} program is designed to be independent from theconfiguration. However, currently it can only handle one version of@code{ciped} (i.e. one protocol and cipher version). This will be fixedin future versions.@node insmod, ciped, Program Names, Run@subsection        Loading the moduleThe kernel module is loaded into the kernel via the command@cindex @command{modprobe} command@examplemodprobe modulename parameter=value...@end exampleThe CIPE module accepts the following additional parameters:@cindex module parameters@table @code@item cipe_debug=(number)Set the debugging level. The file@file{cipe.h} defines different debugging levels which are ORed. Setthis to 0 if you don't need debugging output. Debugging output isemitted via kernel messages, which means it usually winds up in thesyslog somewhere.@cindex debugging level@item cipe_maxdev=(number)Set the number of channels this modulemanages. E.g.@: with @code{cipe_maxdev=4} the devices @code{cipcb0}through @code{cipcb3} are available. Maximum is 9999 Since CIPE 1.2, thereis no need to set this, since channels are allocated dynamically.@cindex devices, number of@end table@cindex autoloading of modulesThe module can be autoloaded via @command{kerneld}/@command{kmod}. Advancedusers will recognize the following options in @file{/etc/conf.modules}necessary to make it work correctly:@examplealias cipcb0 cipcboptions cipcb cipe_debug=0@end exampleNote: with dynamic device allocation, aliasing any device other than@code{cipcb0} is pointless and autoloading only works when therequesting application is @command{ciped} (not @command{ifconfig} etc.)This is a limitation inherent in dynamic device allocation.@node ciped,  , insmod, Run@subsection        Running the @command{ciped} daemonThe @command{ciped} daemon must be run as @emph{root}. (@strong{Do not} makeit setuid.) It takes as command line arguments an optional @option{-ofile} parameter specifying an options file followed by any number ofindividual option arguments. @xref{Specifying options}.Except in debugging mode, the daemon puts itself in the background anduses @code{syslog(3)} for logging messages. Normal operation causes nolog messages except for errors and a notice when the daemon terminates.Shutting down (with @command{ifconfig(8)}) a CIPE device terminates its@command{ciped} process, and vice-versa terminating a @command{ciped} closesthe device. When a device is closed, its configuration parametersincluding all keys and statistics are erased. (This is different fromearlier CIPE versions!) @command{ciped} does not keep any keys in memory.When the device comes up, @command{ciped} spawns @file{/etc/cipe/ip-up}with the parameters described in the sample version. It waits forcompletion of this script before data can be sent over the device andbefore it goes into the background. The script is called with standardinput, output and error to @file{/dev/null}. It typically sets routesand does some logging. Since CIPE 1.4, the script is called with alloptions (except key) in environment variables named after the option.Likewise, when a CIPE device goes down, @file{/etc/cipe/ip-down} isinvoked. @command{ciped} itself logs the interface statistics when closing.@command{ciped} will terminate when an error occurs. This includes a"connection refused" message from the peer, to be able to detectnon-working peers. This default error handling implies that no data maybe sent over a link unless @emph{both} ends are up and running, or thefirst one to come up will go down again immediately. In particular, the"ping" command in the sample @file{ip-up} should not be activated onboth ends of a link. This behaviour can be customized. @xref{Errorhandling}, for more details.@c --------------------------------------------------------------------------@node Configuration, PKCIPE, Installation, Top@chapter        Configuration of the CIPE software@menu* Specifying options::  How CIPE gets its parameters.* Parameter list::      All valid and needed parameters.* Keys in older CIPE::  An incompatibility between Version 1.4 and earlier.* SOCKS::               Routing with CIPE over a SOCKS5 relayer.* Dynamic carrier::     How to deal with dynamic IP address assignment.* Error handling::      How ciped deals with errors.@end menu@node Specifying options, Parameter list, Configuration, Configuration@section        Specifying optionsAll configuration parameters are processed by the @command{ciped} daemon.It takes parameters from@cindex options file@cindex command line options@enumerate@itemthe default options file (@file{/etc/cipe/options}),@iteman options file specified as @option{-o file} on the command line,@itemsingle options given on the command line,@end enumeratein that order. Which means, parameters on the command line overridethose from files, and parameters from an explicit options file overridethose from the default options file.@cindex IP address syntaxOptions are one of the types: boolean, integer, string, IP address, IPaddress with port number. Booleans are default false and specifying themas option makes them true. IP addresses are given as dot-quad notationor domain names which can be resolved using @code{gethostbyname(3)}. UDPor TCP addresses are given as @code{ip:port}, where the port is a numberor a name resolvable by @code{getservbyname(3)}.The syntax for specifying options is @code{name=value} on the commandline, and @code{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 notwritable by group or other, and the options file itself must be even notreadable by group or other (because it may contain secret keys).@node Parameter list, Keys in older CIPE, Specifying options, Configuration@section        List of all parameters(Req=Required parameter)@include options.t@node Keys in older CIPE, SOCKS, Parameter list, Configuration@section        Incompatibility of keys to older CIPE versionsVersions of CIPE before 1.4.0 have a bug in the way the @code{key}option is interpreted. It is supposed to be a 128-bit hexadecimalnumber. However, earlier versions interpret the digits @samp{a} through@samp{f} as equal to @samp{1} through @samp{6}. This reduces theeffective key space from@tex$ 16^{32} $@end tex@ifnottex16^32@end ifnottex(32 hex digits) to@tex$ 10^{32} $@end tex@ifnottex10^32@end ifnottex(32 decimal digits), or 109 bits. Worse, it introducesbias in the distribution of bit patterns in the effective key.This bug needed to be fixed as soon as it was found. Unfortunately thefix means that old and new versions of @command{ciped} will read the samekey parameter differently, in other words: keys are not compatiblebetween 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 atonce (recommended), or generate new keys which consist only of decimaldigits. A possible method to generate such a key is@example(ps aux|md5sum; ps alx|md5sum) | tr -cd 0-9@end exampleAlternatively, the 1.4 or newer package can begiven the option @option{--enable-bug-compatible} to @command{configure}to use the oldbroken key parser.@node SOCKS, Dynamic carrier, Keys in older CIPE, Configuration@section        Working with SOCKS@cindex SOCKSWith the @code{socks} option, CIPE uses a SOCKS5 server for sending andreceiving the encrypted data. Since this is UDP, SOCKS4 (which doesn'tsupport UDP) can not be used. SOCKS5 has a number of authenticationmethods. CIPE can use either no authentication or Username/Password.@footnote{GSSAPI/Kerberos authentication is not supported because (a) Idon't have the environment to test it, and (b) it can specify that UDPpackets be encrypted with its own method, which is unnecessary andcauses only additional load here, and (c) it makes the implementationmuch more complicated.}Username and password are taken from the environment variables@env{SOCKS5_USER} and @env{SOCKS5_PASSWD}.The SOCKS server is free to pick any IP address, or at least any portnumber, as it sees fit. Thus using SOCKS implies a dynamic carrieraddress. @xref{Dynamic carrier}.The implementation is not based on a SOCKS library, don't attempt tolink @command{ciped} with it.@command{ciped} periodically checks whether the SOCKS server has closed thecontrol connection. If the SOCKS server goes down, there is no way torecover without restarting the client (in this case, @command{ciped}). Thisis a limitation in the SOCKS5 protocol. @xref{Error handling}.@node Dynamic carrier, Error handling, SOCKS, Configuration@section Dynamic carrier addresses@cindex dynamic addressesCIPE can handle dynamically changing carrier addresses. This is subjectto certain restrictions, however.When a link is already established, one end must notice when the otherend's carrier address changes. CIPE versions since 0.5.1 do thisautomatically.When one end of the link is on a real dynamic IP address (dial-updevice), it must notice when its own carrier address changes. Thisrequires Linux 2.2 or higher, CIPE version 1.4.0 or higher and the@option{dynip} option set.The trickiest part with using dynamic carrier addresses is finding outthe peer address before the link is established. Each CIPE needs to knowthe IP address and UDP port number to send packets to. Normally this isset with the @option{peer} option. As soon as a valid packet is receivedthe 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 @option{peer} option, and(only!) the dynamic end has the @command{ping} in the example@file{ip-up} activated. The @command{ping} will ensure that the dynamicend tells the static end its carrier address as soon as possible. Thestatic end should use a dummy @option{peer} which does not respond topackets normally@footnote{Use @code{127.0.0.1:9}, the discard UDP porton the local host} and the option @option{maxerr=-1}. The link isinitiated by the dynamic end.Whether a link between two dynamic carriers is possible depends on thesituation. It must be possible for one end to tell the other end itscurrent address in @emph{some} way outside of CIPE, and it should bepossible to initiate an immediate restart of @code{ciped} this way.As of CIPE 1.5, the recommended way to do this is the PKCIPE program.@xref{PKCIPE}.The @file{ip-up} script is always given the correct address in the@env{me} environment variable. For dynamic addresses this is the currentaddress and for SOCKS this is the address of the SOCKS relayer.In such a configuration, both ends should use @option{maxerr=-1} and theinitiating end should use the @code{ping}.@xref{Connection modes}, for an overview on the different sorts ofdynamic addresses and how they can be handled.@node Error handling,  , Dynamic carrier, Configuration@section        Error handling in @command{ciped}When the remote @command{ciped} is down or not available, the local@command{ciped} will get a "connection refused" error. Older versionsalways exited on this error. This has proven impractical in somesituations, so an extra option has been added: @code{maxerr} determineshow many network errors @command{ciped} will tolerate before exiting. Thiscounter is reset when the connection proves OK (more precisely: when akey exchange packet is received). The default for @code{maxerr} is 8,like the non-changeable default in version 0.5.1. A value of -1 willcause @command{ciped} to ignore any network errors. In this case, it canonly be brought down manually.If keep-alive pings are enabled, a failure to respond to a ping countsas 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 anerror occurs on the SOCKS control connection (e.g., the SOCKS servergoes down), @command{ciped} will exit. This behaviour is mandated by the