path: root/utils/nfsdcld/nfsdcld.man

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "NFSDCLD 8"
.TH NFSDCLD 8 "2011-12-21" "" ""
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nfsdcld \- NFSv4 Client Tracking Daemon
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
nfsdcld [\-d] [\-F] [\-p path] [\-s stable storage dir]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
nfsdcld is the NFSv4 client tracking daemon. It is not necessary to run
this daemon on machines that are not acting as NFSv4 servers.
.PP
When a network partition is combined with a server reboot, there are
edge conditions that can cause the server to grant lock reclaims when
other clients have taken conflicting locks in the interim. A more detailed
explanation of this issue is described in \s-1RFC\s0 3530, section 8.6.3.
.PP
In order to prevent these problems, the server must track a small amount
of per-client information on stable storage. This daemon provides the
userspace piece of that functionality.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-d\fR, \fB\-\-debug\fR" 4
.IX Item "-d, --debug"
Enable debug level logging.
.IP "\fB\-F\fR, \fB\-\-foreground\fR" 4
.IX Item "-F, --foreground"
Runs the daemon in the foreground and prints all output to stderr
.IP "\fB\-p\fR \fIpath\fR, \fB\-\-pipefsdir\fR=\fIpath\fR" 4
.IX Item "-p path, --pipefsdir=path"
Location of the rpc_pipefs filesystem. The default value is
\&\fI/var/lib/nfs/rpc_pipefs\fR.
.IP "\fB\-s\fR \fIstorage_dir\fR, \fB\-\-storagedir\fR=\fIstorage_dir\fR" 4
.IX Item "-s storagedir, --storagedir=storage_dir"
Directory where stable storage information should be kept. The default
value is \fI/var/lib/nfs/nfsdcld\fR.
.SH "CONFIGURATION FILE"
.IX Header "CONFIGURATION FILE"
The following values are recognized in the \fB[nfsdcld]\fR section
of the \fI/etc/nfs.conf\fR configuration file:
.IP "\fBstoragedir\fR" 4
.IX Item "storagedir"
Equivalent to \fB\-s\fR/\fB\-\-storagedir\fR.
.IP "\fBdebug\fR" 4
.IX Item "debug"
Setting "debug = 1" is equivalent to \fB\-d\fR/\fB\-\-debug\fR.
.LP
In addition, the following value is recognized from the \fB[general]\fR section:
.IP "\fBpipefs\-directory\fR" 4
.IX Item "pipefs-directory"
Equivalent to \fB\-p\fR/\fB\-\-pipefsdir\fR.
.SH "NOTES"
.IX Header "NOTES"
The Linux kernel NFSv4 server has historically tracked this information
on stable storage by manipulating information on the filesystem
directly, in the directory to which \fI/proc/fs/nfsd/nfsv4recoverydir\fR
points.
.PP
This changed with the original introduction of \fBnfsdcld\fR upcall in kernel version 3.4,
which was later deprecated in favor of the \fBnfsdcltrack\fR(8) usermodehelper
program, support for which was added in kernel version 3.8.  However, since the
usermodehelper upcall does not work in containers, support for a new version of
the \fBnfsdcld\fR upcall was added in kernel version 5.2.
.PP
This daemon requires a kernel that supports the \fBnfsdcld\fR upcall. On older kernels, if
the legacy client name tracking code was in use, then the kernel would not create the
pipe that \fBnfsdcld\fR uses to talk to the kernel.  On newer kernels, nfsd attempts to
initialize client tracking in the following order:  First, the \fBnfsdcld\fR upcall.  Second,
the \fBnfsdcltrack\fR usermodehelper upcall.  Finally, the legacy client tracking.
.PP
This daemon should be run as root, as the pipe that it uses to communicate
with the kernel is only accessable by root. The daemon however does drop all
superuser capabilities after starting. Because of this, the \fIstoragedir\fR
should be owned by root, and be readable and writable by owner.
.PP
The daemon now supports different upcall versions to allow the kernel to pass additional
data to be stored in the on-disk database.  The kernel will query the supported upcall
version from \fBnfsdcld\fR during client tracking initialization.  A restart of \fBnfsd\fR is
not necessary after upgrading \fBnfsdcld\fR, however \fBnfsd\fR will not use a later upcall
version until restart.  A restart of \fBnfsd is necessary\fR after downgrading \fBnfsdcld\fR,
to ensure that \fBnfsd\fR does not use an upcall version that \fBnfsdcld\fR does not support.
Additionally, a downgrade of \fBnfsdcld\fR requires the schema of the on-disk database to
be downgraded as well.  That can be accomplished using the \fBnfsdclddb\fR(8) utility.
.SH FILES
.TP
.B /var/lib/nfs/nfsdcld/main.sqlite
.SH SEE ALSO
.BR nfsdcltrack "(8), " nfsdclddb (8)
.SH "AUTHORS"
.IX Header "AUTHORS"
The nfsdcld daemon was developed by Jeff Layton <jlayton@redhat.com>
with modifications from Scott Mayhew <smayhew@redhat.com>.