Add a slightly modified version of NetBSD's diskless.8 manpage.

PR:		docs/2153
Obtained from:	NetBSD

1 files changed, 331 insertions, 0 deletions

diff --git a/share/man/man8/diskless.8 b/share/man/man8/diskless.8
new file mode 100644
index 0000000..8292598
--- /dev/null
+++ b/share/man/man8/diskless.8
@@ -0,0 +1,331 @@
+.\"	$NetBSD: diskless.8,v 1.11 1997/06/16 07:50:35 mrg Exp $
+.\"
+.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd October 2, 1994
+.Dt DISKLESS 8
+.Os
+.Sh NAME
+.Nm diskless
+.Nd booting a system over the network
+.Sh DESCRIPTION
+The ability to boot a machine over the network is useful for
+.Xr diskless
+or
+.Xr dataless
+machines, or as a temporary measure while repairing or
+re-installing filesystems on a local disk.
+This file provides a general description of the interactions between
+a client and its server when a client is booting over the network.
+The general description is followed by specific instructions for
+configuring a server for diskless Sun clients.
+.Pp
+.Sh OPERATION
+When booting a system over the network, there are three
+phases of interaction between client and server:
+.Pp
+.Bl -tag -width 1.2 -compact
+.It 1.
+The PROM (or stage-1 bootstrap) loads a boot program.
+.It 2.
+The boot program loads a kernel.
+.It 3.
+The kernel does NFS mounts for root.
+.El
+.Pp
+Each of these phases are described in further detail below.
+.Pp
+In phase 1, the PROM loads a boot program.  PROM designs
+vary widely, so this phase is inherently machine-specific.
+Sun machines use
+.Tn RARP
+to determine the client's
+.Tn IP
+address and then use
+.Tn TFTP
+to download a boot program from whoever sent the
+.Tn RARP
+reply.  HP 300-series machines use the
+.Tn HP Remote Maintenance Protocol
+to download a boot program.
+Typical personal computers may load a
+network boot program either from diskette or
+using a special PROM on the network card.
+.Pp
+In phase 2, the boot program loads a kernel.  Operation in
+this phase depends on the design of the boot program.
+(The design described here is the one used by Sun and NetBSD/hp300.)
+The boot program:
+.Pp
+.Bl -tag -width 2.2 -compact
+.It 2.1
+gets the client IP address using
+.Tn RARP .
+.It 2.2
+gets the client name and server
+.Tn IP
+address by broadcasting an
+.Tn RPC / BOOTPARAMS / WHOAMI
+request with the client IP address.
+.It 2.3
+gets the server path for this client's
+root using an
+.Tn RPC / BOOTPARAMS / GETFILE
+request with the client name.
+.It 2.4
+gets the root file handle by calling
+.Xr mountd 8
+with the server path for the client root.
+.It 2.5
+gets the kernel file handle by calling
+.Tn NFS
+lookup on the root file handle.
+.It 2.6
+loads the kernel using
+.Tn NFS
+read calls on the kernel file handle.
+.It 2.7
+transfers control to the kernel entry point.
+.El
+.Pp
+In phase 3, the kernel does NFS mounts for root.
+The kernel repeats much of the work done by the boot program
+because there is no standard way for the boot program to pass
+the information it gathered on to the kernel.
+The procedure used by the kernel is as follows:
+.Pp
+.Bl -tag -width 2.2 -compact
+.It 3.1
+The kernel finds a boot server using the same procedure
+as described in steps 2.1 and 2.2 above.
+.It 3.2
+The kernel gets the
+.Tn NFS
+file handle for root using the same procedure
+as described in steps 2.3 through 2.5 above.
+.It 3.3
+The kernel calls the
+.Tn NFS
+getattr function to get the last-modified time of the root
+directory, and uses it to check the system clock.
+.El
+.Sh CONFIGURATION
+Before a client can boot over the network,
+its server must be configured correctly.
+This example will demonstrate how a Sun client
+might be configured -- other clients should be similar.
+.Pp
+Assuming the client's hostname is to be
+"myclient",
+.Pp
+.Bl -tag -width 2.1 -compact
+.It 1.
+Add an entry to 
+.Pa /etc/ethers
+corresponding to the client's ethernet address:
+.Bd -literal -offset indent -compact
+8:0:20:7:c5:c7          myclient
+.Ed
+This will be used by
+.Xr rarpd 8 .
+.Pp
+.It 2.
+Assign an IP address for myclient in your
+.Pa /etc/hosts
+or DNS database:
+.Bd -literal -offset indent -compact
+192.197.96.12           myclient
+.Ed
+.Pp
+.It 3.
+If booting a Sun machine, ensure that
+.Pa /etc/inetd.conf
+is configured to run
+.Xr tftpd 8
+in the directory
+.Pa /tftpboot .
+.Pp
+If booting an HP 300-series machine, ensure that
+.Pa /etc/rbootd.conf
+is configured properly to transfer the boot program to the client.
+An entry might look like this:
+.Bd -literal -offset indent -compact
+08:00:09:01:23:E6	SYS_UBOOT	# myclient
+.Ed
+.Pp
+See the
+.Xr rbootd 8
+manual page for more information.
+.Pp
+.It 4.
+If booting a SPARC machine, install a copy of the appropriate diskless boot
+loader (such as
+.Pa /usr/mdec/boot )
+in the
+.Pa /tftpboot
+directory.
+Make a link such that the boot program is
+accessible by a file name composed of the client's IP address
+in HEX, a dot, and the architecture name (all upper case).
+For example:
+.Bd -literal -offset indent -compact
+# cd /tftpboot
+# ln -s boot C0C5600C.SUN4
+.Ed
+.Pp
+For a Sun3 machine, the name would be just C0C5600C
+(the sun3 PROM does not append the architecture name). The name
+used is architecture dependent, it simply has to match what the
+booting client's PROM wishes to it to be.
+If the client's PROM fails to fetch the expected file,
+.Xr tcpdump 8
+can be used to discover which filename the client is trying to read.
+.Pp
+If booting an HP 300-series machine, ensure that the network boot program
+.Pa SYS_UBOOT
+(which may be called
+.Pa uboot.lif
+before installation)
+is installed in the directory
+.Pa /usr/mdec/rbootd .
+
+.It 5.
+Add myclient to the bootparams database
+.Pa /etc/bootparams :
+.Bd -literal -offset indent -compact
+myclient  root=server:/export/myclient/root
+.Ed
+.Pp
+.It 6.
+Build the swap file for myclient:
+.Bd -literal -offset indent -compact
+# mkdir /export/myclient
+# cd /export/myclient
+# dd if=/dev/zero of=swap bs=16k count=1024
+.Ed
+This creates a 16 Megabyte swap file.
+.Pp
+.It 7.
+Populate myclient's
+.Pa /
+filesystem on the server.  How this is done depends on the
+client architecture and the version of the NetBSD distribution.
+It can be as simple as copying and modifying the server's root
+filesystem, or perhaps you need to get those files out of the
+standard binary distribution.
+.Pp
+Note that, unlike SunOS, you need to create a mount point for the
+client's swap:
+.Bd -literal -offset indent -compact
+# mkdir /export/myclient/root/swap
+.Ed
+.Pp
+.It 8.
+Export the required filesystems in
+.Pa /etc/exports :
+.Bd -literal -offset indent -compact
+/usr -ro myclient
+# for SunOS:
+# /export/myclient -rw=myclient,root=myclient
+# for NetBSD:
+/export/myclient -maproot=root -alldirs myclient
+.Ed
+.Pp
+If the server and client are of the same architecture, then the client
+can share the server's
+.Pa /usr
+filesystem (as is done above).
+If not, you must build a properly fleshed out
+.Pa /usr
+partition for the client in some other place.
+.Pp
+If your server was a sparc, and your client a sun3,
+you might create and fill
+.Pa /export/usr.sun3
+and then use the following
+.Pa /etc/exports
+lines:
+.Bd -literal -offset indent -compact
+/export/usr.sun3 -ro myclient
+/export/myclient -rw=myclient,root=myclient
+.Ed
+.Pp
+.It 9.
+Copy and customize at least the following files in
+.Pa /export/myclient/root :
+.Bd -literal -offset indent -compact
+# cd /export/myclient/root/etc
+# cp fstab.nfs fstab
+# cp /etc/hosts hosts
+# echo myclient > myname
+# echo 192.197.96.12 > hostname.le0
+.Ed
+.Pp
+Note that "le0" above should be replaced with the name of
+the network interface that the client will use for booting.
+.Pp
+.It 10.
+Correct the critical mount points and the swap file in the client's
+.Pa /etc/fstab
+(which will be
+.Pa /export/myclient/root/etc/fstab )
+ie.
+.Bd -literal -offset indent -compact
+myserver:/export/myclient/root / nfs rw 0 0
+myserver:/usr /usr nfs rw 0 0
+myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap
+.Ed
+.Pp
+Note, you must specify the swap file in
+.Pa /etc/fstab
+or it will not be used!
+.El
+.Sh FILES
+.Bl -tag -width /usr/mdec/rbootd -compact
+.It Pa /etc/ethers
+Ethernet addresses of known clients
+.It Pa /etc/bootparams
+client root pathname
+.It Pa /etc/exports
+exported NFS mount points
+.It Pa /etc/rbootd.conf
+configuration file for HP Remote Boot Daemon
+.It Pa /tftpboot
+location of boot programs loaded by the Sun PROM
+.It Pa /usr/mdec/rbootd
+location of boot programs loaded by the HP Boot ROM
+.El
+.Sh "SEE ALSO"
+.Xr rarpd 8 ,
+.Xr ethers 5 ,
+.Xr tftpd 8 ,
+.Xr bootparamd 8 ,
+.Xr bootparams 5 ,
+.Xr mountd 8 ,
+.Xr exports 5 ,
+.Xr nfsd 8 ,
+.Xr rbootd 8 ,
+.Xr reboot 8