Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Mounting the root filesystem via NFS (nfsroot) |
2 | =============================================== | |
3 | ||
4 | Written 1996 by Gero Kuhlmann <gero@gkminix.han.de> | |
5 | Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz> | |
7e9dd124 | 6 | Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org> |
64552a50 | 7 | Updated 2006 by Horms <horms@verge.net.au> |
1da177e4 LT |
8 | |
9 | ||
10 | ||
64552a50 H |
11 | In order to use a diskless system, such as an X-terminal or printer server |
12 | for example, it is necessary for the root filesystem to be present on a | |
13 | non-disk device. This may be an initramfs (see Documentation/filesystems/ | |
14 | ramfs-rootfs-initramfs.txt), a ramdisk (see Documenation/initrd.txt) or a | |
15 | filesystem mounted via NFS. The following text describes on how to use NFS | |
16 | for the root filesystem. For the rest of this text 'client' means the | |
1da177e4 LT |
17 | diskless system, and 'server' means the NFS server. |
18 | ||
19 | ||
20 | ||
21 | ||
22 | 1.) Enabling nfsroot capabilities | |
23 | ----------------------------- | |
24 | ||
64552a50 H |
25 | In order to use nfsroot, NFS client support needs to be selected as |
26 | built-in during configuration. Once this has been selected, the nfsroot | |
27 | option will become available, which should also be selected. | |
28 | ||
29 | In the networking options, kernel level autoconfiguration can be selected, | |
30 | along with the types of autoconfiguration to support. Selecting all of | |
31 | DHCP, BOOTP and RARP is safe. | |
1da177e4 LT |
32 | |
33 | ||
34 | ||
35 | ||
36 | 2.) Kernel command line | |
37 | ------------------- | |
38 | ||
64552a50 H |
39 | When the kernel has been loaded by a boot loader (see below) it needs to be |
40 | told what root fs device to use. And in the case of nfsroot, where to find | |
41 | both the server and the name of the directory on the server to mount as root. | |
42 | This can be established using the following kernel command line parameters: | |
1da177e4 LT |
43 | |
44 | ||
45 | root=/dev/nfs | |
46 | ||
47 | This is necessary to enable the pseudo-NFS-device. Note that it's not a | |
48 | real device but just a synonym to tell the kernel to use NFS instead of | |
49 | a real device. | |
50 | ||
51 | ||
52 | nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] | |
53 | ||
64552a50 H |
54 | If the `nfsroot' parameter is NOT given on the command line, |
55 | the default "/tftpboot/%s" will be used. | |
1da177e4 | 56 | |
64552a50 H |
57 | <server-ip> Specifies the IP address of the NFS server. |
58 | The default address is determined by the `ip' parameter | |
59 | (see below). This parameter allows the use of different | |
60 | servers for IP autoconfiguration and NFS. | |
1da177e4 | 61 | |
64552a50 H |
62 | <root-dir> Name of the directory on the server to mount as root. |
63 | If there is a "%s" token in the string, it will be | |
64 | replaced by the ASCII-representation of the client's | |
65 | IP address. | |
1da177e4 LT |
66 | |
67 | <nfs-options> Standard NFS options. All options are separated by commas. | |
64552a50 | 68 | The following defaults are used: |
1da177e4 LT |
69 | port = as given by server portmap daemon |
70 | rsize = 1024 | |
71 | wsize = 1024 | |
72 | timeo = 7 | |
73 | retrans = 3 | |
74 | acregmin = 3 | |
75 | acregmax = 60 | |
76 | acdirmin = 30 | |
77 | acdirmax = 60 | |
78 | flags = hard, nointr, noposix, cto, ac | |
79 | ||
80 | ||
81 | ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> | |
82 | ||
83 | This parameter tells the kernel how to configure IP addresses of devices | |
64552a50 H |
84 | and also how to set up the IP routing table. It was originally called |
85 | `nfsaddrs', but now the boot-time IP configuration works independently of | |
86 | NFS, so it was renamed to `ip' and the old name remained as an alias for | |
87 | compatibility reasons. | |
1da177e4 LT |
88 | |
89 | If this parameter is missing from the kernel command line, all fields are | |
90 | assumed to be empty, and the defaults mentioned below apply. In general | |
64552a50 H |
91 | this means that the kernel tries to configure everything using |
92 | autoconfiguration. | |
93 | ||
94 | The <autoconf> parameter can appear alone as the value to the `ip' | |
95 | parameter (without all the ':' characters before) in which case auto- | |
96 | configuration is used. | |
97 | ||
98 | <client-ip> IP address of the client. | |
1da177e4 | 99 | |
64552a50 | 100 | Default: Determined using autoconfiguration. |
1da177e4 LT |
101 | |
102 | <server-ip> IP address of the NFS server. If RARP is used to determine | |
103 | the client address and this parameter is NOT empty only | |
64552a50 H |
104 | replies from the specified server are accepted. |
105 | ||
106 | Only required for for NFS root. That is autoconfiguration | |
107 | will not be triggered if it is missing and NFS root is not | |
108 | in operation. | |
109 | ||
110 | Default: Determined using autoconfiguration. | |
111 | The address of the autoconfiguration server is used. | |
112 | ||
113 | <gw-ip> IP address of a gateway if the server is on a different subnet. | |
114 | ||
115 | Default: Determined using autoconfiguration. | |
116 | ||
117 | <netmask> Netmask for local network interface. If unspecified | |
1da177e4 | 118 | the netmask is derived from the client IP address assuming |
64552a50 | 119 | classful addressing. |
1da177e4 | 120 | |
64552a50 | 121 | Default: Determined using autoconfiguration. |
1da177e4 | 122 | |
64552a50 H |
123 | <hostname> Name of the client. May be supplied by autoconfiguration, |
124 | but its absence will not trigger autoconfiguration. | |
1da177e4 | 125 | |
64552a50 | 126 | Default: Client IP address is used in ASCII notation. |
1da177e4 | 127 | |
64552a50 H |
128 | <device> Name of network device to use. |
129 | ||
130 | Default: If the host only has one device, it is used. | |
131 | Otherwise the device is determined using | |
132 | autoconfiguration. This is done by sending | |
133 | autoconfiguration requests out of all devices, | |
134 | and using the device that received the first reply. | |
1da177e4 | 135 | |
64552a50 H |
136 | <autoconf> Method to use for autoconfiguration. In the case of options |
137 | which specify multiple autoconfiguration protocols, | |
138 | requests are sent using all protocols, and the first one | |
139 | to reply is used. | |
1da177e4 | 140 | |
64552a50 H |
141 | Only autoconfiguration protocols that have been compiled |
142 | into the kernel will be used, regardless of the value of | |
143 | this option. | |
1da177e4 | 144 | |
64552a50 H |
145 | off or none: don't use autoconfiguration (default) |
146 | on or any: use any protocol available in the kernel | |
147 | dhcp: use DHCP | |
148 | bootp: use BOOTP | |
149 | rarp: use RARP | |
150 | both: use both BOOTP and RARP but not DHCP | |
151 | (old option kept for backwards compatibility) | |
1da177e4 | 152 | |
64552a50 | 153 | Default: any |
1da177e4 | 154 | |
1da177e4 LT |
155 | |
156 | ||
1da177e4 | 157 | |
64552a50 H |
158 | 3.) Boot Loader |
159 | ---------- | |
1da177e4 | 160 | |
64552a50 H |
161 | To get the kernel into memory different approaches can be used. |
162 | They depend on various facilities being available: | |
1da177e4 | 163 | |
1da177e4 | 164 | |
64552a50 | 165 | 3.1) Booting from a floppy using syslinux |
1da177e4 | 166 | |
64552a50 H |
167 | When building kernels, an easy way to create a boot floppy that uses |
168 | syslinux is to use the zdisk or bzdisk make targets which use | |
169 | and bzimage images respectively. Both targets accept the | |
170 | FDARGS parameter which can be used to set the kernel command line. | |
1da177e4 | 171 | |
64552a50 H |
172 | e.g. |
173 | make bzdisk FDARGS="root=/dev/nfs" | |
174 | ||
175 | Note that the user running this command will need to have | |
176 | access to the floppy drive device, /dev/fd0 | |
177 | ||
178 | For more information on syslinux, including how to create bootdisks | |
179 | for prebuilt kernels, see http://syslinux.zytor.com/ | |
180 | ||
181 | N.B: Previously it was possible to write a kernel directly to | |
182 | a floppy using dd, configure the boot device using rdev, and | |
183 | boot using the resulting floppy. Linux no longer supports this | |
184 | method of booting. | |
185 | ||
186 | 3.2) Booting from a cdrom using isolinux | |
187 | ||
188 | When building kernels, an easy way to create a bootable cdrom that | |
189 | uses isolinux is to use the isoimage target which uses a bzimage | |
190 | image. Like zdisk and bzdisk, this target accepts the FDARGS | |
191 | parameter which can be used to set the kernel command line. | |
192 | ||
193 | e.g. | |
194 | make isoimage FDARGS="root=/dev/nfs" | |
195 | ||
196 | The resulting iso image will be arch/<ARCH>/boot/image.iso | |
197 | This can be written to a cdrom using a variety of tools including | |
198 | cdrecord. | |
199 | ||
200 | e.g. | |
201 | cdrecord dev=ATAPI:1,0,0 arch/i386/boot/image.iso | |
202 | ||
203 | For more information on isolinux, including how to create bootdisks | |
204 | for prebuilt kernels, see http://syslinux.zytor.com/ | |
1da177e4 | 205 | |
1da177e4 | 206 | 3.2) Using LILO |
64552a50 H |
207 | When using LILO all the necessary command line parameters may be |
208 | specified using the 'append=' directive in the LILO configuration | |
209 | file. | |
210 | ||
211 | However, to use the 'root=' directive you also need to create | |
212 | a dummy root device, which may be removed after LILO is run. | |
213 | ||
214 | mknod /dev/boot255 c 0 255 | |
215 | ||
216 | For information on configuring LILO, please refer to its documentation. | |
1da177e4 | 217 | |
7e9dd124 | 218 | 3.3) Using GRUB |
64552a50 H |
219 | When using GRUB, kernel parameter are simply appended after the kernel |
220 | specification: kernel <kernel> <parameters> | |
7e9dd124 NS |
221 | |
222 | 3.4) Using loadlin | |
64552a50 H |
223 | loadlin may be used to boot Linux from a DOS command prompt without |
224 | requiring a local hard disk to mount as root. This has not been | |
225 | thoroughly tested by the authors of this document, but in general | |
226 | it should be possible configure the kernel command line similarly | |
227 | to the configuration of LILO. | |
228 | ||
229 | Please refer to the loadlin documentation for further information. | |
1da177e4 | 230 | |
7e9dd124 | 231 | 3.5) Using a boot ROM |
64552a50 H |
232 | This is probably the most elegant way of booting a diskless client. |
233 | With a boot ROM the kernel is loaded using the TFTP protocol. The | |
234 | authors of this document are not aware of any no commercial boot | |
235 | ROMs that support booting Linux over the network. However, there | |
236 | are two free implementations of a boot ROM, netboot-nfs and | |
237 | etherboot, both of which are available on sunsite.unc.edu, and both | |
238 | of which contain everything you need to boot a diskless Linux client. | |
1da177e4 | 239 | |
7e9dd124 | 240 | 3.6) Using pxelinux |
64552a50 H |
241 | Pxelinux may be used to boot linux using the PXE boot loader |
242 | which is present on many modern network cards. | |
243 | ||
244 | When using pxelinux, the kernel image is specified using | |
7e9dd124 NS |
245 | "kernel <relative-path-below /tftpboot>". The nfsroot parameters |
246 | are passed to the kernel by adding them to the "append" line. | |
64552a50 H |
247 | It is common to use serial console in conjunction with pxeliunx, |
248 | see Documentation/serial-console.txt for more information. | |
249 | ||
250 | For more information on isolinux, including how to create bootdisks | |
251 | for prebuilt kernels, see http://syslinux.zytor.com/ | |
7e9dd124 | 252 | |
1da177e4 LT |
253 | |
254 | ||
255 | ||
256 | 4.) Credits | |
257 | ------- | |
258 | ||
259 | The nfsroot code in the kernel and the RARP support have been written | |
260 | by Gero Kuhlmann <gero@gkminix.han.de>. | |
261 | ||
262 | The rest of the IP layer autoconfiguration code has been written | |
263 | by Martin Mares <mj@atrey.karlin.mff.cuni.cz>. | |
264 | ||
265 | In order to write the initial version of nfsroot I would like to thank | |
266 | Jens-Uwe Mager <jum@anubis.han.de> for his help. |