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) in which case auto- 96 configuration is used. 97 98 <client-ip> IP address of the client. 99 100 Default: Determined using autoconfiguration. 101 102 <server-ip> IP address of the NFS server. If RARP is used to determine 103 the client address and this parameter is NOT empty only 104 replies from the specified server are accepted. 105 106 Only required for for NFS root. That is autoconfiguration 107 will not be triggered if it is missing and NFS root is not 108 in operation. 109 110 Default: Determined using autoconfiguration. 111 The address of the autoconfiguration server is used. 112 113 <gw-ip> IP address of a gateway if the server is on a different subnet. 114 115 Default: Determined using autoconfiguration. 116 117 <netmask> Netmask for local network interface. If unspecified 118 the netmask is derived from the client IP address assuming 119 classful addressing. 120 121 Default: Determined using autoconfiguration. 122 123 <hostname> Name of the client. May be supplied by autoconfiguration, 124 but its absence will not trigger autoconfiguration. 125 126 Default: Client IP address is used in ASCII notation. 127 128 <device> Name of network device to use. 129 130 Default: If the host only has one device, it is used. 131 Otherwise the device is determined using 132 autoconfiguration. This is done by sending 133 autoconfiguration requests out of all devices, 134 and using the device that received the first reply. 135 136 <autoconf> Method to use for autoconfiguration. In the case of options 137 which specify multiple autoconfiguration protocols, 138 requests are sent using all protocols, and the first one 139 to reply is used. 140 141 Only autoconfiguration protocols that have been compiled 142 into the kernel will be used, regardless of the value of 143 this option. 144 145 off or none: don't use autoconfiguration (default) 146 on or any: use any protocol available in the kernel 147 dhcp: use DHCP 148 bootp: use BOOTP 149 rarp: use RARP 150 both: use both BOOTP and RARP but not DHCP 151 (old option kept for backwards compatibility) 152 153 Default: any 154 155 156 157 1583.) Boot Loader 159 ---------- 160 161To get the kernel into memory different approaches can be used. 162They depend on various facilities being available: 163 164 1653.1) Booting from a floppy using syslinux 166 167 When building kernels, an easy way to create a boot floppy that uses 168 syslinux is to use the zdisk or bzdisk make targets which use 169 and bzimage images respectively. Both targets accept the 170 FDARGS parameter which can be used to set the kernel command line. 171 172 e.g. 173 make bzdisk FDARGS="root=/dev/nfs" 174 175 Note that the user running this command will need to have 176 access to the floppy drive device, /dev/fd0 177 178 For more information on syslinux, including how to create bootdisks 179 for prebuilt kernels, see http://syslinux.zytor.com/ 180 181 N.B: Previously it was possible to write a kernel directly to 182 a floppy using dd, configure the boot device using rdev, and 183 boot using the resulting floppy. Linux no longer supports this 184 method of booting. 185 1863.2) Booting from a cdrom using isolinux 187 188 When building kernels, an easy way to create a bootable cdrom that 189 uses isolinux is to use the isoimage target which uses a bzimage 190 image. Like zdisk and bzdisk, this target accepts the FDARGS 191 parameter which can be used to set the kernel command line. 192 193 e.g. 194 make isoimage FDARGS="root=/dev/nfs" 195 196 The resulting iso image will be arch/<ARCH>/boot/image.iso 197 This can be written to a cdrom using a variety of tools including 198 cdrecord. 199 200 e.g. 201 cdrecord dev=ATAPI:1,0,0 arch/i386/boot/image.iso 202 203 For more information on isolinux, including how to create bootdisks 204 for prebuilt kernels, see http://syslinux.zytor.com/ 205 2063.2) Using LILO 207 When using LILO all the necessary command line parameters may be 208 specified using the 'append=' directive in the LILO configuration 209 file. 210 211 However, to use the 'root=' directive you also need to create 212 a dummy root device, which may be removed after LILO is run. 213 214 mknod /dev/boot255 c 0 255 215 216 For information on configuring LILO, please refer to its documentation. 217 2183.3) Using GRUB 219 When using GRUB, kernel parameter are simply appended after the kernel 220 specification: kernel <kernel> <parameters> 221 2223.4) Using loadlin 223 loadlin may be used to boot Linux from a DOS command prompt without 224 requiring a local hard disk to mount as root. This has not been 225 thoroughly tested by the authors of this document, but in general 226 it should be possible configure the kernel command line similarly 227 to the configuration of LILO. 228 229 Please refer to the loadlin documentation for further information. 230 2313.5) Using a boot ROM 232 This is probably the most elegant way of booting a diskless client. 233 With a boot ROM the kernel is loaded using the TFTP protocol. The 234 authors of this document are not aware of any no commercial boot 235 ROMs that support booting Linux over the network. However, there 236 are two free implementations of a boot ROM, netboot-nfs and 237 etherboot, both of which are available on sunsite.unc.edu, and both 238 of which contain everything you need to boot a diskless Linux client. 239 2403.6) Using pxelinux 241 Pxelinux may be used to boot linux using the PXE boot loader 242 which is present on many modern network cards. 243 244 When using pxelinux, the kernel image is specified using 245 "kernel <relative-path-below /tftpboot>". The nfsroot parameters 246 are passed to the kernel by adding them to the "append" line. 247 It is common to use serial console in conjunction with pxeliunx, 248 see Documentation/serial-console.txt for more information. 249 250 For more information on isolinux, including how to create bootdisks 251 for prebuilt kernels, see http://syslinux.zytor.com/ 252 253 254 255 2564.) Credits 257 ------- 258 259 The nfsroot code in the kernel and the RARP support have been written 260 by Gero Kuhlmann <gero@gkminix.han.de>. 261 262 The rest of the IP layer autoconfiguration code has been written 263 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>. 264 265 In order to write the initial version of nfsroot I would like to thank 266 Jens-Uwe Mager <jum@anubis.han.de> for his help. 267