1DC_CLIENT(1) distcache DC_CLIENT(1)
2
6 dc_client - Distributed session cache client proxy
7
9 dc_client -server <address> [options]
10
12 dc_client runs a client proxy to provide access to a remote cache
13 server (typically over TCP/IPv4) by providing a local service (typi‐
14 cally over unix domain sockets). It starts listening on a configurable
15 network address for connections and establishes a persistent connection
16 to an instance of dc_server for proxying cache operations to. Incoming
17 connections are expected to communicate using the distcache(8) proto‐
18 col, and would typically be applications using one of the distcache
19 APIs in libdistcache to encapsulate these communications.
20 The common use of dc_client is to run as a local agent on each host
22 machine that requires use of the distributed cache, as the listening
23 address should probably use unix domain sockets which are better suited
24 to frequent (and temporary) connections being used for individual cache
25 operations. Likewise, the connection dc_client makes to the cache
26 server (dc_server) for proxying cache operations is typically over a
27 genuine network to remote machine, using TCP/IPv4.
28
30 -daemon
31 After initialising, dc_client will detach from the parent process,
32 close standard file-descriptors, etc. If this flag is not set,
33 dc_client will run in the foreground. It is recommended to use this
34 flag in combination with the pidfile flag to simplify stopping and
35 restarting services.
36 -user user
38 This switch will attempt to change user privileges of dc_client to
39 the given user ID after initialising its listening socket. On most
40 systems, this can only work if dc_client is started as the root
41 user. It is important to note that the change of user ID occurs
42 after the listening socket is created but before any attempts are
43 made to connect to distcache servers. This ensures that the listen‐
44 ing socket is created with the most restrictive permissions, and
45 that the ability to connect to servers at run-time corresponds to
46 the given user (rather than having unusual root permissions on
47 startup).
48 -listen address
50 Configures the address on which dc_client should listen for incom‐
51 ing connections. The syntax is that defined by the libnal API.
52 Though this can listen on any supported network transport,
53 dc_client should be expected to receive a lot of short-lived (and
54 frequest) connections, so unix domain sockets are generally prefer‐
55 able to TCP/IPv4. Eg.
56 # Listen on a unix domain socket in the /tmp directory
58 dc_client -listen UNIX:/tmp/cacheclient
59 The default value for this flag is: UNIX:/tmp/scache
61 -sockowner user
63 This switch is only useful when listening (see -listen) on unix
64 domain sockets. It will attempt to change ownership of the created
65 socket file.
66 -sockgroup group
68 This switch is only useful when listening (see -listen) on unix
69 domain sockets. It will attempt to change group ownership of the
70 created socket file.
71 -sockperms perms
73 This switch is only useful when listening (see -listen) on unix
74 domain sockets. It will attempt to change file permissions for the
75 created socket file, and is specified in the standard octal nota‐
76 tion used for unix file permissions. Eg. to start dc_client to run
77 as the nobody user, listening on a unix domain socket that can only
78 be connected to by the root user or members of the ssl group;
79 # dc_client -listen UNIX:/tmp/cacheclient -user nobody \
81 -sockgroup ssl -sockperms 440
82 -server address
84 -connect address
85 These flags are identical, and specify the address of the cache
86 server dc_client should connect to. Cache operations requested by
87 clients of dc_client (using short-lived local connections to the
88 service address specified by -listen) are multiplexed to/from the
89 cache server over this persistent connection. The syntax is that
90 defined by the libnal API and would typically be over TCP/IPv4,
91 particularly if the cache server is running on a remote machine.
92 Eg.
93 # Connect to a remote cache server listening on port 9001
95 dc_client -listen UNIX:/tmp/cacheclient \
96 -server IP:cacheserver.localnet:9001
97 -retry msecs
99 Distcache is designed to be as fault-tolerant as possible, and part
100 of this approach is to have dc_client manage the possible disap‐
101 pearance and subsequent reappearance of the remote instance of
102 dc_server it proxies to. In actuality, this could happen for a
103 variety of reasons including the cache server being restarted, or a
104 network error at any point in between the two programs. During any
105 period in which dc_client has lost communications with the cache
106 server, any/all local connections and corresponding cache operation
107 requests will be responded to directly by dc_client itself. The
108 consequence is that cache operations return as failures during this
109 time, so the application requesting the operations must make do
110 without (eg. in SSL/TLS session caching, this means that attempts
111 to resume SSL/TLS sessions fail and so full handshakes are
112 required).
113 The default behaviour of dc_client when losing communications with
115 the instance of dc_server (as specified by -server or -connect) is
116 to try to reestablish communications every 5 seconds. This flag
117 allows the retry period to be configured to any number of millisec‐
118 onds. Note: confusing milliseconds with seconds can cause emotional
119 disturbance and should be avoided at all costs.
120 -idle msecs
122 Normal behaviour with dc_client is to have its clients (applica‐
123 tions using distcache(8) APIs for communication) use temporary con‐
124 nections for each cache operation. However, there are modes of
125 operation in those APIs that allow persistent connections to be
126 used together with various associated options. This is especially
127 important for any platforms that (for whatever reason) can't use
128 unix domain sockets and don't want to bloat file-descriptor tables
129 with IPv4 sockets sitting in TIME_WAIT state. For this reason, as
130 well as resilience against client applications that hang, it useful
131 to configure dc_client to automatically drop client connections
132 that have been idle for some configurable period of time.
133 This flag specifies the period of idle time after which client con‐
135 nections will be dropped, and is in units of milliseconds and not
136 seconds. The default value is zero, and this means that client con‐
137 nections are never intentionally dropped.
138 Note, provided client applications are appropriately configured
140 they need not necessarily be vulnerable to race conditions when
141 dc_client configures this flag. The distcache(8) DC_CTX API pro‐
142 vides additional persistence options such as fork(2)-checking and
143 resistance against idle timeouts. Ie. if a request is commenced on
144 a client connection that is in the process of being timed-out by
145 dc_client, the DC_CTX will allow one retry with an immediate re-
146 connection before considering the operation to have failed.
147 -pidfile path
149 This is a standard flag for many programs, and most useful in com‐
150 bination with -daemon. When -pidfile is specified dc_client will
151 write its process ID to a file at the specified path upon success‐
152 ful initialisation. To use this path file to later kill the running
153 dc_client instance, use something like (where pidfile.pid is what‐
154 ever path was);
155 kill `cat pidfile.pid`
157 -h, -help, -?
159 Any of these flags will cause dc_client to display a brief usage
160 summary to the console and exit cleanly. Any other flags are
161 ignored.
162
164 dc_server(1)
165 Distributed cache server.
166 dc_snoop(1)
168 Distcache protocol analyser and debugging tool.
169 distcache(8)
171 Overview of the distcache architecture.
172 http://www.distcache.org/
174 Distcache home page.
175
177 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
178 graphic Appliances Incorporated. Since the project was released into
179 open source, it has a home page and a project environment where devel‐
180 opment, mailing lists, and releases are organised. For problems with
181 the software or this man page please check for new releases at the
182 project web-site below, mail the users mailing list described there, or
183 contact the author at geoff@geoffthorpe.net.
184 Home Page: http://www.distcache.org
1861.4.5 2004.03.23 DC_CLIENT(1)