DISTCACHE(8)                       distcache                      DISTCACHE(8)

       distcache - Distributed session caching

       The distcache architecture provides a protocol and set of accompanying
       tools to allow applications, and indeed machines, to share session
       state between them by way of a network service.

       The primary use of distcache right now is SSL/TLS session caching. This
       allows SSL/TLS servers (eg. a secure Apache web server providing HTTPS
       support) to use a centralised session cache, i.e any server may resume
       SSL/TLS sessions negotiated by any other server on the network. The
       advantages to this approach include increased freedom of mechanisms for

       Existing SSL/TLS load-balancing solutions

       Many load-balancers attempt to route incoming connections to servers
       based on remembering the last mapping from the same source network
       address. Others, called "SSL sticky" load-balancers, attempt to parse
       SSL/TLS session ids from handshake messages and so map future session-
       resume attempts. Both methods have serious weaknesses - the former is
       generally confused by any form of network address translation (eg. when
       clients are behind masquerading gateways), and the latter is confused
       by any SSL/TLS renegotiations. Moreover both are stateful and a
       potential bottleneck, because there is no obvious way to scale the
       architecture to multiple load-balancers.

       Arbitrary SSL/TLS load-balancing with distcache

       There is no need nor motivation to route incoming connections to "the
       same server" to improve the chances for SSL/TLS session resumption, and
       indeed doing so defeats the point of load-balancing (which is to
       balance according load or availability). The use of distcache is to
       ensure that all servers share the same "cache" and so can respond to
       SSL/TLS session resume requests irrespective of where the previous
       SSL/TLS connection from the same client was mapped to.

       It ain't just for SSL/TLS ...

       Future versions of distcache will expand on the protocol and should
       provide for a variety of "shared-state" uses besides SSL/TLS session
       caching. The possibilities include application state caching, network-
       based shared virtual memory, etc.

           Runs a cache server listening on a configurable network address.
           See dc_server(1).

           Runs a local client proxy. From the point of view of applications
           this behaves like dc_server, but manages multiplexing application
           requests to/from a cache server over a single persistent
           connection. See dc_client(1).

           Sends a (configurable) barrage of session caching requests to a
           given network address using the distcache protocol. Useful for
           testing correctness of an installation as well as benchmarking. Can
           be used directly against an instance of dc_server or against a
           dc_client proxy. See dc_test(1).

           A transparent proxy tool supporting the distcache protocol that can
           be used to monitor cache operation requests and responses between
           any two end-points (eg.  between an application and dc_client, or
           between dc_client and dc_server). See dc_snoop(1).

       The comments below provide a short summary of the APIs available in
       distcache.  To view more details, consult the section 2 man pages these
       summaries refer to.  If you are using a packaged version of distcache,
       you may need to ensure that a corresponding "devel" package is
       installed as the libraries, headers, and API documentation is often
       packaged independantly of the user tools.


       This is the underlying Network Abstraction Library (hence "NAL") used
       by the distcache libraries and tools. libnal uses non-blocking sockets,
       with an addressing abstraction that allows tools to transparently work
       over unix domain sockets or TCP/IPv4 sockets by a change of address
       text. For this reason, all the distcache tools can have their "-listen"
       and "-connect" switches set to work over either kind of transport.

       libnal defines various object types;

       NAL_ADDRESS (see NAL_ADDRESS_new(2))
           The addressing abstraction converts to and from text
           representations, indicates whether given addresses are valid for
           listening on, connecting to, or both.

           This encapsulates a network connection that can be used for sending
           and receiving arbitrary binary data.

       NAL_LISTENER (see NAL_LISTENER_new(2))
           This encapsulates a listening socket that can be used to accept
           incoming connection requests on a configured address, creating a
           NAL_CONNECTION wrapper for each accepted connection.

       NAL_SELECTOR (see NAL_SELECTOR_new(2))
           This provides an object that can be prepared with various
           NAL_LISTENER and NAL_CONNECTION objects, and then can block waiting
           for network activity up to some configurable limit of time. This is
           the basis of non-blocking I/O and is an encapsulation of the
           traditional select(2) function.

       NAL_BUFFER (see NAL_BUFFER_new(2))
           This abstraction implements a FIFO data array and is used primarily
           for representing the read and send parts of a NAL_CONNECTION

       There are also some helper functions to assist in serialising data,
       particularly with respect to putting integral data into network byte
       order (allowing interoperability between platforms with differing
       byte-order). These functions are documented in NAL_decode_uint32(2).


       There are two APIs implemented by the libdistcache library;

           This header provides the DC_PLUG abstraction. This encapsulates a
           connection and implements the distcache protocol and various
           functions for manipulating the reading and writing of distcache
           messages (requests or responses). This abstraction can support
           client and server implementations of the distcache protocol and
           supports asynchronous behaviour by interacting with libnal's
           NAL_SELECTOR type. For more information, see DC_PLUG_new(2).

           This header declares a higher-level (and much simpler) API than
           dc_plug.h, and is useful in applications that want API functions
           that ``do cache operations''.  The API is blocking, and provides
           simplistic ``add'', ``remove'', and ``get'' functions that only
           return once the full request/response cycle is complete or an error
           has occured. This is the API used to add distcache support to
           applications like Apache, stunnel, etc. For more information, see


       This header declares an API for implementing a session cache supporting
       the distcache protocol. It is primarily intended for environments that
       wish to implement an alternative method for session storage. As with
       elements of libdistcache, this API is likely to be undergoing some
       important restructuring and enhancements. Please consider subscribing
       to the distcache mail list and/or monitoring CVS, this gives you an
       opportunity to influence ongoing development and be less surprised at
       changes the turn up in future versions. For more information, see

       The distcache toolkit, including the libnal network abstraction library
       that comes bundled with it, is distributed under the LGPL license
       ("Library GNU Public License") and you should have received a copy of
       this license with this software and its documents.

       Quite possibly. In particular, portability has not been tested under
       many platforms as the current developers have limited OS resources.
       Feedback, access to alternative platforms, bug-reports, and questions
       are all welcome - please go to the distcache website and subscribe to
       the distcache-users mail list.

           Distributed caching server.

           Distributed caching client proxy

           Distcache protocol analyser and debugging tool.

           Distcache home page.

       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 geoff@geoffthorpe.net.

       Home Page: http://www.distcache.org

1.4.5                             2004.03.23                      DISTCACHE(8)