xref: /freebsd/share/man/man8/diskless.8 (revision 6fd05b64b5b65dd4ba9b86482a0634a5f0b96c29)
1.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
2.\" Updated by Luigi Rizzo, Robert Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
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.
15.\"
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.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd January 10, 2004
30.Dt DISKLESS 8
31.Os
32.Sh NAME
33.Nm diskless
34.Nd booting a system over the network
35.Sh DESCRIPTION
36The ability to boot a machine over the network is useful for
37.Em diskless
38or
39.Em dataless
40machines, or as a temporary measure while repairing or
41re-installing file systems on a local disk.
42This file provides a general description of the interactions between
43a client and its server when a client is booting over the network.
44.Sh OPERATION
45When booting a system over the network, there are three
46phases of interaction between client and server:
47.Bl -enum
48.It
49The stage-1 bootstrap, typically PXE built into your Ethernet
50card, loads a second-stage boot program.
51.It
52The second-stage boot program, typically
53.Xr pxeboot 8 ,
54loads modules and
55the kernel, and boots the kernel.
56.It
57The kernel
58.Tn NFS
59mounts the root directory and continues from there.
60.El
61.Pp
62Each of these phases are described in further detail below.
63.Pp
64First, the stage-1 bootstrap loads the stage-2 boot program over
65the network.
66The stage-1 bootstrap typically uses
67.Tn BOOTP
68or
69.Tn DHCP
70to obtain the filename to load, then uses
71.Tn TFTP
72to load the file.
73This file is typically called
74.Pa pxeboot ,
75and should be copied from
76.Pa /boot/pxeboot
77into the
78.Tn TFTP
79directory on the server, which is typically
80.Pa /tftpdir .
81.Pp
82The stage-2 boot program then loads additional modules and the kernel.
83These files may not exist on the
84.Tn DHCP
85or
86.Tn BOOTP
87server.
88You can use the
89.Ic next-server
90option available in
91.Tn DHCP
92configurations to specify the server holding
93the second stage boot files and kernel.
94The stage-2 program uses
95.Tn NFS
96or
97.Tn TFTP
98to obtain these files.
99By default,
100.Tn NFS
101is used.
102If you are using
103.Xr pxeboot 8 ,
104you can install a version that uses
105.Tn TFTP
106by setting
107.Li LOADER_TFTP_SUPPORT=YES
108in your
109.Pa /etc/make.conf ,
110then recompiling and reinstalling
111.Xr pxeboot 8
112via the command listed below.
113It is often necessary to use
114.Tn TFTP
115here so you can place a custom kernel
116in
117.Pa /tftpdir/ .
118If you use
119.Tn NFS
120and do not have a custom root file system for the
121.Nm
122client, the stage-2 boot will load your server's kernel as the kernel for
123the
124.Nm
125machine, which may not be what you want to have happen.
126.Bd -literal -offset indent
127cd /usr/src/sys/boot/i386
128make clean; make; make install
129cp /boot/pxeboot /tftpdir/
130.Ed
131.Pp
132In phase 3, the kernel acquires IP networking configuration in one
133of two ways, and then proceeds to mount the root file system and start
134operation.
135If the phase 2 loader supports passing network configuration to the
136kernel using the kernel environment, then the kernel will configure
137the network interface using that information.
138Otherwise, it must use
139.Tn DHCP
140or
141.Tn BOOTP
142to acquire
143configuration information.
144The boot
145scripts recognize a
146.Nm
147startup and perform
148the actions found in
149.Pa /etc/rc.d/initdiskless
150and
151.Pa /etc/rc.d/diskless .
152On older systems, the scripts are located in
153.Pa /etc/rc.diskless1
154and
155.Pa /etc/rc.diskless2 .
156.Sh CONFIGURATION
157In order to run a
158.Nm
159client, you need the following:
160.Bl -bullet
161.It
162An
163.Tn NFS
164server which exports a root and
165.Pa /usr
166partitions with appropriate permissions.
167The
168.Nm
169scripts work with read-only partitions, as long as root is exported with
170.Fl maproot Ns =0
171so that some system files can be accessed.
172As an example,
173.Pa /etc/exports
174can contain the following lines:
175.Bd -literal -offset indent
176<ROOT> -ro -maproot=0 -alldirs <list of diskless clients>
177/usr -ro -alldirs <list of diskless clients>
178.Ed
179.Pp
180where
181.Aq ROOT
182is the mount point on the server of the root partition.
183The script
184.Pa /usr/share/examples/diskless/clone_root
185can be used to create a shared read-only root partition,
186but in many cases you may decide to export
187(again as read-only) the root directory used by
188the server itself.
189.It
190A
191.Tn BOOTP
192or
193.Tn DHCP
194server.
195.Xr bootpd 8
196can be enabled by
197uncommenting the
198.Dq Li bootps
199line in
200.Pa /etc/inetd.conf .
201A sample
202.Pa /etc/bootptab
203can be the following:
204.Bd -literal -offset indent
205 .default:\\
206    hn:ht=1:vm=rfc1048:\\
207    :sm=255.255.255.0:\\
208    :sa=<SERVER>:\\
209    :gw=<GATEWAY>:\\
210    :rp="<SERVER>:<ROOT>":
211
212<CLIENT>:ha=0123456789ab:tc=.default
213.Ed
214.Pp
215where
216.Aq SERVER ,
217.Aq GATEWAY
218and
219.Aq ROOT
220have the obvious meanings.
221.It
222A properly initialized root partition.
223The script
224.Pa /usr/share/examples/diskless/clone_root
225can help in creating it, using the server's root partition
226as a reference.
227If you are just starting out, you should
228simply use the server's own root directory,
229.Pa / ,
230and not try to clone it.
231.Pp
232You often do not want to use the same
233.Pa rc.conf
234or
235.Pa rc.local
236files for the
237.Nm
238boot as you do on the server.
239The
240.Nm
241boot
242scripts provide a mechanism through which you can override various files
243in
244.Pa /etc
245(as well as other subdirectories of root).
246The scripts provide four
247overriding directories situated in
248.Pa /conf/base ,
249.Pa /conf/default ,
250.Pa /conf/<broadcast-ip> ,
251and
252.Pa /conf/<machine-ip> .
253You should always create
254.Pa /conf/base/etc ,
255which will entirely replace the server's
256.Pa /etc
257on the
258.Nm
259machine.
260You can clone the server's
261.Pa /etc
262here or you can create a special file which tells the
263.Nm
264boot scripts
265to remount the server's
266.Pa /etc
267onto
268.Pa /conf/base/etc .
269You do this by creating the file
270.Pa /conf/base/etc/diskless_remount
271containing the mount point to use as a basis of the
272.Nm
273machine's
274.Pa /etc .
275For example, the file might contain:
276.Pp
277.Dl 10.0.0.1:/etc
278.Pp
279Alternatively, if the server contains several independent roots, the file
280might contain:
281.Pp
282.Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc
283.Pp
284This would work, but if you copied
285.Pa /usr/diskless/4.7-RELEASE
286to
287.Pa /usr/diskless/4.8-RELEASE
288and upgraded the installation, you would need to modify the
289.Pa diskless_remount
290files to reflect that move.
291To avoid that, paths in
292.Pa diskless_remount
293files beginning with
294.Pa /
295have the actual path of the client's root prepended to them so the file
296could instead contain:
297.Pp
298.Dl /etc
299.Pp
300The
301.Nm
302scripts create memory file systems to hold the overridden
303directories.
304Only a 2MB partition is created by default, which may not
305be sufficient for your purposes.
306To override this, you can create the
307file
308.Pa /conf/base/etc/md_size
309containing the size, in 512 byte sectors, of the memory disk to create
310for that directory.
311.Pp
312You then typically provide file-by-file overrides in the
313.Pa /conf/default/etc
314directory.
315At a minimum, you must provide overrides for
316.Pa /etc/fstab , /etc/rc.conf ,
317and
318.Pa /etc/rc.local
319via
320.Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf ,
321and
322.Pa /conf/default/etc/rc.local .
323.Pp
324Overrides are hierarchical.
325You can supply network-specific defaults
326in the
327.Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc
328directory, where
329.Aq Ar BROADCASTIP
330represents the broadcast IP address of
331the
332.Nm
333system as given to it via
334.Tn BOOTP .
335The
336.Pa diskless_remount
337and
338.Pa md_size
339features work in any of these directories.
340The configuration feature works on directories other then
341.Pa /etc ,
342you simply create the directory you wish to replace or override in
343.Pa /conf/{base,default,<broadcast>,<ip>}/*
344and work it in the same way that you work
345.Pa /etc .
346.Pp
347Since you normally clone the server's
348.Pa /etc
349using the
350.Pa /conf/base/etc/diskless_remount ,
351you might wish to remove unneeded files from the memory file system.
352For example,
353if the server has a firewall but you do not, you might wish
354to remove
355.Pa /etc/ipfw.conf .
356You can do this by creating a
357.Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove
358file.
359For example,
360.Pa /conf/base/etc.remove ,
361which contains a list of relative paths that the boot scripts should remove
362from the memory file systems.
363.Pp
364As a minimum, you normally need to have the following in
365.Pa /conf/default/etc/fstab
366.Bd -literal -offset indent
367<SERVER>:<ROOT> /     nfs    ro 0 0
368<SERVER>:/usr   /usr  nfs    ro 0 0
369proc            /proc procfs rw 0 0
370.Ed
371.Pp
372You also need to create a customized version of
373.Pa /conf/default/etc/rc.conf
374which should contain
375the startup options for the
376.Nm
377client, and
378.Pa /conf/default/etc/rc.local
379which could be empty but prevents the server's own
380.Pa /etc/rc.local
381from leaking onto the
382.Nm
383system.
384.Pp
385In
386.Pa rc.conf ,
387most likely
388you will not need to set
389.Va hostname
390and
391.Va ifconfig_*
392because these will be already set by the startup code.
393Finally, it might be convenient to use a
394.Ic case
395statement using
396.Li `hostname`
397as the switch variable to do machine-specific configuration
398in case a number of
399.Nm
400clients share the same configuration
401files.
402.It
403The kernel for the
404.Nm
405clients, which will be loaded using
406.Tn NFS
407or
408.Tn TFTP ,
409must include support for the NFS client:
410.Pp
411.D1 Cd "options NFSCLIENT"
412.D1 Cd "options NFS_ROOT"
413.Pp
414If you are using a boot mechanism that does not pass network configuration
415to the kernel using the kernel environment, you will also need to include
416the following options:
417.Pp
418.D1 Cd "options BOOTP"
419.D1 Cd "options BOOTP_NFSROOT"
420.D1 Cd "options BOOTP_COMPAT"
421.Pp
422.Em Note :
423the PXE environment does not require these options.
424.Pp
425The
426.Nm
427booting environment relies on memory-backed file systems to
428support temporary local storage in the event that the root file system
429is mounted read-only; as such, it is necessary to add the following
430to the device section of the kernel configuration:
431.Pp
432.D1 Cd "device md"
433.Pp
434If you use the firewall, remember to default to
435.Dq open ,
436or your kernel
437will not be able to send/receive the
438.Tn BOOTP
439packets.
440.El
441.Sh SECURITY ISSUES
442Be warned that using unencrypted
443.Tn NFS
444to mount root and user
445partitions may expose information such as
446encryption keys.
447.Sh BUGS
448This manpage is probably incomplete.
449.Pp
450.Fx
451sometimes requires to write onto
452the root partition, so the startup scripts mount MFS
453file systems on some locations (e.g.\&
454.Pa /etc
455and
456.Pa /var ) ,
457while
458trying to preserve the original content.
459The process might not handle all cases.
460.Sh SEE ALSO
461.Xr ethers 5 ,
462.Xr exports 5 ,
463.Xr bootpd 8 ,
464.Xr mountd 8 ,
465.Xr nfsd 8 ,
466.Xr pxeboot 8 ,
467.Xr reboot 8 ,
468.Xr tftpd 8
469.Pp
470.Pa ports/net/etherboot
471