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