=head1 NAME dc_client - Distributed session cache client proxy =head1 SYNOPSIS B -server
[options] =head1 DESCRIPTION B runs a client proxy to provide access to a remote cache server (typically over TCP/IPv4) by providing a local service (typically over unix domain sockets). It starts listening on a configurable network address for connections and establishes a persistent connection to an instance of B for proxying cache operations to. Incoming connections are expected to communicate using the L protocol, and would typically be applications using one of the distcache APIs in I to encapsulate these communications. The common use of B is to run as a local agent on each host machine that requires use of the distributed cache, as the listening address should probably use unix domain sockets which are better suited to frequent (and temporary) connections being used for individual cache operations. Likewise, the connection B makes to the cache server (B) for proxying cache operations is typically over a genuine network to remote machine, using TCP/IPv4. =head1 OPTIONS =over 4 =item B<-daemon> After initialising, B will detach from the parent process, close standard file-descriptors, etc. If this flag is not set, B will run in the foreground. It is recommended to use this flag in combination with the I flag to simplify stopping and restarting services. =item B<-user> user This switch will attempt to change user privileges of B to the given user ID after initialising its listening socket. On most systems, this can only work if B is started as the I user. It is important to note that the change of user ID occurs after the listening socket is created but before any attempts are made to connect to distcache servers. This ensures that the listening socket is created with the most restrictive permissions, and that the ability to connect to servers at run-time corresponds to the given user (rather than having unusual root permissions on startup). =item B<-listen> address Configures the address on which B should listen for incoming connections. The syntax is that defined by the I API. Though this can listen on any supported network transport, B should be expected to receive a lot of short-lived (and frequest) connections, so unix domain sockets are generally preferable to TCP/IPv4. Eg. # Listen on a unix domain socket in the /tmp directory dc_client -listen UNIX:/tmp/cacheclient The default value for this flag is: UNIX:/tmp/scache =item B<-sockowner> user This switch is only useful when listening (see B<-listen>) on unix domain sockets. It will attempt to change ownership of the created socket file. =item B<-sockgroup> group This switch is only useful when listening (see B<-listen>) on unix domain sockets. It will attempt to change group ownership of the created socket file. =item B<-sockperms> perms This switch is only useful when listening (see B<-listen>) on unix domain sockets. It will attempt to change file permissions for the created socket file, and is specified in the standard octal notation used for unix file permissions. Eg. to start dc_client to run as the I user, listening on a unix domain socket that can only be connected to by the I user or members of the I group; # dc_client -listen UNIX:/tmp/cacheclient -user nobody \ -sockgroup ssl -sockperms 440 =item B<-server> address =item B<-connect> address These flags are identical, and specify the address of the cache server B should connect to. Cache operations requested by clients of B (using short-lived local connections to the service address specified by B<-listen>) are multiplexed to/from the cache server over this persistent connection. The syntax is that defined by the I API and would typically be over TCP/IPv4, particularly if the cache server is running on a remote machine. Eg. # Connect to a remote cache server listening on port 9001 dc_client -listen UNIX:/tmp/cacheclient \ -server IP:cacheserver.localnet:9001 =item B<-retry> msecs Distcache is designed to be as fault-tolerant as possible, and part of this approach is to have B manage the possible disappearance and subsequent reappearance of the remote instance of B it proxies to. In actuality, this could happen for a variety of reasons including the cache server being restarted, or a network error at any point in between the two programs. During any period in which B has lost communications with the cache server, any/all local connections and corresponding cache operation requests will be responded to directly by B itself. The consequence is that cache operations return as failures during this time, so the application requesting the operations must make do without (eg. in SSL/TLS session caching, this means that attempts to resume SSL/TLS sessions fail and so full handshakes are required). The default behaviour of B when losing communications with the instance of B (as specified by B<-server> or B<-connect>) is to try to reestablish communications every 5 seconds. This flag allows the retry period to be configured to any number of milliseconds. Note: confusing milliseconds with seconds can cause emotional disturbance and should be avoided at all costs. =item B<-idle> msecs Normal behaviour with B is to have its clients (applications using B APIs for communication) use temporary connections for each cache operation. However, there are modes of operation in those APIs that allow persistent connections to be used together with various associated options. This is especially important for any platforms that (for whatever reason) can't use unix domain sockets and don't want to bloat file-descriptor tables with IPv4 sockets sitting in TIME_WAIT state. For this reason, as well as resilience against client applications that hang, it useful to configure B to automatically drop client connections that have been idle for some configurable period of time. This flag specifies the period of idle time after which client connections will be dropped, and is in units of milliseconds and B seconds. The default value is zero, and this means that client connections are never intentionally dropped. Note, provided client applications are appropriately configured they need not necessarily be vulnerable to race conditions when B configures this flag. The B I API provides additional persistence options such as fork(2)-checking and resistance against idle timeouts. Ie. if a request is commenced on a client connection that is in the process of being timed-out by B, the I will allow one retry with an immediate re-connection before considering the operation to have failed. =item B<-pidfile> path This is a standard flag for many programs, and most useful in combination with B<-daemon>. When B<-pidfile> is specified B will write its process ID to a file at the specified path upon successful initialisation. To use this path file to later kill the running B instance, use something like (where B is whatever B was); kill `cat pidfile.pid` =item B<-h>, B<-help>, B<-?> Any of these flags will cause B to display a brief usage summary to the console and exit cleanly. Any other flags are ignored. =back =head1 SEE ALSO =over 4 =item L Distributed cache server. =item L Distcache protocol analyser and debugging tool. =item L Overview of the distcache architecture. =item F Distcache home page. =back =head1 AUTHOR This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances Incorporated. Since the project was released into open source, it has a home page and a project environment where development, mailing lists, and releases are organised. For problems with the software or this man page please check for new releases at the project web-site below, mail the users mailing list described there, or contact the author at F. Home Page: F