aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/nfsroot.txt
diff options
context:
space:
mode:
authorHorms <horms@verge.net.au>2006-07-10 07:43:58 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2006-07-10 16:24:13 -0400
commit64552a50bc80fecb73617336bf197375868faf6e (patch)
tree767b65ce1b4cd757f95b4048376d6f63fad68b8c /Documentation/nfsroot.txt
parent73ce5934e2d855db436566297f12966eb507a435 (diff)
[PATCH] nfs: Update Documentation/nfsroot.txt to include dhcp, syslinux and isolinux
* Document the ip command a little differently to make the interaction between defaults and autoconfiguration a little clearer (I hope) * Update autoconfiguration the current set of options, including DHCP * Update the boot methods to add syslinux and isolinux, and remove dd of=/dev/fd0 which is no longer supported by linux * Add a referance to initramfs along side initrd. Should the latter and its document be removed some time soon? * Various cleanups to put the text consistently into the thrid person * Reformated a bit to fit into 80 columns a bit more nicely * Should the bootloaders documentation be removed or split into a separate documentation, it seems somewhat out of scope Signed-off-by: Horms <horms@verge.net.au> Cc: "H. Peter Anvin" <hpa@zytor.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation/nfsroot.txt')
-rw-r--r--Documentation/nfsroot.txt275
1 files changed, 160 insertions, 115 deletions
diff --git a/Documentation/nfsroot.txt b/Documentation/nfsroot.txt
index d56dc71d9430..3cc953cb288f 100644
--- a/Documentation/nfsroot.txt
+++ b/Documentation/nfsroot.txt
@@ -4,15 +4,16 @@ Mounting the root filesystem via NFS (nfsroot)
4Written 1996 by Gero Kuhlmann <gero@gkminix.han.de> 4Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
5Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz> 5Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
6Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org> 6Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
7Updated 2006 by Horms <horms@verge.net.au>
7 8
8 9
9 10
10If you want to use a diskless system, as an X-terminal or printer 11In order to use a diskless system, such as an X-terminal or printer server
11server for example, you have to put your root filesystem onto a 12for example, it is necessary for the root filesystem to be present on a
12non-disk device. This can either be a ramdisk (see initrd.txt in 13non-disk device. This may be an initramfs (see Documentation/filesystems/
13this directory for further information) or a filesystem mounted 14ramfs-rootfs-initramfs.txt), a ramdisk (see Documenation/initrd.txt) or a
14via NFS. The following text describes on how to use NFS for the 15filesystem mounted via NFS. The following text describes on how to use NFS
15root filesystem. For the rest of this text 'client' means the 16for the root filesystem. For the rest of this text 'client' means the
16diskless system, and 'server' means the NFS server. 17diskless system, and 'server' means the NFS server.
17 18
18 19
@@ -21,11 +22,13 @@ diskless system, and 'server' means the NFS server.
211.) Enabling nfsroot capabilities 221.) Enabling nfsroot capabilities
22 ----------------------------- 23 -----------------------------
23 24
24In order to use nfsroot you have to select support for NFS during 25In order to use nfsroot, NFS client support needs to be selected as
25kernel configuration. Note that NFS cannot be loaded as a module 26built-in during configuration. Once this has been selected, the nfsroot
26in this case. The configuration script will then ask you whether 27option will become available, which should also be selected.
27you want to use nfsroot, and if yes what kind of auto configuration 28
28system you want to use. Selecting both BOOTP and RARP is safe. 29In the networking options, kernel level autoconfiguration can be selected,
30along with the types of autoconfiguration to support. Selecting all of
31DHCP, BOOTP and RARP is safe.
29 32
30 33
31 34
@@ -33,11 +36,10 @@ system you want to use. Selecting both BOOTP and RARP is safe.
332.) Kernel command line 362.) Kernel command line
34 ------------------- 37 -------------------
35 38
36When the kernel has been loaded by a boot loader (either by loadlin, 39When the kernel has been loaded by a boot loader (see below) it needs to be
37LILO or a network boot program) it has to be told what root fs device 40told what root fs device to use. And in the case of nfsroot, where to find
38to use, and where to find the server and the name of the directory 41both the server and the name of the directory on the server to mount as root.
39on the server to mount as root. This can be established by a couple 42This can be established using the following kernel command line parameters:
40of kernel command line parameters:
41 43
42 44
43root=/dev/nfs 45root=/dev/nfs
@@ -49,23 +51,21 @@ root=/dev/nfs
49 51
50nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] 52nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
51 53
52 If the `nfsroot' parameter is NOT given on the command line, the default 54 If the `nfsroot' parameter is NOT given on the command line,
53 "/tftpboot/%s" will be used. 55 the default "/tftpboot/%s" will be used.
54 56
55 <server-ip> Specifies the IP address of the NFS server. If this field 57 <server-ip> Specifies the IP address of the NFS server.
56 is not given, the default address as determined by the 58 The default address is determined by the `ip' parameter
57 `ip' variable (see below) is used. One use of this 59 (see below). This parameter allows the use of different
58 parameter is for example to allow using different servers 60 servers for IP autoconfiguration and NFS.
59 for RARP and NFS. Usually you can leave this blank.
60 61
61 <root-dir> Name of the directory on the server to mount as root. If 62 <root-dir> Name of the directory on the server to mount as root.
62 there is a "%s" token in the string, the token will be 63 If there is a "%s" token in the string, it will be
63 replaced by the ASCII-representation of the client's IP 64 replaced by the ASCII-representation of the client's
64 address. 65 IP address.
65 66
66 <nfs-options> Standard NFS options. All options are separated by commas. 67 <nfs-options> Standard NFS options. All options are separated by commas.
67 If the options field is not given, the following defaults 68 The following defaults are used:
68 will be used:
69 port = as given by server portmap daemon 69 port = as given by server portmap daemon
70 rsize = 1024 70 rsize = 1024
71 wsize = 1024 71 wsize = 1024
@@ -81,129 +81,174 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
81ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> 81ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
82 82
83 This parameter tells the kernel how to configure IP addresses of devices 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', 84 and also how to set up the IP routing table. It was originally called
85 but now the boot-time IP configuration works independently of NFS, so it 85 `nfsaddrs', but now the boot-time IP configuration works independently of
86 was renamed to `ip' and the old name remained as an alias for compatibility 86 NFS, so it was renamed to `ip' and the old name remained as an alias for
87 reasons. 87 compatibility reasons.
88 88
89 If this parameter is missing from the kernel command line, all fields are 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 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 91 this means that the kernel tries to configure everything using
92 RARP and BOOTP (depending on what has been enabled during kernel confi- 92 autoconfiguration.
93 guration, and if both what protocol answer got in first). 93
94 The <autoconf> parameter can appear alone as the value to the `ip'
95 parameter (without all the ':' characters before) in which case auto-
96 configuration is used.
97
98 <client-ip> IP address of the client.
94 99
95 <client-ip> IP address of the client. If empty, the address will either 100 Default: Determined using autoconfiguration.
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
101 <server-ip> IP address of the NFS server. If RARP is used to determine 102 <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 the client address and this parameter is NOT empty only
103 replies from the specified server are accepted. To use 104 replies from the specified server are accepted.
104 different RARP and NFS server, specify your RARP server 105
105 here (or leave it blank), and specify your NFS server in 106 Only required for for NFS root. That is autoconfiguration
106 the `nfsroot' parameter (see above). If this entry is blank 107 will not be triggered if it is missing and NFS root is not
107 the address of the server is used which answered the RARP 108 in operation.
108 or BOOTP request. 109
109 110 Default: Determined using autoconfiguration.
110 <gw-ip> IP address of a gateway if the server is on a different 111 The address of the autoconfiguration server is used.
111 subnet. If this entry is empty no gateway is used and the 112
112 server is assumed to be on the local network, unless a 113 <gw-ip> IP address of a gateway if the server is on a different subnet.
113 value has been received by BOOTP. 114
114 115 Default: Determined using autoconfiguration.
115 <netmask> Netmask for local network interface. If this is empty, 116
117 <netmask> Netmask for local network interface. If unspecified
116 the netmask is derived from the client IP address assuming 118 the netmask is derived from the client IP address assuming
117 classful addressing, unless overridden in BOOTP reply. 119 classful addressing.
118 120
119 <hostname> Name of the client. If empty, the client IP address is 121 Default: Determined using autoconfiguration.
120 used in ASCII notation, or the value received by BOOTP.
121 122
122 <device> Name of network device to use. If this is empty, all 123 <hostname> Name of the client. May be supplied by autoconfiguration,
123 devices are used for RARP and BOOTP requests, and the 124 but its absence will not trigger autoconfiguration.
124 first one we receive a reply on is configured. If you have
125 only one device, you can safely leave this blank.
126 125
127 <autoconf> Method to use for autoconfiguration. If this is either 126 Default: Client IP address is used in ASCII notation.
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 127
133 The <autoconf> parameter can appear alone as the value to the `ip' 128 <device> Name of network device to use.
134 parameter (without all the ':' characters before) in which case auto- 129
135 configuration is used. 130 Default: If the host only has one device, it is used.
131 Otherwise the device is determined using
132 autoconfiguration. This is done by sending
133 autoconfiguration requests out of all devices,
134 and using the device that received the first reply.
136 135
136 <autoconf> Method to use for autoconfiguration. In the case of options
137 which specify multiple autoconfiguration protocols,
138 requests are sent using all protocols, and the first one
139 to reply is used.
137 140
141 Only autoconfiguration protocols that have been compiled
142 into the kernel will be used, regardless of the value of
143 this option.
138 144
145 off or none: don't use autoconfiguration (default)
146 on or any: use any protocol available in the kernel
147 dhcp: use DHCP
148 bootp: use BOOTP
149 rarp: use RARP
150 both: use both BOOTP and RARP but not DHCP
151 (old option kept for backwards compatibility)
139 152
1403.) Kernel loader 153 Default: any
141 -------------
142 154
143To get the kernel into memory different approaches can be used. They
144depend on what facilities are available:
145 155
146 156
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 157
153 mknod /dev/boot255 c 0 255 1583.) Boot Loader
159 ----------
154 160
155 Then copy the kernel zImage file onto a floppy using dd: 161To get the kernel into memory different approaches can be used.
162They depend on various facilities being available:
156 163
157 dd if=/usr/src/linux/arch/i386/boot/zImage of=/dev/fd0
158 164
159 And finally use rdev to set the root device: 1653.1) Booting from a floppy using syslinux
160 166
161 rdev /dev/fd0 /dev/boot255 167 When building kernels, an easy way to create a boot floppy that uses
168 syslinux is to use the zdisk or bzdisk make targets which use
169 and bzimage images respectively. Both targets accept the
170 FDARGS parameter which can be used to set the kernel command line.
162 171
163 You can then remove the dummy device /dev/boot255 again. There 172 e.g.
164 is no real device available for it. 173 make bzdisk FDARGS="root=/dev/nfs"
165 The other two kernel command line parameters cannot be substi- 174
166 tuted with rdev. Therefore, using this method the kernel will 175 Note that the user running this command will need to have
167 by default use RARP and/or BOOTP, and if it gets an answer via 176 access to the floppy drive device, /dev/fd0
168 RARP will mount the directory /tftpboot/<client-ip>/ as its 177
169 root. If it got a BOOTP answer the directory name in that answer 178 For more information on syslinux, including how to create bootdisks
170 is used. 179 for prebuilt kernels, see http://syslinux.zytor.com/
180
181 N.B: Previously it was possible to write a kernel directly to
182 a floppy using dd, configure the boot device using rdev, and
183 boot using the resulting floppy. Linux no longer supports this
184 method of booting.
185
1863.2) Booting from a cdrom using isolinux
187
188 When building kernels, an easy way to create a bootable cdrom that
189 uses isolinux is to use the isoimage target which uses a bzimage
190 image. Like zdisk and bzdisk, this target accepts the FDARGS
191 parameter which can be used to set the kernel command line.
192
193 e.g.
194 make isoimage FDARGS="root=/dev/nfs"
195
196 The resulting iso image will be arch/<ARCH>/boot/image.iso
197 This can be written to a cdrom using a variety of tools including
198 cdrecord.
199
200 e.g.
201 cdrecord dev=ATAPI:1,0,0 arch/i386/boot/image.iso
202
203 For more information on isolinux, including how to create bootdisks
204 for prebuilt kernels, see http://syslinux.zytor.com/
171 205
1723.2) Using LILO 2063.2) Using LILO
173 When using LILO you can specify all necessary command line 207 When using LILO all the necessary command line parameters may be
174 parameters with the 'append=' command in the LILO configuration 208 specified using the 'append=' directive in the LILO configuration
175 file. However, to use the 'root=' command you also need to 209 file.
176 set up a dummy device as described in 3.1 above. For how to use 210
177 LILO and its 'append=' command please refer to the LILO 211 However, to use the 'root=' directive you also need to create
178 documentation. 212 a dummy root device, which may be removed after LILO is run.
213
214 mknod /dev/boot255 c 0 255
215
216 For information on configuring LILO, please refer to its documentation.
179 217
1803.3) Using GRUB 2183.3) Using GRUB
181 When you use GRUB, you simply append the parameters after the kernel 219 When using GRUB, kernel parameter are simply appended after the kernel
182 specification: "kernel <kernel> <parameters>" (without the quotes). 220 specification: kernel <kernel> <parameters>
183 221
1843.4) Using loadlin 2223.4) Using loadlin
185 When you want to boot Linux from a DOS command prompt without 223 loadlin may be used to boot Linux from a DOS command prompt without
186 having a local hard disk to mount as root, you can use loadlin. 224 requiring a local hard disk to mount as root. This has not been
187 I was told that it works, but haven't used it myself yet. In 225 thoroughly tested by the authors of this document, but in general
188 general you should be able to create a kernel command line simi- 226 it should be possible configure the kernel command line similarly
189 lar to how LILO is doing it. Please refer to the loadlin docu- 227 to the configuration of LILO.
190 mentation for further information. 228
229 Please refer to the loadlin documentation for further information.
191 230
1923.5) Using a boot ROM 2313.5) Using a boot ROM
193 This is probably the most elegant way of booting a diskless 232 This is probably the most elegant way of booting a diskless client.
194 client. With a boot ROM the kernel gets loaded using the TFTP 233 With a boot ROM the kernel is loaded using the TFTP protocol. The
195 protocol. As far as I know, no commercial boot ROMs yet 234 authors of this document are not aware of any no commercial boot
196 support booting Linux over the network, but there are two 235 ROMs that support booting Linux over the network. However, there
197 free implementations of a boot ROM available on sunsite.unc.edu 236 are two free implementations of a boot ROM, netboot-nfs and
198 and its mirrors. They are called 'netboot-nfs' and 'etherboot'. 237 etherboot, both of which are available on sunsite.unc.edu, and both
199 Both contain everything you need to boot a diskless Linux client. 238 of which contain everything you need to boot a diskless Linux client.
200 239
2013.6) Using pxelinux 2403.6) Using pxelinux
202 Using pxelinux you specify the kernel you built with 241 Pxelinux may be used to boot linux using the PXE boot loader
242 which is present on many modern network cards.
243
244 When using pxelinux, the kernel image is specified using
203 "kernel <relative-path-below /tftpboot>". The nfsroot parameters 245 "kernel <relative-path-below /tftpboot>". The nfsroot parameters
204 are passed to the kernel by adding them to the "append" line. 246 are passed to the kernel by adding them to the "append" line.
205 You may perhaps also want to fine tune the console output, 247 It is common to use serial console in conjunction with pxeliunx,
206 see Documentation/serial-console.txt for serial console help. 248 see Documentation/serial-console.txt for more information.
249
250 For more information on isolinux, including how to create bootdisks
251 for prebuilt kernels, see http://syslinux.zytor.com/
207 252
208 253
209 254