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.
32 .Nd booting a system over the network
34 The ability to boot a machine over the network is useful for
38 machines, or as a temporary measure while repairing or
39 re-installing file systems on a local disk.
40 This file provides a general description of the interactions between
41 a client and its server when a client is booting over the network.
43 When booting a system over the network, there are three
44 phases of interaction between client and server:
47 The stage-1 bootstrap, typically PXE built into your Ethernet
48 card, loads a second-stage boot program.
50 The second-stage boot program, typically
53 the kernel, and boots the kernel.
57 mounts the root directory and continues from there.
60 Each of these phases are described in further detail below.
62 First, the stage-1 bootstrap loads the stage-2 boot program over
64 The stage-1 bootstrap typically uses
68 to obtain the filename to load, then uses
71 This file is typically called
73 and should be copied from
77 directory on the server, which is typically
80 The stage-2 boot program then loads additional modules and the kernel.
81 These files may not exist on the
90 configurations to specify the server holding
91 the second stage boot files and kernel.
92 The stage-2 program uses
96 to obtain these files.
102 you can install a version that uses
105 .Li LOADER_TFTP_SUPPORT=YES
108 then recompiling and reinstalling
110 via the command listed below.
111 It is often necessary to use
113 here so you can place a custom kernel
118 and do not have a custom root file system for the
120 client, the stage-2 boot will load your server's kernel as the kernel for
123 machine, which may not be what you want to have happen.
124 .Bd -literal -offset indent
126 make clean; make; make install
127 cp /boot/pxeboot /tftpdir/
130 In phase 3, the kernel acquires IP networking configuration in one
131 of two ways, and then proceeds to mount the root file system and start
133 If the phase 2 loader supports passing network configuration to the
134 kernel using the kernel environment, then the kernel will configure
135 the network interface using that information.
136 Otherwise, it must use
141 configuration information.
147 .Pa /etc/rc.d/resolv ,
151 .Pa /etc/rc.initdiskless .
155 client, you need the following:
160 server which exports a root and
162 partitions with appropriate permissions.
165 scripts work with read-only partitions, as long as root is exported with
167 so that some system files can be accessed.
170 can contain the following lines:
171 .Bd -literal -offset indent
172 <ROOT> -ro -maproot=0 -alldirs <list of diskless clients>
173 /usr -ro -alldirs <list of diskless clients>
178 is the mount point on the server of the root partition.
180 .Pa /usr/share/examples/diskless/clone_root
181 can be used to create a shared read-only root partition,
182 but in many cases you may decide to export
183 (again as read-only) the root directory used by
196 .Pa /etc/inetd.conf .
199 can be the following:
200 .Bd -literal -offset indent
202 hn:ht=1:vm=rfc1048:\\
206 :rp="<SERVER>:<ROOT>":
208 <CLIENT>:ha=0123456789ab:tc=.default
216 have the obvious meanings.
218 A properly initialized root partition.
220 .Pa /usr/share/examples/diskless/clone_root
221 can help in creating it, using the server's root partition
223 If you are just starting out, you should
224 simply use the server's own root directory,
226 and not try to clone it.
228 You often do not want to use the same
234 boot as you do on the server.
238 scripts provide a mechanism through which you can override various files
241 (as well as other subdirectories of root).
243 One difference that you should pay particular attention to is
247 .Pa /etc/defaults/rc.conf .
248 A typical value for a
251 .Va mountcritremote ,
252 however your needs may be different.
254 The scripts provide four
255 overriding directories situated in
258 .Pa /conf/<broadcast-ip> ,
260 .Pa /conf/<machine-ip> .
261 You should always create
263 which will entirely replace the server's
268 You can clone the server's
270 here or you can create a special file which tells the
273 to remount the server's
277 You do this by creating the file
278 .Pa /conf/base/etc/diskless_remount
279 containing the mount point to use as a basis of the
283 For example, the file might contain:
287 Alternatively, if the server contains several independent roots, the file
290 .Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc
292 This would work, but if you copied
293 .Pa /usr/diskless/4.7-RELEASE
295 .Pa /usr/diskless/4.8-RELEASE
296 and upgraded the installation, you would need to modify the
298 files to reflect that move.
299 To avoid that, paths in
303 have the actual path of the client's root prepended to them so the file
304 could instead contain:
310 scripts create memory file systems to hold the overridden
312 Only a 5MB partition is created by default, which may not
313 be sufficient for your purposes.
314 To override this, you can create the
316 .Pa /conf/base/etc/md_size
317 containing the size, in 512 byte sectors, of the memory disk to create
320 You then typically provide file-by-file overrides in the
321 .Pa /conf/default/etc
323 At a minimum, you must provide overrides for
324 .Pa /etc/fstab , /etc/rc.conf ,
328 .Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf ,
330 .Pa /conf/default/etc/rc.local .
332 Overrides are hierarchical.
333 You can supply network-specific defaults
335 .Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc
338 represents the broadcast IP address of
341 system as given to it via
347 features work in any of these directories.
348 The configuration feature works on directories other then
350 you simply create the directory you wish to replace or override in
351 .Pa /conf/{base,default,<broadcast>,<ip>}/*
352 and work it in the same way that you work
355 Since you normally clone the server's
358 .Pa /conf/base/etc/diskless_remount ,
359 you might wish to remove unneeded files from the memory file system.
361 if the server has a firewall but you do not, you might wish
364 You can do this by creating a
365 .Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove
368 .Pa /conf/base/etc.remove ,
369 which contains a list of relative paths that the boot scripts should remove
370 from the memory file systems.
372 As a minimum, you normally need to have the following in
373 .Pa /conf/default/etc/fstab
374 .Bd -literal -offset indent
375 <SERVER>:<ROOT> / nfs ro 0 0
376 <SERVER>:/usr /usr nfs ro 0 0
379 You also need to create a customized version of
380 .Pa /conf/default/etc/rc.conf
382 the startup options for the
385 .Pa /conf/default/etc/rc.local
386 which could be empty but prevents the server's own
388 from leaking onto the
395 you will not need to set
399 because these will be already set by the startup code.
400 Finally, it might be convenient to use a
404 as the switch variable to do machine-specific configuration
407 clients share the same configuration
412 clients, which will be loaded using
416 must include support for the NFS client:
418 .D1 Cd "options NFSCL"
419 .D1 Cd "options NFS_ROOT"
421 If you are using a boot mechanism that does not pass network configuration
422 to the kernel using the kernel environment, you will also need to include
423 the following options:
425 .D1 Cd "options BOOTP"
426 .D1 Cd "options BOOTP_NFSROOT"
427 .D1 Cd "options BOOTP_COMPAT"
430 the PXE environment does not require these options.
434 booting environment relies on memory-backed file systems to
435 support temporary local storage in the event that the root file system
436 is mounted read-only; as such, it is necessary to add the following
437 to the device section of the kernel configuration:
441 If you use the firewall, remember to default to
444 will not be able to send/receive the
449 Be warned that using unencrypted
451 to mount root and user
452 partitions may expose information such as
465 .Pa ports/net/etherboot
469 environment first appeared in
472 This manpage is probably incomplete.
475 sometimes requires to write onto
476 the root partition, so the startup scripts mount MFS
477 file systems on some locations (e.g.\&
482 trying to preserve the original content.
483 The process might not handle all cases.