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