1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
|
.\" $OpenBSD: diskless.8,v 1.11 2000/01/22 02:17:54 aaron 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
.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 and swap.
.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 and Motorola 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.
Other machines 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 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 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 -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.
.It 3.4
If the kernel is configured for swap on
.Tn NFS ,
it uses the same mechanism as for root, but uses the
.Tn NFS
getattr function to determine the size of the swap area.
.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 or Motorola 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-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_NBOOT # myclient
.Ed
.Pp
See the
.Xr rbootd 8
manual page for more information.
.Pp
.It 4.
If booting a Sun or Motorola client, install a copy of the
appropriate diskless boot loader (such as
.Pa boot.net
from the root directory of the OpenBSD 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 -compact
# cd /tftpboot
# ln -s boot.net 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_NBOOT
(which may be called
.Pa netboot.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 \\
swap=server:/export/myclient/swap
.Ed
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 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 OpenBSD 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
.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 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, 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 inet 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 in the client's
.Pa /etc/fstab
(which will be
.Pa /export/myclient/root/etc/fstab )
i.e.,
.Bd -literal -offset indent -compact
myserver:/export/myclient/root / nfs rw 0 0
myserver:/usr /usr nfs rw 0 0
.Ed
.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 and swap pathnames
.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 rpc.bootparamd 8 ,
.Xr bootparams 5 ,
.Xr mountd 8 ,
.Xr exports 5 ,
.Xr nfsd 8 ,
.Xr rbootd 8 ,
.Xr reboot 8
|