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 Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
   7
   8
   9
  10 If you want to use a diskless system, as an X-terminal or printer
  11 server for example, you have to put your root filesystem onto a
  12 non-disk device. This can either be a ramdisk (see initrd.txt in
  13 this directory for further information) or a filesystem mounted
  14 via NFS. The following text describes on how to use NFS for the
  15 root filesystem. For the rest of this text 'client' means the
  16 diskless system, and 'server' means the NFS server.
  17
  18
  19
  20
  21 1.) Enabling nfsroot capabilities
  22     -----------------------------
  23
  24 In order to use nfsroot you have to select support for NFS during
  25 kernel configuration. Note that NFS cannot be loaded as a module
  26 in this case. The configuration script will then ask you whether
  27 you want to use nfsroot, and if yes what kind of auto configuration
  28 system you want to use. Selecting both BOOTP and RARP is safe.
  29
  30
  31
  32
  33 2.) Kernel command line
  34     -------------------
  35
  36 When the kernel has been loaded by a boot loader (either by loadlin,
  37 LILO or a network boot program) it has to be told what root fs device
  38 to use, and where to find the server and the name of the directory
  39 on the server to mount as root. This can be established by a couple
  40 of kernel command line parameters:
  41
  42
  43 root=/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
  50 nfsroot=[<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
  81 ip=<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
 140 3.) Kernel loader
 141     -------------
 142
 143 To get the kernel into memory different approaches can be used. They
 144 depend on what facilities are available:
 145
 146
 147 3.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
 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 GRUB
 181         When you use GRUB, you simply append the parameters after the kernel
 182         specification: "kernel <kernel> <parameters>" (without the quotes).
 183
 184 3.4) Using loadlin
 185         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
 192 3.5) Using a boot ROM
 193         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
 201 3.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
 208
 209
 210
 211 4.) 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.