original/man4/initrd.4

   1 .\" -*- nroff -*-
   2 .\" This man-page is Copyright (C) 1997 John S. Kallal
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and author(s) of this work.
  23 .\"
  24 .\" If the you wish to distribute versions of this work under other
  25 .\" conditions than the above, please contact the author(s) at the following
  26 .\" for permission:
  27 .\"
  28 .\"  John S. Kallal -
  29 .\"     email: <kallal@voicenet.com>
  30 .\"     mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA
  31 .\"     phone: (302)654-5478
  32 .\"
  33 .\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $
  34 .TH INITRD 4 2010-09-04 "Linux" "Linux Programmer's Manual"
  35 .SH NAME
  36 initrd \- boot loader initialized RAM disk
  37 .SH CONFIGURATION
  38 The
  39 .I /dev/initrd
  40 is a read-only block device assigned
  41 major number 1 and minor number 250.
  42 Typically
  43 .I /dev/initrd
  44 is owned by
  45 .I root.disk
  46 with mode 0400 (read access by root only).
  47 If the Linux system does not have
  48 .I /dev/initrd
  49 already created, it can be created with the following commands:
  50 .nf
  51 \fB
  52         mknod \-m 400 /dev/initrd b 1 250
  53         chown root:disk /dev/initrd
  54 \fP
  55 .fi
  56 .PP
  57 Also, support for both "RAM disk" and "Initial RAM disk"
  58 (e.g.
  59 .BR CONFIG_BLK_DEV_RAM=y
  60 and
  61 .BR CONFIG_BLK_DEV_INITRD=y )
  62 must be compiled directly into the Linux kernel to use
  63 .IR /dev/initrd .
  64 When using
  65 .IR /dev/initrd ,
  66 the RAM disk driver cannot be loaded as a module.
  67 .\"
  68 .\"
  69 .\"
  70 .SH DESCRIPTION
  71 The special file
  72 .I /dev/initrd
  73 is a read-only block device.
  74 This device is a RAM disk that is initialized (e.g., loaded)
  75 by the boot loader before the kernel is started.
  76 The kernel then can use
  77 .IR /dev/initrd "'s "
  78 contents for a two-phase system boot-up.
  79 .PP
  80 In the first boot-up phase, the kernel starts up
  81 and mounts an initial root file-system from the contents of
  82 .I /dev/initrd
  83 (e.g., RAM disk initialized by the boot loader).
  84 In the second phase, additional drivers or other modules
  85 are loaded from the initial root device's contents.
  86 After loading the additional modules, a new root file system
  87 (i.e., the normal root file system) is mounted from a
  88 different device.
  89 .\"
  90 .\"
  91 .\"
  92 .SS "Boot-up Operation"
  93 When booting up with
  94 .BR initrd ,
  95 the system boots as follows:
  96 .IP 1. 3
  97 The boot loader loads the kernel program and
  98 .IR /dev/initrd 's
  99 contents into memory.
 100 .IP 2.
 101 On kernel startup,
 102 the kernel uncompresses and copies the contents of the device
 103 .I /dev/initrd
 104 onto device
 105 .I /dev/ram0
 106 and then frees the memory used by
 107 .IR /dev/initrd .
 108 .IP 3.
 109 The kernel then read-write mounts the device
 110 .I /dev/ram0
 111 as the initial root file system.
 112 .IP 4.
 113 If the indicated normal root file system is also the initial
 114 root file-system (e.g.
 115 .IR /dev/ram0 )
 116 then the kernel skips to the last step for the usual boot sequence.
 117 .IP 5.
 118 If the executable file
 119 .IR /linuxrc
 120 is present in the initial root file-system,
 121 .I /linuxrc
 122 is executed with UID 0.
 123 (The file
 124 .I /linuxrc
 125 must have executable permission.
 126 The file
 127 .I /linuxrc
 128 can be any valid executable, including a shell script.)
 129 .IP 6.
 130 If
 131 .I /linuxrc
 132 is not executed or when
 133 .I /linuxrc
 134 terminates, the normal root file system is mounted.
 135 (If
 136 .I /linuxrc
 137 exits with any file-systems mounted on the initial root
 138 file-system, then the behavior of the kernel is
 139 .BR UNSPECIFIED .
 140 See the NOTES section for the current kernel behavior.)
 141 .IP 7.
 142 If the normal root file system has a directory
 143 .IR /initrd ,
 144 the device
 145 .I /dev/ram0
 146 is moved from
 147 .IR /
 148 to
 149 .IR /initrd .
 150 Otherwise if the directory
 151 .IR /initrd
 152 does not exist, the device
 153 .I /dev/ram0
 154 is unmounted.
 155 (When moved from
 156 .IR /
 157 to
 158 .IR /initrd ,
 159 .I /dev/ram0
 160 is not unmounted and therefore processes can remain running from
 161 .IR /dev/ram0 .
 162 If directory
 163 .I /initrd
 164 does not exist on the normal root file system
 165 and any processes remain running from
 166 .IR /dev/ram0
 167 when
 168 .I /linuxrc
 169 exits, the behavior of the kernel is
 170 .BR UNSPECIFIED .
 171 See the NOTES section for the current kernel behavior.)
 172 .IP 8.
 173 The usual boot sequence (e.g., invocation of
 174 .IR /sbin/init )
 175 is performed on the normal root file system.
 176 .\"
 177 .\"
 178 .\"
 179 .SS Options
 180 The following boot loader options, when used with
 181 .BR initrd ,
 182 affect the kernel's boot-up operation:
 183 .TP
 184 .BI initrd= "filename"
 185 Specifies the file to load as the contents of
 186 .IR /dev/initrd .
 187 For
 188 .B LOADLIN
 189 this is a command-line option.
 190 For
 191 .B LILO
 192 you have to use this command in the
 193 .B LILO
 194 configuration file
 195 .IR /etc/lilo.config .
 196 The filename specified with this
 197 option will typically be a gzipped file-system image.
 198 .TP
 199 .I noinitrd
 200 This boot option disables the two-phase boot-up operation.
 201 The kernel performs the usual boot sequence as if
 202 .I /dev/initrd
 203 was not initialized.
 204 With this option, any contents of
 205 .I /dev/initrd
 206 loaded into memory by the boot loader contents are preserved.
 207 This option permits the contents of
 208 .I /dev/initrd
 209 to be any data and need not be limited to a file system image.
 210 However, device
 211 .I /dev/initrd
 212 is read-only and can be read only one time after system startup.
 213 .TP
 214 .BI root= "device-name"
 215 Specifies the device to be used as the normal root file system.
 216 For
 217 .B LOADLIN
 218 this is a command-line option.
 219 For
 220 .B LILO
 221 this is a boot time option or
 222 can be used as an option line in the
 223 .B LILO
 224 configuration file
 225 .IR /etc/lilo.config .
 226 The device specified by the this option must be a mountable
 227 device having a suitable root file-system.
 228 .\"
 229 .\"
 230 .\"
 231 .SS "Changing the Normal Root File System"
 232 By default,
 233 the kernel's settings
 234 (e.g., set in the kernel file with
 235 .BR rdev (8)
 236 or compiled into the kernel file),
 237 or the boot loader option setting
 238 is used for the normal root file systems.
 239 For an NFS-mounted normal root file system, one has to use the
 240 .B nfs_root_name
 241 and
 242 .B nfs_root_addrs
 243 boot options to give the NFS settings.
 244 For more information on NFS-mounted root see the kernel documentation file
 245 .BR Documentation/filesystems/nfsroot.txt .
 246 For more information on setting the root file system see also the
 247 .BR LILO
 248 and
 249 .BR LOADLIN
 250 documentation.
 251 .PP
 252 It is also possible for the
 253 .I /linuxrc
 254 executable to change the normal root device.
 255 For
 256 .I /linuxrc
 257 to change the normal root device,
 258 .IR /proc
 259 must be mounted.
 260 After mounting
 261 .IR /proc ,
 262 .I /linuxrc
 263 changes the normal root device by writing into the proc files
 264 .IR /proc/sys/kernel/real-root-dev ,
 265 .IR /proc/sys/kernel/nfs-root-name ,
 266 and
 267 .IR /proc/sys/kernel/nfs-root-addrs .
 268 For a physical root device, the root device is changed by having
 269 .I /linuxrc
 270 write the new root file system device number into
 271 .IR /proc/sys/kernel/real-root-dev .
 272 For an NFS root file system, the root device is changed by having
 273 .I /linuxrc
 274 write the NFS setting into files
 275 .IR /proc/sys/kernel/nfs-root-name
 276 and
 277 .I /proc/sys/kernel/nfs-root-addrs
 278 and then writing 0xff (e.g., the pseudo-NFS-device number) into file
 279 .IR /proc/sys/kernel/real-root-dev .
 280 For example, the following shell command line would change
 281 the normal root device to
 282 .IR /dev/hdb1 :
 283 .nf
 284
 285     echo 0x365 >/proc/sys/kernel/real-root-dev
 286
 287 .fi
 288 For an NFS example, the following shell command lines would change the
 289 normal root device to the NFS directory
 290 .I /var/nfsroot
 291 on a local networked NFS server with IP number 193.8.232.7 for a system with
 292 IP number 193.8.232.2 and named "idefix":
 293 .nf
 294
 295     echo /var/nfsroot >/proc/sys/kernel/nfs-root-name
 296     echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \\
 297         >/proc/sys/kernel/nfs-root-addrs
 298     echo 255 >/proc/sys/kernel/real-root-dev
 299 .fi
 300
 301 .BR Note :
 302 The use of
 303 .I /proc/sys/kernel/real-root-dev
 304 to change the root file system is obsolete.
 305 See the kernel source file
 306 .I Documentation/initrd.txt
 307 as well as
 308 .BR pivot_root (2)
 309 and
 310 .BR pivot_root (8)
 311 for information on the modern method of changing the root file system.
 312 .\" FIXME the manual page should describe the pivot_root mechanism.
 313 .\"
 314 .\"
 315 .\"
 316 .SS Usage
 317 The main motivation for implementing
 318 .B initrd
 319 was to allow for modular kernel configuration at system installation.
 320 .PP
 321 A possible system installation scenario is as follows:
 322 .IP 1. 3
 323 The loader program boots from floppy or other media with a minimal kernel
 324 (e.g., support for
 325 .IR /dev/ram ,
 326 .IR /dev/initrd ,
 327 and the ext2 file-system) and loads
 328 .IR /dev/initrd
 329 with a gzipped version of the initial file-system.
 330 .IP 2.
 331 The executable
 332 .I /linuxrc
 333 determines what is needed to (1) mount the normal root file-system
 334 (i.e., device type, device drivers, file system) and (2) the
 335 distribution media (e.g., CD-ROM, network, tape, ...).
 336 This can be done by asking the user, by auto-probing,
 337 or by using a hybrid approach.
 338 .IP 3.
 339 The executable
 340 .I /linuxrc
 341 loads the necessary modules from the initial root file-system.
 342 .IP 4.
 343 The executable
 344 .I /linuxrc
 345 creates and populates the root file system.
 346 (At this stage the normal root file system does not have to be a
 347 completed system yet.)
 348 .IP 5.
 349 The executable
 350 .IR /linuxrc
 351 sets
 352 .IR /proc/sys/kernel/real-root-dev ,
 353 unmount
 354 .IR /proc ,
 355 the normal root file system and any other file
 356 systems it has mounted, and then terminates.
 357 .IP 6.
 358 The kernel then mounts the normal root file system.
 359 .IP 7.
 360 Now that the file system is accessible and intact,
 361 the boot loader can be installed.
 362 .IP 8.
 363 The boot loader is configured to load into
 364 .I /dev/initrd
 365 a file system with the set of modules that was used to bring up the system.
 366 (e.g., Device
 367 .I /dev/ram0
 368 can be modified, then unmounted, and finally, the image is written from
 369 .I /dev/ram0
 370 to a file.)
 371 .IP 9.
 372 The system is now bootable and additional installation tasks can be
 373 performed.
 374 .PP
 375 The key role of
 376 .I /dev/initrd
 377 in the above is to reuse the configuration data during normal system operation
 378 without requiring initial kernel selection, a large generic kernel or,
 379 recompiling the kernel.
 380 .PP
 381 A second scenario is for installations where Linux runs on systems with
 382 different hardware configurations in a single administrative network.
 383 In such cases, it may be desirable to use only a small set of kernels
 384 (ideally only one) and to keep the system-specific part of configuration
 385 information as small as possible.
 386 In this case, create a common file
 387 with all needed modules.
 388 Then, only the
 389 .I /linuxrc
 390 file or a file executed by
 391 .I /linuxrc
 392 would be different.
 393 .PP
 394 A third scenario is more convenient recovery disks.
 395 Because information like the location of the root file-system
 396 partition is not needed at boot time, the system loaded from
 397 .I /dev/initrd
 398 can use a dialog and/or auto-detection followed by a
 399 possible sanity check.
 400 .PP
 401 Last but not least, Linux distributions on CD-ROM may use
 402 .B initrd
 403 for easy installation from the CD-ROM.
 404 The distribution can use
 405 .B LOADLIN
 406 to directly load
 407 .I /dev/initrd
 408 from CD-ROM without the need of any floppies.
 409 The distribution could also use a
 410 .B LILO
 411 boot floppy and then bootstrap a bigger RAM disk via
 412 .IR /dev/initrd
 413 from the CD-ROM.
 414 .\"
 415 .\"
 416 .\"
 417 .SH FILES
 418 .I /dev/initrd
 419 .br
 420 .I /dev/ram0
 421 .br
 422 .I /linuxrc
 423 .br
 424 .I /initrd
 425 .\"
 426 .\"
 427 .\"
 428 .SH NOTES
 429 .IP 1. 3
 430 With the current kernel, any file systems that remain mounted when
 431 .I /dev/ram0
 432 is moved from
 433 .I /
 434 to
 435 .I /initrd
 436 continue to be accessible.
 437 However, the
 438 .I /proc/mounts
 439 entries are not updated.
 440 .IP 2.
 441 With the current kernel, if directory
 442 .I /initrd
 443 does not exist, then
 444 .I /dev/ram0
 445 will
 446 .B not
 447 be fully unmounted if
 448 .I /dev/ram0
 449 is used by any process or has any file-system mounted on it.
 450 If
 451 .IR /dev/ram0
 452 is
 453 .B not
 454 fully unmounted, then
 455 .I /dev/ram0
 456 will remain in memory.
 457 .IP 3.
 458 Users of
 459 .I /dev/initrd
 460 should not depend on the behavior give in the above notes.
 461 The behavior may change in future versions of the Linux kernel.
 462 .\"
 463 .\"
 464 .\"
 465 .\" .SH AUTHORS
 466 .\" The kernel code for device
 467 .\" .BR initrd
 468 .\" was written by Werner Almesberger <almesber@lrc.epfl.ch> and
 469 .\" Hans Lermen <lermen@elserv.ffm.fgan.de>.
 470 .\" The code for
 471 .\" .BR initrd
 472 .\" was added to the baseline Linux kernel in development version 1.3.73.
 473 .SH "SEE ALSO"
 474 .BR chown (1),
 475 .BR mknod (1),
 476 .BR ram (4),
 477 .BR freeramdisk (8),
 478 .BR rdev (8)
 479
 480 The documentation file
 481 .I initrd.txt
 482 in the kernel source package, the LILO documentation,
 483 the LOADLIN documentation, the SYSLINUX documentation.