.\" 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 "DC_CLIENT 1"
.TH DC_CLIENT 1 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
dc_client \- Distributed session cache client proxy
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdc_client\fR \-server <address> [options]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdc_client\fR runs a client proxy to provide access to a remote cache server
(typically over TCP/IPv4) by providing a local service (typically over unix
domain sockets). It starts listening on a configurable network address for
connections and establishes a persistent connection to an instance of
\&\fBdc_server\fR for proxying cache operations to. Incoming connections are
expected to communicate using the \fIdistcache\fR\|(8) protocol, and would typically
be applications using one of the distcache APIs in \fIlibdistcache\fR to
encapsulate these communications.
.PP
The common use of \fBdc_client\fR is to run as a local agent on each host machine
that requires use of the distributed cache, as the listening address should
probably use unix domain sockets which are better suited to frequent (and
temporary) connections being used for individual cache operations. Likewise,
the connection \fBdc_client\fR makes to the cache server (\fBdc_server\fR) for
proxying cache operations is typically over a genuine network to remote
machine, using TCP/IPv4.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-daemon\fR" 4
.IX Item "-daemon"
After initialising, \fBdc_client\fR will detach from the parent process, close
standard file\-descriptors, etc. If this flag is not set, \fBdc_client\fR will run in
the foreground. It is recommended to use this flag in combination with the
\&\fIpidfile\fR flag to simplify stopping and restarting services.
.IP "\fB\-user\fR user" 4
.IX Item "-user user"
This switch will attempt to change user privileges of \fBdc_client\fR to the given
user \s-1ID\s0 after initialising its listening socket. On most systems, this can only
work if \fBdc_client\fR is started as the \fIroot\fR user. It is important to note
that the change of user \s-1ID\s0 occurs after the listening socket is created but
before any attempts are made to connect to distcache servers. This ensures that
the listening socket is created with the most restrictive permissions, and that
the ability to connect to servers at run-time corresponds to the given user
(rather than having unusual root permissions on startup).
.IP "\fB\-listen\fR address" 4
.IX Item "-listen address"
Configures the address on which \fBdc_client\fR should listen for incoming
connections.  The syntax is that defined by the \fIlibnal\fR \s-1API\s0. Though this can
listen on any supported network transport, \fBdc_client\fR should be expected to
receive a lot of short-lived (and frequest) connections, so unix domain sockets
are generally preferable to TCP/IPv4. Eg.
.Sp
.Vb 2
\&    # Listen on a unix domain socket in the /tmp directory
\&    dc_client -listen UNIX:/tmp/cacheclient
.Ve
.Sp
The default value for this flag is: UNIX:/tmp/scache
.IP "\fB\-sockowner\fR user" 4
.IX Item "-sockowner user"
This switch is only useful when listening (see \fB\-listen\fR) on unix domain sockets.
It will attempt to change ownership of the created socket file.
.IP "\fB\-sockgroup\fR group" 4
.IX Item "-sockgroup group"
This switch is only useful when listening (see \fB\-listen\fR) on unix domain sockets.
It will attempt to change group ownership of the created socket file.
.IP "\fB\-sockperms\fR perms" 4
.IX Item "-sockperms perms"
This switch is only useful when listening (see \fB\-listen\fR) on unix domain sockets.
It will attempt to change file permissions for the created socket file, and is
specified in the standard octal notation used for unix file permissions. Eg. to
start dc_client to run as the \fInobody\fR user, listening on a unix domain socket
that can only be connected to by the \fIroot\fR user or members of the \fIssl\fR
group;
.Sp
.Vb 2
\&    # dc_client -listen UNIX:/tmp/cacheclient -user nobody \e
\&          -sockgroup ssl -sockperms 440
.Ve
.IP "\fB\-server\fR address" 4
.IX Item "-server address"
.PD 0
.IP "\fB\-connect\fR address" 4
.IX Item "-connect address"
.PD
These flags are identical, and specify the address of the cache server
\&\fBdc_client\fR should connect to. Cache operations requested by clients of
\&\fBdc_client\fR (using short-lived local connections to the service address
specified by \fB\-listen\fR) are multiplexed to/from the cache server over this
persistent connection. The syntax is that defined by the \fIlibnal\fR \s-1API\s0 and
would typically be over TCP/IPv4, particularly if the cache server is running
on a remote machine. Eg.
.Sp
.Vb 3
\&    # Connect to a remote cache server listening on port 9001
\&    dc_client -listen UNIX:/tmp/cacheclient \e
\&              -server IP:cacheserver.localnet:9001
.Ve
.IP "\fB\-retry\fR msecs" 4
.IX Item "-retry msecs"
Distcache is designed to be as fault-tolerant as possible, and part of this
approach is to have \fBdc_client\fR manage the possible disappearance and
subsequent reappearance of the remote instance of \fBdc_server\fR it proxies to.
In actuality, this could happen for a variety of reasons including the cache
server being restarted, or a network error at any point in between the two
programs. During any period in which \fBdc_client\fR has lost communications with
the cache server, any/all local connections and corresponding cache operation
requests will be responded to directly by \fBdc_client\fR itself. The consequence
is that cache operations return as failures during this time, so the
application requesting the operations must make do without (eg. in \s-1SSL/TLS\s0
session caching, this means that attempts to resume \s-1SSL/TLS\s0 sessions fail and
so full handshakes are required).
.Sp
The default behaviour of \fBdc_client\fR when losing communications with the
instance of \fBdc_server\fR (as specified by \fB\-server\fR or \fB\-connect\fR) is to try
to reestablish communications every 5 seconds. This flag allows the retry
period to be configured to any number of milliseconds. Note: confusing
milliseconds with seconds can cause emotional disturbance and should be avoided
at all costs.
.IP "\fB\-idle\fR msecs" 4
.IX Item "-idle msecs"
Normal behaviour with \fBdc_client\fR is to have its clients (applications using
\&\fB\f(BIdistcache\fB\|(8)\fR APIs for communication) use temporary connections for each
cache operation. However, there are modes of operation in those APIs that allow
persistent connections to be used together with various associated options.
This is especially important for any platforms that (for whatever reason) can't
use unix domain sockets and don't want to bloat file-descriptor tables with
IPv4 sockets sitting in \s-1TIME_WAIT\s0 state. For this reason, as well as resilience
against client applications that hang, it useful to configure \fBdc_client\fR to
automatically drop client connections that have been idle for some configurable
period of time.
.Sp
This flag specifies the period of idle time after which client connections will
be dropped, and is in units of milliseconds and \fBnot\fR seconds. The default
value is zero, and this means that client connections are never intentionally
dropped.
.Sp
Note, provided client applications are appropriately configured they need not
necessarily be vulnerable to race conditions when \fBdc_client\fR configures this
flag. The \fB\f(BIdistcache\fB\|(8)\fR \fI\s-1DC_CTX\s0\fR \s-1API\s0 provides additional persistence options
such as \fIfork\fR\|(2)\-checking and resistance against idle timeouts. Ie. if a request
is commenced on a client connection that is in the process of being timed-out
by \fBdc_client\fR, the \fI\s-1DC_CTX\s0\fR will allow one retry with an immediate
re-connection before considering the operation to have failed.
.IP "\fB\-pidfile\fR path" 4
.IX Item "-pidfile path"
This is a standard flag for many programs, and most useful in combination with
\&\fB\-daemon\fR. When \fB\-pidfile\fR is specified \fBdc_client\fR will write its process
\&\s-1ID\s0 to a file at the specified path upon successful initialisation. To use this
path file to later kill the running \fBdc_client\fR instance, use something like
(where \fBpidfile.pid\fR is whatever \fBpath\fR was);
.Sp
.Vb 1
\&    kill `cat pidfile.pid`
.Ve
.IP "\fB\-h\fR, \fB\-help\fR, \fB\-?\fR" 4
.IX Item "-h, -help, -?"
Any of these flags will cause \fBdc_client\fR to display a brief usage summary to
the console and exit cleanly. Any other flags are ignored.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\fIdc_server\fR\|(1)" 4
.IX Item "dc_server"
Distributed cache server.
.IP "\fIdc_snoop\fR\|(1)" 4
.IX Item "dc_snoop"
Distcache protocol analyser and debugging tool.
.IP "\fIdistcache\fR\|(8)" 4
.IX Item "distcache"
Overview of the distcache architecture.
.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