Distributed session cache client proxy. It runs a client proxy to provide access to a remote cache server by providing a local service
Now lets see the manual of dc_client service.Manual dc_client:NAME
dc_client - Distributed session cache client proxySYNOPSIS
dc_client -server <address> [options]DESCRIPTION
dc_client 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 dc_server for proxying cache operations to.
Incoming connections are expected to communicate using the distcache(8) protocol, and would typically be applications
using one of the distcache APIs in libdistcache to encapsulate these communications.
The common use of dc_client 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 dc_client makes to the
cache server (dc_server) for proxying cache operations is typically over a genuine network to remote machine, using
After initialising, dc_client will detach from the parent process, close standard file-descriptors, etc. If
this flag is not set, dc_client will run in the foreground. It is recommended to use this flag in combination
with the pidfile flag to simplify stopping and restarting services.
This switch will attempt to change user privileges of dc_client to the given user ID after initialising its
listening socket. On most systems, this can only work if dc_client is started as the root 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).
Configures the address on which dc_client should listen for incoming connections. The syntax is that defined
by the libnal API. Though this can listen on any supported network transport, dc_client should be expected to
receive a lot of short-lived (and frequest) connections, so unix domain sockets are generally preferable to
# 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
This switch is only useful when listening (see -listen) on unix domain sockets. It will attempt to change ownership
of the created socket file.
This switch is only useful when listening (see -listen) on unix domain sockets. It will attempt to change
group ownership of the created socket file.
This switch is only useful when listening (see -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 nobody user, listening on a unix domain socket that can only
be connected to by the root user or members of the ssl group;
# dc_client -listen UNIX:/tmp/cacheclient -user nobody
-sockgroup ssl -sockperms 440
These flags are identical, and specify the address of the cache server dc_client should connect to. Cache operations
requested by clients of dc_client (using short-lived local connections to the service address specified
by -listen) are multiplexed to/from the cache server over this persistent connection. The syntax is that
defined by the libnal 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
Distcache is designed to be as fault-tolerant as possible, and part of this approach is to have dc_client manage
the possible disappearance and subsequent reappearance of the remote instance of dc_server 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 dc_client has lost communications
with the cache server, any/all local connections and corresponding cache operation requests will be
responded to directly by dc_client 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 dc_client when losing communications with the instance of dc_server (as specified by
-server or -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.
Normal behaviour with dc_client is to have its clients (applications using distcache(8) 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 filedescriptor
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 dc_client 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 not seconds. The default value is zero, and this means that client connections are never
Note, provided client applications are appropriately configured they need not necessarily be vulnerable to race
conditions when dc_client configures this flag. The distcache(8) DC_CTX 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 dc_client, the DC_CTX will allow one retry with
an immediate re-connection before considering the operation to have failed.
This is a standard flag for many programs, and most useful in combination with -daemon. When -pidfile is specified
dc_client 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 dc_client instance, use something like (where pidfile.pid is whatever
kill 'cat pidfile.pid'
-h, -help, -?
Any of these flags will cause dc_client to display a brief usage summary to the console and exit cleanly. Any
other flags are ignored.SEE ALSO
Distributed cache server.
Distcache protocol analyser and debugging tool.
Overview of the distcache architecture.
Distcache home page.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
Home Page: http://www.distcache.org