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 load−balancing.

     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;

    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.

    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.

    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.

    This abstraction implements a FIFO data array and is
    used primarily for representing the read and send parts
    of a NAL_CONNECTION object.

     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


     There are two APIs implemented by the libdistcache

    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

    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 DC_CTX_new(2).


     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 DC_SERVER_new(2).

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