.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DISTCACHE 8"
.TH DISTCACHE 8 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
distcache \- Distributed session caching
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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.
.PP
The primary use of distcache right now is \s-1SSL/TLS\s0 session caching. This
allows \s-1SSL/TLS\s0 servers (eg. a secure Apache web server providing \s-1HTTPS\s0 support)
to use a centralised session cache, i.e any server may resume
\&\s-1SSL/TLS\s0 sessions negotiated by any other server on the network. The advantages to
this approach include increased freedom of mechanisms for load\-balancing.
.Sh "Existing \s-1SSL/TLS\s0 load-balancing solutions"
.IX Subsection "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 \*(L"\s-1SSL\s0 sticky\*(R" load\-balancers, attempt to parse \s-1SSL/TLS\s0 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 \s-1SSL/TLS\s0 renegotiations. Moreover both are
stateful and a potential bottleneck, because there is no obvious way to scale
the architecture to multiple load\-balancers.
.Sh "Arbitrary \s-1SSL/TLS\s0 load-balancing with distcache"
.IX Subsection "Arbitrary SSL/TLS load-balancing with distcache"
There is no need nor motivation to route incoming connections to \*(L"the same
server\*(R" to improve the chances for \s-1SSL/TLS\s0 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 \*(L"cache\*(R" and so can respond to \s-1SSL/TLS\s0 session resume requests irrespective of
where the previous \s-1SSL/TLS\s0 connection from the same client was mapped to.
.Sh "It ain't just for \s-1SSL/TLS\s0 ..."
.IX Subsection "It ain't just for SSL/TLS ..."
Future versions of distcache will expand on the protocol and should provide for
a variety of \*(L"shared\-state\*(R" uses besides \s-1SSL/TLS\s0 session caching. The
possibilities include application state caching, network-based shared virtual
memory, etc.
.SH "TOOLS"
.IX Header "TOOLS"
.IP "\fBdc_server\fR" 4
.IX Item "dc_server"
Runs a cache server listening on a configurable network address. See
\&\fIdc_server\fR\|(1).
.IP "\fBdc_client\fR" 4
.IX Item "dc_client"
Runs a local client proxy. From the point of view of applications this behaves like
\&\fBdc_server\fR, but manages multiplexing application requests to/from a
cache server over a single persistent connection. See \fIdc_client\fR\|(1).
.IP "\fBdc_test\fR" 4
.IX Item "dc_test"
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 \fBdc_server\fR or against a \fBdc_client\fR proxy. See \fIdc_test\fR\|(1).
.IP "\fBdc_snoop\fR" 4
.IX Item "dc_snoop"
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 \fBdc_client\fR, or between \fBdc_client\fR and
\&\fBdc_server\fR). See \fIdc_snoop\fR\|(1).
.SH "APIS"
.IX Header "APIS"
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 \*(L"devel\*(R" package is installed as the libraries, headers, and \s-1API\s0
documentation is often packaged independantly of the user tools.
.Sh "libnal"
.IX Subsection "libnal"
This is the underlying Network Abstraction Library (hence \*(L"\s-1NAL\s0\*(R") 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 \*(L"\-listen\*(R" and \*(L"\-connect\*(R" switches set to
work over either kind of transport.
.PP
libnal defines various object types;
.IP "\s-1NAL_ADDRESS\s0 (see \fINAL_ADDRESS_new\fR\|(2))" 4
.IX Item "NAL_ADDRESS (see NAL_ADDRESS_new)"
The addressing abstraction converts to and from text representations, indicates
whether given addresses are valid for listening on, connecting to, or both.
.IP "\s-1NAL_CONNECTION\s0 (see \fINAL_CONNECTION_new\fR\|(2))" 4
.IX Item "NAL_CONNECTION (see NAL_CONNECTION_new)"
This encapsulates a network connection that can be used for sending and receiving
arbitrary binary data.
.IP "\s-1NAL_LISTENER\s0 (see \fINAL_LISTENER_new\fR\|(2))" 4
.IX Item "NAL_LISTENER (see NAL_LISTENER_new)"
This encapsulates a listening socket that can be used to accept incoming
connection requests on a configured address, creating a \s-1NAL_CONNECTION\s0 wrapper
for each accepted connection.
.IP "\s-1NAL_SELECTOR\s0 (see \fINAL_SELECTOR_new\fR\|(2))" 4
.IX Item "NAL_SELECTOR (see NAL_SELECTOR_new)"
This provides an object that can be prepared with various \s-1NAL_LISTENER\s0 and
\&\s-1NAL_CONNECTION\s0 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 \fIselect\fR\|(2) function.
.IP "\s-1NAL_BUFFER\s0 (see \fINAL_BUFFER_new\fR\|(2))" 4
.IX Item "NAL_BUFFER (see NAL_BUFFER_new)"
This abstraction implements a \s-1FIFO\s0 data array and is used primarily for
representing the read and send parts of a \s-1NAL_CONNECTION\s0 object.
.PP
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 \fINAL_decode_uint32\fR\|(2).
.Sh "libdistcache"
.IX Subsection "libdistcache"
There are two APIs implemented by the \fBlibdistcache\fR library;
.IP "distcache/dc_plug.h" 4
.IX Item "distcache/dc_plug.h"
This header provides the \s-1DC_PLUG\s0 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 \fIlibnal\fR's
\&\s-1NAL_SELECTOR\s0 type. For more information, see \fIDC_PLUG_new\fR\|(2).
.IP "distcache/dc_client.h" 4
.IX Item "distcache/dc_client.h"
This header declares a higher-level (and much simpler) \s-1API\s0 than dc_plug.h, and
is useful in applications that want \s-1API\s0 functions that ``do cache operations''.
The \s-1API\s0 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 \s-1API\s0 used to add distcache support to
applications like Apache, stunnel, etc. For more information, see
\&\fIDC_CTX_new\fR\|(2).
.Sh "libdistcacheserver"
.IX Subsection "libdistcacheserver"
This header declares an \s-1API\s0 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
\&\fIlibdistcache\fR, this \s-1API\s0 is likely to be undergoing some important
restructuring and enhancements. Please consider subscribing to the distcache
mail list and/or monitoring \s-1CVS\s0, 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 \fIDC_SERVER_new\fR\|(2).
.SH "LICENSE"
.IX Header "LICENSE"
The \fIdistcache\fR toolkit, including the \fIlibnal\fR network abstraction library
that comes bundled with it, is distributed under the \s-1LGPL\s0 license (\*(L"Library \s-1GNU\s0
Public License\*(R") and you should have received a copy of this license with this
software and its documents.
.SH "BUGS"
.IX Header "BUGS"
Quite possibly. In particular, portability has not been tested under many
platforms as the current developers have limited \s-1OS\s0 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\fIdc_server\fR\|(1)" 4
.IX Item "dc_server"
Distributed caching server.
.IP "\fIdc_client\fR\|(1)" 4
.IX Item "dc_client"
Distributed caching client proxy
.IP "\fIdc_snoop\fR\|(1)" 4
.IX Item "dc_snoop"
Distcache protocol analyser and debugging tool.
.IP "\fIhttp://www.distcache.org/\fR" 4
.IX Item "http://www.distcache.org/"
Distcache home page.
.SH "AUTHOR"
.IX Header "AUTHOR"
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 \fIgeoff@geoffthorpe.net\fR.
.PP
Home Page: \fIhttp://www.distcache.org\fR