FreeBSD Manual Pages
DC_CLIENT(1) distcache DC_CLIENT(1) NAME dc_client - Distributed session cache client proxy SYNOPSIS 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 (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. 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 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 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 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. 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 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- quired). 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 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 ig- nored. 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 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.5.1 2004.10.19 DC_CLIENT(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dc_client&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>