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 <dns0-ip>:<dns1-ip> 83 84 This parameter tells the kernel how to configure IP addresses of devices 85 and also how to set up the IP routing table. It was originally called 86 `nfsaddrs', but now the boot-time IP configuration works independently of 87 NFS, so it was renamed to `ip' and the old name remained as an alias for 88 compatibility reasons. 89 90 If this parameter is missing from the kernel command line, all fields are 91 assumed to be empty, and the defaults mentioned below apply. In general 92 this means that the kernel tries to configure everything using 93 autoconfiguration. 94 95 The <autoconf> parameter can appear alone as the value to the `ip' 96 parameter (without all the ':' characters before). If the value is 97 "ip=off" or "ip=none", no autoconfiguration will take place, otherwise 98 autoconfiguration will take place. The most common way to use this 99 is "ip=dhcp". 100 101 <client-ip> IP address of the client. 102 103 Default: Determined using autoconfiguration. 104 105 <server-ip> IP address of the NFS server. If RARP is used to determine 106 the client address and this parameter is NOT empty only 107 replies from the specified server are accepted. 108 109 Only required for NFS root. That is autoconfiguration 110 will not be triggered if it is missing and NFS root is not 111 in operation. 112 113 Default: Determined using autoconfiguration. 114 The address of the autoconfiguration server is used. 115 116 <gw-ip> IP address of a gateway if the server is on a different subnet. 117 118 Default: Determined using autoconfiguration. 119 120 <netmask> Netmask for local network interface. If unspecified 121 the netmask is derived from the client IP address assuming 122 classful addressing. 123 124 Default: Determined using autoconfiguration. 125 126 <hostname> Name of the client. May be supplied by autoconfiguration, 127 but its absence will not trigger autoconfiguration. 128 If specified and DHCP is used, the user provided hostname will 129 be carried in the DHCP request to hopefully update DNS record. 130 131 Default: Client IP address is used in ASCII notation. 132 133 <device> Name of network device to use. 134 135 Default: If the host only has one device, it is used. 136 Otherwise the device is determined using 137 autoconfiguration. This is done by sending 138 autoconfiguration requests out of all devices, 139 and using the device that received the first reply. 140 141 <autoconf> Method to use for autoconfiguration. In the case of options 142 which specify multiple autoconfiguration protocols, 143 requests are sent using all protocols, and the first one 144 to reply is used. 145 146 Only autoconfiguration protocols that have been compiled 147 into the kernel will be used, regardless of the value of 148 this option. 149 150 off or none: don't use autoconfiguration 151 (do static IP assignment instead) 152 on or any: use any protocol available in the kernel 153 (default) 154 dhcp: use DHCP 155 bootp: use BOOTP 156 rarp: use RARP 157 both: use both BOOTP and RARP but not DHCP 158 (old option kept for backwards compatibility) 159 160 Default: any 161 162 <dns0-ip> IP address of first nameserver. 163 Value gets exported by /proc/net/pnp which is often linked 164 on embedded systems by /etc/resolv.conf. 165 166 <dns1-ip> IP address of secound nameserver. 167 Same as above. 168 169 170nfsrootdebug 171 172 This parameter enables debugging messages to appear in the kernel 173 log at boot time so that administrators can verify that the correct 174 NFS mount options, server address, and root path are passed to the 175 NFS client. 176 177 178rdinit=<executable file> 179 180 To specify which file contains the program that starts system 181 initialization, administrators can use this command line parameter. 182 The default value of this parameter is "/init". If the specified 183 file exists and the kernel can execute it, root filesystem related 184 kernel command line parameters, including `nfsroot=', are ignored. 185 186 A description of the process of mounting the root file system can be 187 found in: 188 189 Documentation/early-userspace/README 190 191 192 193 1943.) Boot Loader 195 ---------- 196 197To get the kernel into memory different approaches can be used. 198They depend on various facilities being available: 199 200 2013.1) Booting from a floppy using syslinux 202 203 When building kernels, an easy way to create a boot floppy that uses 204 syslinux is to use the zdisk or bzdisk make targets which use zimage 205 and bzimage images respectively. Both targets accept the 206 FDARGS parameter which can be used to set the kernel command line. 207 208 e.g. 209 make bzdisk FDARGS="root=/dev/nfs" 210 211 Note that the user running this command will need to have 212 access to the floppy drive device, /dev/fd0 213 214 For more information on syslinux, including how to create bootdisks 215 for prebuilt kernels, see http://syslinux.zytor.com/ 216 217 N.B: Previously it was possible to write a kernel directly to 218 a floppy using dd, configure the boot device using rdev, and 219 boot using the resulting floppy. Linux no longer supports this 220 method of booting. 221 2223.2) Booting from a cdrom using isolinux 223 224 When building kernels, an easy way to create a bootable cdrom that 225 uses isolinux is to use the isoimage target which uses a bzimage 226 image. Like zdisk and bzdisk, this target accepts the FDARGS 227 parameter which can be used to set the kernel command line. 228 229 e.g. 230 make isoimage FDARGS="root=/dev/nfs" 231 232 The resulting iso image will be arch/<ARCH>/boot/image.iso 233 This can be written to a cdrom using a variety of tools including 234 cdrecord. 235 236 e.g. 237 cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso 238 239 For more information on isolinux, including how to create bootdisks 240 for prebuilt kernels, see http://syslinux.zytor.com/ 241 2423.2) Using LILO 243 When using LILO all the necessary command line parameters may be 244 specified using the 'append=' directive in the LILO configuration 245 file. 246 247 However, to use the 'root=' directive you also need to create 248 a dummy root device, which may be removed after LILO is run. 249 250 mknod /dev/boot255 c 0 255 251 252 For information on configuring LILO, please refer to its documentation. 253 2543.3) Using GRUB 255 When using GRUB, kernel parameter are simply appended after the kernel 256 specification: kernel <kernel> <parameters> 257 2583.4) Using loadlin 259 loadlin may be used to boot Linux from a DOS command prompt without 260 requiring a local hard disk to mount as root. This has not been 261 thoroughly tested by the authors of this document, but in general 262 it should be possible configure the kernel command line similarly 263 to the configuration of LILO. 264 265 Please refer to the loadlin documentation for further information. 266 2673.5) Using a boot ROM 268 This is probably the most elegant way of booting a diskless client. 269 With a boot ROM the kernel is loaded using the TFTP protocol. The 270 authors of this document are not aware of any no commercial boot 271 ROMs that support booting Linux over the network. However, there 272 are two free implementations of a boot ROM, netboot-nfs and 273 etherboot, both of which are available on sunsite.unc.edu, and both 274 of which contain everything you need to boot a diskless Linux client. 275 2763.6) Using pxelinux 277 Pxelinux may be used to boot linux using the PXE boot loader 278 which is present on many modern network cards. 279 280 When using pxelinux, the kernel image is specified using 281 "kernel <relative-path-below /tftpboot>". The nfsroot parameters 282 are passed to the kernel by adding them to the "append" line. 283 It is common to use serial console in conjunction with pxeliunx, 284 see Documentation/serial-console.txt for more information. 285 286 For more information on isolinux, including how to create bootdisks 287 for prebuilt kernels, see http://syslinux.zytor.com/ 288 289 290 291 2924.) Credits 293 ------- 294 295 The nfsroot code in the kernel and the RARP support have been written 296 by Gero Kuhlmann <gero@gkminix.han.de>. 297 298 The rest of the IP layer autoconfiguration code has been written 299 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>. 300 301 In order to write the initial version of nfsroot I would like to thank 302 Jens-Uwe Mager <jum@anubis.han.de> for his help. 303