path: root/share/man/man8/diskless.8

.\"	$OpenBSD: diskless.8,v 1.42 2006/05/18 15:57:02 jmc Exp $
.\"	$NetBSD: diskless.8,v 1.7.4.1 1996/05/30 18:58:10 cgd 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
.Em diskless
or
.Em 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 clients.
.Pp
When booting a system over the network, there are three
phases of interaction between client and server:
.Pp
.Bl -enum -compact
.It
The PROM (or stage-1 bootstrap) loads a boot program.
.It
The boot program loads a kernel.
.It
The kernel does NFS mounts for root and swap.
.El
.Pp
Each of these phases are described in further detail below.
.Pp
In
.Em phase 1 ,
the PROM loads a boot program.
PROM designs vary widely, so this phase is inherently
machine-specific.
Sun and Motorola machines use RARP to determine the client's IP address
and then use TFTP to download a boot program
from whoever sent the RARP reply.
HP 300-series machines use the
HP Remote Maintenance Protocol
to download a boot program.
Other machines may load a
network boot program either from diskette or
using a special PROM on the network card.
.Pp
In
.Em phase 2 ,
the boot program loads a kernel.
Operation in this phase depends on the design of the boot program.
The procedure used by the boot program is as follows:
.Pp
.Bl -enum -compact
.It
The boot program
gets the client IP address using RARP.
.It
The boot program
gets the client name and server IP address by broadcasting an
RPC/BOOTPARAMS/WHOAMI request with the client IP address.
.It
The boot program
gets the server path for this client's root
using an RPC/BOOTPARAMS/GETFILE request with the client name.
.It
The boot program
gets the root file handle by calling
.Xr mountd 8
with the server path for the client root.
.It
The boot program
gets the kernel file handle by calling
NFS lookup on the root file handle.
.It
The boot program
loads the kernel using
NFS read calls on the kernel file handle.
.It
The boot program
transfers control to the kernel entry point.
.El
.Pp
In
.Em phase 3 ,
the kernel does NFS mounts for root and swap.
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 -enum -compact
.It
The kernel finds a boot server using the same procedure
as described in steps 1 and 2 of phase 2, above.
.It
The kernel gets the NFS
file handle for root using the same procedure
as described in steps 3, 4, and 5 of phase 2, above.
.It
The kernel calls the NFS
getattr function to get the last-modified time of the root
directory, and uses it to check the system clock.
.It
If the kernel is configured for swap on NFS,
it uses the same mechanism as for root, but uses the NFS
getattr function to determine the size of the swap area.
.El
.Sh EXAMPLES
Before a client can boot over the network,
its server must be configured correctly.
This example will demonstrate how to configure a server and client.
.Pp
Assuming the client's hostname is to be
"myclient":
.Bl -enum
.It
Add an entry to
.Pa /etc/ethers
corresponding to the client's Ethernet address:
.Bd -literal -offset indent
8:0:20:7:c5:c7          myclient
.Ed
.Pp
This will be used by
.Xr rarpd 8 .
.Pp
.It
Assign an IP address for myclient in
.Pa /etc/hosts :
.Bd -literal -offset indent
192.197.96.12           myclient
.Ed
.Pp
.It
If booting an Alpha, HPPA64, Mips64, Motorola, Sun, or Vax client,
ensure that
.Pa /etc/inetd.conf
is configured to run
.Xr tftpd 8
in the directory
.Pa /tftpboot .
.Pp
If booting an HP 300 or HPPA 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
08:00:09:01:23:E6	SYS_UBOOT	# myclient
.Ed
.Pp
See the
.Xr rbootd 8
manual page for more information.
.Pp
.It
If booting an HPPA64, Mips64, Motorola, or Sun client,
install a copy of the appropriate diskless boot loader (such as
.Pa boot.net
from the root directory of the
.Ox
sparc tree) 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
# cd /tftpboot
# ln -s boot.net C0C5600C.SUN4
.Ed
.Pp
The following example converts an IP address to hex:
.Bd -literal -offset indent
$ echo 192.197.96.12 | awk -F . \e
	'{ printf "0x%02x%02x%02x%02x\n", $1, $2, $3 ,$4 }'
