blob: d56dc71d943086e45a28b2448ee4038471f0e7eb [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Mounting 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>
Nico Schottelius7e9dd122006-03-24 03:18:18 -08006Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
Linus Torvalds1da177e2005-04-16 15:20:36 -07007
8
9
10If you want to use a diskless system, as an X-terminal or printer
11server for example, you have to put your root filesystem onto a
12non-disk device. This can either be a ramdisk (see initrd.txt in
13this directory for further information) or a filesystem mounted
14via NFS. The following text describes on how to use NFS for the
15root filesystem. For the rest of this text 'client' means the
16diskless system, and 'server' means the NFS server.
17
18
19
20
211.) Enabling nfsroot capabilities
22 -----------------------------
23
24In order to use nfsroot you have to select support for NFS during
25kernel configuration. Note that NFS cannot be loaded as a module
26in this case. The configuration script will then ask you whether
27you want to use nfsroot, and if yes what kind of auto configuration
28system you want to use. Selecting both BOOTP and RARP is safe.
29
30
31
32
332.) Kernel command line
34 -------------------
35
36When the kernel has been loaded by a boot loader (either by loadlin,
37LILO or a network boot program) it has to be told what root fs device
38to use, and where to find the server and the name of the directory
39on the server to mount as root. This can be established by a couple
40of kernel command line parameters:
41
42
43root=/dev/nfs
44
45 This is necessary to enable the pseudo-NFS-device. Note that it's not a
46 real device but just a synonym to tell the kernel to use NFS instead of
47 a real device.
48
49
50nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
51
52 If the `nfsroot' parameter is NOT given on the command line, the default
53 "/tftpboot/%s" will be used.
54
55 <server-ip> Specifies the IP address of the NFS server. If this field
56 is not given, the default address as determined by the
57 `ip' variable (see below) is used. One use of this
58 parameter is for example to allow using different servers
59 for RARP and NFS. Usually you can leave this blank.
60
61 <root-dir> Name of the directory on the server to mount as root. If
62 there is a "%s" token in the string, the token will be
63 replaced by the ASCII-representation of the client's IP
64 address.
65
66 <nfs-options> Standard NFS options. All options are separated by commas.
67 If the options field is not given, the following defaults
68 will be used:
69 port = as given by server portmap daemon
70 rsize = 1024
71 wsize = 1024
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 `nfsaddrs',
85 but now the boot-time IP configuration works independently of NFS, so it
86 was renamed to `ip' and the old name remained as an alias for compatibility
87 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 both
92 RARP and BOOTP (depending on what has been enabled during kernel confi-
93 guration, and if both what protocol answer got in first).
94
95 <client-ip> IP address of the client. If empty, the address will either
96 be determined by RARP or BOOTP. What protocol is used de-
97 pends on what has been enabled during kernel configuration
98 and on the <autoconf> parameter. If this parameter is not
99 empty, neither RARP nor BOOTP will be used.
100
101 <server-ip> IP address of the NFS server. If RARP is used to determine
102 the client address and this parameter is NOT empty only
103 replies from the specified server are accepted. To use
104 different RARP and NFS server, specify your RARP server
105 here (or leave it blank), and specify your NFS server in
106 the `nfsroot' parameter (see above). If this entry is blank
107 the address of the server is used which answered the RARP
108 or BOOTP request.
109
110 <gw-ip> IP address of a gateway if the server is on a different
111 subnet. If this entry is empty no gateway is used and the
112 server is assumed to be on the local network, unless a
113 value has been received by BOOTP.
114
115 <netmask> Netmask for local network interface. If this is empty,
116 the netmask is derived from the client IP address assuming
117 classful addressing, unless overridden in BOOTP reply.
118
119 <hostname> Name of the client. If empty, the client IP address is
120 used in ASCII notation, or the value received by BOOTP.
121
122 <device> Name of network device to use. If this is empty, all
123 devices are used for RARP and BOOTP requests, and the
124 first one we receive a reply on is configured. If you have
125 only one device, you can safely leave this blank.
126
127 <autoconf> Method to use for autoconfiguration. If this is either
128 'rarp' or 'bootp', the specified protocol is used.
129 If the value is 'both' or empty, both protocols are used
130 so far as they have been enabled during kernel configura-
131 tion. 'off' means no autoconfiguration.
132
133 The <autoconf> parameter can appear alone as the value to the `ip'
134 parameter (without all the ':' characters before) in which case auto-
135 configuration is used.
136
137
138
139
1403.) Kernel loader
141 -------------
142
143To get the kernel into memory different approaches can be used. They
144depend on what facilities are available:
145
146
1473.1) Writing the kernel onto a floppy using dd:
148 As always you can just write the kernel onto a floppy using dd,
149 but then it's not possible to use kernel command lines at all.
150 To substitute the 'root=' parameter, create a dummy device on any
151 linux system with major number 0 and minor number 255 using mknod:
152
153 mknod /dev/boot255 c 0 255
154
155 Then copy the kernel zImage file onto a floppy using dd:
156
157 dd if=/usr/src/linux/arch/i386/boot/zImage of=/dev/fd0
158
159 And finally use rdev to set the root device:
160
161 rdev /dev/fd0 /dev/boot255
162
163 You can then remove the dummy device /dev/boot255 again. There
164 is no real device available for it.
165 The other two kernel command line parameters cannot be substi-
166 tuted with rdev. Therefore, using this method the kernel will
167 by default use RARP and/or BOOTP, and if it gets an answer via
168 RARP will mount the directory /tftpboot/<client-ip>/ as its
169 root. If it got a BOOTP answer the directory name in that answer
170 is used.
171
Linus Torvalds1da177e2005-04-16 15:20:36 -07001723.2) Using LILO
173 When using LILO you can specify all necessary command line
174 parameters with the 'append=' command in the LILO configuration
175 file. However, to use the 'root=' command you also need to
176 set up a dummy device as described in 3.1 above. For how to use
177 LILO and its 'append=' command please refer to the LILO
178 documentation.
179
Nico Schottelius7e9dd122006-03-24 03:18:18 -08001803.3) Using GRUB
181 When you use GRUB, you simply append the parameters after the kernel
182 specification: "kernel <kernel> <parameters>" (without the quotes).
183
1843.4) Using loadlin
Linus Torvalds1da177e2005-04-16 15:20:36 -0700185 When you want to boot Linux from a DOS command prompt without
186 having a local hard disk to mount as root, you can use loadlin.
187 I was told that it works, but haven't used it myself yet. In
188 general you should be able to create a kernel command line simi-
189 lar to how LILO is doing it. Please refer to the loadlin docu-
190 mentation for further information.
191
Nico Schottelius7e9dd122006-03-24 03:18:18 -08001923.5) Using a boot ROM
Linus Torvalds1da177e2005-04-16 15:20:36 -0700193 This is probably the most elegant way of booting a diskless
194 client. With a boot ROM the kernel gets loaded using the TFTP
195 protocol. As far as I know, no commercial boot ROMs yet
196 support booting Linux over the network, but there are two
197 free implementations of a boot ROM available on sunsite.unc.edu
198 and its mirrors. They are called 'netboot-nfs' and 'etherboot'.
199 Both contain everything you need to boot a diskless Linux client.
200
Nico Schottelius7e9dd122006-03-24 03:18:18 -08002013.6) Using pxelinux
202 Using pxelinux you specify the kernel you built with
203 "kernel <relative-path-below /tftpboot>". The nfsroot parameters
204 are passed to the kernel by adding them to the "append" line.
205 You may perhaps also want to fine tune the console output,
206 see Documentation/serial-console.txt for serial console help.
207
Linus Torvalds1da177e2005-04-16 15:20:36 -0700208
209
210
2114.) Credits
212 -------
213
214 The nfsroot code in the kernel and the RARP support have been written
215 by Gero Kuhlmann <gero@gkminix.han.de>.
216
217 The rest of the IP layer autoconfiguration code has been written
218 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>.
219
220 In order to write the initial version of nfsroot I would like to thank
221 Jens-Uwe Mager <jum@anubis.han.de> for his help.