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> 8Updated 2018 by Chris Novakovic <chris@chrisn.me.uk> 9 10 11 12In order to use a diskless system, such as an X-terminal or printer server 13for example, it is necessary for the root filesystem to be present on a 14non-disk device. This may be an initramfs (see Documentation/filesystems/ 15ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a 16filesystem mounted via NFS. The following text describes on how to use NFS 17for the root filesystem. For the rest of this text 'client' means the 18diskless system, and 'server' means the NFS server. 19 20 21 22 231.) Enabling nfsroot capabilities 24 ----------------------------- 25 26In order to use nfsroot, NFS client support needs to be selected as 27built-in during configuration. Once this has been selected, the nfsroot 28option will become available, which should also be selected. 29 30In the networking options, kernel level autoconfiguration can be selected, 31along with the types of autoconfiguration to support. Selecting all of 32DHCP, BOOTP and RARP is safe. 33 34 35 36 372.) Kernel command line 38 ------------------- 39 40When the kernel has been loaded by a boot loader (see below) it needs to be 41told what root fs device to use. And in the case of nfsroot, where to find 42both the server and the name of the directory on the server to mount as root. 43This can be established using the following kernel command line parameters: 44 45 46root=/dev/nfs 47 48 This is necessary to enable the pseudo-NFS-device. Note that it's not a 49 real device but just a synonym to tell the kernel to use NFS instead of 50 a real device. 51 52 53nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] 54 55 If the `nfsroot' parameter is NOT given on the command line, 56 the default "/tftpboot/%s" will be used. 57 58 <server-ip> Specifies the IP address of the NFS server. 59 The default address is determined by the `ip' parameter 60 (see below). This parameter allows the use of different 61 servers for IP autoconfiguration and NFS. 62 63 <root-dir> Name of the directory on the server to mount as root. 64 If there is a "%s" token in the string, it will be 65 replaced by the ASCII-representation of the client's 66 IP address. 67 68 <nfs-options> Standard NFS options. All options are separated by commas. 69 The following defaults are used: 70 port = as given by server portmap daemon 71 rsize = 4096 72 wsize = 4096 73 timeo = 7 74 retrans = 3 75 acregmin = 3 76 acregmax = 60 77 acdirmin = 30 78 acdirmax = 60 79 flags = hard, nointr, noposix, cto, ac 80 81 82ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: 83 <dns0-ip>:<dns1-ip>:<ntp0-ip> 84 85 This parameter tells the kernel how to configure IP addresses of devices 86 and also how to set up the IP routing table. It was originally called 87 `nfsaddrs', but now the boot-time IP configuration works independently of 88 NFS, so it was renamed to `ip' and the old name remained as an alias for 89 compatibility reasons. 90 91 If this parameter is missing from the kernel command line, all fields are 92 assumed to be empty, and the defaults mentioned below apply. In general 93 this means that the kernel tries to configure everything using 94 autoconfiguration. 95 96 The <autoconf> parameter can appear alone as the value to the `ip' 97 parameter (without all the ':' characters before). If the value is 98 "ip=off" or "ip=none", no autoconfiguration will take place, otherwise 99 autoconfiguration will take place. The most common way to use this 100 is "ip=dhcp". 101 102 <client-ip> IP address of the client. 103 104 Default: Determined using autoconfiguration. 105 106 <server-ip> IP address of the NFS server. If RARP is used to determine 107 the client address and this parameter is NOT empty only 108 replies from the specified server are accepted. 109 110 Only required for NFS root. That is autoconfiguration 111 will not be triggered if it is missing and NFS root is not 112 in operation. 113 114 Value is exported to /proc/net/pnp with the prefix "bootserver " 115 (see below). 116 117 Default: Determined using autoconfiguration. 118 The address of the autoconfiguration server is used. 119 120 <gw-ip> IP address of a gateway if the server is on a different subnet. 121 122 Default: Determined using autoconfiguration. 123 124 <netmask> Netmask for local network interface. If unspecified 125 the netmask is derived from the client IP address assuming 126 classful addressing. 127 128 Default: Determined using autoconfiguration. 129 130 <hostname> Name of the client. If a '.' character is present, anything 131 before the first '.' is used as the client's hostname, and anything 132 after it is used as its NIS domain name. May be supplied by 133 autoconfiguration, but its absence will not trigger autoconfiguration. 134 If specified and DHCP is used, the user-provided hostname (and NIS 135 domain name, if present) will be carried in the DHCP request; this 136 may cause a DNS record to be created or updated for the client. 137 138 Default: Client IP address is used in ASCII notation. 139 140 <device> Name of network device to use. 141 142 Default: If the host only has one device, it is used. 143 Otherwise the device is determined using 144 autoconfiguration. This is done by sending 145 autoconfiguration requests out of all devices, 146 and using the device that received the first reply. 147 148 <autoconf> Method to use for autoconfiguration. In the case of options 149 which specify multiple autoconfiguration protocols, 150 requests are sent using all protocols, and the first one 151 to reply is used. 152 153 Only autoconfiguration protocols that have been compiled 154 into the kernel will be used, regardless of the value of 155 this option. 156 157 off or none: don't use autoconfiguration 158 (do static IP assignment instead) 159 on or any: use any protocol available in the kernel 160 (default) 161 dhcp: use DHCP 162 bootp: use BOOTP 163 rarp: use RARP 164 both: use both BOOTP and RARP but not DHCP 165 (old option kept for backwards compatibility) 166 167 if dhcp is used, the client identifier can be used by following 168 format "ip=dhcp,client-id-type,client-id-value" 169 170 Default: any 171 172 <dns0-ip> IP address of primary nameserver. 173 Value is exported to /proc/net/pnp with the prefix "nameserver " 174 (see below). 175 176 Default: None if not using autoconfiguration; determined 177 automatically if using autoconfiguration. 178 179 <dns1-ip> IP address of secondary nameserver. 180 See <dns0-ip>. 181 182 <ntp0-ip> IP address of a Network Time Protocol (NTP) server. 183 Value is exported to /proc/net/ipconfig/ntp_servers, but is 184 otherwise unused (see below). 185 186 Default: None if not using autoconfiguration; determined 187 automatically if using autoconfiguration. 188 189 After configuration (whether manual or automatic) is complete, two files 190 are created in the following format; lines are omitted if their respective 191 value is empty following configuration: 192 193 - /proc/net/pnp: 194 195 #PROTO: <DHCP|BOOTP|RARP|MANUAL> (depending on configuration method) 196 domain <dns-domain> (if autoconfigured, the DNS domain) 197 nameserver <dns0-ip> (primary name server IP) 198 nameserver <dns1-ip> (secondary name server IP) 199 nameserver <dns2-ip> (tertiary name server IP) 200 bootserver <server-ip> (NFS server IP) 201 202 - /proc/net/ipconfig/ntp_servers: 203 204 <ntp0-ip> (NTP server IP) 205 <ntp1-ip> (NTP server IP) 206 <ntp2-ip> (NTP server IP) 207 208 <dns-domain> and <dns2-ip> (in /proc/net/pnp) and <ntp1-ip> and <ntp2-ip> 209 (in /proc/net/ipconfig/ntp_servers) are requested during autoconfiguration; 210 they cannot be specified as part of the "ip=" kernel command line parameter. 211 212 Because the "domain" and "nameserver" options are recognised by DNS 213 resolvers, /etc/resolv.conf is often linked to /proc/net/pnp on systems 214 that use an NFS root filesystem. 215 216 Note that the kernel will not synchronise the system time with any NTP 217 servers it discovers; this is the responsibility of a user space process 218 (e.g. an initrd/initramfs script that passes the IP addresses listed in 219 /proc/net/ipconfig/ntp_servers to an NTP client before mounting the real 220 root filesystem if it is on NFS). 221 222 223nfsrootdebug 224 225 This parameter enables debugging messages to appear in the kernel 226 log at boot time so that administrators can verify that the correct 227 NFS mount options, server address, and root path are passed to the 228 NFS client. 229 230 231rdinit=<executable file> 232 233 To specify which file contains the program that starts system 234 initialization, administrators can use this command line parameter. 235 The default value of this parameter is "/init". If the specified 236 file exists and the kernel can execute it, root filesystem related 237 kernel command line parameters, including `nfsroot=', are ignored. 238 239 A description of the process of mounting the root file system can be 240 found in: 241 242 Documentation/driver-api/early-userspace/early_userspace_support.rst 243 244 245 246 2473.) Boot Loader 248 ---------- 249 250To get the kernel into memory different approaches can be used. 251They depend on various facilities being available: 252 253 2543.1) Booting from a floppy using syslinux 255 256 When building kernels, an easy way to create a boot floppy that uses 257 syslinux is to use the zdisk or bzdisk make targets which use zimage 258 and bzimage images respectively. Both targets accept the 259 FDARGS parameter which can be used to set the kernel command line. 260 261 e.g. 262 make bzdisk FDARGS="root=/dev/nfs" 263 264 Note that the user running this command will need to have 265 access to the floppy drive device, /dev/fd0 266 267 For more information on syslinux, including how to create bootdisks 268 for prebuilt kernels, see http://syslinux.zytor.com/ 269 270 N.B: Previously it was possible to write a kernel directly to 271 a floppy using dd, configure the boot device using rdev, and 272 boot using the resulting floppy. Linux no longer supports this 273 method of booting. 274 2753.2) Booting from a cdrom using isolinux 276 277 When building kernels, an easy way to create a bootable cdrom that 278 uses isolinux is to use the isoimage target which uses a bzimage 279 image. Like zdisk and bzdisk, this target accepts the FDARGS 280 parameter which can be used to set the kernel command line. 281 282 e.g. 283 make isoimage FDARGS="root=/dev/nfs" 284 285 The resulting iso image will be arch/<ARCH>/boot/image.iso 286 This can be written to a cdrom using a variety of tools including 287 cdrecord. 288 289 e.g. 290 cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso 291 292 For more information on isolinux, including how to create bootdisks 293 for prebuilt kernels, see http://syslinux.zytor.com/ 294 2953.2) Using LILO 296 When using LILO all the necessary command line parameters may be 297 specified using the 'append=' directive in the LILO configuration 298 file. 299 300 However, to use the 'root=' directive you also need to create 301 a dummy root device, which may be removed after LILO is run. 302 303 mknod /dev/boot255 c 0 255 304 305 For information on configuring LILO, please refer to its documentation. 306 3073.3) Using GRUB 308 When using GRUB, kernel parameter are simply appended after the kernel 309 specification: kernel <kernel> <parameters> 310 3113.4) Using loadlin 312 loadlin may be used to boot Linux from a DOS command prompt without 313 requiring a local hard disk to mount as root. This has not been 314 thoroughly tested by the authors of this document, but in general 315 it should be possible configure the kernel command line similarly 316 to the configuration of LILO. 317 318 Please refer to the loadlin documentation for further information. 319 3203.5) Using a boot ROM 321 This is probably the most elegant way of booting a diskless client. 322 With a boot ROM the kernel is loaded using the TFTP protocol. The 323 authors of this document are not aware of any no commercial boot 324 ROMs that support booting Linux over the network. However, there 325 are two free implementations of a boot ROM, netboot-nfs and 326 etherboot, both of which are available on sunsite.unc.edu, and both 327 of which contain everything you need to boot a diskless Linux client. 328 3293.6) Using pxelinux 330 Pxelinux may be used to boot linux using the PXE boot loader 331 which is present on many modern network cards. 332 333 When using pxelinux, the kernel image is specified using 334 "kernel <relative-path-below /tftpboot>". The nfsroot parameters 335 are passed to the kernel by adding them to the "append" line. 336 It is common to use serial console in conjunction with pxeliunx, 337 see Documentation/admin-guide/serial-console.rst for more information. 338 339 For more information on isolinux, including how to create bootdisks 340 for prebuilt kernels, see http://syslinux.zytor.com/ 341 342 343 344 3454.) Credits 346 ------- 347 348 The nfsroot code in the kernel and the RARP support have been written 349 by Gero Kuhlmann <gero@gkminix.han.de>. 350 351 The rest of the IP layer autoconfiguration code has been written 352 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>. 353 354 In order to write the initial version of nfsroot I would like to thank 355 Jens-Uwe Mager <jum@anubis.han.de> for his help. 356
