| 1 |
.\" |
| 2 |
.\" nfsd(7) - The nfsd filesystem |
| 3 |
.\" |
| 4 |
.\" Copyright (C) 2003 Neil Brown <[email protected]> |
| 5 |
.\" Licensed for public use under the terms of the FSF |
| 6 |
.\" General Public License (GPL) version 2. |
| 7 |
.TH nfsd 7 "3 July 2003" |
| 8 |
.SH NAME |
| 9 |
nfsd \- special filesystem for controlling Linux NFS server |
| 10 |
.SH SYNPOSIS |
| 11 |
.B "mount -t nfsd nfsd /proc/fs/nfsd" |
| 12 |
.SH DESCRIPTION |
| 13 |
The |
| 14 |
.B nfsd |
| 15 |
filesystem is a special filesystem which provides access to the Linux |
| 16 |
NFS server. Writing to files in this filesystem can affect the server. |
| 17 |
Reading from them can provide information about the server. |
| 18 |
.P |
| 19 |
As well as this filesystem, there are a collection of files in the |
| 20 |
.B procfs |
| 21 |
filesystem (normally mounted at |
| 22 |
.BR /proc ) |
| 23 |
which are used to control the NFS server. |
| 24 |
This manual page describes all of these files. |
| 25 |
.P |
| 26 |
The |
| 27 |
.I exportfs |
| 28 |
and |
| 29 |
.I mountd |
| 30 |
programs (part of the nfs-utils package) expect to find this |
| 31 |
filesystem mounted at |
| 32 |
.B /proc/fs/nfsd |
| 33 |
or |
| 34 |
.BR /proc/fs/nfs . |
| 35 |
.SH DETAILS |
| 36 |
Files in the |
| 37 |
.B nfsd |
| 38 |
filesystem include: |
| 39 |
.TP |
| 40 |
.B exports |
| 41 |
This file contains a list of filesystems that are currently exported |
| 42 |
and clients that each filesystem is exported to, together with a list |
| 43 |
of export options for that client/filesystem pair. This is similar |
| 44 |
to the |
| 45 |
.B /proc/fs/nfs/exports |
| 46 |
file in 2.4. |
| 47 |
One difference is that a client doesn't necessarily correspond to just |
| 48 |
one host. It can respond to a large collection of hosts that are |
| 49 |
being treated identically. |
| 50 |
|
| 51 |
Each line of the file contains a path name, a client name, and a |
| 52 |
number of options in parentheses. Any space, tab, newline or |
| 53 |
back-slash character in the path name or client name will be replaced |
| 54 |
by a backslash followed by the octal ASCII code for that character. |
| 55 |
|
| 56 |
.TP |
| 57 |
.B threads |
| 58 |
This file represents the number of |
| 59 |
.B nfsd |
| 60 |
thread currently running. Reading it will show the number of |
| 61 |
threads. Writing an ASCII decimal number will cause the number of |
| 62 |
threads to be changed (increased or decreased as necessary) to achieve |
| 63 |
that number. |
| 64 |
|
| 65 |
.TP |
| 66 |
.B filehandle |
| 67 |
This is a somewhat unusual file in that what is read from it depends |
| 68 |
on what was just written to it. It provides a transactional interface |
| 69 |
where a program can open the file, write a request, and read a |
| 70 |
response. If two separate programs open, write, and read at the same |
| 71 |
time, their requests will not be mixed up. |
| 72 |
|
| 73 |
The request written to |
| 74 |
.B filehandle |
| 75 |
should be a client name, a path name, and a number of bytes. This |
| 76 |
should be followed by a newline, with white-space separating the |
| 77 |
fields, and octal quoting of special characters. |
| 78 |
|
| 79 |
On writing this, the program will be able to read back a filehandle |
| 80 |
for that path as exported to the given client. The filehandle's length |
| 81 |
will be at most the number of bytes given. |
| 82 |
|
| 83 |
The filehandle will be represented in hex with a leading '\ex'. |
| 84 |
|
| 85 |
.TP |
| 86 |
.B clients/ |
| 87 |
This directory contains a subdirectory for each NFSv4 client. Each file |
| 88 |
under that subdirectory gives some details about the client in YAML |
| 89 |
format. In addition, writing "expire\\n" to the |
| 90 |
.B ctl |
| 91 |
file will force the server to immediately revoke all state held by that |
| 92 |
client. |
| 93 |
|
| 94 |
.PP |
| 95 |
The directory |
| 96 |
.B /proc/net/rpc |
| 97 |
in the |
| 98 |
.B procfs |
| 99 |
filesystem contains a number of files and directories. |
| 100 |
The files contain statistics that can be display using the |
| 101 |
.I nfsstat |
| 102 |
program. |
| 103 |
The directories contain information about various caches that the NFS |
| 104 |
server maintains to keep track of access permissions that different |
| 105 |
clients have for different filesystems. |
| 106 |
The caches are: |
| 107 |
|
| 108 |
.TP |
| 109 |
.B auth.unix.ip |
| 110 |
This cache contains a mapping from IP address to the name of the |
| 111 |
authentication domain that the ipaddress should be treated as part of. |
| 112 |
|
| 113 |
.TP |
| 114 |
.B nfsd.export |
| 115 |
This cache contains a mapping from directory and domain to export |
| 116 |
options. |
| 117 |
|
| 118 |
.TP |
| 119 |
.B nfsd.fh |
| 120 |
This cache contains a mapping from domain and a filesystem identifier |
| 121 |
to a directory. The filesystem identifier is stored in the |
| 122 |
filehandles and consists of a number indicating the type of identifier |
| 123 |
and a number of hex bytes indicating the content of the identifier. |
| 124 |
|
| 125 |
.PP |
| 126 |
Each directory representing a cache can hold from 1 to 3 files. They |
| 127 |
are: |
| 128 |
.TP |
| 129 |
.B flush |
| 130 |
When a number of seconds since epoch (1 Jan 1970) is written to this |
| 131 |
file, all entries in the cache that were last updated before that file |
| 132 |
become invalidated and will be flushed out. Writing a time in the |
| 133 |
future (in seconds since epoch) will flush |
| 134 |
everything. This is the only file that will always be present. |
| 135 |
|
| 136 |
.TP |
| 137 |
.B content |
| 138 |
This file, if present, contains a textual representation of ever entry |
| 139 |
in the cache, one per line. If an entry is still in the cache |
| 140 |
(because it is actively being used) but has expired or is otherwise |
| 141 |
invalid, it will be presented as a comment (with a leading hash |
| 142 |
character). |
| 143 |
|
| 144 |
.TP |
| 145 |
.B channel |
| 146 |
This file, if present, acts a channel for request from the kernel-based |
| 147 |
nfs server to be passed to a user-space program for handling. |
| 148 |
|
| 149 |
When the kernel needs some information which isn't in the cache, it |
| 150 |
makes a line appear in the |
| 151 |
.B channel |
| 152 |
file giving the key for the information. A user-space program should |
| 153 |
read this, find the answer, and write a line containing the key, an |
| 154 |
expiry time, and the content. |
| 155 |
For example the kernel might make |
| 156 |
.ti +5 |
| 157 |
nfsd 127.0.0.1 |
| 158 |
.br |
| 159 |
appear in the |
| 160 |
.B auth.unix.ip/content |
| 161 |
file. The user-space program might then write |
| 162 |
.ti +5 |
| 163 |
nfsd 127.0.0.1 1057206953 localhost |
| 164 |
.br |
| 165 |
to indicate that 127.0.0.1 should map to localhost, at least for now. |
| 166 |
|
| 167 |
If the program uses select(2) or poll(2) to discover if it can read |
| 168 |
from the |
| 169 |
.B channel |
| 170 |
then it will never see and end-of-file but when all requests have been |
| 171 |
answered, it will block until another request appears. |
| 172 |
|
| 173 |
.PP |
| 174 |
In the |
| 175 |
.B /proc |
| 176 |
filesystem there are 4 files that can be used to enabled extra tracing |
| 177 |
of nfsd and related code. They are: |
| 178 |
.in +5 |
| 179 |
.B /proc/sys/sunrpc/nfs_debug |
| 180 |
.br |
| 181 |
.B /proc/sys/sunrpc/nfsd_debug |
| 182 |
.br |
| 183 |
.B /proc/sys/sunrpc/nlm_debug |
| 184 |
.br |
| 185 |
.B /proc/sys/sunrpc/rpc_debug |
| 186 |
.br |
| 187 |
.in -5 |
| 188 |
They control tracing for the NFS client, the NFS server, the Network |
| 189 |
Lock Manager (lockd) and the underlying RPC layer respectively. |
| 190 |
Decimal numbers can be read from or written to these files. Each |
| 191 |
number represents a bit-pattern where bits that are set cause certain |
| 192 |
classes of tracing to be enabled. Consult the kernel header files to |
| 193 |
find out what number correspond to what tracing. |
| 194 |
|
| 195 |
.SH NOTES |
| 196 |
This file system is only available in Linux 2.6 and later series |
| 197 |
kernels (and in the later parts of the 2.5 development series leading |
| 198 |
up to 2.6). This man page does not apply to 2.4 and earlier. |
| 199 |
.P |
| 200 |
Previously the nfsctl systemcall was used for communication between nfsd |
| 201 |
and user utilities. That systemcall was removed in kernel version 3.1. |
| 202 |
Older nfs-utils versions were able to fall back to nfsctl if necessary; |
| 203 |
that was removed from nfs-utils 1.3.5. |
| 204 |
|
| 205 |
.SH SEE ALSO |
| 206 |
.BR nfsd (8), |
| 207 |
.BR rpc.nfsd (8), |
| 208 |
.BR exports (5), |
| 209 |
.BR nfsstat (8), |
| 210 |
.BR mountd (8) |
| 211 |
.BR exportfs (8). |
| 212 |
|
| 213 |
.SH AUTHOR |
| 214 |
NeilBrown |