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