annotate Documentation/nfsroot.txt @ 524:7f8b544237bf

netfront: Allow netfront in domain 0.

This is useful if your physical network device is in a utility domain.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 15 15:18:58 2008 +0100 (2008-04-15)
parents 831230e53067
rev   line source
ian@0 1 Mounting the root filesystem via NFS (nfsroot)
ian@0 2 ===============================================
ian@0 3
ian@0 4 Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
ian@0 5 Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
ian@0 6 Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
ian@0 7 Updated 2006 by Horms <horms@verge.net.au>
ian@0 8
ian@0 9
ian@0 10
ian@0 11 In order to use a diskless system, such as an X-terminal or printer server
ian@0 12 for example, it is necessary for the root filesystem to be present on a
ian@0 13 non-disk device. This may be an initramfs (see Documentation/filesystems/
ian@0 14 ramfs-rootfs-initramfs.txt), a ramdisk (see Documenation/initrd.txt) or a
ian@0 15 filesystem mounted via NFS. The following text describes on how to use NFS
ian@0 16 for the root filesystem. For the rest of this text 'client' means the
ian@0 17 diskless system, and 'server' means the NFS server.
ian@0 18
ian@0 19
ian@0 20
ian@0 21
ian@0 22 1.) Enabling nfsroot capabilities
ian@0 23 -----------------------------
ian@0 24
ian@0 25 In order to use nfsroot, NFS client support needs to be selected as
ian@0 26 built-in during configuration. Once this has been selected, the nfsroot
ian@0 27 option will become available, which should also be selected.
ian@0 28
ian@0 29 In the networking options, kernel level autoconfiguration can be selected,
ian@0 30 along with the types of autoconfiguration to support. Selecting all of
ian@0 31 DHCP, BOOTP and RARP is safe.
ian@0 32
ian@0 33
ian@0 34
ian@0 35
ian@0 36 2.) Kernel command line
ian@0 37 -------------------
ian@0 38
ian@0 39 When the kernel has been loaded by a boot loader (see below) it needs to be
ian@0 40 told what root fs device to use. And in the case of nfsroot, where to find
ian@0 41 both the server and the name of the directory on the server to mount as root.
ian@0 42 This can be established using the following kernel command line parameters:
ian@0 43
ian@0 44
ian@0 45 root=/dev/nfs
ian@0 46
ian@0 47 This is necessary to enable the pseudo-NFS-device. Note that it's not a
ian@0 48 real device but just a synonym to tell the kernel to use NFS instead of
ian@0 49 a real device.
ian@0 50
ian@0 51
ian@0 52 nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
ian@0 53
ian@0 54 If the `nfsroot' parameter is NOT given on the command line,
ian@0 55 the default "/tftpboot/%s" will be used.
ian@0 56
ian@0 57 <server-ip> Specifies the IP address of the NFS server.
ian@0 58 The default address is determined by the `ip' parameter
ian@0 59 (see below). This parameter allows the use of different
ian@0 60 servers for IP autoconfiguration and NFS.
ian@0 61
ian@0 62 <root-dir> Name of the directory on the server to mount as root.
ian@0 63 If there is a "%s" token in the string, it will be
ian@0 64 replaced by the ASCII-representation of the client's
ian@0 65 IP address.
ian@0 66
ian@0 67 <nfs-options> Standard NFS options. All options are separated by commas.
ian@0 68 The following defaults are used:
ian@0 69 port = as given by server portmap daemon
ian@0 70 rsize = 1024
ian@0 71 wsize = 1024
ian@0 72 timeo = 7
ian@0 73 retrans = 3
ian@0 74 acregmin = 3
ian@0 75 acregmax = 60
ian@0 76 acdirmin = 30
ian@0 77 acdirmax = 60
ian@0 78 flags = hard, nointr, noposix, cto, ac
ian@0 79
ian@0 80
ian@0 81 ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
ian@0 82
ian@0 83 This parameter tells the kernel how to configure IP addresses of devices
ian@0 84 and also how to set up the IP routing table. It was originally called
ian@0 85 `nfsaddrs', but now the boot-time IP configuration works independently of
ian@0 86 NFS, so it was renamed to `ip' and the old name remained as an alias for
ian@0 87 compatibility reasons.
ian@0 88
ian@0 89 If this parameter is missing from the kernel command line, all fields are
ian@0 90 assumed to be empty, and the defaults mentioned below apply. In general
ian@0 91 this means that the kernel tries to configure everything using
ian@0 92 autoconfiguration.
ian@0 93
ian@0 94 The <autoconf> parameter can appear alone as the value to the `ip'
ian@0 95 parameter (without all the ':' characters before) in which case auto-
ian@0 96 configuration is used.
ian@0 97
ian@0 98 <client-ip> IP address of the client.
ian@0 99
ian@0 100 Default: Determined using autoconfiguration.
ian@0 101
ian@0 102 <server-ip> IP address of the NFS server. If RARP is used to determine
ian@0 103 the client address and this parameter is NOT empty only
ian@0 104 replies from the specified server are accepted.
ian@0 105
ian@0 106 Only required for for NFS root. That is autoconfiguration
ian@0 107 will not be triggered if it is missing and NFS root is not
ian@0 108 in operation.
ian@0 109
ian@0 110 Default: Determined using autoconfiguration.
ian@0 111 The address of the autoconfiguration server is used.
ian@0 112
ian@0 113 <gw-ip> IP address of a gateway if the server is on a different subnet.
ian@0 114
ian@0 115 Default: Determined using autoconfiguration.
ian@0 116
ian@0 117 <netmask> Netmask for local network interface. If unspecified
ian@0 118 the netmask is derived from the client IP address assuming
ian@0 119 classful addressing.
ian@0 120
ian@0 121 Default: Determined using autoconfiguration.
ian@0 122
ian@0 123 <hostname> Name of the client. May be supplied by autoconfiguration,
ian@0 124 but its absence will not trigger autoconfiguration.
ian@0 125
ian@0 126 Default: Client IP address is used in ASCII notation.
ian@0 127
ian@0 128 <device> Name of network device to use.
ian@0 129
ian@0 130 Default: If the host only has one device, it is used.
ian@0 131 Otherwise the device is determined using
ian@0 132 autoconfiguration. This is done by sending
ian@0 133 autoconfiguration requests out of all devices,
ian@0 134 and using the device that received the first reply.
ian@0 135
ian@0 136 <autoconf> Method to use for autoconfiguration. In the case of options
ian@0 137 which specify multiple autoconfiguration protocols,
ian@0 138 requests are sent using all protocols, and the first one
ian@0 139 to reply is used.
ian@0 140
ian@0 141 Only autoconfiguration protocols that have been compiled
ian@0 142 into the kernel will be used, regardless of the value of
ian@0 143 this option.
ian@0 144
ian@0 145 off or none: don't use autoconfiguration (default)
ian@0 146 on or any: use any protocol available in the kernel
ian@0 147 dhcp: use DHCP
ian@0 148 bootp: use BOOTP
ian@0 149 rarp: use RARP
ian@0 150 both: use both BOOTP and RARP but not DHCP
ian@0 151 (old option kept for backwards compatibility)
ian@0 152
ian@0 153 Default: any
ian@0 154
ian@0 155
ian@0 156
ian@0 157
ian@0 158 3.) Boot Loader
ian@0 159 ----------
ian@0 160
ian@0 161 To get the kernel into memory different approaches can be used.
ian@0 162 They depend on various facilities being available:
ian@0 163
ian@0 164
ian@0 165 3.1) Booting from a floppy using syslinux
ian@0 166
ian@0 167 When building kernels, an easy way to create a boot floppy that uses
ian@0 168 syslinux is to use the zdisk or bzdisk make targets which use
ian@0 169 and bzimage images respectively. Both targets accept the
ian@0 170 FDARGS parameter which can be used to set the kernel command line.
ian@0 171
ian@0 172 e.g.
ian@0 173 make bzdisk FDARGS="root=/dev/nfs"
ian@0 174
ian@0 175 Note that the user running this command will need to have
ian@0 176 access to the floppy drive device, /dev/fd0
ian@0 177
ian@0 178 For more information on syslinux, including how to create bootdisks
ian@0 179 for prebuilt kernels, see http://syslinux.zytor.com/
ian@0 180
ian@0 181 N.B: Previously it was possible to write a kernel directly to
ian@0 182 a floppy using dd, configure the boot device using rdev, and
ian@0 183 boot using the resulting floppy. Linux no longer supports this
ian@0 184 method of booting.
ian@0 185
ian@0 186 3.2) Booting from a cdrom using isolinux
ian@0 187
ian@0 188 When building kernels, an easy way to create a bootable cdrom that
ian@0 189 uses isolinux is to use the isoimage target which uses a bzimage
ian@0 190 image. Like zdisk and bzdisk, this target accepts the FDARGS
ian@0 191 parameter which can be used to set the kernel command line.
ian@0 192
ian@0 193 e.g.
ian@0 194 make isoimage FDARGS="root=/dev/nfs"
ian@0 195
ian@0 196 The resulting iso image will be arch/<ARCH>/boot/image.iso
ian@0 197 This can be written to a cdrom using a variety of tools including
ian@0 198 cdrecord.
ian@0 199
ian@0 200 e.g.
ian@0 201 cdrecord dev=ATAPI:1,0,0 arch/i386/boot/image.iso
ian@0 202
ian@0 203 For more information on isolinux, including how to create bootdisks
ian@0 204 for prebuilt kernels, see http://syslinux.zytor.com/
ian@0 205
ian@0 206 3.2) Using LILO
ian@0 207 When using LILO all the necessary command line parameters may be
ian@0 208 specified using the 'append=' directive in the LILO configuration
ian@0 209 file.
ian@0 210
ian@0 211 However, to use the 'root=' directive you also need to create
ian@0 212 a dummy root device, which may be removed after LILO is run.
ian@0 213
ian@0 214 mknod /dev/boot255 c 0 255
ian@0 215
ian@0 216 For information on configuring LILO, please refer to its documentation.
ian@0 217
ian@0 218 3.3) Using GRUB
ian@0 219 When using GRUB, kernel parameter are simply appended after the kernel
ian@0 220 specification: kernel <kernel> <parameters>
ian@0 221
ian@0 222 3.4) Using loadlin
ian@0 223 loadlin may be used to boot Linux from a DOS command prompt without
ian@0 224 requiring a local hard disk to mount as root. This has not been
ian@0 225 thoroughly tested by the authors of this document, but in general
ian@0 226 it should be possible configure the kernel command line similarly
ian@0 227 to the configuration of LILO.
ian@0 228
ian@0 229 Please refer to the loadlin documentation for further information.
ian@0 230
ian@0 231 3.5) Using a boot ROM
ian@0 232 This is probably the most elegant way of booting a diskless client.
ian@0 233 With a boot ROM the kernel is loaded using the TFTP protocol. The
ian@0 234 authors of this document are not aware of any no commercial boot
ian@0 235 ROMs that support booting Linux over the network. However, there
ian@0 236 are two free implementations of a boot ROM, netboot-nfs and
ian@0 237 etherboot, both of which are available on sunsite.unc.edu, and both
ian@0 238 of which contain everything you need to boot a diskless Linux client.
ian@0 239
ian@0 240 3.6) Using pxelinux
ian@0 241 Pxelinux may be used to boot linux using the PXE boot loader
ian@0 242 which is present on many modern network cards.
ian@0 243
ian@0 244 When using pxelinux, the kernel image is specified using
ian@0 245 "kernel <relative-path-below /tftpboot>". The nfsroot parameters
ian@0 246 are passed to the kernel by adding them to the "append" line.
ian@0 247 It is common to use serial console in conjunction with pxeliunx,
ian@0 248 see Documentation/serial-console.txt for more information.
ian@0 249
ian@0 250 For more information on isolinux, including how to create bootdisks
ian@0 251 for prebuilt kernels, see http://syslinux.zytor.com/
ian@0 252
ian@0 253
ian@0 254
ian@0 255
ian@0 256 4.) Credits
ian@0 257 -------
ian@0 258
ian@0 259 The nfsroot code in the kernel and the RARP support have been written
ian@0 260 by Gero Kuhlmann <gero@gkminix.han.de>.
ian@0 261
ian@0 262 The rest of the IP layer autoconfiguration code has been written
ian@0 263 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>.
ian@0 264
ian@0 265 In order to write the initial version of nfsroot I would like to thank
ian@0 266 Jens-Uwe Mager <jum@anubis.han.de> for his help.