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/ | |
fff9289b | 14 | ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/initrd.txt) or a |
64552a50 H |
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 | 69 | port = as given by server portmap daemon |
91dd26ad DA |
70 | rsize = 4096 |
71 | wsize = 4096 | |
1da177e4 LT |
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' | |
f33e1d9f AW |
95 | parameter (without all the ':' characters before). If the value is |
96 | "ip=off" or "ip=none", no autoconfiguration will take place, otherwise | |
97 | autoconfiguration will take place. The most common way to use this | |
98 | is "ip=dhcp". | |
99 | ||
64552a50 | 100 | <client-ip> IP address of the client. |
1da177e4 | 101 | |
64552a50 | 102 | Default: Determined using autoconfiguration. |
1da177e4 LT |
103 | |
104 | <server-ip> IP address of the NFS server. If RARP is used to determine | |
105 | the client address and this parameter is NOT empty only | |
64552a50 H |
106 | replies from the specified server are accepted. |
107 | ||
108 | Only required for for NFS root. That is autoconfiguration | |
109 | will not be triggered if it is missing and NFS root is not | |
110 | in operation. | |
111 | ||
112 | Default: Determined using autoconfiguration. | |
113 | The address of the autoconfiguration server is used. | |
114 | ||
115 | <gw-ip> IP address of a gateway if the server is on a different subnet. | |
116 | ||
117 | Default: Determined using autoconfiguration. | |
118 | ||
119 | <netmask> Netmask for local network interface. If unspecified | |
1da177e4 | 120 | the netmask is derived from the client IP address assuming |
64552a50 | 121 | classful addressing. |
1da177e4 | 122 | |
64552a50 | 123 | Default: Determined using autoconfiguration. |
1da177e4 | 124 | |
64552a50 H |
125 | <hostname> Name of the client. May be supplied by autoconfiguration, |
126 | but its absence will not trigger autoconfiguration. | |
1da177e4 | 127 | |
64552a50 | 128 | Default: Client IP address is used in ASCII notation. |
1da177e4 | 129 | |
64552a50 H |
130 | <device> Name of network device to use. |
131 | ||
132 | Default: If the host only has one device, it is used. | |
133 | Otherwise the device is determined using | |
134 | autoconfiguration. This is done by sending | |
135 | autoconfiguration requests out of all devices, | |
136 | and using the device that received the first reply. | |
1da177e4 | 137 | |
64552a50 H |
138 | <autoconf> Method to use for autoconfiguration. In the case of options |
139 | which specify multiple autoconfiguration protocols, | |
140 | requests are sent using all protocols, and the first one | |
141 | to reply is used. | |
1da177e4 | 142 | |
64552a50 H |
143 | Only autoconfiguration protocols that have been compiled |
144 | into the kernel will be used, regardless of the value of | |
145 | this option. | |
1da177e4 | 146 | |
f33e1d9f | 147 | off or none: don't use autoconfiguration |
92ffb85d | 148 | (do static IP assignment instead) |
64552a50 | 149 | on or any: use any protocol available in the kernel |
a6c05c3d | 150 | (default) |
64552a50 H |
151 | dhcp: use DHCP |
152 | bootp: use BOOTP | |
153 | rarp: use RARP | |
154 | both: use both BOOTP and RARP but not DHCP | |
155 | (old option kept for backwards compatibility) | |
1da177e4 | 156 | |
64552a50 | 157 | Default: any |
1da177e4 | 158 | |
1da177e4 LT |
159 | |
160 | ||
1da177e4 | 161 | |
64552a50 H |
162 | 3.) Boot Loader |
163 | ---------- | |
1da177e4 | 164 | |
64552a50 H |
165 | To get the kernel into memory different approaches can be used. |
166 | They depend on various facilities being available: | |
1da177e4 | 167 | |
1da177e4 | 168 | |
64552a50 | 169 | 3.1) Booting from a floppy using syslinux |
1da177e4 | 170 | |
64552a50 | 171 | When building kernels, an easy way to create a boot floppy that uses |
1c828320 | 172 | syslinux is to use the zdisk or bzdisk make targets which use zimage |
64552a50 H |
173 | and bzimage images respectively. Both targets accept the |
174 | FDARGS parameter which can be used to set the kernel command line. | |
1da177e4 | 175 | |
64552a50 H |
176 | e.g. |
177 | make bzdisk FDARGS="root=/dev/nfs" | |
178 | ||
179 | Note that the user running this command will need to have | |
180 | access to the floppy drive device, /dev/fd0 | |
181 | ||
182 | For more information on syslinux, including how to create bootdisks | |
183 | for prebuilt kernels, see http://syslinux.zytor.com/ | |
184 | ||
185 | N.B: Previously it was possible to write a kernel directly to | |
186 | a floppy using dd, configure the boot device using rdev, and | |
187 | boot using the resulting floppy. Linux no longer supports this | |
188 | method of booting. | |
189 | ||
190 | 3.2) Booting from a cdrom using isolinux | |
191 | ||
192 | When building kernels, an easy way to create a bootable cdrom that | |
193 | uses isolinux is to use the isoimage target which uses a bzimage | |
194 | image. Like zdisk and bzdisk, this target accepts the FDARGS | |
195 | parameter which can be used to set the kernel command line. | |
196 | ||
197 | e.g. | |
198 | make isoimage FDARGS="root=/dev/nfs" | |
199 | ||
200 | The resulting iso image will be arch/<ARCH>/boot/image.iso | |
201 | This can be written to a cdrom using a variety of tools including | |
202 | cdrecord. | |
203 | ||
204 | e.g. | |
205 | cdrecord dev=ATAPI:1,0,0 arch/i386/boot/image.iso | |
206 | ||
207 | For more information on isolinux, including how to create bootdisks | |
208 | for prebuilt kernels, see http://syslinux.zytor.com/ | |
1da177e4 | 209 | |
1da177e4 | 210 | 3.2) Using LILO |
64552a50 H |
211 | When using LILO all the necessary command line parameters may be |
212 | specified using the 'append=' directive in the LILO configuration | |
213 | file. | |
214 | ||
215 | However, to use the 'root=' directive you also need to create | |
216 | a dummy root device, which may be removed after LILO is run. | |
217 | ||
218 | mknod /dev/boot255 c 0 255 | |
219 | ||
220 | For information on configuring LILO, please refer to its documentation. | |
1da177e4 | 221 | |
7e9dd124 | 222 | 3.3) Using GRUB |
64552a50 H |
223 | When using GRUB, kernel parameter are simply appended after the kernel |
224 | specification: kernel <kernel> <parameters> | |
7e9dd124 NS |
225 | |
226 | 3.4) Using loadlin | |
64552a50 H |
227 | loadlin may be used to boot Linux from a DOS command prompt without |
228 | requiring a local hard disk to mount as root. This has not been | |
229 | thoroughly tested by the authors of this document, but in general | |
230 | it should be possible configure the kernel command line similarly | |
231 | to the configuration of LILO. | |
232 | ||
233 | Please refer to the loadlin documentation for further information. | |
1da177e4 | 234 | |
7e9dd124 | 235 | 3.5) Using a boot ROM |
64552a50 H |
236 | This is probably the most elegant way of booting a diskless client. |
237 | With a boot ROM the kernel is loaded using the TFTP protocol. The | |
238 | authors of this document are not aware of any no commercial boot | |
239 | ROMs that support booting Linux over the network. However, there | |
240 | are two free implementations of a boot ROM, netboot-nfs and | |
241 | etherboot, both of which are available on sunsite.unc.edu, and both | |
242 | of which contain everything you need to boot a diskless Linux client. | |
1da177e4 | 243 | |
7e9dd124 | 244 | 3.6) Using pxelinux |
64552a50 H |
245 | Pxelinux may be used to boot linux using the PXE boot loader |
246 | which is present on many modern network cards. | |
247 | ||
248 | When using pxelinux, the kernel image is specified using | |
7e9dd124 NS |
249 | "kernel <relative-path-below /tftpboot>". The nfsroot parameters |
250 | are passed to the kernel by adding them to the "append" line. | |
64552a50 H |
251 | It is common to use serial console in conjunction with pxeliunx, |
252 | see Documentation/serial-console.txt for more information. | |
253 | ||
254 | For more information on isolinux, including how to create bootdisks | |
255 | for prebuilt kernels, see http://syslinux.zytor.com/ | |
7e9dd124 | 256 | |
1da177e4 LT |
257 | |
258 | ||
259 | ||
260 | 4.) Credits | |
261 | ------- | |
262 | ||
263 | The nfsroot code in the kernel and the RARP support have been written | |
264 | by Gero Kuhlmann <gero@gkminix.han.de>. | |
265 | ||
266 | The rest of the IP layer autoconfiguration code has been written | |
267 | by Martin Mares <mj@atrey.karlin.mff.cuni.cz>. | |
268 | ||
269 | In order to write the initial version of nfsroot I would like to thank | |
270 | Jens-Uwe Mager <jum@anubis.han.de> for his help. |