Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DC_CLIENT(1)			   distcache			  DC_CLIENT(1)

       dc_client - Distributed session cache client proxy

       dc_client -server <address> [options]

       dc_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 ma-
       chine that requires use of the distributed cache, as the	listening ad-
       dress 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.

	   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 af-
	   ter 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

       -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 do-
	   main	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 do-
	   main	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 do-
	   main	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.

	       # 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 va-
	   riety 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 re-

	   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 al-
	   lows	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 op-
	   eration in those APIs that allow persistent connections to be used
	   together with various associated options.  This is especially im-
	   portant 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 is	what-
	   ever	path was);

	       kill `cat`

       -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	ig-

	   Distributed cache server.

	   Distcache protocol analyser and debugging tool.

	   Overview of the distcache architecture.
	   Distcache home page.

       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

       Home Page:

1.5.1				  2004.10.19			  DC_CLIENT(1)


Want to link to this manual page? Use this URL:

home | help