DC_CLIENT(1) distcache DC_CLIENT(1)
NAME
dc_client - Distributed session cache client proxy
SYNOPSIS
dc_client -server [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 connec-
tions 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 communi-
cations.
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 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).
-listen address
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 net-
work transport, dc_client should be expected to receive a lot of short-lived (and fre-
quest) 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
-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 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 con-
nected 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 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 conse-
quence is that cache operations return as failures during this time, so the applica-
tion 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 communica-
tions every 5 seconds. This flag allows the retry period to be configured to any num-
ber of milliseconds. 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 (applications using dist-
cache(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 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 con-
figure 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 intentionally dropped.
Note, provided client applications are appropriately configured they need not neces-
sarily be vulnerable to race conditions when dc_client configures this flag. The dist-
cache(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 con-
nection 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 combination with -dae-
mon. 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 path
was);
kill 'cat pidfile.pid'
-h, -help, -?
Any of these flags will cause dc_client to display a brief usage summary to the con-
sole and exit cleanly. Any other flags are ignored.
SEE ALSO
dc_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 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
1.4.5 2004.03.23 DC_CLIENT(1)
|