Cleanup; fixed some links
[ikiwiki.git] / docs / handbook / handbook-network-diskless.mdwn
1 ## 19.7 Diskless Operation 
2
3
4
5  **Updated by Jean-Fran�ois Dock�s. Reorganized and enhanced by Alex Dupre. **
6
7
8 A DragonFly machine can boot over the network and operate without a local disk, using filesystems mounted from an NFS server. No system modification is necessary, beyond standard configuration files. Such a system is relatively easy to set up because all the necessary elements are readily available:
9
10
11 * There are at least two possible methods to load the kernel over the network:
12
13 * PXE: The Intel® Preboot Execution Environment system is a form of smart boot ROM built into some networking cards or motherboards. See [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pxeboot&section=8) for more details.
14
15 * The  **etherboot**  port ([`net/etherboot`](http://pkgsrc.se/net/etherboot)) produces ROM-able code to boot kernels over the network. The code can be either burnt into a boot PROM on a network card, or loaded from a local floppy (or hard) disk drive, or from a running MS-DOS® system. Many network cards are supported.
16
17 * A sample script (`/usr/share/examples/diskless/clone_root`) eases the creation and maintenance of the workstation's root filesystem on the server. The script will probably require a little customization but it will get you started very quickly.
18
19 * Standard system startup files exist in `/etc` to detect and support a diskless system startup.
20
21 * Swapping, if needed, can be done either to an NFS file or to a local disk.
22
23
24 There are many ways to set up diskless workstations. Many elements are involved, and most can be customized to suit local taste. The following will describe variations on the setup of a complete system, emphasizing simplicity and compatibility with the standard DragonFly startup scripts. The system described has the following characteristics:
25
26
27
28
29 * The diskless workstations use a shared read-only `root` filesystem, and a shared read-only `/usr`.
30
31   The `root` filesystem is a copy of a standard DragonFly root (typically the server's), with some configuration files overridden by ones specific to diskless operation or, possibly, to the workstation they belong to.
32
33   The parts of the `root` which have to be writable are overlaid with [mfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mfs&section=8) filesystems. Any changes will be lost when the system reboots.
34
35
36 * The kernel is transferred and loaded either with  **etherboot**  or PXE as some situations may mandate the use of either method.
37
38
39  **Caution:** As described, this system is insecure. It should live in a protected area of a network, and be untrusted by other hosts.
40
41
42 ### 19.7.1 Background Information 
43
44
45 Setting up diskless workstations is both relatively straightforward and prone to errors. These are sometimes difficult to diagnose for a number of reasons. For example:
46
47
48 * Compile time options may determine different behaviours at runtime.
49
50 * Error messages are often cryptic or totally absent.
51
52
53 In this context, having some knowledge of the background mechanisms involved is very useful to solve the problems that may arise.
54
55
56 Several operations need to be performed for a successful bootstrap:
57
58
59 * The machine needs to obtain initial parameters such as its IP address, executable filename, server name, root path. This is done using the DHCP or BOOTP protocols. DHCP is a compatible extension of BOOTP, and uses the same port numbers and basic packet format.
60
61   It is possible to configure a system to use only BOOTP. The [bootpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=bootpd&section8) server program is included in the base DragonFly system.
62
63   However, DHCP has a number of advantages over BOOTP (nicer configuration files, possibility of using PXE, plus many others not directly related to diskless operation), and we will describe mainly a DHCP configuration, with equivalent exemples using [bootpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=bootpd&section8) when possible. The sample configuration will use the  **ISC DHCP**  software package (release 3.0.1.r12 was installed on the test server).
64
65
66 * The machine needs to transfer one or several programs to local memory. Either TFTP or NFS are used. The choice between TFTP and NFS is a compile time option in several places. A common source of error is to specify filenames for the wrong protocol: TFTP typically transfers all files from a single directory on the server, and would expect filenames relative to this directory. NFS needs absolute file paths.
67
68 * The possible intermediate bootstrap programs and the kernel need to be initialized and executed. There are several important variations in this area:
69
70
71 * PXE will load [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pxeboot&section8), which is a modified version of the DragonFly third stage loader. The [loader(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader&section=8) will obtain most parameters necessary to system startup, and leave them in the kernel environment before transferring control. It is possible to use a `GENERIC` kernel in this case.
72
73
74 *  **etherboot** , will directly load the kernel, with less preparation. You will need to build a kernel with specific options.
75
76 * Finally, the machine needs to access its filesystems. NFS is used in all cases.
77
78
79 See also [diskless(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=diskless&section8) manual page.
80
81
82 ### 19.7.2 Setup Instructions 
83
84
85 #### 19.7.2.1 Configuration Using  **ISC DHCP**  
86
87
88 The  **ISC DHCP**  server can answer both BOOTP and DHCP requests.
89
90
91  **ISC DHCP**  needs a configuration file to run, (normally named `/usr/pkg/etc/dhcpd.conf`). Here follows a commented example, where host `margaux` uses  **etherboot**  and host `corbieres` uses PXE:
92
93
94     default-lease-time 600;
95
96     max-lease-time 7200;
97
98     authoritative;
99
100     
101
102     option domain-name "example.com";
103
104     option domain-name-servers 192.168.4.1;
105
106     option routers 192.168.4.1;
107
108     
109
110     subnet 192.168.4.0 netmask 255.255.255.0 {
111
112       use-host-decl-names on;
113
114       option subnet-mask 255.255.255.0;
115
116       option broadcast-address 192.168.4.255;
117
118     
119
120       host margaux {
121
122         hardware ethernet 01:23:45:67:89:ab;
123
124         fixed-address margaux.example.com;
125
126         next-server 192.168.4.4;
127
128         filename "/data/misc/kernel.diskless";
129
130         option root-path "192.168.4.4:/data/misc/diskless";
131
132       }
133
134       host corbieres {
135
136         hardware ethernet 00:02:b3:27:62:df;
137
138         fixed-address corbieres.example.com;
139
140         next-server 192.168.4.4;
141
142         filename "pxeboot";
143
144         option root-path "192.168.4.4:/data/misc/diskless";
145
146       }
147
148     }
149
150
151 The `use-host-decl-names` option tells  **dhcpd**  to send the value in the `host` declarations as the hostname for the diskless host. An alternate way would be to add an `option host-name` **margaux** inside the host declarations.
152
153
154 The `next-server` directive designates the TFTP or NFS server to use for loading loader or kernel file (the default is to use the same host as the DHCP server).
155
156
157 The `filename` directive defines the file that  **etherboot**  or PXE will load for the next execution step. It must be specified according to the transfer method used.  **etherboot**  can be compiled to use NFS or TFTP. The DragonFly port configures NFS by default. PXE uses TFTP, which is why a relative filename is used here (this may depend on the TFTP server configuration, but would be fairly typical). Also, PXE loads `pxeboot`, not the kernel. There are other interesting possibilities, like loading `pxeboot` from a DragonFly CD-ROM `/boot` directory (as [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pxeboot&section8) can load a `GENERIC` kernel, this makes it possible to use PXE to boot from a remote CD-ROM).
158
159
160 The `root-path` option defines the path to the root filesystem, in usual NFS notation. When using PXE, it is possible to leave off the host's IP as long as you do not enable the kernel option BOOTP. The NFS server will then be the same as the TFTP one.
161
162
163 #### 19.7.2.2 Configuration Using BOOTP 
164
165
166 Here follows an equivalent  **bootpd**  configuration (reduced to one client). This would be found in `/etc/bootptab`.
167
168
169 Please note that  **etherboot**  must be compiled with the non-default option `NO_DHCP_SUPPORT` in order to use BOOTP, and that PXE **needs** DHCP. The only obvious advantage of  **bootpd**  is that it exists in the base system.
170     
171
172     .def100:\
173
174       :hn:ht#1:sa192.168.4.4:vm=rfc1048:\
175
176       :sm=255.255.255.0:\
177
178       :ds=192.168.4.1:\
179
180       :gw=192.168.4.1:\
181
182       :hd="/tftpboot":\
183
184       :bf="/kernel.diskless":\
185
186       :rp="192.168.4.4:/data/misc/diskless":
187
188
189     margaux:ha#0123456789ab:tc.def100
190
191     
192 #### 19.7.2.3 Booting with PXE 
193
194
195 By default, the [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pxeboot&section8) loader loads the kernel via NFS. It can be compiled to use TFTP instead by specifying the `LOADER_TFTP_SUPPORT` option in `/etc/make.conf`. See the comments in `/etc/defaults/make.conf` (or `/usr/share/examples/etc/make.conf` for 5.X systems) for instructions.
196
197
198 There are two other undocumented `make.conf` options which may be useful for setting up a serial console diskless machine: `BOOT_PXELDR_PROBE_KEYBOARD`, and `BOOT_PXELDR_ALWAYS_SERIAL`.
199
200
201 To use PXE when the machine starts, you will usually need to select the `Boot from network` option in your BIOS setup, or type a function key during the PC initialization.
202
203
204 #### 19.7.2.4 Configuring the TFTP and NFS Servers 
205
206
207 If you are using PXE or *etherboot*  configured to use TFTP, you need to enable *tftpd* on the file server:
208
209   1. Create a directory from which  *tftpd*  will serve the files, e.g. `/tftpboot`.
210
211   1. Add this line to your `/etc/inetd.conf`:
212
213         tftp    dgram   udp     wait    root    /usr/libexec/tftpd      tftpd -l -s /tftpboot
214
215   
216    **Note:** It appears that at least some PXE versions want the TCP version of TFTP. In this case, add a second line, replacing `dgram udp` with `stream tcp`.
217
218   1. Tell *inetd* to reread its configuration file:
219
220         # kill -HUP `cat /var/run/inetd.pid`
221
222
223 You can place the `tftpboot` directory anywhere on the server. Make sure that the location is set in both `inetd.conf` and `dhcpd.conf`.
224
225
226 In all cases, you also need to enable NFS and export the appropriate filesystem on the NFS server.
227
228   1. Add this to `/etc/rc.conf`:
229
230         nfs_server_enable="YES"
231
232   1. Export the filesystem where the diskless root directory is located by adding the following to `/etc/exports` (adjust the volume mount point and replace `margaux corbieres` with the names of the diskless workstations):
233
234         `/data/misc` -alldirs -ro `margaux corbieres`
235
236   1. Tell  **mountd**  to reread its configuration file. If you actually needed to enable NFS in `/etc/rc.conf` at the first step, you probably want to reboot instead.
237
238         # kill -HUP `cat /var/run/mountd.pid`
239
240
241 #### 19.7.2.5 Building a Diskless Kernel 
242
243
244 If using *etherboot*, you need to create a kernel configuration file for the diskless client with the following options (in addition to the usual ones):
245
246     options     BOOTP          # Use BOOTP to obtain IP address/hostname
247
248     options     BOOTP_NFSROOT  # NFS mount root filesystem using BOOTP info
249
250
251 You may also want to use `BOOTP_NFSV3`, `BOOT_COMPAT` and `BOOTP_WIRED_TO` (refer to `LINT`.
252
253
254 These option names are historical and slightly misleading as they actually enable indifferent use of DHCP and BOOTP inside the kernel (it is also possible to force strict BOOTP or DHCP use).
255
256
257 Build the kernel (see [[Configure a custom kernel|docs/newhandbook/ConfigureKernel]]), and copy it to the place specified in `dhcpd.conf`.
258
259
260  **Note:** When using PXE, building a kernel with the above options is not strictly necessary (though suggested). Enabling them will cause more DHCP requests to be issued during kernel startup, with a small risk of inconsistency between the new values and those retrieved by [pxeboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pxeboot&section=8) in some special cases. The advantage of using them is that the host name will be set as a side effect. Otherwise you will need to set the host name by another method, for example in a client-specific `rc.conf` file.
261
262
263 #### 19.7.2.6 Preparing the Root Filesystem 
264
265
266 You need to create a root filesystem for the diskless workstations, in the location listed as `root-path` in `dhcpd.conf`. The following sections describe two ways to do it.
267
268
269 ##### 19.7.2.6.1 Using the `clone_root` Script 
270
271
272 This is the quickest way to create a root filesystem. but This shell script is located at `/usr/share/examples/diskless/clone_root` and needs customization, at least to adjust the place where the filesystem will be created (the `DEST` variable).
273
274
275
276 Refer to the comments at the top of the script for instructions. They explain how the base filesystem is built, and how files may be selectively overridden by versions specific to diskless operation, to a subnetwork, or to an individual workstation. They also give examples for the diskless `/etc/fstab` and ` /etc/rc.conf` files.
277
278
279 The `README` files in `/usr/share/examples/diskless` contain a lot of interesting background information, but, together with the other examples in the `diskless` directory, they actually document a configuration method which is distinct from the one used by `clone_root` and the system startup scripts in `/etc`, which is a little confusing. Use them for reference only, except if you prefer the method that they describe, in which case you will need customized `rc` scripts.
280
281
282 ##### 19.7.2.6.2 Using the Standard `make world` Procedure 
283
284
285 This method will install a complete virgin system (not only the root filesystem) into `DESTDIR`. All you have to do is simply execute the following script:
286
287     #!/bin/sh
288
289     export DESTDIR=/data/misc/diskless
290
291     mkdir -p ${DESTDIR}
292
293     cd /usr/src; make world && make kernel
294
295     cd /usr/src/etc; make distribution
296
297
298 Once done, you may need to customize your `/etc/rc.conf` and `/etc/fstab` placed into `DESTDIR` according to your needs.
299
300
301 #### 19.7.2.7 Configuring Swap 
302
303
304 If needed, a swap file located on the server can be accessed via NFS.
305
306
307 ##### 19.7.2.7.1 NFS Swap with DragonFly 
308
309
310 The swap file location and size can be specified with BOOTP/DHCP DragonFly-specific options 128 and 129. Examples of configuration files for **ISC DHCP 3.0** or **bootpd** follow:
311
312
313   1. Add the following lines to `dhcpd.conf`:
314
315         # Global section
316
317         option swap-path code 128 = string;
318
319         option swap-size code 129 = integer 32;
320
321         host margaux {
322
323           ... # Standard lines, see above
324
325           option swap-path 192.168.4.4:/netswapvolume/netswap;
326
327           option swap-size 64000;
328
329         }
330
331
332   `swap-path` is the path to a directory where swap files will be located. Each file will be named `swap.client-ip`.
333
334   Older versions of  **dhcpd**  used a syntax of `option option-128 ...`, which is no longer supported.
335
336   `/etc/bootptab` would use the following syntax instead:
337
338       
339         T128#"192.168.4.4:/netswapvolume/netswap":T1290000fa00
340   
341
342    **Note:** In `/etc/bootptab`, the swap size must be expressed in hexadecimal format.
343
344   1. On the NFS swap file server, create the swap file(s)
345
346
347         # mkdir /netswapvolume/netswap
348
349         # cd /netswapvolume/netswap
350
351         # dd if=/dev/zero bs=1024 count=64000 of=swap.192.168.4.6
352
353         # chmod 0600 swap.`192.168.4.6`
354
355
356   `192.168.4.6` is the IP address for the diskless client.
357
358   1. On the NFS swap file server, add the following line to `/etc/exports`:
359
360       
361         /netswapvolume -maproot=0:10 -alldirs margaux corbieres
362
363
364   Then tell  **mountd**  to reread the exports file, as above.
365
366
367 #### 19.7.2.8 Miscellaneous Issues 
368
369
370 ##### 19.7.2.8.1 Running with a Read-only `/usr` 
371
372
373 If the diskless workstation is configured to run X, you will have to adjust the xdm configuration file, which puts the error log on `/usr` by default.
374
375
376 ##### 19.7.2.8.2 Using a Non-DragonFly Server 
377
378
379 When the server for the root filesystem is not running DragonFly, you will have to create the root filesystem on a DragonFly machine, then copy it to its destination, using `tar` or `cpio`.
380
381
382 In this situation, there are sometimes problems with the special files in `/dev`, due to differing major/minor integer sizes. A solution to this problem is to export a directory from the non-DragonFly server, mount this directory onto a DragonFly machine, and run `MAKEDEV` on the DragonFly machine to create the correct device entries.