1 .\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
2 .\" Updated by Luigi Rizzo, Robert Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. The name of the author may not be used to endorse or promote products
14 .\" derived from this software without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 .Dd September 28, 2004
34 .Nd booting a system over the network
36 The ability to boot a machine over the network is useful for
40 machines, or as a temporary measure while repairing or
41 re-installing file systems on a local disk.
42 This file provides a general description of the interactions between
43 a client and its server when a client is booting over the network.
45 When booting a system over the network, there are three
46 phases of interaction between client and server:
49 The stage-1 bootstrap, typically PXE built into your Ethernet
50 card, loads a second-stage boot program.
52 The second-stage boot program, typically
55 the kernel, and boots the kernel.
59 mounts the root directory and continues from there.
62 Each of these phases are described in further detail below.
64 First, the stage-1 bootstrap loads the stage-2 boot program over
66 The stage-1 bootstrap typically uses
70 to obtain the filename to load, then uses
73 This file is typically called
75 and should be copied from
79 directory on the server, which is typically
82 The stage-2 boot program then loads additional modules and the kernel.
83 These files may not exist on the
92 configurations to specify the server holding
93 the second stage boot files and kernel.
94 The stage-2 program uses
98 to obtain these files.
104 you can install a version that uses
107 .Li LOADER_TFTP_SUPPORT=YES
110 then recompiling and reinstalling
112 via the command listed below.
113 It is often necessary to use
115 here so you can place a custom kernel
120 and do not have a custom root file system for the
122 client, the stage-2 boot will load your server's kernel as the kernel for
125 machine, which may not be what you want to have happen.
126 .Bd -literal -offset indent
127 cd /usr/src/sys/boot/i386
128 make clean; make; make install
129 cp /boot/pxeboot /tftpdir/
132 In phase 3, the kernel acquires IP networking configuration in one
133 of two ways, and then proceeds to mount the root file system and start
135 If the phase 2 loader supports passing network configuration to the
136 kernel using the kernel environment, then the kernel will configure
137 the network interface using that information.
138 Otherwise, it must use
143 configuration information.
149 .Pa /etc/rc.d/initdiskless ,
150 .Pa /etc/rc.d/resolv ,
154 On early 5.x releases, the functions of latter three scripts where
156 .Pa /etc/rc.d/diskless .
157 On older systems, the scripts are located in
158 .Pa /etc/rc.diskless1
160 .Pa /etc/rc.diskless2 .
164 client, you need the following:
169 server which exports a root and
171 partitions with appropriate permissions.
174 scripts work with read-only partitions, as long as root is exported with
176 so that some system files can be accessed.
179 can contain the following lines:
180 .Bd -literal -offset indent
181 <ROOT> -ro -maproot=0 -alldirs <list of diskless clients>
182 /usr -ro -alldirs <list of diskless clients>
187 is the mount point on the server of the root partition.
189 .Pa /usr/share/examples/diskless/clone_root
190 can be used to create a shared read-only root partition,
191 but in many cases you may decide to export
192 (again as read-only) the root directory used by
205 .Pa /etc/inetd.conf .
208 can be the following:
209 .Bd -literal -offset indent
211 hn:ht=1:vm=rfc1048:\\
215 :rp="<SERVER>:<ROOT>":
217 <CLIENT>:ha=0123456789ab:tc=.default
225 have the obvious meanings.
227 A properly initialized root partition.
229 .Pa /usr/share/examples/diskless/clone_root
230 can help in creating it, using the server's root partition
232 If you are just starting out, you should
233 simply use the server's own root directory,
235 and not try to clone it.
237 You often do not want to use the same
243 boot as you do on the server.
247 scripts provide a mechanism through which you can override various files
250 (as well as other subdirectories of root).
251 The scripts provide four
252 overriding directories situated in
255 .Pa /conf/<broadcast-ip> ,
257 .Pa /conf/<machine-ip> .
258 You should always create
260 which will entirely replace the server's
265 You can clone the server's
267 here or you can create a special file which tells the
270 to remount the server's
274 You do this by creating the file
275 .Pa /conf/base/etc/diskless_remount
276 containing the mount point to use as a basis of the
280 For example, the file might contain:
284 Alternatively, if the server contains several independent roots, the file
287 .Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc
289 This would work, but if you copied
290 .Pa /usr/diskless/4.7-RELEASE
292 .Pa /usr/diskless/4.8-RELEASE
293 and upgraded the installation, you would need to modify the
295 files to reflect that move.
296 To avoid that, paths in
300 have the actual path of the client's root prepended to them so the file
301 could instead contain:
307 scripts create memory file systems to hold the overridden
309 Only a 2MB partition is created by default, which may not
310 be sufficient for your purposes.
311 To override this, you can create the
313 .Pa /conf/base/etc/md_size
314 containing the size, in 512 byte sectors, of the memory disk to create
317 You then typically provide file-by-file overrides in the
318 .Pa /conf/default/etc
320 At a minimum, you must provide overrides for
321 .Pa /etc/fstab , /etc/rc.conf ,
325 .Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf ,
327 .Pa /conf/default/etc/rc.local .
329 Overrides are hierarchical.
330 You can supply network-specific defaults
332 .Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc
335 represents the broadcast IP address of
338 system as given to it via
344 features work in any of these directories.
345 The configuration feature works on directories other then
347 you simply create the directory you wish to replace or override in
348 .Pa /conf/{base,default,<broadcast>,<ip>}/*
349 and work it in the same way that you work
352 Since you normally clone the server's
355 .Pa /conf/base/etc/diskless_remount ,
356 you might wish to remove unneeded files from the memory file system.
358 if the server has a firewall but you do not, you might wish
361 You can do this by creating a
362 .Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove
365 .Pa /conf/base/etc.remove ,
366 which contains a list of relative paths that the boot scripts should remove
367 from the memory file systems.
369 As a minimum, you normally need to have the following in
370 .Pa /conf/default/etc/fstab
371 .Bd -literal -offset indent
372 <SERVER>:<ROOT> / nfs ro 0 0
373 <SERVER>:/usr /usr nfs ro 0 0
374 proc /proc procfs rw 0 0
377 You also need to create a customized version of
378 .Pa /conf/default/etc/rc.conf
380 the startup options for the
383 .Pa /conf/default/etc/rc.local
384 which could be empty but prevents the server's own
386 from leaking onto the
393 you will not need to set
397 because these will be already set by the startup code.
398 Finally, it might be convenient to use a
402 as the switch variable to do machine-specific configuration
405 clients share the same configuration
410 clients, which will be loaded using
414 must include support for the NFS client:
416 .D1 Cd "options NFSCLIENT"
417 .D1 Cd "options NFS_ROOT"
419 If you are using a boot mechanism that does not pass network configuration
420 to the kernel using the kernel environment, you will also need to include
421 the following options:
423 .D1 Cd "options BOOTP"
424 .D1 Cd "options BOOTP_NFSROOT"
425 .D1 Cd "options BOOTP_COMPAT"
428 the PXE environment does not require these options.
432 booting environment relies on memory-backed file systems to
433 support temporary local storage in the event that the root file system
434 is mounted read-only; as such, it is necessary to add the following
435 to the device section of the kernel configuration:
439 If you use the firewall, remember to default to
442 will not be able to send/receive the
447 Be warned that using unencrypted
449 to mount root and user
450 partitions may expose information such as
463 .Pa ports/net/etherboot
465 This manpage is probably incomplete.
468 sometimes requires to write onto
469 the root partition, so the startup scripts mount MFS
470 file systems on some locations (e.g.\&
475 trying to preserve the original content.
476 The process might not handle all cases.