.\" 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_SERVER 1"
.TH DC_SERVER 1 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
dc_server \- Distributed session cache server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdc_server\fR \-listen <address> [options]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdc_server\fR runs a cache server and starts listening on a configurable network
address for connections. Incoming connections are expected to communicate using
the \fIdistcache\fR\|(8) protocol, and would typically be instances of
\&\fIdc_client\fR\|(1) running on other machines.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-daemon\fR" 4
.IX Item "-daemon"
After initialising, \fBdc_server\fR will detach from the parent process, close
standard file\-descriptors, etc. If this flag is not set, \fBdc_server\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_server\fR to the given
user \s-1ID\s0 after initialising its listening socket. On most systems, this can only
work if \fBdc_server\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 create. 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_server\fR should listen for incoming connections.
The syntax is that defined by the \fIlibnal\fR \s-1API\s0. Some examples follow;
.Sp
.Vb 2
\&    # Listen on port 9001 for all TCP/IPv4 interfaces
\&    dc_server -listen IP:9001
.Ve
.Sp
.Vb 3
\&    # Listen on port 9001 on a specific TCP/IPv4 interface
\&    dc_server -listen IP:192.168.0.1:9001
\&    dc_server -listen IP:cacheserver.localnet:9001
.Ve
.Sp
.Vb 2
\&    # Listen on a unix domain socket in the /tmp directory
\&    dc_server -listen UNIX:/tmp/cacheserver
.Ve
.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_server 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 \fIdcclient\fR
group;
.Sp
.Vb 2
\&    # dc_server -listen UNIX:/tmp/cacheserver -user nobody \e
\&          -sockgroup dcclient -sockperms 440
.Ve
.IP "\fB\-sessions\fR num" 4
.IX Item "-sessions num"
Specifies a maximum number of sessions that should be stored in the cache. All
sessions in a cache have an expiry time so that they will, if they have not
been forcibly removed before that time, be expired out of the cache. If it is
desirable to allow long session timeouts under normal situations yet protect
against the session cache growing without limit periods of high\-load, this
limit can provide the required balance. If the session cache reaches this
limit, it will automatically rotate out those sessions in the cache that are
due to expire soonest. It is not (yet) possible to have no limit at all, though
a future version should support this by allowing the user to specify zero.
.Sp
The default value for this flag is 512.
.IP "\fB\-progress\fR num" 4
.IX Item "-progress num"
\&\fBdc_server\fR will, by default, log a line of output to stdout whenever there is
cache activity, but will make sure to do so no more often than once a second.
If \fB\-progress\fR is specified, this will take precedence  so that output will be
emitted whenever \fBnum\fR operations have occurred since the last output,
irrespective of how little time has elapsed. The once-a-second logic remains
behind this, so that if less than \fBnum\fR operations has taken place but at
least one second has passed, output will still be logged. This flag has no
effect if \fB\-daemon\fR is used.
.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_server\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_server\fR instance, use something like
(where \fBpidfile.pid\fR is whatever \fBpath\fR was);
.Sp
.Vb 1
\&    kill `cat pidfile.pid`
.Ve
.IP "\fB\-killable\fR" 4
.IX Item "-killable"
The default behaviour of \fBdc_server\fR is to silently ignore \s-1SIGUSR1\s0 and \s-1SIGUSR2\s0
signals, but with this switch enabled it will handle these signals and close
down cleanly (mainly useful for developers as an alternative to \s-1SIGKILL\s0 which
is less useful for debugging memory leaks).
.IP "\fB\-h\fR, \fB\-help\fR, \fB\-?\fR" 4
.IX Item "-h, -help, -?"
Any of these flags will cause \fBdc_server\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_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 "\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