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