0001 ===============================================
0002 Mounting the root filesystem via NFS (nfsroot)
0003 ===============================================
0004
0005 :Authors:
0006 Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
0007
0008 Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
0009
0010 Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
0011
0012 Updated 2006 by Horms <horms@verge.net.au>
0013
0014 Updated 2018 by Chris Novakovic <chris@chrisn.me.uk>
0015
0016
0017
0018 In order to use a diskless system, such as an X-terminal or printer server for
0019 example, it is necessary for the root filesystem to be present on a non-disk
0020 device. This may be an initramfs (see
0021 Documentation/filesystems/ramfs-rootfs-initramfs.rst), a ramdisk (see
0022 Documentation/admin-guide/initrd.rst) or a filesystem mounted via NFS. The
0023 following text describes on how to use NFS for the root filesystem. For the rest
0024 of this text 'client' means the diskless system, and 'server' means the NFS
0025 server.
0026
0027
0028
0029
0030 Enabling nfsroot capabilities
0031 =============================
0032
0033 In order to use nfsroot, NFS client support needs to be selected as
0034 built-in during configuration. Once this has been selected, the nfsroot
0035 option will become available, which should also be selected.
0036
0037 In the networking options, kernel level autoconfiguration can be selected,
0038 along with the types of autoconfiguration to support. Selecting all of
0039 DHCP, BOOTP and RARP is safe.
0040
0041
0042
0043
0044 Kernel command line
0045 ===================
0046
0047 When the kernel has been loaded by a boot loader (see below) it needs to be
0048 told what root fs device to use. And in the case of nfsroot, where to find
0049 both the server and the name of the directory on the server to mount as root.
0050 This can be established using the following kernel command line parameters:
0051
0052
0053 root=/dev/nfs
0054 This is necessary to enable the pseudo-NFS-device. Note that it's not a
0055 real device but just a synonym to tell the kernel to use NFS instead of
0056 a real device.
0057
0058
0059 nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
0060 If the `nfsroot' parameter is NOT given on the command line,
0061 the default ``"/tftpboot/%s"`` will be used.
0062
0063 <server-ip> Specifies the IP address of the NFS server.
0064 The default address is determined by the ip parameter
0065 (see below). This parameter allows the use of different
0066 servers for IP autoconfiguration and NFS.
0067
0068 <root-dir> Name of the directory on the server to mount as root.
0069 If there is a "%s" token in the string, it will be
0070 replaced by the ASCII-representation of the client's
0071 IP address.
0072
0073 <nfs-options> Standard NFS options. All options are separated by commas.
0074 The following defaults are used::
0075
0076 port = as given by server portmap daemon
0077 rsize = 4096
0078 wsize = 4096
0079 timeo = 7
0080 retrans = 3
0081 acregmin = 3
0082 acregmax = 60
0083 acdirmin = 30
0084 acdirmax = 60
0085 flags = hard, nointr, noposix, cto, ac
0086
0087
0088 ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip>
0089 This parameter tells the kernel how to configure IP addresses of devices
0090 and also how to set up the IP routing table. It was originally called
0091 nfsaddrs, but now the boot-time IP configuration works independently of
0092 NFS, so it was renamed to ip and the old name remained as an alias for
0093 compatibility reasons.
0094
0095 If this parameter is missing from the kernel command line, all fields are
0096 assumed to be empty, and the defaults mentioned below apply. In general
0097 this means that the kernel tries to configure everything using
0098 autoconfiguration.
0099
0100 The <autoconf> parameter can appear alone as the value to the ip
0101 parameter (without all the ':' characters before). If the value is
0102 "ip=off" or "ip=none", no autoconfiguration will take place, otherwise
0103 autoconfiguration will take place. The most common way to use this
0104 is "ip=dhcp".
0105
0106 <client-ip> IP address of the client.
0107 Default: Determined using autoconfiguration.
0108
0109 <server-ip> IP address of the NFS server.
0110 If RARP is used to determine
0111 the client address and this parameter is NOT empty only
0112 replies from the specified server are accepted.
0113
0114 Only required for NFS root. That is autoconfiguration
0115 will not be triggered if it is missing and NFS root is not
0116 in operation.
0117
0118 Value is exported to /proc/net/pnp with the prefix "bootserver "
0119 (see below).
0120
0121 Default: Determined using autoconfiguration.
0122 The address of the autoconfiguration server is used.
0123
0124 <gw-ip> IP address of a gateway if the server is on a different subnet.
0125 Default: Determined using autoconfiguration.
0126
0127 <netmask> Netmask for local network interface.
0128 If unspecified the netmask is derived from the client IP address
0129 assuming classful addressing.
0130
0131 Default: Determined using autoconfiguration.
0132
0133 <hostname> Name of the client.
0134 If a '.' character is present, anything
0135 before the first '.' is used as the client's hostname, and anything
0136 after it is used as its NIS domain name. May be supplied by
0137 autoconfiguration, but its absence will not trigger autoconfiguration.
0138 If specified and DHCP is used, the user-provided hostname (and NIS
0139 domain name, if present) will be carried in the DHCP request; this
0140 may cause a DNS record to be created or updated for the client.
0141
0142 Default: Client IP address is used in ASCII notation.
0143
0144 <device> Name of network device to use.
0145 Default: If the host only has one device, it is used.
0146 Otherwise the device is determined using
0147 autoconfiguration. This is done by sending
0148 autoconfiguration requests out of all devices,
0149 and using the device that received the first reply.
0150
0151 <autoconf> Method to use for autoconfiguration.
0152 In the case of options
0153 which specify multiple autoconfiguration protocols,
0154 requests are sent using all protocols, and the first one
0155 to reply is used.
0156
0157 Only autoconfiguration protocols that have been compiled
0158 into the kernel will be used, regardless of the value of
0159 this option::
0160
0161 off or none: don't use autoconfiguration
0162 (do static IP assignment instead)
0163 on or any: use any protocol available in the kernel
0164 (default)
0165 dhcp: use DHCP
0166 bootp: use BOOTP
0167 rarp: use RARP
0168 both: use both BOOTP and RARP but not DHCP
0169 (old option kept for backwards compatibility)
0170
0171 if dhcp is used, the client identifier can be used by following
0172 format "ip=dhcp,client-id-type,client-id-value"
0173
0174 Default: any
0175
0176 <dns0-ip> IP address of primary nameserver.
0177 Value is exported to /proc/net/pnp with the prefix "nameserver "
0178 (see below).
0179
0180 Default: None if not using autoconfiguration; determined
0181 automatically if using autoconfiguration.
0182
0183 <dns1-ip> IP address of secondary nameserver.
0184 See <dns0-ip>.
0185
0186 <ntp0-ip> IP address of a Network Time Protocol (NTP) server.
0187 Value is exported to /proc/net/ipconfig/ntp_servers, but is
0188 otherwise unused (see below).
0189
0190 Default: None if not using autoconfiguration; determined
0191 automatically if using autoconfiguration.
0192
0193 After configuration (whether manual or automatic) is complete, two files
0194 are created in the following format; lines are omitted if their respective
0195 value is empty following configuration:
0196
0197 - /proc/net/pnp:
0198
0199 #PROTO: <DHCP|BOOTP|RARP|MANUAL> (depending on configuration method)
0200 domain <dns-domain> (if autoconfigured, the DNS domain)
0201 nameserver <dns0-ip> (primary name server IP)
0202 nameserver <dns1-ip> (secondary name server IP)
0203 nameserver <dns2-ip> (tertiary name server IP)
0204 bootserver <server-ip> (NFS server IP)
0205
0206 - /proc/net/ipconfig/ntp_servers:
0207
0208 <ntp0-ip> (NTP server IP)
0209 <ntp1-ip> (NTP server IP)
0210 <ntp2-ip> (NTP server IP)
0211
0212 <dns-domain> and <dns2-ip> (in /proc/net/pnp) and <ntp1-ip> and <ntp2-ip>
0213 (in /proc/net/ipconfig/ntp_servers) are requested during autoconfiguration;
0214 they cannot be specified as part of the "ip=" kernel command line parameter.
0215
0216 Because the "domain" and "nameserver" options are recognised by DNS
0217 resolvers, /etc/resolv.conf is often linked to /proc/net/pnp on systems
0218 that use an NFS root filesystem.
0219
0220 Note that the kernel will not synchronise the system time with any NTP
0221 servers it discovers; this is the responsibility of a user space process
0222 (e.g. an initrd/initramfs script that passes the IP addresses listed in
0223 /proc/net/ipconfig/ntp_servers to an NTP client before mounting the real
0224 root filesystem if it is on NFS).
0225
0226
0227 nfsrootdebug
0228 This parameter enables debugging messages to appear in the kernel
0229 log at boot time so that administrators can verify that the correct
0230 NFS mount options, server address, and root path are passed to the
0231 NFS client.
0232
0233
0234 rdinit=<executable file>
0235 To specify which file contains the program that starts system
0236 initialization, administrators can use this command line parameter.
0237 The default value of this parameter is "/init". If the specified
0238 file exists and the kernel can execute it, root filesystem related
0239 kernel command line parameters, including 'nfsroot=', are ignored.
0240
0241 A description of the process of mounting the root file system can be
0242 found in Documentation/driver-api/early-userspace/early_userspace_support.rst
0243
0244
0245 Boot Loader
0246 ===========
0247
0248 To get the kernel into memory different approaches can be used.
0249 They depend on various facilities being available:
0250
0251
0252 - Booting from a floppy using syslinux
0253
0254 When building kernels, an easy way to create a boot floppy that uses
0255 syslinux is to use the zdisk or bzdisk make targets which use zimage
0256 and bzimage images respectively. Both targets accept the
0257 FDARGS parameter which can be used to set the kernel command line.
0258
0259 e.g::
0260
0261 make bzdisk FDARGS="root=/dev/nfs"
0262
0263 Note that the user running this command will need to have
0264 access to the floppy drive device, /dev/fd0
0265
0266 For more information on syslinux, including how to create bootdisks
0267 for prebuilt kernels, see https://syslinux.zytor.com/
0268
0269 .. note::
0270 Previously it was possible to write a kernel directly to
0271 a floppy using dd, configure the boot device using rdev, and
0272 boot using the resulting floppy. Linux no longer supports this
0273 method of booting.
0274
0275 - Booting from a cdrom using isolinux
0276
0277 When building kernels, an easy way to create a bootable cdrom that
0278 uses isolinux is to use the isoimage target which uses a bzimage
0279 image. Like zdisk and bzdisk, this target accepts the FDARGS
0280 parameter which can be used to set the kernel command line.
0281
0282 e.g::
0283
0284 make isoimage FDARGS="root=/dev/nfs"
0285
0286 The resulting iso image will be arch/<ARCH>/boot/image.iso
0287 This can be written to a cdrom using a variety of tools including
0288 cdrecord.
0289
0290 e.g::
0291
0292 cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso
0293
0294 For more information on isolinux, including how to create bootdisks
0295 for prebuilt kernels, see https://syslinux.zytor.com/
0296
0297 - Using LILO
0298
0299 When using LILO all the necessary command line parameters may be
0300 specified using the 'append=' directive in the LILO configuration
0301 file.
0302
0303 However, to use the 'root=' directive you also need to create
0304 a dummy root device, which may be removed after LILO is run.
0305
0306 e.g::
0307
0308 mknod /dev/boot255 c 0 255
0309
0310 For information on configuring LILO, please refer to its documentation.
0311
0312 - Using GRUB
0313
0314 When using GRUB, kernel parameter are simply appended after the kernel
0315 specification: kernel <kernel> <parameters>
0316
0317 - Using loadlin
0318
0319 loadlin may be used to boot Linux from a DOS command prompt without
0320 requiring a local hard disk to mount as root. This has not been
0321 thoroughly tested by the authors of this document, but in general
0322 it should be possible configure the kernel command line similarly
0323 to the configuration of LILO.
0324
0325 Please refer to the loadlin documentation for further information.
0326
0327 - Using a boot ROM
0328
0329 This is probably the most elegant way of booting a diskless client.
0330 With a boot ROM the kernel is loaded using the TFTP protocol. The
0331 authors of this document are not aware of any no commercial boot
0332 ROMs that support booting Linux over the network. However, there
0333 are two free implementations of a boot ROM, netboot-nfs and
0334 etherboot, both of which are available on sunsite.unc.edu, and both
0335 of which contain everything you need to boot a diskless Linux client.
0336
0337 - Using pxelinux
0338
0339 Pxelinux may be used to boot linux using the PXE boot loader
0340 which is present on many modern network cards.
0341
0342 When using pxelinux, the kernel image is specified using
0343 "kernel <relative-path-below /tftpboot>". The nfsroot parameters
0344 are passed to the kernel by adding them to the "append" line.
0345 It is common to use serial console in conjunction with pxeliunx,
0346 see Documentation/admin-guide/serial-console.rst for more information.
0347
0348 For more information on isolinux, including how to create bootdisks
0349 for prebuilt kernels, see https://syslinux.zytor.com/
0350
0351
0352
0353
0354 Credits
0355 =======
0356
0357 The nfsroot code in the kernel and the RARP support have been written
0358 by Gero Kuhlmann <gero@gkminix.han.de>.
0359
0360 The rest of the IP layer autoconfiguration code has been written
0361 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>.
0362
0363 In order to write the initial version of nfsroot I would like to thank
0364 Jens-Uwe Mager <jum@anubis.han.de> for his help.
