Use rtld's TLS interface to allocate tcb.
[dragonfly.git] / share / doc / smm / 06.nfs / 1.t
1 .\" Copyright (c) 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" This document is derived from software contributed to Berkeley by
5 .\" Rick Macklem at The University of Guelph.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\"    must display the following acknowledgement:
17 .\"     This product includes software developed by the University of
18 .\"     California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\"    may be used to endorse or promote products derived from this software
21 .\"    without specific prior written permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\"     @(#)1.t 8.1 (Berkeley) 6/8/93
36 .\"
37 .sh 1 "NFS Implementation"
38 .pp
39 The 4.4BSD implementation of NFS and the alternate protocol nicknamed
40 Not Quite NFS (NQNFS) are kernel resident, but make use of a few system
41 daemons.
42 The kernel implementation does not use an RPC library, handling the RPC
43 request and reply messages directly in \fImbuf\fR data areas. NFS
44 interfaces to the network using
45 sockets via. the kernel interface available in
46 \fIsys/kern/uipc_syscalls.c\fR as \fIsosend(), soreceive(),\fR...
47 There are connection management routines for support of sockets for connection
48 oriented protocols and timeout/retransmit support for datagram sockets on
49 the client side.
50 For connection oriented transport protocols,
51 such as TCP/IP, there is one connection
52 for each client to server mount point that is maintained until an umount.
53 If the connection breaks, the client will attempt a reconnect with a new
54 socket.
55 The client side can operate without any daemons running, but performance
56 will be improved by running nfsiod daemons that perform read-aheads
57 and write-behinds.
58 For the server side to function, the daemons portmap, mountd and
59 nfsd must be running.
60 The mountd daemon performs two important functions.
61 .ip 1)
62 Upon startup and after a hangup signal, mountd reads the exports
63 file and pushes the export information for each local file system down
64 into the kernel via. the mount system call.
65 .ip 2)
66 Mountd handles remote mount protocol (RFC1094, Appendix A) requests.
67 .lp
68 The nfsd master daemon forks off children that enter the kernel
69 via. the nfssvc system call. The children normally remain kernel
70 resident, providing a process context for the NFS RPC servers. The only
71 exception to this is when a Kerberos [Steiner88]
72 ticket is received and at that time
73 the nfsd exits the kernel temporarily to verify the ticket via. the
74 Kerberos libraries and then returns to the kernel with the results.
75 (This only happens for Kerberos mount points as described further under
76 Security.)
77 Meanwhile, the master nfsd waits to accept new connections from clients
78 using connection oriented transport protocols and passes the new sockets down
79 into the kernel.
80 The client side mount_nfs along with portmap and
81 mountd are the only parts of the NFS subsystem that make any
82 use of the Sun RPC library.
83 .sh 1 "Mount Problems"
84 .pp
85 There are several problems that can be encountered at the time of an NFS
86 mount, ranging from a unresponsive NFS server (crashed, network partitioned
87 from client, etc.) to various interoperability problems between different
88 NFS implementations.
89 .pp
90 On the server side,
91 if the 4.4BSD NFS server will be handling any PC clients, mountd will
92 require the \fB-n\fR option to enable non-root mount request servicing.
93 Running of a pcnfsd\** daemon will also be necessary.
94 .(f
95 \** Pcnfsd is available in source form from Sun Microsystems and many
96 anonymous ftp sites.
97 .)f
98 The server side requires that the daemons
99 mountd and nfsd be running and that
100 they be registered with portmap properly.
101 If problems are encountered,
102 the safest fix is to kill all the daemons and then restart them in
103 the order portmap, mountd and nfsd.
104 Other server side problems are normally caused by problems with the format
105 of the exports file, which is covered under
106 Security and in the exports man page.
107 .pp
108 On the client side, there are several mount options useful for dealing
109 with server problems.
110 In cases where a file system is not critical for system operation, the
111 \fB-b\fR
112 mount option may be specified so that mount_nfs will go into the
113 background for a mount attempt on an unresponsive server.
114 This is useful for mounts specified in
115 \fIfstab(5)\fR,
116 so that the system will not get hung while booting doing
117 \fBmount -a\fR
118 because a file server is not responsive.
119 On the other hand, if the file system is critical to system operation, this
120 option should not be used so that the client will wait for the server to
121 come up before completing bootstrapping.
122 There are also three mount options to help deal with interoperability issues
123 with various non-BSD NFS servers. The
124 \fB-P\fR
125 option specifies that the NFS
126 client use a reserved IP port number to satisfy some servers' security
127 requirements.\**
128 .(f
129 \**Any security benefit of this is highly questionable and as
130 such the BSD server does not require a client to use a reserved port number.
131 .)f
132 The
133 \fB-c\fR
134 option stops the NFS client from doing a \fIconnect\fR on the UDP
135 socket, so that the mount works with servers that send NFS replies from
136 port numbers other than the standard 2049.\**
137 .(f
138 \**The Encore Multimax is known
139 to require this.
140 .)f
141 Finally, the
142 \fB-g=\fInum\fR
143 option sets the maximum size of the group list in the credentials passed
144 to an NFS server in every RPC request. Although RFC1057 specifies a maximum
145 size of 16 for the group list, some servers can't handle that many.
146 If a user, particularly root doing a mount,
147 keeps getting access denied from a file server, try temporarily
148 reducing the number of groups that user is in to less than 5
149 by editing /etc/group. If the user can then access the file system, slowly
150 increase the number of groups for that user until the limit is found and
151 then peg the limit there with the
152 \fB-g=\fInum\fR
153 option.
154 This implies that the server will only see the first \fInum\fR
155 groups that the user is in, which can cause some accessibility problems.
156 .pp
157 For sites that have many NFS servers, amd [Pendry93]
158 is a useful administration tool.
159 It also reduces the number of actual NFS mount points, alleviating problems
160 with commands such as df(1) that hang when any of the NFS servers is
161 unreachable.
162 .sh 1 "Dealing with Hung Servers"
163 .pp
164 There are several mount options available to help a client deal with
165 being hung waiting for response from a crashed or unreachable\** server.
166 .(f
167 \**Due to a network partitioning or similar.
168 .)f
169 By default, a hard mount will continue to try to contact the server
170 ``forever'' to complete the system call. This type of mount is appropriate
171 when processes on the client that access files in the file system do not
172 tolerate file I/O systems calls that return -1 with \fIerrno == EINTR\fR
173 and/or access to the file system is critical for normal system operation.
174 .lp
175 There are two other alternatives:
176 .ip 1)
177 A soft mount (\fB-s\fR option) retries an RPC \fIn\fR
178 times and then the corresponding
179 system call returns -1 with errno set to EINTR.
180 For TCP transport, the actual RPC request is not retransmitted, but the
181 timeout intervals waiting for a reply from the server are done
182 in the same manner as UDP for this purpose.
183 The problem with this type of mount is that most applications do not
184 expect an EINTR error return from file I/O system calls (since it never
185 occurs for a local file system) and get confused by the error return
186 from the I/O system call.
187 The option
188 \fB-x=\fInum\fR
189 is used to set the RPC retry limit and if set too low, the error returns
190 will start occurring whenever the NFS server is slow due to heavy load.
191 Alternately, a large retry limit can result in a process hung for a long
192 time, due to a crashed server or network partitioning.
193 .ip 2)
194 An interruptible mount (\fB-i\fR option) checks to see if a termination signal
195 is pending for the process when waiting for server response and if it is,
196 the I/O system call posts an EINTR. Normally this results in the process
197 being terminated by the signal when returning from the system call.
198 This feature allows you to ``^C'' out of processes that are hung
199 due to unresponsive servers.
200 The problem with this approach is that signals that are caught by
201 a process are not recognized as termination signals
202 and the process will remain hung.\**
203 .(f
204 \**Unfortunately, there are also some resource allocation situations in the
205 BSD kernel where the termination signal will be ignored and the process
206 will not terminate.
207 .)f
208 .sh 1 "RPC Transport Issues"
209 .pp
210 The NFS Version 2 protocol runs over UDP/IP transport by
211 sending each Sun Remote Procedure Call (RFC1057)
212 request/reply message in a single UDP
213 datagram. Since UDP does not guarantee datagram delivery, the
214 Remote Procedure Call (RPC) layer
215 times out and retransmits an RPC request if
216 no RPC reply has been received. Since this round trip timeout (RTO) value 
217 is for the entire RPC operation, including RPC message transmission to the
218 server, queuing at the server for an nfsd, performing the RPC and
219 sending the RPC reply message back to the client, it can be highly variable
220 for even a moderately loaded NFS server.
221 As a result, the RTO interval must be a conservation (large) estimate, in
222 order to avoid extraneous RPC request retransmits.\**
223 .(f
224 \**At best, an extraneous RPC request retransmit increases
225 the load on the server and at worst can result in damaged files
226 on the server when non-idempotent RPCs are redone [Juszczak89].
227 .)f
228 Also, with an 8Kbyte read/write data size
229 (the default), the read/write reply/request will be an 8+Kbyte UDP datagram
230 that must normally be fragmented at the IP layer for transmission.\**
231 .(f
232 \**6 IP fragments for an Ethernet,
233 which has an maximum transmission unit of 1500bytes.
234 .)f
235 For IP fragments to be successfully reassembled into
236 the IP datagram at the receive end, all
237 fragments must be received within a fairly short ``time to live''.
238 If one fragment is lost/damaged in transit,
239 the entire RPC must be retransmitted and redone.
240 This problem can be exaggerated by a network interface on the receiver that
241 cannot handle the reception of back to back network packets. [Kent87a]
242 .pp
243 There are several tuning mount
244 options on the client side that can prove useful when trying to
245 alleviate performance problems related to UDP RPC transport.
246 The options
247 \fB-r=\fInum\fR
248 and
249 \fB-w=\fInum\fR
250 specify the maximum read or write data size respectively.
251 The size \fInum\fR
252 should be a power of 2 (4K, 2K, 1K) and adjusted downward from the
253 maximum of 8Kbytes
254 whenever IP fragmentation is causing problems. The best indicator of
255 IP fragmentation problems is a significant number of
256 \fIfragments dropped after timeout\fR
257 reported by the \fIip:\fR section of a \fBnetstat -s\fR
258 command on either the client or server.
259 Of course, if the fragments are being dropped at the server, it can be
260 fun figuring out which client(s) are involved.
261 The most likely candidates are clients that are not
262 on the same local area network as the
263 server or have network interfaces that do not receive several
264 back to back network packets properly.
265 .pp
266 By default, the 4.4BSD NFS client dynamically estimates the retransmit
267 timeout interval for the RPC and this appears to work reasonably well for
268 many environments. However, the
269 \fB-d\fR
270 flag can be specified to turn off
271 the dynamic estimation of retransmit timeout, so that the client will
272 use a static initial timeout interval.\**
273 .(f
274 \**After the first retransmit timeout, the initial interval is backed off
275 exponentially.
276 .)f
277 The
278 \fB-t=\fInum\fR
279 option can be used with
280 \fB-d\fR
281 to set the initial timeout interval to other than the default of 2 seconds.
282 The best indicator that dynamic estimation should be turned off would
283 be a significant number\** in the \fIX Replies\fR field and a
284 .(f
285 \**Even 0.1% of the total RPCs is probably significant.
286 .)f
287 large number in the \fIRetries\fR field
288 in the \fIRpc Info:\fR section as reported
289 by the \fBnfsstat\fR command.
290 On the server, there would be significant numbers of \fIInprog\fR recent
291 request cache hits in the \fIServer Cache Stats:\fR section as reported
292 by the \fBnfsstat\fR command, when run on the server.
293 .pp
294 The tradeoff is that a smaller timeout interval results in a better
295 average RPC response time, but increases the risk of extraneous retries
296 that in turn increase server load and the possibility of damaged files
297 on the server. It is probably best to err on the safe side and use a large
298 (>= 2sec) fixed timeout if the dynamic retransmit timeout estimation
299 seems to be causing problems.
300 .pp
301 An alternative to all this fiddling is to run NFS over TCP transport instead
302 of UDP.
303 Since the 4.4BSD TCP implementation provides reliable
304 delivery with congestion control, it avoids all of the above problems.
305 It also permits the use of read and write data sizes greater than the 8Kbyte
306 limit for UDP transport.\**
307 .(f
308 \**Read/write data sizes greater than 8Kbytes will not normally improve
309 performance unless the kernel constant MAXBSIZE is increased and the
310 file system on the server has a block size greater than 8Kbytes.
311 .)f
312 NFS over TCP usually delivers comparable to significantly better performance
313 than NFS over UDP
314 unless the client or server processor runs at less than 5-10MIPS. For a
315 slow processor, the extra CPU overhead of using TCP transport will become
316 significant and TCP transport may only be useful when the client
317 to server interconnect traverses congested gateways.
318 The main problem with using TCP transport is that it is only supported
319 between BSD clients and servers.\**
320 .(f
321 \**There are rumors of commercial NFS over TCP implementations on the horizon
322 and these may well be worth exploring.
323 .)f
324 .sh 1 "Other Tuning Tricks"
325 .pp
326 Another mount option that may improve performance over
327 certain network interconnects is \fB-a=\fInum\fR
328 which sets the number of blocks that the system will
329 attempt to read-ahead during sequential reading of a file. The default value
330 of 1 seems to be appropriate for most situations, but a larger value might
331 achieve better performance for some environments, such as a mount to a server
332 across a ``high bandwidth * round trip delay'' interconnect.
333 .pp
334 For the adventurous, playing with the size of the buffer cache
335 can also improve performance for some environments that use NFS heavily.
336 Under some workloads, a buffer cache of 4-6Mbytes can result in significant
337 performance improvements over 1-2Mbytes, both in client side system call
338 response time and reduced server RPC load.
339 The buffer cache size defaults to 10% of physical memory,
340 but this can be overridden by specifying the BUFPAGES option
341 in the machine's config file.\**
342 .(f
343 BUFPAGES is the number of physical machine pages allocated to the buffer cache.
344 ie. BUFPAGES * NBPG = buffer cache size in bytes
345 .)f
346 When increasing the size of BUFPAGES, it is also advisable to increase the
347 number of buffers NBUF by a corresponding amount.
348 Note that there is a tradeoff of memory allocated to the buffer cache versus
349 available for paging, which implies that making the buffer cache larger
350 will increase paging rate, with possibly disastrous results.
351 .sh 1 "Security Issues"
352 .pp
353 When a machine is running an NFS server it opens up a great big security hole.
354 For ordinary NFS, the server receives client credentials
355 in the RPC request as a user id
356 and a list of group ids and trusts them to be authentic!
357 The only tool available to restrict remote access to
358 file systems with is the exports(5) file,
359 so file systems should be exported with great care.
360 The exports file is read by mountd upon startup and after a hangup signal
361 is posted for it and then as much of the access specifications as possible are
362 pushed down into the kernel for use by the nfsd(s).
363 The trick here is that the kernel information is stored on a per
364 local file system mount point and client host address basis and cannot refer to
365 individual directories within the local server file system.
366 It is best to think of the exports file as referring to the various local
367 file systems and not just directory paths as mount points.
368 A local file system may be exported to a specific host, all hosts that
369 match a subnet mask or all other hosts (the world). The latter is very
370 dangerous and should only be used for public information. It is also
371 strongly recommended that file systems exported to ``the world'' be exported
372 read-only.
373 For each host or group of hosts, the file system can be exported read-only or
374 read/write.
375 You can also define one of three client user id to server credential
376 mappings to help control access.
377 Root (user id == 0) can be mapped to some default credentials while all other
378 user ids are accepted as given.
379 If the default credentials for user id equal zero
380 are root, then there is essentially no remapping.
381 Most NFS file systems are exported this way, most commonly mapping
382 user id == 0 to the credentials for the user nobody.
383 Since the client user id and group id list is used unchanged on the server
384 (except for root), this also implies that
385 the user id and group id space must be common between the client and server.
386 (ie. user id N on the client must refer to the same user on the server)
387 All user ids can be mapped to a default set of credentials, typically that of
388 the user nobody. This essentially gives world access to all
389 users on the corresponding hosts.
390 .pp
391 There is also a non-standard BSD
392 \fB-kerb\fR export option that requires the client provide
393 a KerberosIV rcmd service ticket to authenticate the user on the server.
394 If successful, the Kerberos principal is looked up in the server's password
395 and group databases to get a set of credentials and a map of client userid to
396 these credentials is then cached.
397 The use of TCP transport is strongly recommended,
398 since the scheme depends on the TCP connection to avert replay attempts.
399 Unfortunately, this option is only usable
400 between BSD clients and servers since it is
401 not compatible with other known ``kerberized'' NFS systems.
402 To enable use of this Kerberos option, both mount_nfs on the client and
403 nfsd on the server must be rebuilt with the -DKERBEROS option and
404 linked to KerberosIV libraries.
405 The file system is then exported to the client(s) with the \fB-kerb\fR option
406 in the exports file on the server
407 and the client mount specifies the
408 \fB-K\fR
409 and
410 \fB-T\fR
411 options.
412 The
413 \fB-m=\fIrealm\fR
414 mount option may be used to specify a Kerberos Realm for the ticket
415 (it must be the Kerberos Realm of the server) that is other than
416 the client's local Realm.
417 To access files in a \fB-kerb\fR mount point, the user must have a valid
418 TGT for the server's Realm, as provided by kinit or similar.
419 .pp
420 As well as the standard NFS Version 2 protocol (RFC1094) implementation, BSD
421 systems can use a variant of the protocol called Not Quite NFS (NQNFS) that
422 supports a variety of protocol extensions.
423 This protocol uses 64bit file offsets
424 and sizes, an \fIaccess rpc\fR, an \fIappend\fR option on the write rpc
425 and extended file attributes to support 4.4BSD file system functionality
426 more fully.
427 It also makes use of a variant of short term
428 \fIleases\fR [Gray89] with delayed write client caching,
429 in an effort to provide full cache consistency and better performance.
430 This protocol is available between 4.4BSD systems only and is used when
431 the \fB-q\fR mount option is specified.
432 It can be used with any of the aforementioned options for NFS, such as TCP
433 transport (\fB-T\fR) and KerberosIV authentication (\fB-K\fR).
434 Although this protocol is experimental, it is recommended over NFS for
435 mounts between 4.4BSD systems.\**
436 .(f
437 \**I would appreciate email from anyone who can provide
438 NFS vs. NQNFS performance measurements,
439 particularly fast clients, many clients or over an internetwork
440 connection with a large ``bandwidth * RTT'' product.
441 .)f
442 .sh 1 "Monitoring NFS Activity"
443 .pp
444 The basic command for monitoring NFS activity on clients and servers is
445 nfsstat. It reports cumulative statistics of various NFS activities,
446 such as counts of the various different RPCs and cache hit rates on the client
447 and server. Of particular interest on the server are the fields in the
448 \fIServer Cache Stats:\fR section, which gives numbers for RPC retries received
449 in the first three fields and total RPCs in the fourth. The first three fields
450 should remain a very small percentage of the total. If not, it
451 would indicate one or more clients doing retries too aggressively and the fix
452 would be to isolate these clients,
453 disable the dynamic RTO estimation on them and
454 make their initial timeout interval a conservative (ie. large) value.
455 .pp
456 On the client side, the fields in the \fIRpc Info:\fR section are of particular
457 interest, as they give an overall picture of NFS activity.
458 The \fITimedOut\fR field is the number of I/O system calls that returned -1
459 for ``soft'' mounts and can be reduced
460 by increasing the retry limit or changing
461 the mount type to ``intr'' or ``hard''.
462 The \fIInvalid\fR field is a count of trashed RPC replies that are received
463 and should remain zero.\**
464 .(f
465 \**Some NFS implementations run with UDP checksums disabled, so garbage RPC
466 messages can be received.
467 .)f
468 The \fIX Replies\fR field counts the number of repeated RPC replies received
469 from the server and is a clear indication of a too aggressive RTO estimate.
470 Unfortunately, a good NFS server implementation will use a ``recent request
471 cache'' [Juszczak89] that will suppress the extraneous replies.
472 A large value for \fIRetries\fR indicates a problem, but
473 it could be any of:
474 .ip \(bu
475 a too aggressive RTO estimate
476 .ip \(bu
477 an overloaded NFS server
478 .ip \(bu
479 IP fragments being dropped (gateway, client or server)
480 .lp
481 and requires further investigation.
482 The \fIRequests\fR field is the total count of RPCs done on all servers.
483 .pp
484 The \fBnetstat -s\fR comes in useful during investigation of RPC transport
485 problems.
486 The field \fIfragments dropped after timeout\fR in
487 the \fIip:\fR section indicates IP fragments are
488 being lost and a significant number of these occurring indicates that the
489 use of TCP transport or a smaller read/write data size is in order.
490 A significant number of \fIbad checksums\fR reported in the \fIudp:\fR
491 section would suggest network problems of a more generic sort.
492 (cabling, transceiver or network hardware interface problems or similar)
493 .pp
494 There is a RPC activity logging facility for both the client and
495 server side in the kernel.
496 When logging is enabled by setting the kernel variable nfsrtton to
497 one, the logs in the kernel structures nfsrtt (for the client side)
498 and nfsdrt (for the server side) are updated upon the completion
499 of each RPC in a circular manner.
500 The pos element of the structure is the index of the next element
501 of the log array to be updated.
502 In other words, elements of the log array from \fIlog\fR[pos] to
503 \fIlog\fR[pos - 1] are in chronological order.
504 The include file <sys/nfsrtt.h> should be consulted for details on the
505 fields in the two log structures.\**
506 .(f
507 \**Unfortunately, a monitoring tool that uses these logs is still in the
508 planning (dreaming) stage.
509 .)f
510 .sh 1 "Diskless Client Support"
511 .pp
512 The NFS client does include kernel support for diskless/dataless operation
513 where the root file system and optionally the swap area is remote NFS mounted.
514 A diskless/dataless client is configured using a version of the
515 ``swapkernel.c'' file as provided in the directory \fIcontrib/diskless.nfs\fR.
516 If the swap device == NODEV, it specifies an NFS mounted swap area and should
517 be configured the same size as set up by diskless_setup when run on the server.
518 This file must be put in the \fIsys/compile/<machine_name>\fR kernel build
519 directory after the config command has been run, since config does
520 not know about specifying NFS root and swap areas.
521 The kernel variable mountroot must be set to nfs_mountroot instead of
522 ffs_mountroot and the kernel structure nfs_diskless must be filled in
523 properly.
524 There are some primitive system administration tools in the \fIcontrib/diskless.nfs\fR directory to assist in filling in
525 the nfs_diskless structure and in setting up an NFS server for
526 diskless/dataless clients.
527 The tools were designed to provide a bare bones capability, to allow maximum
528 flexibility when setting up different servers.
529 .lp
530 The tools are as follows:
531 .ip \(bu
532 diskless_offset.c - This little program reads a ``kernel'' object file and
533 writes the file byte offset of the nfs_diskless structure in it to
534 standard out. It was kept separate because it sometimes has to
535 be compiled/linked in funny ways depending on the client architecture.
536 (See the comment at the beginning of it.)
537 .ip \(bu
538 diskless_setup.c - This program is run on the server and sets up files for a
539 given client. It mostly just fills in an nfs_diskless structure and
540 writes it out to either the "kernel" file or a separate file called
541 /var/diskless/setup.<official-hostname>
542 .ip \(bu
543 diskless_boot.c - There are two functions in here that may be used
544 by a bootstrap server such as tftpd to permit sharing of the ``kernel''
545 object file for similar clients. This saves disk space on the bootstrap
546 server and simplify organization, but are not critical for correct operation.
547 They read the ``kernel''
548 file, but optionally fill in the nfs_diskless structure from a
549 separate "setup.<official-hostname>" file so that there is only
550 one copy of "kernel" for all similar (same arch etc.) clients.
551 These functions use a text file called
552 /var/diskless/boot.<official-hostname> to control the netboot.
553 .lp
554 The basic setup steps are:
555 .ip \(bu
556 make a "kernel" for the client(s) with mountroot() == nfs_mountroot()
557 and swdevt[0].sw_dev == NODEV if it is to do nfs swapping as well
558 (See the same swapkernel.c file)
559 .ip \(bu
560 run diskless_offset on the kernel file to find out the byte offset
561 of the nfs_diskless structure
562 .ip \(bu
563 Run diskless_setup on the server to set up the server and fill in the
564 nfs_diskless structure for that client.
565 The nfs_diskless structure can either be written into the
566 kernel file (the -x option) or
567 saved in /var/diskless/setup.<official-hostname>.
568 .ip \(bu
569 Set up the bootstrap server. If the nfs_diskless structure was written into
570 the ``kernel'' file, any vanilla bootstrap protocol such as bootp/tftp can
571 be used. If the bootstrap server has been modified to use the functions in
572 diskless_boot.c, then a
573 file called /var/diskless/boot.<official-hostname>
574 must be created.
575 It is simply a two line text file, where the first line is the pathname
576 of the correct ``kernel'' file and the second line has the pathname of
577 the nfs_diskless structure file and its byte offset in it.
578 For example:
579 .br
580         /var/diskless/kernel.pmax
581 .br
582         /var/diskless/setup.rickers.cis.uoguelph.ca 642308
583 .br
584 .ip \(bu
585 Create a /var subtree for each client in an appropriate place on the server,
586 such as /var/diskless/var/<client-hostname>/...
587 By using the <client-hostname> to differentiate /var for each host,
588 /etc/rc can be modified to mount the correct /var from the server.