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 162nfsrootdebug 163 164 This parameter enables debugging messages to appear in the kernel 165 log at boot time so that administrators can verify that the correct 166 NFS mount options, server address, and root path are passed to the 167 NFS client. 168 169 170rdinit=<executable file> 171 172 To specify which file contains the program that starts system 173 initialization, administrators can use this command line parameter. 174 The default value of this parameter is "/init". If the specified 175 file exists and the kernel can execute it, root filesystem related 176 kernel command line parameters, including `nfsroot=', are ignored. 177 178 A description of the process of mounting the root file system can be 179 found in: 180 181 Documentation/early-userspace/README 182 183 184 185 1863.) Boot Loader 187 ---------- 188 189To get the kernel into memory different approaches can be used. 190They depend on various facilities being available: 191 192 1933.1) Booting from a floppy using syslinux 194 195 When building kernels, an easy way to create a boot floppy that uses 196 syslinux is to use the zdisk or bzdisk make targets which use zimage 197 and bzimage images respectively. Both targets accept the 198 FDARGS parameter which can be used to set the kernel command line. 199 200 e.g. 201 make bzdisk FDARGS="root=/dev/nfs" 202 203 Note that the user running this command will need to have 204 access to the floppy drive device, /dev/fd0 205 206 For more information on syslinux, including how to create bootdisks 207 for prebuilt kernels, see http://syslinux.zytor.com/ 208 209 N.B: Previously it was possible to write a kernel directly to 210 a floppy using dd, configure the boot device using rdev, and 211 boot using the resulting floppy. Linux no longer supports this 212 method of booting. 213 2143.2) Booting from a cdrom using isolinux 215 216 When building kernels, an easy way to create a bootable cdrom that 217 uses isolinux is to use the isoimage target which uses a bzimage 218 image. Like zdisk and bzdisk, this target accepts the FDARGS 219 parameter which can be used to set the kernel command line. 220 221 e.g. 222 make isoimage FDARGS="root=/dev/nfs" 223 224 The resulting iso image will be arch/<ARCH>/boot/image.iso 225 This can be written to a cdrom using a variety of tools including 226 cdrecord. 227 228 e.g. 229 cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso 230 231 For more information on isolinux, including how to create bootdisks 232 for prebuilt kernels, see http://syslinux.zytor.com/ 233 2343.2) Using LILO 235 When using LILO all the necessary command line parameters may be 236 specified using the 'append=' directive in the LILO configuration 237 file. 238 239 However, to use the 'root=' directive you also need to create 240 a dummy root device, which may be removed after LILO is run. 241 242 mknod /dev/boot255 c 0 255 243 244 For information on configuring LILO, please refer to its documentation. 245 2463.3) Using GRUB 247 When using GRUB, kernel parameter are simply appended after the kernel 248 specification: kernel <kernel> <parameters> 249 2503.4) Using loadlin 251 loadlin may be used to boot Linux from a DOS command prompt without 252 requiring a local hard disk to mount as root. This has not been 253 thoroughly tested by the authors of this document, but in general 254 it should be possible configure the kernel command line similarly 255 to the configuration of LILO. 256 257 Please refer to the loadlin documentation for further information. 258 2593.5) Using a boot ROM 260 This is probably the most elegant way of booting a diskless client. 261 With a boot ROM the kernel is loaded using the TFTP protocol. The 262 authors of this document are not aware of any no commercial boot 263 ROMs that support booting Linux over the network. However, there 264 are two free implementations of a boot ROM, netboot-nfs and 265 etherboot, both of which are available on sunsite.unc.edu, and both 266 of which contain everything you need to boot a diskless Linux client. 267 2683.6) Using pxelinux 269 Pxelinux may be used to boot linux using the PXE boot loader 270 which is present on many modern network cards. 271 272 When using pxelinux, the kernel image is specified using 273 "kernel <relative-path-below /tftpboot>". The nfsroot parameters 274 are passed to the kernel by adding them to the "append" line. 275 It is common to use serial console in conjunction with pxeliunx, 276 see Documentation/serial-console.txt for more information. 277 278 For more information on isolinux, including how to create bootdisks 279 for prebuilt kernels, see http://syslinux.zytor.com/ 280 281 282 283 2844.) Credits 285 ------- 286 287 The nfsroot code in the kernel and the RARP support have been written 288 by Gero Kuhlmann <gero@gkminix.han.de>. 289 290 The rest of the IP layer autoconfiguration code has been written 291 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>. 292 293 In order to write the initial version of nfsroot I would like to thank 294 Jens-Uwe Mager <jum@anubis.han.de> for his help. 295