DC_CLIENT(1) distcache DC_CLIENT(1)NAMEdc_client - Distributed session cache client proxy
SYNOPSISdc_client-server <address> [options]
DESCRIPTIONdc_client runs a client proxy to provide access to a remote cache
server (typically over TCP/IPv4) by providing a local service (typi‐
cally 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) proto‐
col, 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 TCP/IPv4.
OPTIONS-daemon
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.
-user user
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 listen‐
ing 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).
-listen address
Configures the address on which dc_client should listen for incom‐
ing 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 prefer‐
able 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
-sockowner user
This switch is only useful when listening (see -listen) on unix
domain sockets. It will attempt to change ownership of the created
socket file.
-sockgroup group
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.
-sockperms perms
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 nota‐
tion 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
-server address
-connect address
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 \
-server IP:cacheserver.localnet:9001
-retry msecs
Distcache is designed to be as fault-tolerant as possible, and part
of this approach is to have dc_client manage the possible disap‐
pearance 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 millisec‐
onds. Note: confusing milliseconds with seconds can cause emotional
disturbance and should be avoided at all costs.
-idle msecs
Normal behaviour with dc_client is to have its clients (applica‐
tions using distcache(8) APIs for communication) use temporary con‐
nections 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 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 con‐
nections will be dropped, and is in units of milliseconds and not
seconds. The default value is zero, and this means that client con‐
nections are never intentionally dropped.
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 pro‐
vides 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.
-pidfile path
This is a standard flag for many programs, and most useful in com‐
bination with -daemon. When -pidfile is specified dc_client will
write its process ID to a file at the specified path upon success‐
ful initialisation. To use this path file to later kill the running
dc_client instance, use something like (where pidfile.pid is what‐
ever path was);
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 ALSOdc_server(1)
Distributed cache server.
dc_snoop(1)
Distcache protocol analyser and debugging tool.
distcache(8)
Overview of the distcache architecture.
http://www.distcache.org/
Distcache home page.
AUTHOR
This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
graphic Appliances Incorporated. Since the project was released into
open source, it has a home page and a project environment where devel‐
opment, 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 geoff@geoffthorpe.net.
Home Page: http://www.distcache.org
1.4.5 2004.03.23 DC_CLIENT(1)