summaryrefslogtreecommitdiffstats
path: root/share/man/man8/diskless.8
blob: 3fcbc25c727f1967d16b0b027d4436f25ca26b21 (plain)
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
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
.\" Updated by Luigi Rizzo, Robert Watson
.\" 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.
.\"
.\" $FreeBSD$
.\"
.Dd August 7, 2011
.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 file systems 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.
.Sh OPERATION
When booting a system over the network, there are three
phases of interaction between client and server:
.Bl -enum
.It
The stage-1 bootstrap, typically PXE built into your Ethernet
card, loads a second-stage boot program.
.It
The second-stage boot program, typically
.Xr pxeboot 8 ,
loads modules and
the kernel, and boots the kernel.
.It
The kernel
.Tn NFS
mounts the root directory and continues from there.
.El
.Pp
Each of these phases are described in further detail below.
.Pp
First, the stage-1 bootstrap loads the stage-2 boot program over
the network.
The stage-1 bootstrap typically uses
.Tn BOOTP
or
.Tn DHCP
to obtain the filename to load, then uses
.Tn TFTP
to load the file.
This file is typically called
.Pa pxeboot ,
and should be copied from
.Pa /boot/pxeboot
into the
.Tn TFTP
directory on the server, which is typically
.Pa /tftpdir .
.Pp
The stage-2 boot program then loads additional modules and the kernel.
These files may not exist on the
.Tn DHCP
or
.Tn BOOTP
server.
You can use the
.Ic next-server
option available in
.Tn DHCP
configurations to specify the server holding
the second stage boot files and kernel.
The stage-2 program uses
.Tn NFS
or
.Tn TFTP
to obtain these files.
By default,
.Tn NFS
is used.
If you are using
.Xr pxeboot 8 ,
you can install a version that uses
.Tn TFTP
by setting
.Li LOADER_TFTP_SUPPORT=YES
in your
.Xr make.conf 5 ,
then recompiling and reinstalling
.Xr pxeboot 8
via the command listed below.
It is often necessary to use
.Tn TFTP
here so you can place a custom kernel
in
.Pa /tftpdir/ .
If you use
.Tn NFS
and do not have a custom root file system for the
.Nm
client, the stage-2 boot will load your server's kernel as the kernel for
the
.Nm
machine, which may not be what you want to have happen.
.Bd -literal -offset indent
cd /usr/src/sys/boot/i386
make clean; make; make install
cp /boot/pxeboot /tftpdir/
.Ed
.Pp
In phase 3, the kernel acquires IP networking configuration in one
of two ways, and then proceeds to mount the root file system and start
operation.
If the phase 2 loader supports passing network configuration to the
kernel using the kernel environment, then the kernel will configure
the network interface using that information.
Otherwise, it must use
.Tn DHCP
or
.Tn BOOTP
to acquire
configuration information.
The boot
scripts recognize a
.Nm
startup and perform
the actions found in
.Pa /etc/rc.d/resolv ,
.Pa /etc/rc.d/tmp ,
.Pa /etc/rc.d/var ,
and
.Pa /etc/rc.initdiskless .
.Sh CONFIGURATION
In order to run a
.Nm
client, you need the following:
.Bl -bullet
.It
An
.Tn NFS
server which exports a root and
.Pa /usr
partitions with appropriate permissions.
The
.Nm
scripts work with read-only partitions, as long as root is exported with
.Fl maproot Ns =0
so that some system files can be accessed.
As an example,
.Pa /etc/exports
can contain the following lines:
.Bd -literal -offset indent
<ROOT> -ro -maproot=0 -alldirs <list of diskless clients>
/usr -ro -alldirs <list of diskless clients>
.Ed
.Pp
where
.Aq ROOT
is the mount point on the server of the root partition.
The script
.Pa /usr/share/examples/diskless/clone_root
can be used to create a shared read-only root partition,
but in many cases you may decide to export
(again as read-only) the root directory used by
the server itself.
.It
A
.Tn BOOTP
or
.Tn DHCP
server.
.Xr bootpd 8
can be enabled by
uncommenting the
.Dq Li bootps
line in
.Pa /etc/inetd.conf .
A sample
.Pa /etc/bootptab
can be the following:
.Bd -literal -offset indent
 .default:\\
    hn:ht=1:vm=rfc1048:\\
    :sm=255.255.255.0:\\
    :sa=<SERVER>:\\
    :gw=<GATEWAY>:\\
    :rp="<SERVER>:<ROOT>":

