| 1 |
.ie \nF \{\ |
| 2 |
. de IX |
| 3 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 4 |
.. |
| 5 |
. nr % 0 |
| 6 |
. rr F |
| 7 |
.\} |
| 8 |
.el \{\ |
| 9 |
. de IX |
| 10 |
.. |
| 11 |
.\} |
| 12 |
.IX Title "NFSDCLTRACK 8" |
| 13 |
.TH NFSDCLTRACK 8 "2012-10-24" "" "" |
| 14 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 15 |
.\" way too many mistakes in technical documents. |
| 16 |
.if n .ad l |
| 17 |
.nh |
| 18 |
.SH "NAME" |
| 19 |
nfsdcltrack \- NFSv4 Client Tracking Callout Program |
| 20 |
.SH "SYNOPSIS" |
| 21 |
.IX Header "SYNOPSIS" |
| 22 |
nfsdcltrack [\-d] [\-f] [\-s stable storage dir] <command> <args...> |
| 23 |
.SH "DESCRIPTION" |
| 24 |
.IX Header "DESCRIPTION" |
| 25 |
nfsdcltrack is the NFSv4 client tracking callout program. It is not necessary |
| 26 |
to install this program on machines that are not acting as NFSv4 servers. |
| 27 |
.PP |
| 28 |
When a network partition is combined with a server reboot, there are |
| 29 |
edge conditions that can cause the server to grant lock reclaims when |
| 30 |
other clients have taken conflicting locks in the interim. A more detailed |
| 31 |
explanation of this issue is described in \s-1RFC\s0 3530, section 8.6.3 |
| 32 |
and in \s-1RFC\s0 5661, section 8.4.3. |
| 33 |
.PP |
| 34 |
In order to prevent these problems, the server must track a small amount |
| 35 |
of per-client information on stable storage. This program provides the |
| 36 |
userspace piece of that functionality. When the kernel needs to manipulate |
| 37 |
the database that stores this info, it will execute this program to handle |
| 38 |
it. |
| 39 |
.SH "OPTIONS" |
| 40 |
.IX Header "OPTIONS" |
| 41 |
.IP "\fB\-d\fR, \fB\-\-debug\fR" 4 |
| 42 |
.IX Item "-d, --debug" |
| 43 |
Enable debug level logging. |
| 44 |
.IP "\fB\-f\fR, \fB\-\-foreground\fR" 4 |
| 45 |
.IX Item "-f, --foreground" |
| 46 |
Log to stderr instead of syslog. |
| 47 |
.IP "\fB\-s\fR \fIstoragedir\fR, \fB\-\-storagedir\fR=\fIstorage_dir\fR" 4 |
| 48 |
.IX Item "-s storagedir, --storagedir=storage_dir" |
| 49 |
Directory where stable storage information should be kept. The default |
| 50 |
value is \fI/var/lib/nfs/nfsdcltrack\fR. |
| 51 |
.SH "COMMANDS" |
| 52 |
.IX Header "COMMANDS" |
| 53 |
nfsdcltrack requires a command for each invocation. Supported commands |
| 54 |
are: |
| 55 |
.IP "\fBinit\fR" 4 |
| 56 |
.IX Item "init" |
| 57 |
Initialize the database. This command requires no argument. |
| 58 |
.IP "\fBcreate\fR" 4 |
| 59 |
.IX Item "create" |
| 60 |
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. |
| 61 |
.IP "\fBremove\fR" 4 |
| 62 |
.IX Item "remove" |
| 63 |
Remove a client record from the database. This command requires a hex-encoded nfs_client_id4 as an argument. |
| 64 |
.IP "\fBcheck\fR" 4 |
| 65 |
.IX Item "check" |
| 66 |
Check to see if a nfs_client_id4 is allowed to reclaim. This command requires a hex-encoded nfs_client_id4 as an argument. |
| 67 |
.IP "\fBgracedone\fR" 4 |
| 68 |
.IX Item "gracedone" |
| 69 |
Remove any unreclaimed client records from the database. This command requires a epoch boot time as an argument. |
| 70 |
.SH "EXTERNAL CONFIGURATION" |
| 71 |
The directory for stable storage information can be set via the file |
| 72 |
.B /etc/nfs.conf |
| 73 |
by setting the |
| 74 |
.B storagedir |
| 75 |
value in the |
| 76 |
.B nfsdcltrack |
| 77 |
section. For example: |
| 78 |
.in +5 |
| 79 |
[nfsdcltrack] |
| 80 |
.br |
| 81 |
storagedir = /shared/nfs/nfsdcltrack |
| 82 |
.in -5 |
| 83 |
Debugging to syslog can also be enabled by setting "debug = 1" in this file. |
| 84 |
.SH "LEGACY TRANSITION MECHANISM" |
| 85 |
.IX Header "LEGACY TRANSITION MECHANISM" |
| 86 |
The Linux kernel NFSv4 server has historically tracked this information |
| 87 |
on stable storage by manipulating information on the filesystem |
| 88 |
directly, in the directory to which \fI/proc/fs/nfsd/nfsv4recoverydir\fR |
| 89 |
points. If the kernel passes the correct information, then nfsdcltrack |
| 90 |
can use it to allow a seamless transition from the old client tracking |
| 91 |
scheme to the new one. |
| 92 |
.PP |
| 93 |
On a \fBcheck\fR operation, if there is no record of the client in the |
| 94 |
database, nfsdcltrack will look to see if the \fB\s-1NFSDCLTRACK_LEGACY_RECDIR\s0\fR |
| 95 |
environment variable is set. If it is, then it will fetch that value and |
| 96 |
see if a directory exists by that name. If it does, then the check |
| 97 |
operation will succeed and the directory will be removed. |
| 98 |
.PP |
| 99 |
On a \fBgracedone\fR operation, nfsdcltrack will look to see if the |
| 100 |
\&\fB\s-1NFSDCLTRACK_LEGACY_TOPDIR\s0\fR environment variable is set. If it is, then |
| 101 |
it will attempt to clean out that directory prior to exiting. |
| 102 |
.PP |
| 103 |
Note that this transition is one-way. If the machine subsequently reboots |
| 104 |
back into an older kernel that does not support the nfsdcltrack upcall |
| 105 |
then the clients will not be able to recover their state. |
| 106 |
.SH "NOTES" |
| 107 |
.IX Header "NOTES" |
| 108 |
This program requires a kernel that supports the nfsdcltrack usermodehelper |
| 109 |
upcall. This support was first added to mainline kernels in 3.8. |
| 110 |
.SH "AUTHORS" |
| 111 |
.IX Header "AUTHORS" |
| 112 |
nfsdcltrack was developed by Jeff Layton <[email protected]>. |