.\"	$NetBSD: diskless.8,v 1.34 2018/10/29 21:04:18 wiz 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 23, 2018
.Dt DISKLESS 8
.Os
.Sh NAME
.Nm diskless
.Nd booting a system over the network
.Sh DESCRIPTION
The ability to boot a system over the network is useful for
two kinds of systems:
.Bl -tag -width diskless
.It Em diskless
a system with no attached mass storage media to boot or run from
.Pq e.g. a network computer .
.It Em dataless
a system with a hard drive that only contains system and application
software, and user data is mounted over the network from a central server.
.El
.Pp
It can also be done as a temporary measure while repairing or
re-installing file systems on a local disk.
This capability is necessarily platform dependent because of its
dependence on system firmware support; not all platforms supported by
.Nx
are capable of being network booted.
.Pp
The protocols used to obtain a network address
.Pq e.g. an Tn \&IP host address ,
include, but are not limited to:
.Pp
.Bl -tag -width BOOTP -offset indent -compact
.It Tn RARP
Reverse Address Resolution Protocol
.Pq Tn ARP
.It Tn DHCP
Dynamic Host Configuration Protocol
.It Tn BOOTP
Bootstrap Protocol
.El
.Pp
This information can also be derived from non-volatile
.Tn RAM
or by a transform of a network interface
.Pq e.g. Tn Ethernet
.Tn MAC
address.
.Pp
The protocols used to load a
.Nx
kernel over a network include, but are not limited to:
.Pp
.Bl -tag -width TFTP -offset indent -compact
.It Tn TFTP
Trivial File Transfer Protocol
.It Tn NFS
.Tn Sun
Network File System
.It Tn RMP
.Tn \&HP
Remote Maintenance Protocol
.It Tn MOP
.Tn DEC
Maintenance Operations Protocol
.El
.Pp
Derivation of the filename of the secondary bootstrap program can
be done by a transform of a network interface
.Tn MAC
address
.Pq or other protocol address ,
or provided by a server as with
.Tn BOOTP ,
and
.Tn DHCP .
How this is done is platform dependent; see
.Xr boot 8 .
.Pp
The
.Nx
kernel doesn't care how it gets loaded and started.
The protocols used to boot
.Nx
can be completely different than the ones that
.Nx
uses operationally, i.e. you can netboot the system using
.Tn \&HP
.Tn RMP
and the
.Nx
kernel can use
.Tn \&IP
to communicate after bootstrap.
.Pp
There is no standard way to pass all the required information
from a boot loader to an operating system kernel, so the
.Nx
kernel usually has to recapitulate the same
.Pq or similar
protocol exchanges over the network to obtain a network address,
determine which servers to use, and so on.
.Nx
supports obtaining this information from
.Tn RARP ,
.Tn BOOTP ,
.Tn DHCP ,
and
.Tn Sun RPC
.Qq bootparams .
See
.Xr options 4
for a list of methods that can be compiled into a
.Nx
kernel.
.Pp
.Nx
only supports the
.Tn Sun
Network File System
.Pq Tn NFS
for mounting its root file system over a network.
.Nx
can use any local mass storage device for which it has a driver,
after bootstrap, even if that device is not supported by the system's
firmware for booting.
.Pp
.Sy N.B.
.Tn DHCP
is essentially a series of extensions to
.Tn BOOTP ;
the
.Nx
.Xr dhcpd 8
is capable of responding to both kinds of protocol requests.
.Pp
In the majority of configurations, network boot servers and clients
are attached to the same
.Tn LAN
so that broadcast queries from the clients can be heard by the servers.
Unless specially configured, routers block broadcasts from propagating from
.Tn LAN
to
.Tn LAN ;
some routers can be configured to
.Qq forward
broadcast
.Tn BOOTP
packets to another
.Tn LAN
attached to that router, which permits a server on that remote
.Tn LAN
to respond to the client's broadcast query.
.Sh OPERATION
When booting a system over the network, there are three
phases of interaction between client and server:
.Pp
.Bl -enum -compact
.It
The system firmware
.Pq or stage-1 bootstrap
loads a boot program.
.It
The boot program loads a
.Nx
kernel.
.It
The
.Nx
kernel performs an
.Tn NFS
mount of the root file system.
.El
.Pp
Each of these phases are described in further detail below.
.Ss 1. loading a boot program
In phase 1, the system firmware loads a boot program.
Firmware designs vary widely,
so this phase is inherently machine-specific.
Some examples:
.Pp
.Tn DEC
Alpha systems use
.Tn BOOTP
to determine the client's
.Tn \&IP
address and then use
.Tn TFTP
load a secondary bootstrap program from the server and filename
specified in the
.Tn BOOTP
reply.
.Tn DEC
Alpha systems can also use
.Tn MOP
to load a program to run the system.
.Pp
.Tn Sun
systems use
.Tn RARP
to determine the client's
.Tn \&IP
address, transform that address to a hexadecimal string to form
the filename of the secondary boot program, and then use
.Tn TFTP
to download the boot program from the server that sent the
.Tn RARP
reply.
.Pp
.Tn \&HP
300-series systems use the
.Tn \&HP
.Tn RMP
to download a boot program.
.Pp
Typical personal computers may load a network boot program either
from diskette or from a
.Tn PROM
on a Network Interface Card
.Pq Tn NIC .
Some
.Tn BIOS Ns No \&es
support booting from a network interface.
.Ss 2. loading a kernel
In phase 2, the secondary boot program loads a kernel.
Operation in this phase depends on the design of the boot program
.Po
the design described here is the one used by
.Tn Sun
and
.Nx Ns Tn /hp300
.Pc .
The boot program:
.Pp
.Bl -enum -compact
.It
gets the client
.Tn \&IP
address using
.Tn RARP .
.It
gets the client name and server
.Tn \&IP
address by broadcasting an
.Tn RPC / BOOTPARAMS / WHOAMI
request with the client
.Tn \&IP
address.
.It
gets the server path for this client's
root using an
.Tn RPC / BOOTPARAMS / GETFILE
request with the client name.
.It
gets the root file handle by calling
.Xr mountd 8
with the server path for the client root file system.
.It
gets the kernel file handle by calling
.Tn NFS
.Fn lookup
on the root file handle.
.It
loads the kernel using
.Tn NFS
read calls on the kernel file handle.
.It
transfers control to the kernel entry point.
.El
.Pp
A
.Tn BOOTP
and/or
.Tn DHCP
secondary bootstrap program will do the following:
.Pp
.Bl -enum -compact
.It
query for the client's bootstrap parameters.
The response must include the client's
.Tn \&IP
address, and a
.Tn TFTP
server to load the
.Nx
kernel from.
.It
loads the
.Nx
kernel from the
.Tn TFTP
server.
.It
transfers control to the kernel entry point.
.El
.Ss 3. NFS mounting the root file system
In phase 3, the kernel performs an
.Tn NFS
mount of the root file system.
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.
.Pp
In general, the GENERIC kernel
.Xr config 1
file for any particular architecture will specify compile-time
options to use the same protocol used by the secondary boot program
for that architecture.
A
.Nx
kernel can be compiled to use any of
.Tn BOOTP ,
.Tn DHCP ,
or
.Tn Sun RPC BOOTPARAMS ;
see
.Xr options 4 .
.Pp
The procedure typically used by the kernel is as follows:
.Pp
.Bl -enum -compact
.It
The kernel finds a boot server using the same procedures
as described above to determine the client's
.Tn \&IP
address, an
.Tn NFS
server, etc.
.It
The kernel gets the
.Tn NFS
file handle for root using the same procedure as described above.
.It
The kernel calls the
.Tn NFS
.Fn getattr
function to get the last-modified time of the root
directory, and uses it to check the system clock.
.El
.Sh SERVER CONFIGURATION
Before a client can bootstrap over the network,
its server must be configured.
Each daemon that implements these protocols must be set up so
that it can answer queries from the clients.
Some of these daemons are invoked as packets come in, by
.Xr inetd 8 ,
and some must run independently, started from
.Pa /etc/rc ;
see
.Xr rc.conf 5 .
.Bl -column "Protocol" "rpc.bootparamd" "inetd.conf(5)" -offset indent
.It Sy Protocol Ta Sy Program Ta Sy Startup
.It RARP Ta rarpd Ta Xr rc.conf 5
.It DHCP Ta dhcpd Ta Xr rc.conf 5
.It BOOTP Ta bootpd Ta Xr inetd.conf 5
.It TFTP Ta tftpd Ta Xr inetd.conf 5
.It Sun RPC Ta rpcbind Ta Xr rc.conf 5
.It Sun RPC Ta rpc.bootparamd Ta Xr rc.conf 5
.It Sun NFS Ta mountd Ta Xr rc.conf 5
.It Sun NFS Ta nfsiod Ta Xr rc.conf 5
.It \&HP RMP Ta rbootd Ta Xr rc.conf 5
.El
.Pp
.Sy N.B.
.Tn DHCP
is essentially a series of extensions to
.Tn BOOTP ;
the
.Nx
.Xr dhcpd 8
is capable of responding to both kinds of protocol requests.
Since they both bind to the same
.Tn UDP
port, only one may be run on a given server.
.Pp
In the following examples, the client's hostname is
.Sy myclient ;
the server is
.Sy myserver ,
and the addresses are all fictional.
In these examples
the hostnames may be Fully Qualified Domain Names
.Pq FQDN, e.g. Qq myclient.mydomain.com
provided that they are used consistently.
.Ss RARP
For clients that use
.Tn RARP
to obtain their
.Tn \&IP
address,
an entry must be added for each client to
.Pa /etc/ethers
with the client's
.Tn Ethernet
.Tn MAC
address and Internet hostname:
.Pp
.Bd -literal -offset indent -compact
8:0:20:7:c5:c7          myclient
.Ed
.Pp
This will be used by
.Xr rarpd 8
to reply to queries from the clients.
There must be one entry per client system.
.Pp
A client system's
.Tn Ethernet
.Tn MAC
address is often printed on the system case, or on a chip on its
motherboard, or on the
.Tn NIC .
If not,
.Qq sniffing
the network with
.Xr tcpdump 8
when the client is powered-on should reveal its
.Tn Ethernet
.Tn MAC
address.
.Pp
Each client system that uses
.Tn RARP
must have its own, unique
.Tn \&IP
address assigned to it.
Assign an
.Tn \&IP
address for myclient in your
.Pa /etc/hosts
file, or in the master file for your
.Tn DNS
zone.
For
.Pa /etc/hosts
the entry should look like:
.Pp
.Bd -literal -offset indent -compact
192.197.96.12           myclient
.Ed
.Ss DHCP/BOOTP
The
.Nx
.Tn DHCP
server
.Xr dhcpd 8
was developed by the Internet Software Consortium
.Pq Lk http://www.isc.org/ "ISC" .
.Pp
.Tn DHCP
can provide a wide range of information to a requesting client;
the key data for bootstrapping a diskless client are:
.Pp
.Bl -enum -compact
.It
an
.Tn \&IP
address
.It
a subnet mask
.It
a
.Tn TFTP
server address for loading the secondary bootstrap and the
.Nx
kernel
.It
a filename of the secondary bootstrap
.It
an
.Tn NFS
server address for the client's file system
.It
the client's root file system path, to be
.Tn NFS
mounted.
.El
.Pp
An example for
.Pa /etc/dhcpd.conf
.Bd -literal -offset indent
host myclient {
	hardware ethernet 8:0:20:7:c5:c7;
	fixed-address myclient;		# client's assigned IP address
	filename "myclient.netboot";	# secondary bootstrap
	next-server myserver;		# TFTP server for secondary bootstrap
	option swap-server myserver;	# NFS server for root filesystem
	option root-path "/export/myclient/root";
}
.Ed
.Pp
That
.Sy host
declaration goes inside a
.Sy subnet
declaration, which gives parameters for all hosts on the subnet
that will be using
.Tn DHCP ,
such as the
.Qq routers
.Pq the default route ,
.Qq subnet-mask ,
.Qq broadcast-address ,
.Qq domain-name-servers ,
etc.
See
.Xr dhcpd.conf 5
for details.
In that example,
.Sy myclient
has an assigned IP address.
.Pp
The
.Tn DHCP
parameters required for network bootstrapping a system will vary
from platform to platform, as dictated by each system's firmware.
In particular, because the
.Tn DHCP
is extensible, some hardware vendors have specified
.Tn DHCP
options to return information to requesting clients that are specific
to that platform.
Please see your platform's
.Xr boot 8
for details.
.Ss TFTP
If booting a
.Tn Sun
system, or other system that expects to use
.Tn TFTP ,
ensure that
.Xr inetd 8
is configured to run
.Xr tftpd 8 .
The
.Xr tftpd 8
server should be set up to serve the directory
.Pa /tftpboot .
.Pp
If booting a
.Tn SPARC
system, install a copy of the appropriate diskless secondary boot
loader
.Po
such as
.Pa /usr/mdec/boot
or
.Pa ofwboot.net
.Pc
in the
.Pa /tftpboot
directory.
Make a link such that the boot program is
accessible by a filename composed of the client's
.Tn \&IP
address in hexadecimal, a dot, and the architecture name
.Pq all upper case .
For example:
.Pp
.Bd -literal -offset indent -compact
# cd /tftpboot
# ln -s boot C0C5600C.SUN4
.Ed
.Pp
For a
.Tn Sun-3
or
.Tn UltraSPARC
system, the filename would be just C0C5600C
.Po
these systems' firmware does not append the architecture name
.Pc .
The name used is architecture dependent, it simply has to match
what the booting client's system firmware wishes to it to be.
.Pp
If the client's system firmware fails to fetch the expected file,
.Xr tcpdump 8
can be used to discover which filename the client is being requested.
Also, examination of
.Xr tftpd 8
log entries
.Po
typically in
.Pa /var/log/messages
.Pc
should show whether the server is hearing the client system, and
what filename the client is asking for.
.Ss HP RMP
If booting an
.Tn HP
300-series system, ensure that
.Pa /etc/rbootd.conf
is configured properly to transfer the boot program to the client.
An entry might look like this:
.Pp
.Bd -literal -offset indent -compact
08:00:09:01:23:E6	SYS_UBOOT	# myclient
.Ed
.Pp
The secondary bootstrap program for an
.Tn \&HP
300-series system
.Pa SYS_UBOOT
.Po
which may be called
.Pa uboot.lif
before installation
.Pc
must be installed in the directory
.Pa /usr/mdec/rbootd .
.Pp
See the
.Xr rbootd 8
manual page for more information.
.Ss Sun RPC BOOTPARAMS
Add
.Sy myclient
to the bootparams database in
.Pa /etc/bootparams :
.Pp
.Bd -literal -offset indent -compact
myclient  root=myserver:/export/myclient/root \\
          swap=myserver:/export/myclient/root/swap \\
          dump=myserver:/export/myclient/root/swap