<CLIENT>:ha=0123456789ab:tc=.default
.Ed
.Pp
where
.Aq SERVER ,
.Aq GATEWAY
and
.Aq ROOT
have the obvious meanings.
.It
A properly initialized root partition.
The script
.Pa /usr/share/examples/diskless/clone_root
can help in creating it, using the server's root partition
as a reference.
If you are just starting out, you should
simply use the server's own root directory,
.Pa / ,
and not try to clone it.
.Pp
You often do not want to use the same
.Pa rc.conf
or
.Pa rc.local
files for the
.Nm
boot as you do on the server.
The
.Nm
boot
scripts provide a mechanism through which you can override various files
in
.Pa /etc
(as well as other subdirectories of root).
.Pp
One difference that you should pay particular attention to is
the value of
.Va local_startup
in
.Pa /etc/defaults/rc.conf .
A typical value for a
.Nm
boot is
.Va mountcritremote ,
however your needs may be different.
.Pp
The scripts provide four
overriding directories situated in
.Pa /conf/base ,
.Pa /conf/default ,
.Pa /conf/<broadcast-ip> ,
and
.Pa /conf/<machine-ip> .
You should always create
.Pa /conf/base/etc ,
which will entirely replace the server's
.Pa /etc
on the
.Nm
machine.
You can clone the server's
.Pa /etc
here or you can create a special file which tells the
.Nm
boot scripts
to remount the server's
.Pa /etc
onto
.Pa /conf/base/etc .
You do this by creating the file
.Pa /conf/base/etc/diskless_remount
containing the mount point to use as a basis of the
.Nm
machine's
.Pa /etc .
For example, the file might contain:
.Pp
.Dl 10.0.0.1:/etc
.Pp
Alternatively, if the server contains several independent roots, the file
might contain:
.Pp
.Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc
.Pp
This would work, but if you copied
.Pa /usr/diskless/4.7-RELEASE
to
.Pa /usr/diskless/4.8-RELEASE
and upgraded the installation, you would need to modify the
.Pa diskless_remount
files to reflect that move.
To avoid that, paths in
.Pa diskless_remount
files beginning with
.Pa /
have the actual path of the client's root prepended to them so the file
could instead contain:
.Pp
.Dl /etc
.Pp
The
.Nm
scripts create memory file systems to hold the overridden
directories.
Only a 2MB partition is created by default, which may not
be sufficient for your purposes.
To override this, you can create the
file
.Pa /conf/base/etc/md_size
containing the size, in 512 byte sectors, of the memory disk to create
for that directory.
.Pp
You then typically provide file-by-file overrides in the
.Pa /conf/default/etc
directory.
At a minimum, you must provide overrides for
.Pa /etc/fstab , /etc/rc.conf ,
and
.Pa /etc/rc.local
via
.Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf ,
and
.Pa /conf/default/etc/rc.local .
.Pp
Overrides are hierarchical.
You can supply network-specific defaults
in the
.Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc
directory, where
.Aq Ar BROADCASTIP
represents the broadcast IP address of
the
.Nm
system as given to it via
.Tn BOOTP .
The
.Pa diskless_remount
and
.Pa md_size
features work in any of these directories.
The configuration feature works on directories other then
.Pa /etc ,
you simply create the directory you wish to replace or override in
.Pa /conf/{base,default,<broadcast>,<ip>}/*
and work it in the same way that you work
.Pa /etc .
.Pp
Since you normally clone the server's
.Pa /etc
using the
.Pa /conf/base/etc/diskless_remount ,
you might wish to remove unneeded files from the memory file system.
For example,
if the server has a firewall but you do not, you might wish
to remove
.Pa /etc/ipfw.conf .
You can do this by creating a
.Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove
file.
For example,
.Pa /conf/base/etc.remove ,
which contains a list of relative paths that the boot scripts should remove
from the memory file systems.
.Pp
As a minimum, you normally need to have the following in
.Pa /conf/default/etc/fstab
.Bd -literal -offset indent
<SERVER>:<ROOT> /     nfs    ro 0 0
<SERVER>:/usr   /usr  nfs    ro 0 0
.Ed
.Pp
You also need to create a customized version of
.Pa /conf/default/etc/rc.conf
which should contain
the startup options for the
.Nm
client, and
.Pa /conf/default/etc/rc.local
which could be empty but prevents the server's own
.Pa /etc/rc.local
from leaking onto the
.Nm
system.
.Pp
In
.Pa rc.conf ,
most likely
you will not need to set
.Va hostname
and
.Va ifconfig_*
because these will be already set by the startup code.
Finally, it might be convenient to use a
.Ic case
statement using
.Li `hostname`
as the switch variable to do machine-specific configuration
in case a number of
.Nm
clients share the same configuration
files.
.It
The kernel for the
.Nm
clients, which will be loaded using
.Tn NFS
or
.Tn TFTP ,
must include support for the NFS client:
.Pp
.D1 Cd "options NFSCL"
.D1 Cd "options NFS_ROOT"
.Pp
If you are using a boot mechanism that does not pass network configuration
to the kernel using the kernel environment, you will also need to include
the following options:
.Pp
.D1 Cd "options BOOTP"
.D1 Cd "options BOOTP_NFSROOT"
.D1 Cd "options BOOTP_COMPAT"
.Pp
.Em Note :
the PXE environment does not require these options.
.Pp
The
.Nm
booting environment relies on memory-backed file systems to
support temporary local storage in the event that the root file system
is mounted read-only; as such, it is necessary to add the following
to the device section of the kernel configuration:
.Pp
.D1 Cd "device md"
.Pp
If you use the firewall, remember to default to
.Dq open ,
or your kernel
will not be able to send/receive the
.Tn BOOTP
packets.
.El
.Sh SECURITY ISSUES
Be warned that using unencrypted
.Tn NFS
to mount root and user
partitions may expose information such as
encryption keys.
.Sh SEE ALSO
.Xr ethers 5 ,
.Xr exports 5 ,
.Xr make.conf 5 ,
.Xr bootpd 8 ,
.Xr mountd 8 ,
.Xr nfsd 8 ,
.Xr pxeboot 8 ,
.Xr reboot 8 ,
.Xr tftpd 8
.Pp
.Pa ports/net/etherboot
.Sh BUGS
This manpage is probably incomplete.
.Pp
.Fx
sometimes requires to write onto
the root partition, so the startup scripts mount MFS
file systems on some locations (e.g.\&
.Pa /etc
and
.Pa /var ) ,
while
trying to preserve the original content.
The process might not handle all cases.
OpenPOWER on IntegriCloud