utils/nfsdcltrack/nfsdcltrack.man

   1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "NFSDCLTRACK 8"
 127 .TH NFSDCLTRACK 8 "2012-10-24" "" ""
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 nfsdcltrack \- NFSv4 Client Tracking Callout Program
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 nfsdcltrack [\-d] [\-f] [\-s stable storage dir] <command> <args...>
 137 .SH "DESCRIPTION"
 138 .IX Header "DESCRIPTION"
 139 nfsdcltack is the NFSv4 client tracking callout program. It is not necessary
 140 to install this daemon on machines that are not acting as NFSv4 servers.
 141 .PP
 142 When a network partition is combined with a server reboot, there are
 143 edge conditions that can cause the server to grant lock reclaims when
 144 other clients have taken conflicting locks in the interim. A more detailed
 145 explanation of this issue is described in \s-1RFC\s0 3530, section 8.6.3.
 146 .PP
 147 In order to prevent these problems, the server must track a small amount
 148 of per-client information on stable storage. This program provides the
 149 userspace piece of that functionality. When the kernel needs to manipulate
 150 the database that stores this info, it will execute this program to handle
 151 it.
 152 .SH "OPTIONS"
 153 .IX Header "OPTIONS"
 154 .IP "\fB\-d\fR, \fB\-\-debug\fR" 4
 155 .IX Item "-d, --debug"
 156 Enable debug level logging.
 157 .IP "\fB\-f\fR, \fB\-\-foreground\fR" 4
 158 .IX Item "-f, --foreground"
 159 Log to stderr instead of syslog.
 160 .IP "\fB\-s\fR \fIstoragedir\fR, \fB\-\-storagedir\fR=\fIstorage_dir\fR" 4
 161 .IX Item "-s storagedir, --storagedir=storage_dir"
 162 Directory where stable storage information should be kept. The default
 163 value is \fI/var/lib/nfs/nfsdcltrack\fR.
 164 .SH "COMMANDS"
 165 .IX Header "COMMANDS"
 166 nfsdcltrack requires a command for each invocation. Supported commands
 167 are:
 168 .IP "\fBinit\fR" 4
 169 .IX Item "init"
 170 Initialize the database. This command requires no argument.
 171 .IP "\fBcreate\fR" 4
 172 .IX Item "create"
 173 Create a new client record (or update the timestamp on an existing one). This command requires a hex-encoded nfs_client_id4 as an argument.
 174 .IP "\fBremove\fR" 4
 175 .IX Item "remove"
 176 Remove a client record from the database. This command requires a hex-encoded nfs_client_id4 as an argument.
 177 .IP "\fBcheck\fR" 4
 178 .IX Item "check"
 179 Check to see if a nfs_client_id4 is allowed to reclaim. This command requires a hex-encoded nfs_client_id4 as an argument.
 180 .IP "\fBgracedone\fR" 4
 181 .IX Item "gracedone"
 182 Remove any unreclaimed client records from the database. This command requires a epoch boot time as an argument.
 183 .SH "LEGACY TRANSITION MECHANISM"
 184 .IX Header "LEGACY TRANSITION MECHANISM"
 185 The Linux kernel NFSv4 server has historically tracked this information
 186 on stable storage by manipulating information on the filesystem
 187 directly, in the directory to which \fI/proc/fs/nfsd/nfsv4recoverydir\fR
 188 points. If the kernel passes the correct information, then nfsdcltrack
 189 can use it to allow a seamless transition from the old client tracking
 190 scheme to the new one.
 191 .PP
 192 On a \fBcheck\fR operation, if there is no record of the client in the
 193 database, nfsdcltrack will look to see if the \fB\s-1NFSDCLTRACK_LEGACY_RECDIR\s0\fR
 194 environment variable is set. If it is, then it will fetch that value and
 195 see if a directory exists by that name. If it does, then the check
 196 operation will succeed and the directory will be removed.
 197 .PP
 198 On a \fBgracedone\fR operation, nfsdcltrack will look to see if the
 199 \&\fB\s-1NFSDCLTRACK_LEGACY_TOPDIR\s0\fR environment variable is set. If it is, then
 200 it will attempt to clean out that directory prior to exiting.
 201 .PP
 202 Note that this transition is one-way. If the machine subsequently reboots
 203 back into an older kernel that does not support the nfsdcltrack upcall
 204 then the clients will not be able to recover their state.
 205 .SH "NOTES"
 206 .IX Header "NOTES"
 207 This program requires a kernel that supports the nfsdcltrack usermodehelper
 208 upcall. This support was first added to mainline kernels in 3.8.
 209 .SH "AUTHORS"
 210 .IX Header "AUTHORS"
 211 nfsdcltrack was developed by Jeff Layton <jlayton@redhat.com>.