1DISTCACHE(8) distcache DISTCACHE(8)
2
6 distcache - Distributed session caching
7
9 The distcache architecture provides a protocol and set of accompanying
10 tools to allow applications, and indeed machines, to share session
11 state between them by way of a network service.
12 The primary use of distcache right now is SSL/TLS session caching. This
14 allows SSL/TLS servers (eg. a secure Apache web server providing HTTPS
15 support) to use a centralised session cache, i.e any server may resume
16 SSL/TLS sessions negotiated by any other server on the network. The
17 advantages to this approach include increased freedom of mechanisms for
18 load-balancing.
19 Existing SSL/TLS load-balancing solutions
21 Many load-balancers attempt to route incoming connections to servers
23 based on remembering the last mapping from the same source network
24 address. Others, called "SSL sticky" load-balancers, attempt to parse
25 SSL/TLS session ids from handshake messages and so map future session-
26 resume attempts. Both methods have serious weaknesses - the former is
27 generally confused by any form of network address translation (eg. when
28 clients are behind masquerading gateways), and the latter is confused
29 by any SSL/TLS renegotiations. Moreover both are stateful and a poten‐
30 tial bottleneck, because there is no obvious way to scale the architec‐
31 ture to multiple load-balancers.
32 Arbitrary SSL/TLS load-balancing with distcache
34 There is no need nor motivation to route incoming connections to "the
36 same server" to improve the chances for SSL/TLS session resumption, and
37 indeed doing so defeats the point of load-balancing (which is to bal‐
38 ance according load or availability). The use of distcache is to ensure
39 that all servers share the same "cache" and so can respond to SSL/TLS
40 session resume requests irrespective of where the previous SSL/TLS con‐
41 nection from the same client was mapped to.
42 It ain't just for SSL/TLS ...
44 Future versions of distcache will expand on the protocol and should
46 provide for a variety of "shared-state" uses besides SSL/TLS session
47 caching. The possibilities include application state caching, network-
48 based shared virtual memory, etc.
49
51 dc_server
52 Runs a cache server listening on a configurable network address.
53 See dc_server(1).
54 dc_client
56 Runs a local client proxy. From the point of view of applications
57 this behaves like dc_server, but manages multiplexing application
58 requests to/from a cache server over a single persistent connec‐
59 tion. See dc_client(1).
60 dc_test
62 Sends a (configurable) barrage of session caching requests to a
63 given network address using the distcache protocol. Useful for
64 testing correctness of an installation as well as benchmarking. Can
65 be used directly against an instance of dc_server or against a
66 dc_client proxy. See dc_test(1).
67 dc_snoop
69 A transparent proxy tool supporting the distcache protocol that can
70 be used to monitor cache operation requests and responses between
71 any two end-points (eg. between an application and dc_client, or
72 between dc_client and dc_server). See dc_snoop(1).
73
75 The comments below provide a short summary of the APIs available in
76 distcache. To view more details, consult the section 2 man pages these
77 summaries refer to. If you are using a packaged version of distcache,
78 you may need to ensure that a corresponding "devel" package is
79 installed as the libraries, headers, and API documentation is often
80 packaged independantly of the user tools.
81 libnal
83 This is the underlying Network Abstraction Library (hence "NAL") used
85 by the distcache libraries and tools. libnal uses non-blocking sockets,
86 with an addressing abstraction that allows tools to transparently work
87 over unix domain sockets or TCP/IPv4 sockets by a change of address
88 text. For this reason, all the distcache tools can have their "-listen"
89 and "-connect" switches set to work over either kind of transport.
90 libnal defines various object types;
92 NAL_ADDRESS (see NAL_ADDRESS_new(2))
94 The addressing abstraction converts to and from text representa‐
95 tions, indicates whether given addresses are valid for listening
96 on, connecting to, or both.
97 NAL_CONNECTION (see NAL_CONNECTION_new(2))
99 This encapsulates a network connection that can be used for sending
100 and receiving arbitrary binary data.
101 NAL_LISTENER (see NAL_LISTENER_new(2))
103 This encapsulates a listening socket that can be used to accept
104 incoming connection requests on a configured address, creating a
105 NAL_CONNECTION wrapper for each accepted connection.
106 NAL_SELECTOR (see NAL_SELECTOR_new(2))
108 This provides an object that can be prepared with various NAL_LIS‐
109 TENER and NAL_CONNECTION objects, and then can block waiting for
110 network activity up to some configurable limit of time. This is the
111 basis of non-blocking I/O and is an encapsulation of the tradi‐
112 tional select(2) function.
113 NAL_BUFFER (see NAL_BUFFER_new(2))
115 This abstraction implements a FIFO data array and is used primarily
116 for representing the read and send parts of a NAL_CONNECTION
117 object.
118 There are also some helper functions to assist in serialising data,
120 particularly with respect to putting integral data into network byte
121 order (allowing interoperability between platforms with differing
122 byte-order). These functions are documented in NAL_decode_uint32(2).
123 libdistcache
125 There are two APIs implemented by the libdistcache library;
127 distcache/dc_plug.h
129 This header provides the DC_PLUG abstraction. This encapsulates a
130 connection and implements the distcache protocol and various func‐
131 tions for manipulating the reading and writing of distcache mes‐
132 sages (requests or responses). This abstraction can support client
133 and server implementations of the distcache protocol and supports
134 asynchronous behaviour by interacting with libnal's NAL_SELECTOR
135 type. For more information, see DC_PLUG_new(2).
136 distcache/dc_client.h
138 This header declares a higher-level (and much simpler) API than
139 dc_plug.h, and is useful in applications that want API functions
140 that ``do cache operations''. The API is blocking, and provides
141 simplistic ``add'', ``remove'', and ``get'' functions that only
142 return once the full request/response cycle is complete or an error
143 has occured. This is the API used to add distcache support to
144 applications like Apache, stunnel, etc. For more information, see
145 DC_CTX_new(2).
146 libdistcacheserver
148 This header declares an API for implementing a session cache supporting
150 the distcache protocol. It is primarily intended for environments that
151 wish to implement an alternative method for session storage. As with
152 elements of libdistcache, this API is likely to be undergoing some
153 important restructuring and enhancements. Please consider subscribing
154 to the distcache mail list and/or monitoring CVS, this gives you an
155 opportunity to influence ongoing development and be less surprised at
156 changes the turn up in future versions. For more information, see
157 DC_SERVER_new(2).
158
160 The distcache toolkit, including the libnal network abstraction library
161 that comes bundled with it, is distributed under the LGPL license
162 ("Library GNU Public License") and you should have received a copy of
163 this license with this software and its documents.
164
166 Quite possibly. In particular, portability has not been tested under
167 many platforms as the current developers have limited OS resources.
168 Feedback, access to alternative platforms, bug-reports, and questions
169 are all welcome - please go to the distcache website and subscribe to
170 the distcache-users mail list.
171
173 dc_server(1)
174 Distributed caching server.
175 dc_client(1)
177 Distributed caching client proxy
178 dc_snoop(1)
180 Distcache protocol analyser and debugging tool.
181 http://www.distcache.org/
183 Distcache home page.
184
186 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
187 graphic Appliances Incorporated. Since the project was released into
188 open source, it has a home page and a project environment where devel‐
189 opment, mailing lists, and releases are organised. For problems with
190 the software or this man page please check for new releases at the
191 project web-site below, mail the users mailing list described there, or
192 contact the author at geoff@geoffthorpe.net.
193 Home Page: http://www.distcache.org
1951.4.5 2004.03.23 DISTCACHE(8)