Linux-2.6.12-rc2
[linux-3.10.git] / 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.