Debian Codegraph @

upstream/debian-unstable/man7/nfsd.7

raw
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