.Ed
.Pp
and ensure that
.Xr rpc.bootparamd 8
and
.Xr rpcbind 8
are running.
Both
.Sy myclient
and
.Sy myserver
must have
.Tn \&IP
addresses in the
.Tn DNS
or
.Pa /etc/hosts .
.Ss Diskless Client File Systems
Build the swap file for
.Sy myclient
on the
.Tn NFS
server:
.Pp
.Bd -literal -offset indent -compact
# cd /export/myclient/root
# dd if=/dev/zero of=swap bs=16k count=1024
.Ed
.Pp
This creates a 16 megabyte swap file.
.Pp
Populate
.Sy myclient Ns No 's
root file system on the
.Tn NFS
server.
How this is done depends on the client architecture and the version
of the
.Nx
distribution.
It can be as simple as copying and modifying the server's root
file system, or unpack a complete
.Nx
binary distribution for the appropriate platform.
.Pp
If the
.Tn NFS
server is going to support multiple different architectures
.Po
e.g.
.Tn Alpha ,
.Tn PowerPC ,
.Tn SPARC ,
.Tn MIPS
.Pc ,
then it is important to think carefully about how to lay out the
.Tn NFS
server's exported file systems, to share what can be shared
.Pq e.g. text files, configuration files, user home directories ,
and separate that which is distinct to each architecture
.Pq e.g. binary executables, libraries .
.Ss NFS
Export the client-populated file systems on the
.Tn NFS
server in
.Pa /etc/exports :
.Pp
.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
file system
.Pq as is done above .
If not, you must build a properly fleshed out
.Pa /usr
partition for the client in some other part of the server's
file system, to serve to the client.
.Pp
If your server is a
.Tn SPARC ,
and your client a
.Tn Sun-3 ,
you might create and fill
.Pa /export/usr.sun3
and then use the following
.Pa /etc/exports
lines:
.Pp
.Bd -literal -offset indent -compact
/export/usr.sun3 -ro myclient
/export/myclient -rw=myclient,root=myclient
.Ed
.Pp
Of course, in either case you will have to have an
.Tn NFS
server running on the server side.
.Sh CLIENT CONFIGURATION
Copy and customize at least the following files in
.Pa /export/myclient/root :
.Pp
.Bd -literal -offset indent -compact
# cd /export/myclient/root/etc
# vi fstab
# cp /etc/hosts hosts
# echo 'hostname="myclient"' >> rc.conf
# echo "inet 192.197.96.12" > ifconfig.le0
.Ed
.Pp
Note that "le0" above should be replaced with the name of
the network interface that the client will use for booting;
the network interface name is device dependent in
.Nx .
.Pp
Correct the critical mount points and the swap file in the client's
.Pa /etc/fstab
.Po
which will be
.Pa /export/myclient/root/etc/fstab
.Pc
i.e.
.Pp
.Bd -literal -offset indent -compact
myserver:/export/myclient/root  /    nfs  rw 0 0
myserver:/usr                   /usr nfs  rw 0 0
/swap                           none swap sw 0 0
.Ed
.Pp
Note, you
.Em must
specify the swap file in
.Pa /etc/fstab
or it will not be used!
See
.Xr swapctl 8 .
.Pp
It may be useful to set
.Dq flushroutes=NO
in
.Pa /etc/rc.conf
to avoid the default route supplied by the boot setup
disappearing mid-boot.
.Sh FILES
.Bl -tag -width /usr/mdec/rbootd -compact
.It Pa /etc/hosts
table of associated
.Tn \&IP
addresses and
.Tn \&IP
host names; see
.Xr hosts 5
.It Pa /etc/ethers
table of associated
.Tn Ethernet
.Tn MAC
addresses and
.Tn \&IP
host names used by
.Xr rarpd 8 ;
see
.Xr ethers 5
.It Pa /etc/bootparams
client root pathname and swap pathname; see
.Xr bootparams 5
.It Pa /etc/exports
exported
.Tn NFS
mount points; see
.Xr exports 5
.It Pa /etc/rbootd.conf
configuration file for
.Tn \&HP RMP ;
see
.Xr rbootd 8
.It Pa /usr/mdec/rbootd
location of boot programs offered by
.Xr rbootd 8
.It Pa /tftpboot
location of boot programs offered by
.Xr tftpd 8
.El
.Sh SEE ALSO
.Xr bootparams 5 ,
.Xr dhcpd.conf 5 ,
.Xr ethers 5 ,
.Xr exports 5 ,
.Xr fstab 5 ,
.Xr hosts 5 ,
.Xr networks 5 ,
.Xr boot 8 ,
.Xr dhcpd 8 ,
.Xr mopd 8 ,
.Xr mountd 8 ,
.Xr nfsd 8 ,
.Xr rarpd 8 ,
.Xr rbootd 8 ,
.Xr reboot 8 ,
.Xr rpc.bootparamd 8 ,
.Xr tftpd 8
.Rs
.%R RFC
.%N 903
.%D June 1984
.%T "Reverse Address Resolution Protocol"
.Re
.Rs
.%R RFC
.%N 906
.%D June 1984
.%T "Bootstrap Loading using TFTP"
.Re
.Rs
.%R RFC
.%N 951
.%D September 1985
.%T "Bootstrap Protocol"
.Re
.Rs
.%R RFC
.%N 1350
.%D July 1992
.%T "The TFTP Protocol (Revision 2)"
.Re
.Rs
.%R RFC
.%N 2131
.%D March 1997
.%T "Dynamic Host Configuration Protocol"
.Re
.Rs
.%R RFC
.%N 2132
.%D March 1997
.%T "DHCP Options and BOOTP Vendor Extensions"
.Re
.Pp
.Lk http://www.rfc-editor.org/ "RFC Editor"