manpages: Fix some more typos.
[dragonfly.git] / share / man / man8 / diskless.8
CommitLineData
984263bc
MD
1.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
2.\" Updated by Luigi Rizzo
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: src/share/man/man8/diskless.8,v 1.6.2.9 2003/01/25 18:56:44 dillon Exp $
28.\"
2c40730b 29.Dd February 19, 2008
984263bc
MD
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 filesystems 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.Pp
48.Bl -enum -compact
49.It
50The stage-1 bootstrap loads a boot program, from
51.It
52The boot program loads a kernel.
53.It
54The kernel does NFS mounts for root.
55.El
56.Pp
57Each of these phases are described in further detail below.
58.Pp
59In phase 1, the stage-1 bootstrap code loads a boot program,
60which is typically able to control the network card.
61The boot program can be stored in the BIOS, in a BOOT ROM
62located on the network card (PXE, etherboot, netboot),
63or come from a disk unit (e.g. etherboot or netboot).
64.Pp
65In phase 2, the boot program loads a kernel.
66Operation in
67this phase depends on the design of the boot program.
68Typically, the boot program uses the
69.Tn BOOTP
70or
71.Tn DHCP
72protocol to get the client's IP address and other boot
73information, including but not limited to
74the IP addresses of the NFS server, router and nameserver,
75and the name of the kernel to load.
76Then the kernel is loaded, either directly using NFS
77(as it is the case for etherboot and netboot),
78or through an intermediate loader called pxeboot and
79loaded using TFTP or NFS.
80.Pp
81In phase 3, the kernel again uses DHCP or BOOTP to acquire
82configuration information, and proceeds to mount the
83root filesystem and start operation. The boot
3f5e28f4 84scripts recognize a diskless startup and perform
984263bc
MD
85the actions found in
86.Pa /etc/rc.d/initdiskless
87and
88.Pa /etc/rc.d/diskless .
984263bc
MD
89.Sh CONFIGURATION
90In order to run a diskless client, you need the following:
91.Bl -bullet
92.It
93An NFS server which exports a root and /usr partition with
94appropriate permissions.
95The diskless
96scripts work with readonly partitions, as long as root is exported with
97.Fl maproot Ns =0
98so that some system files can be accessed.
99As an example,
100.Pa /etc/exports
101can contain the following lines:
102.Bd -literal -offset indent
103<ROOT> -ro -maproot=0 -alldirs <list of diskless clients>
104/usr -ro -alldirs <list of diskless clients>
105.Ed
106.Pp
107where
108.Aq ROOT
109is the mountpoint on the server of the root partition.
110The script
111.Pa /usr/share/examples/diskless/clone_root
112can be used to create a shared readonly root partition,
113but in many cases you may decide to export
114(again as readonly) the root directory used by
115the server itself.
116.It
117a
118.Tn BOOTP
119or
120.Tn DHCP
121server.
122.Xr bootpd 8
123can be enabled by
124uncommenting the
125.Em bootps
126line in
127.Pa /etc/inetd.conf .
128A sample
129.Pa /etc/bootptab
130can be the following:
131.Bd -literal -offset indent
132 .default:\\
133 hn:ht=1:vm=rfc1048:\\
134 :sm=255.255.255.0:\\
135 :sa=<SERVER>:\\
136 :gw=<GATEWAY>:\\
137 :rp="<SERVER>:<ROOT>":
138
139<CLIENT>:ha=0123456789ab:tc=.default
140.Ed
141.Pp
142where
143.Aq SERVER ,
144.Aq GATEWAY
145and
146.Aq ROOT
147have the obvious meanings.
148.It
149A properly initialized root partition.
150The script
151.Pa /usr/share/examples/diskless/clone_root
152can help in creating it, using the server's root partition
1bf4b486 153as a reference. If you are just starting out you should
984263bc
MD
154simply use the server's own root directory,
155.Pa / ,
156and not try to clone it.
157.Pp
158You often do not want to use the same
159.Pa rc.conf
160or
161.Pa rc.local
162files for the diskless boot as you do on the server. The diskless boot
163scripts provide a mechanism through which you can override various files
164in
165.Pa /etc
166(as well as other subdirectories of root). The scripts provide four
167overriding directories situated in
168.Pa /conf/base ,
169.Pa /conf/default ,
2c40730b 170.Pa /conf/<BROADCAST-IP> ,
984263bc 171and
2c40730b 172.Pa /conf/<MACHINE-IP> .
984263bc
MD
173You should always create
174.Pa /conf/base/etc ,
175which will entirely replace the server's
176.Pa /etc
177on the diskless machine.
178You can clone the server's
179.Pa /etc
180here or you can create a special file which tells the diskless boot scripts
181to remount the server's
182.Pa /etc
183onto
184.Pa /conf/base/etc .
185You do this by creating the file
186.Pa /conf/base/etc/diskless_remount
187containing the mount point to use as a basis of the diskless machine's
188.Pa /etc .
189For example, the file might contain:
190.Bd -literal -offset 4n
19110.0.0.1:/etc
192.Ed
193.Pp
3221afbe 194The diskless scripts create memory filesystems to hold the overridden
984263bc
MD
195directories. Only a 2MB partition is created by default, which may not
196be sufficient for your purposes. To override this you can create the
197file
198.Pa /conf/base/etc/md_size
199containing the size, in 512 byte sectors, of the memory disk to create
200for that directory.
201.Pp
202You then typically provide file-by-file overrides in the
203.Pa /conf/default/etc
204directory. At a minimum you must provides overrides for
205.Pa /etc/fstab ,
206.Pa /etc/rc.conf ,
207and
208.Pa /etc/rc.local
209via
210.Pa /conf/default/etc/fstab ,
211.Pa /conf/default/etc/rc.conf ,
212and
213.Pa /conf/default/etc/rc.local .
214.Pp
215Overrides are hierarchical. You can supply network-specific defaults
216in the
2c40730b
TN
217.Pa /conf/<BROADCAST-IP>/etc
218directory, where <BROADCAST-IP> represents the broadcast IP address of
984263bc
MD
219the diskless system as given to it via
220.Tn BOOTP .
221The
222.Pa diskless_remount
223and
224.Pa md_size
225features work in any of these directories.
5fba7a97 226The configuration feature works on directories other than
984263bc
MD
227.Pa /etc ,
228you simply create the directory you wish to replace or override in
2c40730b 229.Pa /conf/{base,default,<BROADCAST-IP>,<MACHINE-IP>}/*
984263bc
MD
230and work it in the same way that you work
231.Pa /etc .
232.Pp
233As a minimum, you normally need to have the following in
234.Pa /conf/default/etc/fstab
235.Bd -literal -offset indent
236<SERVER>:<ROOT> / nfs ro 0 0
237<SERVER>:/usr /usr nfs ro 0 0
238proc /proc procfs rw 0 0
239.Ed
240.Pp
241You also need to create a customized version of
242.Pa /conf/default/etc/rc.conf
243which should contain
244the startup options for the diskless client, and
245.Pa /conf/default/etc/rc.local
246which could be empty but prevents the server's own
247.Pa /etc/rc.local
248from leaking onto the diskless system.
249.Pp
250In
251.Pa rc.conf ,
252most likely
253you will not need to set
254.Va hostname
255and
256.Va ifconfig_*
257because these will be already set by the startup code.
258Finally, it might be convenient to use a
259.Ic case
260statement using
261.Li `hostname`
262as the switch variable to do machine-specific configuration
263in case a number of diskless clients share the same configuration
264files.
265.It
266The kernel for the diskless clients, which will be loaded using
267NFS or TFTP, should be built with at least the following options:
c7c7e2c8
SW
268.Pp
269.D1 Cd options MFS
270.D1 Cd options BOOTP
271.D1 Cd options BOOTP_NFSROOT
272.D1 Cd options BOOTP_COMPAT
984263bc
MD
273.Pp
274If you use the firewall, remember to default to open or your kernel
275will not be able to send/receive the bootp packets.
276.El
277.Sh SECURITY ISSUES
278Be warned that using unencrypted NFS to mount root and user
279partitions may expose information such as
280encryption keys.
2c40730b
TN
281.Sh FILES
282.Bl -tag -width /usr/share/examples/diskless/clone_root -compact
283.It Pa /usr/share/examples/diskless/clone_root
284script to clone root filesystem
285.It Pa /conf/base
2861st override
287.It Pa /conf/default
2882nd override
289.It Pa /conf/<BROADCAST-IP>
2903rd override
291.It Pa /conf/<MACHINE-IP>
2924th override
293.It Pa /conf/{base,default,<BROADCAST-IP>,<MACHINE-IP>}/<DIR>
294override for
295.Pa /<DIR>
296.It Pa /conf/{base,default,<BROADCAST-IP>,<MACHINE-IP>}/<DIR>/md_size
297size of memory disk for
298.Pa /<DIR>
299.It Pa /conf/{base,default,<BROADCAST-IP>,<MACHINE-IP>}/<DIR>/diskless_remount
300path to mount on
301.Pa /<DIR>
302.It Pa /conf/{base,default,<BROADCAST-IP>,<MACHINE-IP>}/<DIR>.cpio.gz
303archive to unpack to
304.Pa /<DIR>
305.It Pa /conf/{base,default,<BROADCAST-IP>,<MACHINE-IP>}/<DIR>.remove
306files to remove from
307.Pa /<DIR>
308.El
ac561d34 309.Sh SEE ALSO
2c40730b 310.Xr bootptab 5 ,
ac561d34
SW
311.Xr ethers 5 ,
312.Xr exports 5 ,
2c40730b 313.Xr rc.conf 5 ,
ac561d34 314.Xr bootpd 8 ,
3649133b 315.Xr dhcpd 8 Pq Pa pkgsrc/net/isc-dhcpd4 ,
ac561d34
SW
316.Xr mountd 8 ,
317.Xr nfsd 8 ,
318.Xr pxeboot 8 ,
d8254207 319.Xr rc 8 ,
ac561d34 320.Xr reboot 8 ,
dbb6aa0f 321.Xr tftpd 8
984263bc
MD
322.Sh BUGS
323This manpage is probably incomplete.
324.Pp
9bb2a92d 325.Dx
984263bc
MD
326sometimes requires to write onto
327the root partition, so the startup scripts mount MFS
328filesystems on some locations (e.g.\&
329.Pa /etc
330and
331.Pa /var ) ,
332while
333trying to preserve the original content.
334The process might not handle all cases.