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 al- lows SSL/TLS servers (eg. a secure Apache web server providing HTTPS sup- port) 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. Oth- ers, 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 masquerad- ing 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 re- quests 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 vir- tual 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 connection. 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 cor- rectness of an installation as well as benchmarking. Can be used di- rectly 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 dist- cache. To view more details, consult the section 2 man pages these sum- maries 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 li- braries, headers, and API documentation is often packaged 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 representations, indicates whether given addresses are valid for listening on, connect- ing 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 incom- ing connection requests on a configured address, creating a NAL_CONNEC- TION 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 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 no- tification 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 object. There are also some helper functions to assist in serialising data, partic- ularly with respect to putting integral data into network byte order (al- lowing 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 con- nection 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 implementa- tions 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 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). 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 important restruc- turing and enhancements. Please consider subscribing to the distcache mail list and/or monitoring CVS, this gives you an opportunity to influence on- going 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 ("Library 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 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@ge- offthorpe.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://man.freebsd.org/cgi/man.cgi?query=distcache&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>