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