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