.Ed
.Pp
Some architectures, such as the Sun3 and Ultrasparc machines, do not append the
architecture name.
It this case, the name would be just C0C5600C.
The name used is architecture dependent, it simply has to match what the
booting client's PROM wishes 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 or HPPA machine, ensure that the general purpose
boot program is installed in the directory
.Pa /usr/mdec/rbootd .
.Pp
If booting an Alpha or Vax machine,
follow the instructions in
.Xr mopd 8
for setting up a TFTP boot.
.Pp
.It
Add myclient to the bootparams database
.Pa /etc/bootparams :
.Bd -literal -offset indent
myclient  root=server:/export/myclient/root \e
          swap=server:/export/myclient/swap
.Ed
.Pp
Note that some bootparam servers are somewhat sensitive.
Some require fully qualified hostnames or partially qualified hostnames
(which can be solved by having both fully and partially qualified entries).
Other servers are case sensitive.
.Pp
.It
Build the swap file for myclient:
.Bd -literal -offset indent
# mkdir -p /export/myclient/root/swap
# cd /export/myclient
# dd if=/dev/zero of=swap bs=1m count=120
.Ed
.Pp
This creates a 120 Megabyte swap file and an empty /swap directory.
A smaller swap file may be created if the boot is for
maintenance (i.e. temporary) purposes only.
.Pp
.It
Populate myclient's root
filesystem on the server.
How this is done depends on the client architecture and the version of the
.Ox
distribution.
It can be as simple as copying and modifying the server's root
filesystem, or perhaps the files can be taken from the
standard binary distribution.
.Pp
.It
Export the required filesystems in
.Pa /etc/exports :
.Bd -literal -offset indent
/usr -ro myclient
# for SunOS:
# /export/myclient -rw=myclient,root=myclient
# for OpenBSD:
/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, a properly fleshed out
.Pa /usr
partition will have to be built for the client in some other place.
.Pp
For example,
if the server is a sparc, and the client a sun3,
create and fill
.Pa /export/usr.sun3
and then use the following
.Pa /etc/exports
lines:
.Bd -literal -offset indent
/export/usr.sun3 -ro myclient
/export/myclient -rw=myclient,root=myclient
.Ed
.Pp
.It
Copy and customize at least the following files in
.Pa /export/myclient/root :
.Bd -literal -offset indent
# cd /export/myclient/root/etc
# cp /etc/fstab fstab
# cp /etc/hosts hosts
# echo myclient \*(Gt myname
# echo inet 192.197.96.12 \*(Gt 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
Correct at least
the critical mount points in the client's
.Xr fstab 5
(which will be
.Pa /export/myclient/root/etc/fstab ) :
.Bd -literal -offset indent
myserver:/export/myclient/root / nfs rw 0 0
myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap
myserver:/usr /usr nfs rw 0 0
.Ed
.It
Make sure the following processes are enabled on the server:
.Xr tftpd 8
via
.Xr inetd 8
(for Alpha, HPPA64, Mips64, Motorola, Sun, or Vax clients),
.Xr rarpd 8
(for Alpha, HPPA64, Mips64, Motorola, Sun, or Vax clients),
.Xr rbootd 8
(for HP 300 and HPPA clients),
.Xr mopd 8
(for Alpha or Vax clients),
.Xr rpc.bootparamd 8 ,
.Xr portmap 8 ,
and
.Xr nfsd 8 .
.Pp
See
.Xr rc.conf 8
for details of how to start these processes at boot.
.It
Net boot the client.
.El
.Sh FILES
.Bl -tag -width "/usr/mdec/rbootdXX" -compact
.It /etc/bootparams
Client root and swap pathnames.
.It /etc/ethers
Ethernet addresses of known clients.
.It /etc/exports
Exported NFS mount points.
.It /etc/fstab
Static information about the filesystems.
.It /etc/hostname.$if
Interface-specific configuration file.
.It /etc/hosts
Host name database.
.It /etc/myname
Default hostname and gateway.
.It /etc/rbootd.conf
Configuration file for HP Remote Boot Daemon.
.It /tftpboot
Location of boot programs loaded by the Sun PROM.
.It /usr/mdec/rbootd
Location of boot programs loaded by the HP Boot ROM.
.El
.Sh SEE ALSO
.Xr bootparams 5 ,
.Xr ethers 5 ,
.Xr exports 5 ,
.Xr fstab 5 ,
.Xr hostname.if 5 ,
.Xr hosts 5 ,
.Xr myname 5 ,
.Xr mopd 8 ,
.Xr mountd 8 ,
.Xr nfsd 8 ,
.Xr portmap 8 ,
.Xr rarpd 8 ,
.Xr rbootd 8 ,
.Xr rpc.bootparamd 8 ,
.Xr tcpdump 8 ,
.Xr tftpd 8