1 | .\" |
---|
2 | .\" Must use -- tbl -- with this one |
---|
3 | .\" |
---|
4 | .\" @(#)nfs.rfc.ms 2.2 88/08/05 4.0 RPCSRC |
---|
5 | .de BT |
---|
6 | .if \\n%=1 .tl ''- % -'' |
---|
7 | .. |
---|
8 | .ND |
---|
9 | .\" prevent excess underlining in nroff |
---|
10 | .if n .fp 2 R |
---|
11 | .OH 'Network File System: Version 2 Protocol Specification''Page %' |
---|
12 | .EH 'Page %''Network File System: Version 2 Protocol Specification' |
---|
13 | .if \\n%=1 .bp |
---|
14 | .SH |
---|
15 | \&Network File System: Version 2 Protocol Specification |
---|
16 | .IX NFS "" "" "" PAGE MAJOR |
---|
17 | .IX "Network File System" "" "" "" PAGE MAJOR |
---|
18 | .IX NFS "version-2 protocol specification" |
---|
19 | .IX "Network File System" "version-2 protocol specification" |
---|
20 | .LP |
---|
21 | .NH 0 |
---|
22 | \&Status of this Standard |
---|
23 | .LP |
---|
24 | Note: This document specifies a protocol that Sun Microsystems, Inc., |
---|
25 | and others are using. It specifies it in standard ARPA RFC form. |
---|
26 | .NH 1 |
---|
27 | \&Introduction |
---|
28 | .IX NFS introduction |
---|
29 | .LP |
---|
30 | The Sun Network Filesystem (NFS) protocol provides transparent remote |
---|
31 | access to shared filesystems over local area networks. The NFS |
---|
32 | protocol is designed to be machine, operating system, network architecture, |
---|
33 | and transport protocol independent. This independence is |
---|
34 | achieved through the use of Remote Procedure Call (RPC) primitives |
---|
35 | built on top of an External Data Representation (XDR). Implementations |
---|
36 | exist for a variety of machines, from personal computers to |
---|
37 | supercomputers. |
---|
38 | .LP |
---|
39 | The supporting mount protocol allows the server to hand out remote |
---|
40 | access privileges to a restricted set of clients. It performs the |
---|
41 | operating system-specific functions that allow, for example, to |
---|
42 | attach remote directory trees to some local file system. |
---|
43 | .NH 2 |
---|
44 | \&Remote Procedure Call |
---|
45 | .IX "Remote Procedure Call" |
---|
46 | .LP |
---|
47 | Sun's remote procedure call specification provides a procedure- |
---|
48 | oriented interface to remote services. Each server supplies a |
---|
49 | program that is a set of procedures. NFS is one such "program". |
---|
50 | The combination of host address, program number, and procedure |
---|
51 | number specifies one remote service procedure. RPC does not depend |
---|
52 | on services provided by specific protocols, so it can be used with |
---|
53 | any underlying transport protocol. See the |
---|
54 | .I "Remote Procedure Calls: Protocol Specification" |
---|
55 | chapter of this manual. |
---|
56 | .NH 2 |
---|
57 | \&External Data Representation |
---|
58 | .IX "External Data Representation" |
---|
59 | .LP |
---|
60 | The External Data Representation (XDR) standard provides a common |
---|
61 | way of representing a set of data types over a network. |
---|
62 | The NFS |
---|
63 | Protocol Specification is written using the RPC data description |
---|
64 | language. |
---|
65 | For more information, see the |
---|
66 | .I " External Data Representation Standard: Protocol Specification." |
---|
67 | Sun provides implementations of XDR and |
---|
68 | RPC, but NFS does not require their use. Any software that |
---|
69 | provides equivalent functionality can be used, and if the encoding |
---|
70 | is exactly the same it can interoperate with other implementations |
---|
71 | of NFS. |
---|
72 | .NH 2 |
---|
73 | \&Stateless Servers |
---|
74 | .IX "stateless servers" |
---|
75 | .IX servers stateless |
---|
76 | .LP |
---|
77 | The NFS protocol is stateless. That is, a server does not need to |
---|
78 | maintain any extra state information about any of its clients in |
---|
79 | order to function correctly. Stateless servers have a distinct |
---|
80 | advantage over stateful servers in the event of a failure. With |
---|
81 | stateless servers, a client need only retry a request until the |
---|
82 | server responds; it does not even need to know that the server has |
---|
83 | crashed, or the network temporarily went down. The client of a |
---|
84 | stateful server, on the other hand, needs to either detect a server |
---|
85 | crash and rebuild the server's state when it comes back up, or |
---|
86 | cause client operations to fail. |
---|
87 | .LP |
---|
88 | This may not sound like an important issue, but it affects the |
---|
89 | protocol in some unexpected ways. We feel that it is worth a bit |
---|
90 | of extra complexity in the protocol to be able to write very simple |
---|
91 | servers that do not require fancy crash recovery. |
---|
92 | .LP |
---|
93 | On the other hand, NFS deals with objects such as files and |
---|
94 | directories that inherently have state -- what good would a file be |
---|
95 | if it did not keep its contents intact? The goal is to not |
---|
96 | introduce any extra state in the protocol itself. Another way to |
---|
97 | simplify recovery is by making operations "idempotent" whenever |
---|
98 | possible (so that they can potentially be repeated). |
---|
99 | .NH 1 |
---|
100 | \&NFS Protocol Definition |
---|
101 | .IX NFS "protocol definition" |
---|
102 | .IX NFS protocol |
---|
103 | .LP |
---|
104 | Servers have been known to change over time, and so can the |
---|
105 | protocol that they use. So RPC provides a version number with each |
---|
106 | RPC request. This RFC describes version two of the NFS protocol. |
---|
107 | Even in the second version, there are various obsolete procedures |
---|
108 | and parameters, which will be removed in later versions. An RFC |
---|
109 | for version three of the NFS protocol is currently under |
---|
110 | preparation. |
---|
111 | .NH 2 |
---|
112 | \&File System Model |
---|
113 | .IX filesystem model |
---|
114 | .LP |
---|
115 | NFS assumes a file system that is hierarchical, with directories as |
---|
116 | all but the bottom-level files. Each entry in a directory (file, |
---|
117 | directory, device, etc.) has a string name. Different operating |
---|
118 | systems may have restrictions on the depth of the tree or the names |
---|
119 | used, as well as using different syntax to represent the "pathname", |
---|
120 | which is the concatenation of all the "components" (directory and |
---|
121 | file names) in the name. A "file system" is a tree on a single |
---|
122 | server (usually a single disk or physical partition) with a specified |
---|
123 | "root". Some operating systems provide a "mount" operation to make |
---|
124 | all file systems appear as a single tree, while others maintain a |
---|
125 | "forest" of file systems. Files are unstructured streams of |
---|
126 | uninterpreted bytes. Version 3 of NFS uses a slightly more general |
---|
127 | file system model. |
---|
128 | .LP |
---|
129 | NFS looks up one component of a pathname at a time. It may not be |
---|
130 | obvious why it does not just take the whole pathname, traipse down |
---|
131 | the directories, and return a file handle when it is done. There are |
---|
132 | several good reasons not to do this. First, pathnames need |
---|
133 | separators between the directory components, and different operating |
---|
134 | systems use different separators. We could define a Network Standard |
---|
135 | Pathname Representation, but then every pathname would have to be |
---|
136 | parsed and converted at each end. Other issues are discussed in |
---|
137 | \fINFS Implementation Issues\fP below. |
---|
138 | .LP |
---|
139 | Although files and directories are similar objects in many ways, |
---|
140 | different procedures are used to read directories and files. This |
---|
141 | provides a network standard format for representing directories. The |
---|
142 | same argument as above could have been used to justify a procedure |
---|
143 | that returns only one directory entry per call. The problem is |
---|
144 | efficiency. Directories can contain many entries, and a remote call |
---|
145 | to return each would be just too slow. |
---|
146 | .NH 2 |
---|
147 | \&RPC Information |
---|
148 | .IX NFS "RPC information" |
---|
149 | .IP \fIAuthentication\fP |
---|
150 | The NFS service uses |
---|
151 | .I AUTH_UNIX , |
---|
152 | .I AUTH_DES , |
---|
153 | or |
---|
154 | .I AUTH_SHORT |
---|
155 | style |
---|
156 | authentication, except in the NULL procedure where |
---|
157 | .I AUTH_NONE |
---|
158 | is also allowed. |
---|
159 | .IP "\fITransport Protocols\fP" |
---|
160 | NFS currently is supported on UDP/IP only. |
---|
161 | .IP "\fIPort Number\fP" |
---|
162 | The NFS protocol currently uses the UDP port number 2049. This is |
---|
163 | not an officially assigned port, so later versions of the protocol |
---|
164 | use the \*QPortmapping\*U facility of RPC. |
---|
165 | .NH 2 |
---|
166 | \&Sizes of XDR Structures |
---|
167 | .IX "XDR structure sizes" |
---|
168 | .LP |
---|
169 | These are the sizes, given in decimal bytes, of various XDR |
---|
170 | structures used in the protocol: |
---|
171 | .DS |
---|
172 | /* \fIThe maximum number of bytes of data in a READ or WRITE request\fP */ |
---|
173 | const MAXDATA = 8192; |
---|
174 | |
---|
175 | /* \fIThe maximum number of bytes in a pathname argument\fP */ |
---|
176 | const MAXPATHLEN = 1024; |
---|
177 | |
---|
178 | /* \fIThe maximum number of bytes in a file name argument\fP */ |
---|
179 | const MAXNAMLEN = 255; |
---|
180 | |
---|
181 | /* \fIThe size in bytes of the opaque "cookie" passed by READDIR\fP */ |
---|
182 | const COOKIESIZE = 4; |
---|
183 | |
---|
184 | /* \fIThe size in bytes of the opaque file handle\fP */ |
---|
185 | const FHSIZE = 32; |
---|
186 | .DE |
---|
187 | .NH 2 |
---|
188 | \&Basic Data Types |
---|
189 | .IX "NFS data types" |
---|
190 | .IX NFS "basic data types" |
---|
191 | .LP |
---|
192 | The following XDR definitions are basic structures and types used |
---|
193 | in other structures described further on. |
---|
194 | .KS |
---|
195 | .NH 3 |
---|
196 | \&stat |
---|
197 | .IX "NFS data types" stat "" \fIstat\fP |
---|
198 | .DS |
---|
199 | enum stat { |
---|
200 | NFS_OK = 0, |
---|
201 | NFSERR_PERM=1, |
---|
202 | NFSERR_NOENT=2, |
---|
203 | NFSERR_IO=5, |
---|
204 | NFSERR_NXIO=6, |
---|
205 | NFSERR_ACCES=13, |
---|
206 | NFSERR_EXIST=17, |
---|
207 | NFSERR_NODEV=19, |
---|
208 | NFSERR_NOTDIR=20, |
---|
209 | NFSERR_ISDIR=21, |
---|
210 | NFSERR_FBIG=27, |
---|
211 | NFSERR_NOSPC=28, |
---|
212 | NFSERR_ROFS=30, |
---|
213 | NFSERR_NAMETOOLONG=63, |
---|
214 | NFSERR_NOTEMPTY=66, |
---|
215 | NFSERR_DQUOT=69, |
---|
216 | NFSERR_STALE=70, |
---|
217 | NFSERR_WFLUSH=99 |
---|
218 | }; |
---|
219 | .DE |
---|
220 | .KE |
---|
221 | .LP |
---|
222 | The |
---|
223 | .I stat |
---|
224 | type is returned with every procedure's results. A |
---|
225 | value of |
---|
226 | .I NFS_OK |
---|
227 | indicates that the call completed successfully and |
---|
228 | the results are valid. The other values indicate some kind of |
---|
229 | error occurred on the server side during the servicing of the |
---|
230 | procedure. The error values are derived from UNIX error numbers. |
---|
231 | .IP \fBNFSERR_PERM\fP: |
---|
232 | Not owner. The caller does not have correct ownership |
---|
233 | to perform the requested operation. |
---|
234 | .IP \fBNFSERR_NOENT\fP: |
---|
235 | No such file or directory. The file or directory |
---|
236 | specified does not exist. |
---|
237 | .IP \fBNFSERR_IO\fP: |
---|
238 | Some sort of hard error occurred when the operation was |
---|
239 | in progress. This could be a disk error, for example. |
---|
240 | .IP \fBNFSERR_NXIO\fP: |
---|
241 | No such device or address. |
---|
242 | .IP \fBNFSERR_ACCES\fP: |
---|
243 | Permission denied. The caller does not have the |
---|
244 | correct permission to perform the requested operation. |
---|
245 | .IP \fBNFSERR_EXIST\fP: |
---|
246 | File exists. The file specified already exists. |
---|
247 | .IP \fBNFSERR_NODEV\fP: |
---|
248 | No such device. |
---|
249 | .IP \fBNFSERR_NOTDIR\fP: |
---|
250 | Not a directory. The caller specified a |
---|
251 | non-directory in a directory operation. |
---|
252 | .IP \fBNFSERR_ISDIR\fP: |
---|
253 | Is a directory. The caller specified a directory in |
---|
254 | a non- directory operation. |
---|
255 | .IP \fBNFSERR_FBIG\fP: |
---|
256 | File too large. The operation caused a file to grow |
---|
257 | beyond the server's limit. |
---|
258 | .IP \fBNFSERR_NOSPC\fP: |
---|
259 | No space left on device. The operation caused the |
---|
260 | server's filesystem to reach its limit. |
---|
261 | .IP \fBNFSERR_ROFS\fP: |
---|
262 | Read-only filesystem. Write attempted on a read-only filesystem. |
---|
263 | .IP \fBNFSERR_NAMETOOLONG\fP: |
---|
264 | File name too long. The file name in an operation was too long. |
---|
265 | .IP \fBNFSERR_NOTEMPTY\fP: |
---|
266 | Directory not empty. Attempted to remove a |
---|
267 | directory that was not empty. |
---|
268 | .IP \fBNFSERR_DQUOT\fP: |
---|
269 | Disk quota exceeded. The client's disk quota on the |
---|
270 | server has been exceeded. |
---|
271 | .IP \fBNFSERR_STALE\fP: |
---|
272 | The "fhandle" given in the arguments was invalid. |
---|
273 | That is, the file referred to by that file handle no longer exists, |
---|
274 | or access to it has been revoked. |
---|
275 | .IP \fBNFSERR_WFLUSH\fP: |
---|
276 | The server's write cache used in the |
---|
277 | .I WRITECACHE |
---|
278 | call got flushed to disk. |
---|
279 | .LP |
---|
280 | .KS |
---|
281 | .NH 3 |
---|
282 | \&ftype |
---|
283 | .IX "NFS data types" ftype "" \fIftype\fP |
---|
284 | .DS |
---|
285 | enum ftype { |
---|
286 | NFNON = 0, |
---|
287 | NFREG = 1, |
---|
288 | NFDIR = 2, |
---|
289 | NFBLK = 3, |
---|
290 | NFCHR = 4, |
---|
291 | NFLNK = 5 |
---|
292 | }; |
---|
293 | .DE |
---|
294 | .KE |
---|
295 | The enumeration |
---|
296 | .I ftype |
---|
297 | gives the type of a file. The type |
---|
298 | .I NFNON |
---|
299 | indicates a non-file, |
---|
300 | .I NFREG |
---|
301 | is a regular file, |
---|
302 | .I NFDIR |
---|
303 | is a directory, |
---|
304 | .I NFBLK |
---|
305 | is a block-special device, |
---|
306 | .I NFCHR |
---|
307 | is a character-special device, and |
---|
308 | .I NFLNK |
---|
309 | is a symbolic link. |
---|
310 | .KS |
---|
311 | .NH 3 |
---|
312 | \&fhandle |
---|
313 | .IX "NFS data types" fhandle "" \fIfhandle\fP |
---|
314 | .DS |
---|
315 | typedef opaque fhandle[FHSIZE]; |
---|
316 | .DE |
---|
317 | .KE |
---|
318 | The |
---|
319 | .I fhandle |
---|
320 | is the file handle passed between the server and the client. |
---|
321 | All file operations are done using file handles to refer to a file or |
---|
322 | directory. The file handle can contain whatever information the server |
---|
323 | needs to distinguish an individual file. |
---|
324 | .KS |
---|
325 | .NH 3 |
---|
326 | \&timeval |
---|
327 | .IX "NFS data types" timeval "" \fItimeval\fP |
---|
328 | .DS |
---|
329 | struct timeval { |
---|
330 | unsigned int seconds; |
---|
331 | unsigned int useconds; |
---|
332 | }; |
---|
333 | .DE |
---|
334 | .KE |
---|
335 | The |
---|
336 | .I timeval |
---|
337 | structure is the number of seconds and microseconds |
---|
338 | since midnight January 1, 1970, Greenwich Mean Time. It is used to |
---|
339 | pass time and date information. |
---|
340 | .KS |
---|
341 | .NH 3 |
---|
342 | \&fattr |
---|
343 | .IX "NFS data types" fattr "" \fIfattr\fP |
---|
344 | .DS |
---|
345 | struct fattr { |
---|
346 | ftype type; |
---|
347 | unsigned int mode; |
---|
348 | unsigned int nlink; |
---|
349 | unsigned int uid; |
---|
350 | unsigned int gid; |
---|
351 | unsigned int size; |
---|
352 | unsigned int blocksize; |
---|
353 | unsigned int rdev; |
---|
354 | unsigned int blocks; |
---|
355 | unsigned int fsid; |
---|
356 | unsigned int fileid; |
---|
357 | timeval atime; |
---|
358 | timeval mtime; |
---|
359 | timeval ctime; |
---|
360 | }; |
---|
361 | .DE |
---|
362 | .KE |
---|
363 | The |
---|
364 | .I fattr |
---|
365 | structure contains the attributes of a file; "type" is the type of |
---|
366 | the file; "nlink" is the number of hard links to the file (the number |
---|
367 | of different names for the same file); "uid" is the user |
---|
368 | identification number of the owner of the file; "gid" is the group |
---|
369 | identification number of the group of the file; "size" is the size in |
---|
370 | bytes of the file; "blocksize" is the size in bytes of a block of the |
---|
371 | file; "rdev" is the device number of the file if it is type |
---|
372 | .I NFCHR |
---|
373 | or |
---|
374 | .I NFBLK ; |
---|
375 | "blocks" is the number of blocks the file takes up on disk; "fsid" is |
---|
376 | the file system identifier for the filesystem containing the file; |
---|
377 | "fileid" is a number that uniquely identifies the file within its |
---|
378 | filesystem; "atime" is the time when the file was last accessed for |
---|
379 | either read or write; "mtime" is the time when the file data was last |
---|
380 | modified (written); and "ctime" is the time when the status of the |
---|
381 | file was last changed. Writing to the file also changes "ctime" if |
---|
382 | the size of the file changes. |
---|
383 | .LP |
---|
384 | "mode" is the access mode encoded as a set of bits. Notice that the |
---|
385 | file type is specified both in the mode bits and in the file type. |
---|
386 | This is really a bug in the protocol and will be fixed in future |
---|
387 | versions. The descriptions given below specify the bit positions |
---|
388 | using octal numbers. |
---|
389 | .TS |
---|
390 | box tab (&) ; |
---|
391 | cfI cfI |
---|
392 | lfL l . |
---|
393 | Bit&Description |
---|
394 | _ |
---|
395 | 0040000&This is a directory; "type" field should be NFDIR. |
---|
396 | 0020000&This is a character special file; "type" field should be NFCHR. |
---|
397 | 0060000&This is a block special file; "type" field should be NFBLK. |
---|
398 | 0100000&This is a regular file; "type" field should be NFREG. |
---|
399 | 0120000&This is a symbolic link file; "type" field should be NFLNK. |
---|
400 | 0140000&This is a named socket; "type" field should be NFNON. |
---|
401 | 0004000&Set user id on execution. |
---|
402 | 0002000&Set group id on execution. |
---|
403 | 0001000&Save swapped text even after use. |
---|
404 | 0000400&Read permission for owner. |
---|
405 | 0000200&Write permission for owner. |
---|
406 | 0000100&Execute and search permission for owner. |
---|
407 | 0000040&Read permission for group. |
---|
408 | 0000020&Write permission for group. |
---|
409 | 0000010&Execute and search permission for group. |
---|
410 | 0000004&Read permission for others. |
---|
411 | 0000002&Write permission for others. |
---|
412 | 0000001&Execute and search permission for others. |
---|
413 | .TE |
---|
414 | .KS |
---|
415 | Notes: |
---|
416 | .IP |
---|
417 | The bits are the same as the mode bits returned by the |
---|
418 | .I stat(2) |
---|
419 | system call in the UNIX system. The file type is specified both in |
---|
420 | the mode bits and in the file type. This is fixed in future |
---|
421 | versions. |
---|
422 | .IP |
---|
423 | The "rdev" field in the attributes structure is an operating system |
---|
424 | specific device specifier. It will be removed and generalized in |
---|
425 | the next revision of the protocol. |
---|
426 | .KE |
---|
427 | .LP |
---|
428 | .KS |
---|
429 | .NH 3 |
---|
430 | \&sattr |
---|
431 | .IX "NFS data types" sattr "" \fIsattr\fP |
---|
432 | .DS |
---|
433 | struct sattr { |
---|
434 | unsigned int mode; |
---|
435 | unsigned int uid; |
---|
436 | unsigned int gid; |
---|
437 | unsigned int size; |
---|
438 | timeval atime; |
---|
439 | timeval mtime; |
---|
440 | }; |
---|
441 | .DE |
---|
442 | .KE |
---|
443 | The |
---|
444 | .I sattr |
---|
445 | structure contains the file attributes which can be set |
---|
446 | from the client. The fields are the same as for |
---|
447 | .I fattr |
---|
448 | above. A "size" of zero means the file should be truncated. |
---|
449 | A value of -1 indicates a field that should be ignored. |
---|
450 | .LP |
---|
451 | .KS |
---|
452 | .NH 3 |
---|
453 | \&filename |
---|
454 | .IX "NFS data types" filename "" \fIfilename\fP |
---|
455 | .DS |
---|
456 | typedef string filename<MAXNAMLEN>; |
---|
457 | .DE |
---|
458 | .KE |
---|
459 | The type |
---|
460 | .I filename |
---|
461 | is used for passing file names or pathname components. |
---|
462 | .LP |
---|
463 | .KS |
---|
464 | .NH 3 |
---|
465 | \&path |
---|
466 | .IX "NFS data types" path "" \fIpath\fP |
---|
467 | .DS |
---|
468 | typedef string path<MAXPATHLEN>; |
---|
469 | .DE |
---|
470 | .KE |
---|
471 | The type |
---|
472 | .I path |
---|
473 | is a pathname. The server considers it as a string |
---|
474 | with no internal structure, but to the client it is the name of a |
---|
475 | node in a filesystem tree. |
---|
476 | .LP |
---|
477 | .KS |
---|
478 | .NH 3 |
---|
479 | \&attrstat |
---|
480 | .IX "NFS data types" attrstat "" \fIattrstat\fP |
---|
481 | .DS |
---|
482 | union attrstat switch (stat status) { |
---|
483 | case NFS_OK: |
---|
484 | fattr attributes; |
---|
485 | default: |
---|
486 | void; |
---|
487 | }; |
---|
488 | .DE |
---|
489 | .KE |
---|
490 | The |
---|
491 | .I attrstat |
---|
492 | structure is a common procedure result. It contains |
---|
493 | a "status" and, if the call succeeded, it also contains the |
---|
494 | attributes of the file on which the operation was done. |
---|
495 | .LP |
---|
496 | .KS |
---|
497 | .NH 3 |
---|
498 | \&diropargs |
---|
499 | .IX "NFS data types" diropargs "" \fIdiropargs\fP |
---|
500 | .DS |
---|
501 | struct diropargs { |
---|
502 | fhandle dir; |
---|
503 | filename name; |
---|
504 | }; |
---|
505 | .DE |
---|
506 | .KE |
---|
507 | The |
---|
508 | .I diropargs |
---|
509 | structure is used in directory operations. The |
---|
510 | "fhandle" "dir" is the directory in which to find the file "name". |
---|
511 | A directory operation is one in which the directory is affected. |
---|
512 | .LP |
---|
513 | .KS |
---|
514 | .NH 3 |
---|
515 | \&diropres |
---|
516 | .IX "NFS data types" diropres "" \fIdiropres\fP |
---|
517 | .DS |
---|
518 | union diropres switch (stat status) { |
---|
519 | case NFS_OK: |
---|
520 | struct { |
---|
521 | fhandle file; |
---|
522 | fattr attributes; |
---|
523 | } diropok; |
---|
524 | default: |
---|
525 | void; |
---|
526 | }; |
---|
527 | .DE |
---|
528 | .KE |
---|
529 | The results of a directory operation are returned in a |
---|
530 | .I diropres |
---|
531 | structure. If the call succeeded, a new file handle "file" and the |
---|
532 | "attributes" associated with that file are returned along with the |
---|
533 | "status". |
---|
534 | .NH 2 |
---|
535 | \&Server Procedures |
---|
536 | .IX "NFS server procedures" "" "" "" PAGE MAJOR |
---|
537 | .LP |
---|
538 | The protocol definition is given as a set of procedures with |
---|
539 | arguments and results defined using the RPC language. A brief |
---|
540 | description of the function of each procedure should provide enough |
---|
541 | information to allow implementation. |
---|
542 | .LP |
---|
543 | All of the procedures in the NFS protocol are assumed to be |
---|
544 | synchronous. When a procedure returns to the client, the client |
---|
545 | can assume that the operation has completed and any data associated |
---|
546 | with the request is now on stable storage. For example, a client |
---|
547 | .I WRITE |
---|
548 | request may cause the server to update data blocks, |
---|
549 | filesystem information blocks (such as indirect blocks), and file |
---|
550 | attribute information (size and modify times). When the |
---|
551 | .I WRITE |
---|
552 | returns to the client, it can assume that the write is safe, even |
---|
553 | in case of a server crash, and it can discard the data written. |
---|
554 | This is a very important part of the statelessness of the server. |
---|
555 | If the server waited to flush data from remote requests, the client |
---|
556 | would have to save those requests so that it could resend them in |
---|
557 | case of a server crash. |
---|
558 | .ie t .DS |
---|
559 | .el .DS L |
---|
560 | |
---|
561 | .ft I |
---|
562 | /* |
---|
563 | * Remote file service routines |
---|
564 | */ |
---|
565 | .ft CW |
---|
566 | program NFS_PROGRAM { |
---|
567 | version NFS_VERSION { |
---|
568 | void NFSPROC_NULL(void) = 0; |
---|
569 | attrstat NFSPROC_GETATTR(fhandle) = 1; |
---|
570 | attrstat NFSPROC_SETATTR(sattrargs) = 2; |
---|
571 | void NFSPROC_ROOT(void) = 3; |
---|
572 | diropres NFSPROC_LOOKUP(diropargs) = 4; |
---|
573 | readlinkres NFSPROC_READLINK(fhandle) = 5; |
---|
574 | readres NFSPROC_READ(readargs) = 6; |
---|
575 | void NFSPROC_WRITECACHE(void) = 7; |
---|
576 | attrstat NFSPROC_WRITE(writeargs) = 8; |
---|
577 | diropres NFSPROC_CREATE(createargs) = 9; |
---|
578 | stat NFSPROC_REMOVE(diropargs) = 10; |
---|
579 | stat NFSPROC_RENAME(renameargs) = 11; |
---|
580 | stat NFSPROC_LINK(linkargs) = 12; |
---|
581 | stat NFSPROC_SYMLINK(symlinkargs) = 13; |
---|
582 | diropres NFSPROC_MKDIR(createargs) = 14; |
---|
583 | stat NFSPROC_RMDIR(diropargs) = 15; |
---|
584 | readdirres NFSPROC_READDIR(readdirargs) = 16; |
---|
585 | statfsres NFSPROC_STATFS(fhandle) = 17; |
---|
586 | } = 2; |
---|
587 | } = 100003; |
---|
588 | .DE |
---|
589 | .KS |
---|
590 | .NH 3 |
---|
591 | \&Do Nothing |
---|
592 | .IX "NFS server procedures" NFSPROC_NULL() "" \fINFSPROC_NULL()\fP |
---|
593 | .DS |
---|
594 | void |
---|
595 | NFSPROC_NULL(void) = 0; |
---|
596 | .DE |
---|
597 | .KE |
---|
598 | This procedure does no work. It is made available in all RPC |
---|
599 | services to allow server response testing and timing. |
---|
600 | .KS |
---|
601 | .NH 3 |
---|
602 | \&Get File Attributes |
---|
603 | .IX "NFS server procedures" NFSPROC_GETATTR() "" \fINFSPROC_GETATTR()\fP |
---|
604 | .DS |
---|
605 | attrstat |
---|
606 | NFSPROC_GETATTR (fhandle) = 1; |
---|
607 | .DE |
---|
608 | .KE |
---|
609 | If the reply status is |
---|
610 | .I NFS_OK , |
---|
611 | then the reply attributes contains |
---|
612 | the attributes for the file given by the input fhandle. |
---|
613 | .KS |
---|
614 | .NH 3 |
---|
615 | \&Set File Attributes |
---|
616 | .IX "NFS server procedures" NFSPROC_SETATTR() "" \fINFSPROC_SETATTR()\fP |
---|
617 | .DS |
---|
618 | struct sattrargs { |
---|
619 | fhandle file; |
---|
620 | sattr attributes; |
---|
621 | }; |
---|
622 | |
---|
623 | attrstat |
---|
624 | NFSPROC_SETATTR (sattrargs) = 2; |
---|
625 | .DE |
---|
626 | .KE |
---|
627 | The "attributes" argument contains fields which are either -1 or |
---|
628 | are the new value for the attributes of "file". If the reply |
---|
629 | status is |
---|
630 | .I NFS_OK , |
---|
631 | then the reply attributes have the attributes of |
---|
632 | the file after the "SETATTR" operation has completed. |
---|
633 | .LP |
---|
634 | Note: The use of -1 to indicate an unused field in "attributes" is |
---|
635 | changed in the next version of the protocol. |
---|
636 | .KS |
---|
637 | .NH 3 |
---|
638 | \&Get Filesystem Root |
---|
639 | .IX "NFS server procedures" NFSPROC_ROOT "" \fINFSPROC_ROOT\fP |
---|
640 | .DS |
---|
641 | void |
---|
642 | NFSPROC_ROOT(void) = 3; |
---|
643 | .DE |
---|
644 | .KE |
---|
645 | Obsolete. This procedure is no longer used because finding the |
---|
646 | root file handle of a filesystem requires moving pathnames between |
---|
647 | client and server. To do this right we would have to define a |
---|
648 | network standard representation of pathnames. Instead, the |
---|
649 | function of looking up the root file handle is done by the |
---|
650 | .I MNTPROC_MNT() |
---|
651 | procedure. (See the |
---|
652 | .I "Mount Protocol Definition" |
---|
653 | later in this chapter for details). |
---|
654 | .KS |
---|
655 | .NH 3 |
---|
656 | \&Look Up File Name |
---|
657 | .IX "NFS server procedures" NFSPROC_LOOKUP() "" \fINFSPROC_LOOKUP()\fP |
---|
658 | .DS |
---|
659 | diropres |
---|
660 | NFSPROC_LOOKUP(diropargs) = 4; |
---|
661 | .DE |
---|
662 | .KE |
---|
663 | If the reply "status" is |
---|
664 | .I NFS_OK , |
---|
665 | then the reply "file" and reply |
---|
666 | "attributes" are the file handle and attributes for the file "name" |
---|
667 | in the directory given by "dir" in the argument. |
---|
668 | .KS |
---|
669 | .NH 3 |
---|
670 | \&Read From Symbolic Link |
---|
671 | .IX "NFS server procedures" NFSPROC_READLINK() "" \fINFSPROC_READLINK()\fP |
---|
672 | .DS |
---|
673 | union readlinkres switch (stat status) { |
---|
674 | case NFS_OK: |
---|
675 | path data; |
---|
676 | default: |
---|
677 | void; |
---|
678 | }; |
---|
679 | |
---|
680 | readlinkres |
---|
681 | NFSPROC_READLINK(fhandle) = 5; |
---|
682 | .DE |
---|
683 | .KE |
---|
684 | If "status" has the value |
---|
685 | .I NFS_OK , |
---|
686 | then the reply "data" is the data in |
---|
687 | the symbolic link given by the file referred to by the fhandle argument. |
---|
688 | .LP |
---|
689 | Note: since NFS always parses pathnames on the client, the |
---|
690 | pathname in a symbolic link may mean something different (or be |
---|
691 | meaningless) on a different client or on the server if a different |
---|
692 | pathname syntax is used. |
---|
693 | .KS |
---|
694 | .NH 3 |
---|
695 | \&Read From File |
---|
696 | .IX "NFS server procedures" NFSPROC_READ "" \fINFSPROC_READ\fP |
---|
697 | .DS |
---|
698 | struct readargs { |
---|
699 | fhandle file; |
---|
700 | unsigned offset; |
---|
701 | unsigned count; |
---|
702 | unsigned totalcount; |
---|
703 | }; |
---|
704 | |
---|
705 | union readres switch (stat status) { |
---|
706 | case NFS_OK: |
---|
707 | fattr attributes; |
---|
708 | opaque data<NFS_MAXDATA>; |
---|
709 | default: |
---|
710 | void; |
---|
711 | }; |
---|
712 | |
---|
713 | readres |
---|
714 | NFSPROC_READ(readargs) = 6; |
---|
715 | .DE |
---|
716 | .KE |
---|
717 | Returns up to "count" bytes of "data" from the file given by |
---|
718 | "file", starting at "offset" bytes from the beginning of the file. |
---|
719 | The first byte of the file is at offset zero. The file attributes |
---|
720 | after the read takes place are returned in "attributes". |
---|
721 | .LP |
---|
722 | Note: The argument "totalcount" is unused, and is removed in the |
---|
723 | next protocol revision. |
---|
724 | .KS |
---|
725 | .NH 3 |
---|
726 | \&Write to Cache |
---|
727 | .IX "NFS server procedures" NFSPROC_WRITECACHE() "" \fINFSPROC_WRITECACHE()\fP |
---|
728 | .DS |
---|
729 | void |
---|
730 | NFSPROC_WRITECACHE(void) = 7; |
---|
731 | .DE |
---|
732 | .KE |
---|
733 | To be used in the next protocol revision. |
---|
734 | .KS |
---|
735 | .NH 3 |
---|
736 | \&Write to File |
---|
737 | .IX "NFS server procedures" NFSPROC_WRITE() "" \fINFSPROC_WRITE()\fP |
---|
738 | .DS |
---|
739 | struct writeargs { |
---|
740 | fhandle file; |
---|
741 | unsigned beginoffset; |
---|
742 | unsigned offset; |
---|
743 | unsigned totalcount; |
---|
744 | opaque data<NFS_MAXDATA>; |
---|
745 | }; |
---|
746 | |
---|
747 | attrstat |
---|
748 | NFSPROC_WRITE(writeargs) = 8; |
---|
749 | .DE |
---|
750 | .KE |
---|
751 | Writes "data" beginning "offset" bytes from the beginning of |
---|
752 | "file". The first byte of the file is at offset zero. If the |
---|
753 | reply "status" is NFS_OK, then the reply "attributes" contains the |
---|
754 | attributes of the file after the write has completed. The write |
---|
755 | operation is atomic. Data from this call to |
---|
756 | .I WRITE |
---|
757 | will not be mixed with data from another client's calls. |
---|
758 | .LP |
---|
759 | Note: The arguments "beginoffset" and "totalcount" are ignored and |
---|
760 | are removed in the next protocol revision. |
---|
761 | .KS |
---|
762 | .NH 3 |
---|
763 | \&Create File |
---|
764 | .IX "NFS server procedures" NFSPROC_CREATE() "" \fINFSPROC_CREATE()\fP |
---|
765 | .DS |
---|
766 | struct createargs { |
---|
767 | diropargs where; |
---|
768 | sattr attributes; |
---|
769 | }; |
---|
770 | |
---|
771 | diropres |
---|
772 | NFSPROC_CREATE(createargs) = 9; |
---|
773 | .DE |
---|
774 | .KE |
---|
775 | The file "name" is created in the directory given by "dir". The |
---|
776 | initial attributes of the new file are given by "attributes". A |
---|
777 | reply "status" of NFS_OK indicates that the file was created, and |
---|
778 | reply "file" and reply "attributes" are its file handle and |
---|
779 | attributes. Any other reply "status" means that the operation |
---|
780 | failed and no file was created. |
---|
781 | .LP |
---|
782 | Note: This routine should pass an exclusive create flag, meaning |
---|
783 | "create the file only if it is not already there". |
---|
784 | .KS |
---|
785 | .NH 3 |
---|
786 | \&Remove File |
---|
787 | .IX "NFS server procedures" NFSPROC_REMOVE() "" \fINFSPROC_REMOVE()\fP |
---|
788 | .DS |
---|
789 | stat |
---|
790 | NFSPROC_REMOVE(diropargs) = 10; |
---|
791 | .DE |
---|
792 | .KE |
---|
793 | The file "name" is removed from the directory given by "dir". A |
---|
794 | reply of NFS_OK means the directory entry was removed. |
---|
795 | .LP |
---|
796 | Note: possibly non-idempotent operation. |
---|
797 | .KS |
---|
798 | .NH 3 |
---|
799 | \&Rename File |
---|
800 | .IX "NFS server procedures" NFSPROC_RENAME() "" \fINFSPROC_RENAME()\fP |
---|
801 | .DS |
---|
802 | struct renameargs { |
---|
803 | diropargs from; |
---|
804 | diropargs to; |
---|
805 | }; |
---|
806 | |
---|
807 | stat |
---|
808 | NFSPROC_RENAME(renameargs) = 11; |
---|
809 | .DE |
---|
810 | .KE |
---|
811 | The existing file "from.name" in the directory given by "from.dir" |
---|
812 | is renamed to "to.name" in the directory given by "to.dir". If the |
---|
813 | reply is |
---|
814 | .I NFS_OK , |
---|
815 | the file was renamed. The |
---|
816 | RENAME |
---|
817 | operation is |
---|
818 | atomic on the server; it cannot be interrupted in the middle. |
---|
819 | .LP |
---|
820 | Note: possibly non-idempotent operation. |
---|
821 | .KS |
---|
822 | .NH 3 |
---|
823 | \&Create Link to File |
---|
824 | .IX "NFS server procedures" NFSPROC_LINK() "" \fINFSPROC_LINK()\fP |
---|
825 | .DS |
---|
826 | struct linkargs { |
---|
827 | fhandle from; |
---|
828 | diropargs to; |
---|
829 | }; |
---|
830 | |
---|
831 | stat |
---|
832 | NFSPROC_LINK(linkargs) = 12; |
---|
833 | .DE |
---|
834 | .KE |
---|
835 | Creates the file "to.name" in the directory given by "to.dir", |
---|
836 | which is a hard link to the existing file given by "from". If the |
---|
837 | return value is |
---|
838 | .I NFS_OK , |
---|
839 | a link was created. Any other return value |
---|
840 | indicates an error, and the link was not created. |
---|
841 | .LP |
---|
842 | A hard link should have the property that changes to either of the |
---|
843 | linked files are reflected in both files. When a hard link is made |
---|
844 | to a file, the attributes for the file should have a value for |
---|
845 | "nlink" that is one greater than the value before the link. |
---|
846 | .LP |
---|
847 | Note: possibly non-idempotent operation. |
---|
848 | .KS |
---|
849 | .NH 3 |
---|
850 | \&Create Symbolic Link |
---|
851 | .IX "NFS server procedures" NFSPROC_SYMLINK() "" \fINFSPROC_SYMLINK()\fP |
---|
852 | .DS |
---|
853 | struct symlinkargs { |
---|
854 | diropargs from; |
---|
855 | path to; |
---|
856 | sattr attributes; |
---|
857 | }; |
---|
858 | |
---|
859 | stat |
---|
860 | NFSPROC_SYMLINK(symlinkargs) = 13; |
---|
861 | .DE |
---|
862 | .KE |
---|
863 | Creates the file "from.name" with ftype |
---|
864 | .I NFLNK |
---|
865 | in the directory |
---|
866 | given by "from.dir". The new file contains the pathname "to" and |
---|
867 | has initial attributes given by "attributes". If the return value |
---|
868 | is |
---|
869 | .I NFS_OK , |
---|
870 | a link was created. Any other return value indicates an |
---|
871 | error, and the link was not created. |
---|
872 | .LP |
---|
873 | A symbolic link is a pointer to another file. The name given in |
---|
874 | "to" is not interpreted by the server, only stored in the newly |
---|
875 | created file. When the client references a file that is a symbolic |
---|
876 | link, the contents of the symbolic link are normally transparently |
---|
877 | reinterpreted as a pathname to substitute. A |
---|
878 | .I READLINK |
---|
879 | operation returns the data to the client for interpretation. |
---|
880 | .LP |
---|
881 | Note: On UNIX servers the attributes are never used, since |
---|
882 | symbolic links always have mode 0777. |
---|
883 | .KS |
---|
884 | .NH 3 |
---|
885 | \&Create Directory |
---|
886 | .IX "NFS server procedures" NFSPROC_MKDIR() "" \fINFSPROC_MKDIR()\fP |
---|
887 | .DS |
---|
888 | diropres |
---|
889 | NFSPROC_MKDIR (createargs) = 14; |
---|
890 | .DE |
---|
891 | .KE |
---|
892 | The new directory "where.name" is created in the directory given by |
---|
893 | "where.dir". The initial attributes of the new directory are given |
---|
894 | by "attributes". A reply "status" of NFS_OK indicates that the new |
---|
895 | directory was created, and reply "file" and reply "attributes" are |
---|
896 | its file handle and attributes. Any other reply "status" means |
---|
897 | that the operation failed and no directory was created. |
---|
898 | .LP |
---|
899 | Note: possibly non-idempotent operation. |
---|
900 | .KS |
---|
901 | .NH 3 |
---|
902 | \&Remove Directory |
---|
903 | .IX "NFS server procedures" NFSPROC_RMDIR() "" \fINFSPROC_RMDIR()\fP |
---|
904 | .DS |
---|
905 | stat |
---|
906 | NFSPROC_RMDIR(diropargs) = 15; |
---|
907 | .DE |
---|
908 | .KE |
---|
909 | The existing empty directory "name" in the directory given by "dir" |
---|
910 | is removed. If the reply is |
---|
911 | .I NFS_OK , |
---|
912 | the directory was removed. |
---|
913 | .LP |
---|
914 | Note: possibly non-idempotent operation. |
---|
915 | .KS |
---|
916 | .NH 3 |
---|
917 | \&Read From Directory |
---|
918 | .IX "NFS server procedures" NFSPROC_READDIR() "" \fINFSPROC_READDIR()\fP |
---|
919 | .DS |
---|
920 | struct readdirargs { |
---|
921 | fhandle dir; |
---|
922 | nfscookie cookie; |
---|
923 | unsigned count; |
---|
924 | }; |
---|
925 | |
---|
926 | struct entry { |
---|
927 | unsigned fileid; |
---|
928 | filename name; |
---|
929 | nfscookie cookie; |
---|
930 | entry *nextentry; |
---|
931 | }; |
---|
932 | |
---|
933 | union readdirres switch (stat status) { |
---|
934 | case NFS_OK: |
---|
935 | struct { |
---|
936 | entry *entries; |
---|
937 | bool eof; |
---|
938 | } readdirok; |
---|
939 | default: |
---|
940 | void; |
---|
941 | }; |
---|
942 | |
---|
943 | readdirres |
---|
944 | NFSPROC_READDIR (readdirargs) = 16; |
---|
945 | .DE |
---|
946 | .KE |
---|
947 | Returns a variable number of directory entries, with a total size |
---|
948 | of up to "count" bytes, from the directory given by "dir". If the |
---|
949 | returned value of "status" is |
---|
950 | .I NFS_OK , |
---|
951 | then it is followed by a |
---|
952 | variable number of "entry"s. Each "entry" contains a "fileid" |
---|
953 | which consists of a unique number to identify the file within a |
---|
954 | filesystem, the "name" of the file, and a "cookie" which is an |
---|
955 | opaque pointer to the next entry in the directory. The cookie is |
---|
956 | used in the next |
---|
957 | .I READDIR |
---|
958 | call to get more entries starting at a |
---|
959 | given point in the directory. The special cookie zero (all bits |
---|
960 | zero) can be used to get the entries starting at the beginning of |
---|
961 | the directory. The "fileid" field should be the same number as the |
---|
962 | "fileid" in the the attributes of the file. (See the |
---|
963 | .I "Basic Data Types" |
---|
964 | section.) |
---|
965 | The "eof" flag has a value of |
---|
966 | .I TRUE |
---|
967 | if there are no more entries in the directory. |
---|
968 | .KS |
---|
969 | .NH 3 |
---|
970 | \&Get Filesystem Attributes |
---|
971 | .IX "NFS server procedures" NFSPROC_STATFS() "" \fINFSPROC_STATFS()\fP |
---|
972 | .DS |
---|
973 | union statfsres (stat status) { |
---|
974 | case NFS_OK: |
---|
975 | struct { |
---|
976 | unsigned tsize; |
---|
977 | unsigned bsize; |
---|
978 | unsigned blocks; |
---|
979 | unsigned bfree; |
---|
980 | unsigned bavail; |
---|
981 | } info; |
---|
982 | default: |
---|
983 | void; |
---|
984 | }; |
---|
985 | |
---|
986 | statfsres |
---|
987 | NFSPROC_STATFS(fhandle) = 17; |
---|
988 | .DE |
---|
989 | .KE |
---|
990 | If the reply "status" is |
---|
991 | .I NFS_OK , |
---|
992 | then the reply "info" gives the |
---|
993 | attributes for the filesystem that contains file referred to by the |
---|
994 | input fhandle. The attribute fields contain the following values: |
---|
995 | .IP tsize: |
---|
996 | The optimum transfer size of the server in bytes. This is |
---|
997 | the number of bytes the server would like to have in the |
---|
998 | data part of READ and WRITE requests. |
---|
999 | .IP bsize: |
---|
1000 | The block size in bytes of the filesystem. |
---|
1001 | .IP blocks: |
---|
1002 | The total number of "bsize" blocks on the filesystem. |
---|
1003 | .IP bfree: |
---|
1004 | The number of free "bsize" blocks on the filesystem. |
---|
1005 | .IP bavail: |
---|
1006 | The number of "bsize" blocks available to non-privileged users. |
---|
1007 | .LP |
---|
1008 | Note: This call does not work well if a filesystem has variable |
---|
1009 | size blocks. |
---|
1010 | .NH 1 |
---|
1011 | \&NFS Implementation Issues |
---|
1012 | .IX NFS implementation |
---|
1013 | .LP |
---|
1014 | The NFS protocol is designed to be operating system independent, but |
---|
1015 | since this version was designed in a UNIX environment, many |
---|
1016 | operations have semantics similar to the operations of the UNIX file |
---|
1017 | system. This section discusses some of the implementation-specific |
---|
1018 | semantic issues. |
---|
1019 | .NH 2 |
---|
1020 | \&Server/Client Relationship |
---|
1021 | .IX NFS "server/client relationship" |
---|
1022 | .LP |
---|
1023 | The NFS protocol is designed to allow servers to be as simple and |
---|
1024 | general as possible. Sometimes the simplicity of the server can be a |
---|
1025 | problem, if the client wants to implement complicated filesystem |
---|
1026 | semantics. |
---|
1027 | .LP |
---|
1028 | For example, some operating systems allow removal of open files. A |
---|
1029 | process can open a file and, while it is open, remove it from the |
---|
1030 | directory. The file can be read and written as long as the process |
---|
1031 | keeps it open, even though the file has no name in the filesystem. |
---|
1032 | It is impossible for a stateless server to implement these semantics. |
---|
1033 | The client can do some tricks such as renaming the file on remove, |
---|
1034 | and only removing it on close. We believe that the server provides |
---|
1035 | enough functionality to implement most file system semantics on the |
---|
1036 | client. |
---|
1037 | .LP |
---|
1038 | Every NFS client can also potentially be a server, and remote and |
---|
1039 | local mounted filesystems can be freely intermixed. This leads to |
---|
1040 | some interesting problems when a client travels down the directory |
---|
1041 | tree of a remote filesystem and reaches the mount point on the server |
---|
1042 | for another remote filesystem. Allowing the server to follow the |
---|
1043 | second remote mount would require loop detection, server lookup, and |
---|
1044 | user revalidation. Instead, we decided not to let clients cross a |
---|
1045 | server's mount point. When a client does a LOOKUP on a directory on |
---|
1046 | which the server has mounted a filesystem, the client sees the |
---|
1047 | underlying directory instead of the mounted directory. A client can |
---|
1048 | do remote mounts that match the server's mount points to maintain the |
---|
1049 | server's view. |
---|
1050 | .LP |
---|
1051 | .NH 2 |
---|
1052 | \&Pathname Interpretation |
---|
1053 | .IX NFS "pathname interpretation" |
---|
1054 | .LP |
---|
1055 | There are a few complications to the rule that pathnames are always |
---|
1056 | parsed on the client. For example, symbolic links could have |
---|
1057 | different interpretations on different clients. Another common |
---|
1058 | problem for non-UNIX implementations is the special interpretation of |
---|
1059 | the pathname ".." to mean the parent of a given directory. The next |
---|
1060 | revision of the protocol uses an explicit flag to indicate the parent |
---|
1061 | instead. |
---|
1062 | .NH 2 |
---|
1063 | \&Permission Issues |
---|
1064 | .IX NFS "permission issues" |
---|
1065 | .LP |
---|
1066 | The NFS protocol, strictly speaking, does not define the permission |
---|
1067 | checking used by servers. However, it is expected that a server |
---|
1068 | will do normal operating system permission checking using |
---|
1069 | .I AUTH_UNIX |
---|
1070 | style authentication as the basis of its protection mechanism. The |
---|
1071 | server gets the client's effective "uid", effective "gid", and groups |
---|
1072 | on each call and uses them to check permission. There are various |
---|
1073 | problems with this method that can been resolved in interesting ways. |
---|
1074 | .LP |
---|
1075 | Using "uid" and "gid" implies that the client and server share the |
---|
1076 | same "uid" list. Every server and client pair must have the same |
---|
1077 | mapping from user to "uid" and from group to "gid". Since every |
---|
1078 | client can also be a server, this tends to imply that the whole |
---|
1079 | network shares the same "uid/gid" space. |
---|
1080 | .I AUTH_DES |
---|
1081 | (and the next |
---|
1082 | revision of the NFS protocol) uses string names instead of numbers, |
---|
1083 | but there are still complex problems to be solved. |
---|
1084 | .LP |
---|
1085 | Another problem arises due to the usually stateful open operation. |
---|
1086 | Most operating systems check permission at open time, and then check |
---|
1087 | that the file is open on each read and write request. With stateless |
---|
1088 | servers, the server has no idea that the file is open and must do |
---|
1089 | permission checking on each read and write call. On a local |
---|
1090 | filesystem, a user can open a file and then change the permissions so |
---|
1091 | that no one is allowed to touch it, but will still be able to write |
---|
1092 | to the file because it is open. On a remote filesystem, by contrast, |
---|
1093 | the write would fail. To get around this problem, the server's |
---|
1094 | permission checking algorithm should allow the owner of a file to |
---|
1095 | access it regardless of the permission setting. |
---|
1096 | .LP |
---|
1097 | A similar problem has to do with paging in from a file over the |
---|
1098 | network. The operating system usually checks for execute permission |
---|
1099 | before opening a file for demand paging, and then reads blocks from |
---|
1100 | the open file. The file may not have read permission, but after it |
---|
1101 | is opened it doesn't matter. An NFS server can not tell the |
---|
1102 | difference between a normal file read and a demand page-in read. To |
---|
1103 | make this work, the server allows reading of files if the "uid" given |
---|
1104 | in the call has execute or read permission on the file. |
---|
1105 | .LP |
---|
1106 | In most operating systems, a particular user (on the user ID zero) |
---|
1107 | has access to all files no matter what permission and ownership they |
---|
1108 | have. This "super-user" permission may not be allowed on the server, |
---|
1109 | since anyone who can become super-user on their workstation could |
---|
1110 | gain access to all remote files. The UNIX server by default maps |
---|
1111 | user id 0 to -2 before doing its access checking. This works except |
---|
1112 | for NFS root filesystems, where super-user access cannot be avoided. |
---|
1113 | .NH 2 |
---|
1114 | \&Setting RPC Parameters |
---|
1115 | .IX NFS "setting RPC parameters" |
---|
1116 | .LP |
---|
1117 | Various file system parameters and options should be set at mount |
---|
1118 | time. The mount protocol is described in the appendix below. For |
---|
1119 | example, "Soft" mounts as well as "Hard" mounts are usually both |
---|
1120 | provided. Soft mounted file systems return errors when RPC |
---|
1121 | operations fail (after a given number of optional retransmissions), |
---|
1122 | while hard mounted file systems continue to retransmit forever. |
---|
1123 | Clients and servers may need to keep caches of recent operations to |
---|
1124 | help avoid problems with non-idempotent operations. |
---|
1125 | .NH 1 |
---|
1126 | \&Mount Protocol Definition |
---|
1127 | .IX "mount protocol" "" "" "" PAGE MAJOR |
---|
1128 | .sp 1 |
---|
1129 | .NH 2 |
---|
1130 | \&Introduction |
---|
1131 | .IX "mount protocol" introduction |
---|
1132 | .LP |
---|
1133 | The mount protocol is separate from, but related to, the NFS |
---|
1134 | protocol. It provides operating system specific services to get the |
---|
1135 | NFS off the ground -- looking up server path names, validating user |
---|
1136 | identity, and checking access permissions. Clients use the mount |
---|
1137 | protocol to get the first file handle, which allows them entry into a |
---|
1138 | remote filesystem. |
---|
1139 | .LP |
---|
1140 | The mount protocol is kept separate from the NFS protocol to make it |
---|
1141 | easy to plug in new access checking and validation methods without |
---|
1142 | changing the NFS server protocol. |
---|
1143 | .LP |
---|
1144 | Notice that the protocol definition implies stateful servers because |
---|
1145 | the server maintains a list of client's mount requests. The mount |
---|
1146 | list information is not critical for the correct functioning of |
---|
1147 | either the client or the server. It is intended for advisory use |
---|
1148 | only, for example, to warn possible clients when a server is going |
---|
1149 | down. |
---|
1150 | .LP |
---|
1151 | Version one of the mount protocol is used with version two of the NFS |
---|
1152 | protocol. The only connecting point is the |
---|
1153 | .I fhandle |
---|
1154 | structure, which is the same for both protocols. |
---|
1155 | .NH 2 |
---|
1156 | \&RPC Information |
---|
1157 | .IX "mount protocol" "RPC information" |
---|
1158 | .IP \fIAuthentication\fP |
---|
1159 | The mount service uses |
---|
1160 | .I AUTH_UNIX |
---|
1161 | and |
---|
1162 | .I AUTH_DES |
---|
1163 | style authentication only. |
---|
1164 | .IP "\fITransport Protocols\fP" |
---|
1165 | The mount service is currently supported on UDP/IP only. |
---|
1166 | .IP "\fIPort Number\fP" |
---|
1167 | Consult the server's portmapper, described in the chapter |
---|
1168 | .I "Remote Procedure Calls: Protocol Specification", |
---|
1169 | to find the port number on which the mount service is registered. |
---|
1170 | .NH 2 |
---|
1171 | \&Sizes of XDR Structures |
---|
1172 | .IX "mount protocol" "XDR structure sizes" |
---|
1173 | .LP |
---|
1174 | These are the sizes, given in decimal bytes, of various XDR |
---|
1175 | structures used in the protocol: |
---|
1176 | .DS |
---|
1177 | /* \fIThe maximum number of bytes in a pathname argument\fP */ |
---|
1178 | const MNTPATHLEN = 1024; |
---|
1179 | |
---|
1180 | /* \fIThe maximum number of bytes in a name argument\fP */ |
---|
1181 | const MNTNAMLEN = 255; |
---|
1182 | |
---|
1183 | /* \fIThe size in bytes of the opaque file handle\fP */ |
---|
1184 | const FHSIZE = 32; |
---|
1185 | .DE |
---|
1186 | .NH 2 |
---|
1187 | \&Basic Data Types |
---|
1188 | .IX "mount protocol" "basic data types" |
---|
1189 | .IX "mount data types" |
---|
1190 | .LP |
---|
1191 | This section presents the data types used by the mount protocol. |
---|
1192 | In many cases they are similar to the types used in NFS. |
---|
1193 | .KS |
---|
1194 | .NH 3 |
---|
1195 | \&fhandle |
---|
1196 | .IX "mount data types" fhandle "" \fIfhandle\fP |
---|
1197 | .DS |
---|
1198 | typedef opaque fhandle[FHSIZE]; |
---|
1199 | .DE |
---|
1200 | .KE |
---|
1201 | The type |
---|
1202 | .I fhandle |
---|
1203 | is the file handle that the server passes to the |
---|
1204 | client. All file operations are done using file handles to refer |
---|
1205 | to a file or directory. The file handle can contain whatever |
---|
1206 | information the server needs to distinguish an individual file. |
---|
1207 | .LP |
---|
1208 | This is the same as the "fhandle" XDR definition in version 2 of |
---|
1209 | the NFS protocol; see |
---|
1210 | .I "Basic Data Types" |
---|
1211 | in the definition of the NFS protocol, above. |
---|
1212 | .KS |
---|
1213 | .NH 3 |
---|
1214 | \&fhstatus |
---|
1215 | .IX "mount data types" fhstatus "" \fIfhstatus\fP |
---|
1216 | .DS |
---|
1217 | union fhstatus switch (unsigned status) { |
---|
1218 | case 0: |
---|
1219 | fhandle directory; |
---|
1220 | default: |
---|
1221 | void; |
---|
1222 | }; |
---|
1223 | .DE |
---|
1224 | .KE |
---|
1225 | The type |
---|
1226 | .I fhstatus |
---|
1227 | is a union. If a "status" of zero is returned, |
---|
1228 | the call completed successfully, and a file handle for the |
---|
1229 | "directory" follows. A non-zero status indicates some sort of |
---|
1230 | error. In this case the status is a UNIX error number. |
---|
1231 | .KS |
---|
1232 | .NH 3 |
---|
1233 | \&dirpath |
---|
1234 | .IX "mount data types" dirpath "" \fIdirpath\fP |
---|
1235 | .DS |
---|
1236 | typedef string dirpath<MNTPATHLEN>; |
---|
1237 | .DE |
---|
1238 | .KE |
---|
1239 | The type |
---|
1240 | .I dirpath |
---|
1241 | is a server pathname of a directory. |
---|
1242 | .KS |
---|
1243 | .NH 3 |
---|
1244 | \&name |
---|
1245 | .IX "mount data types" name "" \fIname\fP |
---|
1246 | .DS |
---|
1247 | typedef string name<MNTNAMLEN>; |
---|
1248 | .DE |
---|
1249 | .KE |
---|
1250 | The type |
---|
1251 | .I name |
---|
1252 | is an arbitrary string used for various names. |
---|
1253 | .NH 2 |
---|
1254 | \&Server Procedures |
---|
1255 | .IX "mount server procedures" |
---|
1256 | .LP |
---|
1257 | The following sections define the RPC procedures supplied by a |
---|
1258 | mount server. |
---|
1259 | .ie t .DS |
---|
1260 | .el .DS L |
---|
1261 | .ft I |
---|
1262 | /* |
---|
1263 | * Protocol description for the mount program |
---|
1264 | */ |
---|
1265 | .ft CW |
---|
1266 | |
---|
1267 | program MOUNTPROG { |
---|
1268 | .ft I |
---|
1269 | /* |
---|
1270 | * Version 1 of the mount protocol used with |
---|
1271 | * version 2 of the NFS protocol. |
---|
1272 | */ |
---|
1273 | .ft CW |
---|
1274 | version MOUNTVERS { |
---|
1275 | void MOUNTPROC_NULL(void) = 0; |
---|
1276 | fhstatus MOUNTPROC_MNT(dirpath) = 1; |
---|
1277 | mountlist MOUNTPROC_DUMP(void) = 2; |
---|
1278 | void MOUNTPROC_UMNT(dirpath) = 3; |
---|
1279 | void MOUNTPROC_UMNTALL(void) = 4; |
---|
1280 | exportlist MOUNTPROC_EXPORT(void) = 5; |
---|
1281 | } = 1; |
---|
1282 | } = 100005; |
---|
1283 | .DE |
---|
1284 | .KS |
---|
1285 | .NH 3 |
---|
1286 | \&Do Nothing |
---|
1287 | .IX "mount server procedures" MNTPROC_NULL() "" \fIMNTPROC_NULL()\fP |
---|
1288 | .DS |
---|
1289 | void |
---|
1290 | MNTPROC_NULL(void) = 0; |
---|
1291 | .DE |
---|
1292 | .KE |
---|
1293 | This procedure does no work. It is made available in all RPC |
---|
1294 | services to allow server response testing and timing. |
---|
1295 | .KS |
---|
1296 | .NH 3 |
---|
1297 | \&Add Mount Entry |
---|
1298 | .IX "mount server procedures" MNTPROC_MNT() "" \fIMNTPROC_MNT()\fP |
---|
1299 | .DS |
---|
1300 | fhstatus |
---|
1301 | MNTPROC_MNT(dirpath) = 1; |
---|
1302 | .DE |
---|
1303 | .KE |
---|
1304 | If the reply "status" is 0, then the reply "directory" contains the |
---|
1305 | file handle for the directory "dirname". This file handle may be |
---|
1306 | used in the NFS protocol. This procedure also adds a new entry to |
---|
1307 | the mount list for this client mounting "dirname". |
---|
1308 | .KS |
---|
1309 | .NH 3 |
---|
1310 | \&Return Mount Entries |
---|
1311 | .IX "mount server procedures" MNTPROC_DUMP() "" \fIMNTPROC_DUMP()\fP |
---|
1312 | .DS |
---|
1313 | struct *mountlist { |
---|
1314 | name hostname; |
---|
1315 | dirpath directory; |
---|
1316 | mountlist nextentry; |
---|
1317 | }; |
---|
1318 | |
---|
1319 | mountlist |
---|
1320 | MNTPROC_DUMP(void) = 2; |
---|
1321 | .DE |
---|
1322 | .KE |
---|
1323 | Returns the list of remote mounted filesystems. The "mountlist" |
---|
1324 | contains one entry for each "hostname" and "directory" pair. |
---|
1325 | .KS |
---|
1326 | .NH 3 |
---|
1327 | \&Remove Mount Entry |
---|
1328 | .IX "mount server procedures" MNTPROC_UMNT() "" \fIMNTPROC_UMNT()\fP |
---|
1329 | .DS |
---|
1330 | void |
---|
1331 | MNTPROC_UMNT(dirpath) = 3; |
---|
1332 | .DE |
---|
1333 | .KE |
---|
1334 | Removes the mount list entry for the input "dirpath". |
---|
1335 | .KS |
---|
1336 | .NH 3 |
---|
1337 | \&Remove All Mount Entries |
---|
1338 | .IX "mount server procedures" MNTPROC_UMNTALL() "" \fIMNTPROC_UMNTALL()\fP |
---|
1339 | .DS |
---|
1340 | void |
---|
1341 | MNTPROC_UMNTALL(void) = 4; |
---|
1342 | .DE |
---|
1343 | .KE |
---|
1344 | Removes all of the mount list entries for this client. |
---|
1345 | .KS |
---|
1346 | .NH 3 |
---|
1347 | \&Return Export List |
---|
1348 | .IX "mount server procedures" MNTPROC_EXPORT() "" \fIMNTPROC_EXPORT()\fP |
---|
1349 | .DS |
---|
1350 | struct *groups { |
---|
1351 | name grname; |
---|
1352 | groups grnext; |
---|
1353 | }; |
---|
1354 | |
---|
1355 | struct *exportlist { |
---|
1356 | dirpath filesys; |
---|
1357 | groups groups; |
---|
1358 | exportlist next; |
---|
1359 | }; |
---|
1360 | |
---|
1361 | exportlist |
---|
1362 | MNTPROC_EXPORT(void) = 5; |
---|
1363 | .DE |
---|
1364 | .KE |
---|
1365 | Returns a variable number of export list entries. Each entry |
---|
1366 | contains a filesystem name and a list of groups that are allowed to |
---|
1367 | import it. The filesystem name is in "filesys", and the group name |
---|
1368 | is in the list "groups". |
---|
1369 | .LP |
---|
1370 | Note: The exportlist should contain |
---|
1371 | more information about the status of the filesystem, such as a |
---|
1372 | read-only flag. |
---|