1Mounting the root filesystem via NFS (nfsroot) 2=============================================== 3 4Written 1996 by Gero Kuhlmann <gero@gkminix.han.de> 5Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz> 6Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org> 7Updated 2006 by Horms <horms@verge.net.au> 8 9 10 11In order to use a diskless system, such as an X-terminal or printer server 12for example, it is necessary for the root filesystem to be present on a 13non-disk device. This may be an initramfs (see Documentation/filesystems/ 14ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/initrd.txt) or a 15filesystem mounted via NFS. The following text describes on how to use NFS 16for the root filesystem. For the rest of this text 'client' means the 17diskless system, and 'server' means the NFS server. 18 19 20 21 221.) Enabling nfsroot capabilities 23 ----------------------------- 24 25In order to use nfsroot, NFS client support needs to be selected as 26built-in during configuration. Once this has been selected, the nfsroot 27option will become available, which should also be selected. 28 29In the networking options, kernel level autoconfiguration can be selected, 30along with the types of autoconfiguration to support. Selecting all of 31DHCP, BOOTP and RARP is safe. 32 33 34 35 362.) Kernel command line 37 ------------------- 38 39When the kernel has been loaded by a boot loader (see below) it needs to be 40told what root fs device to use. And in the case of nfsroot, where to find 41both the server and the name of the directory on the server to mount as root. 42This can be established using the following kernel command line parameters: 43 44 45root=/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 52nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] 53 54 If the `nfsroot' parameter is NOT given on the command line, 55 the default "/tftpboot/%s" will be used. 56 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. 61 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. 66 67 <nfs-options> Standard NFS options. All options are separated by commas. 68 The following defaults are used: 69 port = as given by server portmap daemon 70 rsize = 4096 71 wsize = 4096 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 81ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> 82 83 This parameter tells the kernel how to configure IP addresses of devices 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. 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 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). 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 <client-ip> IP address of the client. 101 102 Default: Determined using autoconfiguration. 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 106 replies from the specified server are accepted. 107 108 Only required 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 120 the netmask is derived from the client IP address assuming 121 classful addressing. 122 123 Default: Determined using autoconfiguration. 124 125 <hostname> Name of the client. May be supplied by autoconfiguration, 126 but its absence will not trigger autoconfiguration. 127 If specified and DHCP is used, the user provided hostname will 128 be carried in the DHCP request to hopefully update DNS record. 129 130 Default: Client IP address is used in ASCII notation. 131 132 <device> Name of network device to use. 133 134 Default: If the host only has one device, it is used. 135 Otherwise the device is determined using 136 autoconfiguration. This is done by sending 137 autoconfiguration requests out of all devices, 138 and using the device that received the first reply. 139 140 <autoconf> Method to use for autoconfiguration. In the case of options 141 which specify multiple autoconfiguration protocols, 142 requests are sent using all protocols, and the first one 143 to reply is used. 144 145 Only autoconfiguration protocols that have been compiled 146 into the kernel will be used, regardless of the value of 147 this option. 148 149 off or none: don't use autoconfiguration 150 (do static IP assignment instead) 151 on or any: use any protocol available in the kernel 152 (default) 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 160 161 162 163 1643.) Boot Loader 165 ---------- 166 167To get the kernel into memory different approaches can be used. 168They depend on various facilities being available: 169 170 1713.1) Booting from a floppy using syslinux 172 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 zimage 175 and bzimage images respectively. Both targets accept the 176 FDARGS parameter which can be used to set the kernel command line. 177 178 e.g. 179 make bzdisk FDARGS="root=/dev/nfs" 180 181 Note that the user running this command will need to have 182 access to the floppy drive device, /dev/fd0 183 184 For more information on syslinux, including how to create bootdisks 185 for prebuilt kernels, see http://syslinux.zytor.com/ 186 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. 191 1923.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/ 211 2123.2) Using LILO 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. 223 2243.3) Using GRUB 225 When using GRUB, kernel parameter are simply appended after the kernel 226 specification: kernel <kernel> <parameters> 227 2283.4) Using loadlin 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. 236 2373.5) Using a boot ROM 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. 245 2463.6) Using pxelinux 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 251 "kernel <relative-path-below /tftpboot>". The nfsroot parameters 252 are passed to the kernel by adding them to the "append" line. 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/ 258 259 260 261 2624.) 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. 273