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