Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DISTCACHE(8)			   distcache			  DISTCACHE(8)

NAME
       distcache - Distributed session caching

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.

       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 ad-
       vantages	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 ad-
       dress. 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 poten-
       tial bottleneck,	because	there is no obvious way	to scale the architec-
       ture 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	bal-
       ance 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 con-
       nection 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.

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

       dc_client
	   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 connec-
	   tion. See dc_client(1).

       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 dc_server or	against	a
	   dc_client proxy. See	dc_test(1).

       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 dc_client, or
	   between dc_client and dc_server). See dc_snoop(1).

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 "devel" package is in-
       stalled as the libraries, headers, and API documentation	is often pack-
       aged independantly of the user tools.

       libnal

       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	representa-
	   tions, indicates whether given addresses are	valid for listening
	   on, connecting to, or both.

       NAL_CONNECTION (see NAL_CONNECTION_new(2))
	   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 in-
	   coming 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_LIS-
	   TENER and NAL_CONNECTION objects, and can then manage the non-
	   blocking I/O	"event loop".  Prior to	blocking, this object gives
	   all the listeners and connections it	contains a chance to set state
	   to control their notification criteria. After blocking, this	object
	   can provide a chance	to each	object that has	received I/O activity
	   a chance to post-process. There are implementations for this	object
	   based on the	select(2) and poll(2) functions	that interoperate with
	   the file-descriptor listener	and connection types. Work is underway
	   to bring other I/O models to	this infrastructure, such as epoll(4)
	   and proprietary TOE (TCP Offload Engine) devices.

       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	ob-
	   ject.

       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).

       libdistcache

       There are two APIs implemented by the libdistcache library;

       distcache/dc_plug.h
	   This	header provides	the DC_PLUG abstraction. This encapsulates a
	   connection and implements the distcache protocol and	various	func-
	   tions for manipulating the reading and writing of distcache mes-
	   sages (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).

       distcache/dc_client.h
	   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 re-
	   turn	once the full request/response cycle is	complete or an error
	   has occured.	This is	the API	used to	add distcache support to ap-
	   plications like Apache, stunnel, etc. For more information, see
	   DC_CTX_new(2).

       libdistcacheserver

       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 im-
       portant restructuring and enhancements. Please consider subscribing to
       the distcache mail list and/or monitoring CVS, this gives you an	oppor-
       tunity to influence ongoing development and be less surprised at
       changes the turn	up in future versions. For more	information, see
       DC_SERVER_new(2).

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

BUGS
       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.

SEE ALSO
       dc_server(1)
	   Distributed caching server.

       dc_client(1)
	   Distributed caching client proxy

       dc_snoop(1)
	   Distcache protocol analyser and debugging tool.

       http://www.distcache.org/
	   Distcache home page.

AUTHOR
       This toolkit was	designed and implemented by Geoff Thorpe for Crypto-
       graphic Appliances Incorporated.	Since the project was released into
       open source, it has a home page and a project environment where devel-
       opment, 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.5.1				  2004.10.19			  DISTCACHE(8)

NAME | DESCRIPTION | TOOLS | APIS | LICENSE | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=distcache&sektion=8&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help