d2963123eb1ccca8a299486f1eb998f05acf5041
[muen/linux.git] / Documentation / filesystems / nfs / nfsroot.txt
1 Mounting the root filesystem via NFS (nfsroot)
2 ===============================================
3
4 Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
5 Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
6 Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
7 Updated 2006 by Horms <horms@verge.net.au>
8 Updated 2018 by Chris Novakovic <chris@chrisn.me.uk>
9
10
11
12 In order to use a diskless system, such as an X-terminal or printer server
13 for example, it is necessary for the root filesystem to be present on a
14 non-disk device. This may be an initramfs (see Documentation/filesystems/
15 ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a
16 filesystem mounted via NFS. The following text describes on how to use NFS
17 for the root filesystem. For the rest of this text 'client' means the
18 diskless system, and 'server' means the NFS server.
19
20
21
22
23 1.) Enabling nfsroot capabilities
24     -----------------------------
25
26 In order to use nfsroot, NFS client support needs to be selected as
27 built-in during configuration. Once this has been selected, the nfsroot
28 option will become available, which should also be selected.
29
30 In the networking options, kernel level autoconfiguration can be selected,
31 along with the types of autoconfiguration to support. Selecting all of
32 DHCP, BOOTP and RARP is safe.
33
34
35
36
37 2.) Kernel command line
38     -------------------
39
40 When the kernel has been loaded by a boot loader (see below) it needs to be
41 told what root fs device to use. And in the case of nfsroot, where to find
42 both the server and the name of the directory on the server to mount as root.
43 This can be established using the following kernel command line parameters:
44
45
46 root=/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
53 nfsroot=[<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
82 ip=<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
223 nfsrootdebug
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
231 rdinit=<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/early-userspace/README
243
244
245
246
247 3.) Boot Loader
248     ----------
249
250 To get the kernel into memory different approaches can be used.
251 They depend on various facilities being available:
252
253
254 3.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
275 3.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
295 3.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
307 3.3) Using GRUB
308         When using GRUB, kernel parameter are simply appended after the kernel
309         specification: kernel <kernel> <parameters>
310
311 3.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
320 3.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
329 3.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
345 4.) 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.