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 2007-11-26 "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 " and " CONFIG_BLK_DEV_INITRD=y )
  60 must be compiled directly into the Linux kernel to use
  61 .IR /dev/initrd "."
  62 When using
  63 .IR /dev/initrd ", "
  64 the RAM disk driver cannot be loaded as a module.
  65 .\"
  66 .\"
  67 .\"
  68 .SH FILES
  69 .I /dev/initrd
  70 .br
  71 .I /dev/ram0
  72 .br
  73 .I /linuxrc
  74 .br
  75 .I /initrd
  76 .\"
  77 .\"
  78 .\"
  79 .SH DESCRIPTION
  80 The special file
  81 .I /dev/initrd
  82 is a read-only block device.
  83 Device
  84 .I /dev/initrd
  85 is a RAM disk that is initialized (e.g., loaded) by the boot loader before
  86 the kernel is started.
  87 The kernel then can use the block device
  88 .IR /dev/initrd "'s "
  89 contents for a two phased system boot-up.
  90 .PP
  91 In the first boot-up phase, the kernel starts up
  92 and mounts an initial root file-system from the contents
  93 of
  94 .I /dev/initrd
  95 (e.g. RAM disk initialized by the boot loader).
  96 In the second phase, additional drivers or other modules
  97 are loaded from the initial root device's contents.
  98 After loading the additional modules, a new root file system
  99 (i.e., the normal root file system) is mounted from a
 100 different device.
 101 .\"
 102 .\"
 103 .\"
 104 .SS "Boot-up Operation"
 105 When booting up with
 106 .BR initrd ", the system boots as follows:"
 107 .IP 1. 3
 108 The boot loader loads the kernel program and
 109 .IR /dev/initrd "'s contents into memory."
 110 .IP 2.
 111 On kernel startup,
 112 the kernel uncompresses and copies the contents of the device
 113 .I /dev/initrd
 114 onto device
 115 .I /dev/ram0
 116 and then frees the memory used by
 117 .IR /dev/initrd "."
 118 .IP 3.
 119 The kernel then read-write mounts device
 120 .I /dev/ram0
 121 as the initial root file system.
 122 .IP 4.
 123 If the indicated normal root file system is also the initial root file-system
 124 (e.g.
 125 .I /dev/ram0
 126 ) then the kernel skips to the last step for the usual boot sequence.
 127 .IP 5.
 128 If the executable file
 129 .IR /linuxrc " is present in the initial root file-system, " /linuxrc
 130 is executed with UID 0.
 131 (The file
 132 .I /linuxrc
 133 must have executable permission.
 134 The file
 135 .I /linuxrc
 136 can be any valid executable, including a shell script.)
 137 .IP 6.
 138 If
 139 .I /linuxrc
 140 is not executed or when
 141 .I /linuxrc
 142 terminates, the normal root file system is mounted.
 143 (If
 144 .I /linuxrc
 145 exits with any file-systems mounted on the initial root
 146 file-system, then the behavior of the kernel is
 147 .BR UNSPECIFIED "."
 148 See the NOTES section for the current kernel behavior.)
 149 .IP 7.
 150 If the normal root file has directory
 151 .IR /initrd ", device"
 152 .I /dev/ram0
 153 is moved from
 154 .IR / " to " /initrd "."
 155 Otherwise if directory
 156 .IR /initrd " does not exist device " /dev/ram0 " is unmounted."
 157 (When moved from
 158 .IR / " to " /initrd ", " /dev/ram0
 159 is not unmounted and therefore processes can remain running from
 160 .IR /dev/ram0 "."
 161 If directory
 162 .I /initrd
 163 does not exist on the normal root file-system
 164 and any processes remain running from
 165 .IR /dev/ram0 " when " /linuxrc
 166 exits, the behavior of the kernel is
 167 .BR UNSPECIFIED "."
 168 See the NOTES section for the current kernel behavior.)
 169 .IP 8.
 170 The usual boot sequence (e.g. invocation of
 171 .IR /sbin/init )
 172 is performed on the normal root file system.
 173 .\"
 174 .\"
 175 .\"
 176 .SS Options
 177 The following boot loader options when used with
 178 .BR initrd ", affect the kernel's boot-up operation:"
 179 .TP
 180 .BI initrd= "filename"
 181 Specifies the file to load as the contents of
 182 .IR /dev/initrd "."
 183 For
 184 .B LOADLIN
 185 this is a command line option.
 186 For
 187 .B LILO
 188 you have to use this command in the
 189 .B LILO
 190 configuration file
 191 .IR /etc/lilo.config .
 192 The filename specified with this
 193 option will typically be a gzipped file-system image.
 194 .TP
 195 .I noinitrd
 196 This boot time option disables the two phase boot-up operation.
 197 The kernel performs the usual boot sequence as if
 198 .I /dev/initrd
 199 was not initialized.
 200 With this option, any contents of
 201 .I /dev/initrd
 202 loaded into memory by the boot loader contents are preserved.
 203 This option permits the contents of
 204 .I /dev/initrd
 205 to be any data and need not be limited to a file system image.
 206 However, device
 207 .I /dev/initrd
 208 is read-only and can be read only one time after system startup.
 209 .TP
 210 .BI root= "device-name"
 211 Specifies the device to be used as the normal root file system.
 212 .RB "For " LOADLIN
 213 this is a command line option.
 214 .RB "For " LILO " this is a boot time option or
 215 can be used as an option line in the
 216 .BR LILO " configuration file " /etc/lilo.config "."
 217 The device specified by the this option must be a mountable
 218 device having a suitable root file-system.
 219 .\"
 220 .\"
 221 .\"
 222 .SS "Changing the Normal Root File System"
 223 By default,
 224 the kernel's settings
 225 (e.g. set in the kernel file with
 226 .BR rdev (8)
 227 or compiled into the kernel file),
 228 or the boot loader option setting
 229 is used for the normal root file systems.
 230 For a NFS-mounted normal root file system, one has to use the
 231 .BR nfs_root_name " and " nfs_root_addrs
 232 boot options to give the NFS settings.
 233 For more information on NFS-mounted root see the kernel documentation file
 234 .BR nfsroot.txt "."
 235 For more information on setting the root file system also see the
 236 .BR LILO " and " LOADLIN " documentation."
 237 .PP
 238 It is also possible for the
 239 .I /linuxrc
 240 executable to change the normal root device.
 241 For
 242 .I /linuxrc
 243 to change the normal root device,
 244 .IR /proc " must be mounted."
 245 After mounting
 246 .IR /proc ", " /linuxrc
 247 changes the normal root device by writing into the proc files
 248 .IR /proc/sys/kernel/real-root-dev ", "
 249 .IR /proc/sys/kernel/nfs-root-name ", and "
 250 .IR /proc/sys/kernel/nfs-root-addrs "."
 251 For a physical root device, the root device is changed by having
 252 .I /linuxrc
 253 write the new root file system device number into
 254 .IR /proc/sys/kernel/real-root-dev "."
 255 For a NFS root file system, the root device is changed by having
 256 .I /linuxrc
 257 write the NFS setting into files
 258 .IR /proc/sys/kernel/nfs-root-name " and "
 259 .I /proc/sys/kernel/nfs-root-addrs
 260 and then writing 0xff (e.g. the pseudo-NFS-device number) into file
 261 .IR /proc/sys/kernel/real-root-dev "."
 262 For example, the following shell command line would change
 263 the normal root device to
 264 .IR /dev/hdb1 :
 265 .nf
 266
 267     echo 0x365 >/proc/sys/kernel/real-root-dev
 268
 269 .fi
 270 For a NFS example, the following shell command lines would change the
 271 normal root device to the NFS directory
 272 .I /var/nfsroot
 273 on a local networked NFS server with IP number 193.8.232.7 for a system with
 274 IP number 193.8.232.7 and named 'idefix':
 275 .nf
 276
 277     echo /var/nfsroot >/proc/sys/kernel/nfs-root-name
 278     echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \\
 279         >/proc/sys/kernel/nfs-root-addrs
 280     echo 255 >/proc/sys/kernel/real-root-dev
 281 .fi
 282
 283 .BR Note :
 284 The use of
 285 .I /proc/sys/kernel/real-root-dev
 286 to change the root file system is obsolete.
 287 See the kernel source file
 288 .I Documentation/initrd.txt
 289 as well as
 290 .BR pivot_root (2)
 291 and
 292 .BR pivot_root (8)
 293 for information on the modern method of changing the root file system.
 294 .\" FIXME the manual page should describe the pivot_root mechanism.
 295 .\"
 296 .\"
 297 .\"
 298 .SS Usage
 299 The main motivation for implementing
 300 .B initrd
 301 was to allow for modular kernel configuration at system installation.
 302 .PP
 303 A possible system installation scenario is as follows:
 304 .IP 1. 3
 305 The loader program boots from floppy or other media with a minimal kernel
 306 (e.g. support for
 307 .IR /dev/ram ", " /dev/initrd ", and the ext2 file-system) and loads "
 308 .IR /dev/initrd " with a gzipped version of the initial file-system.
 309 .IP 2.
 310 The executable
 311 .I /linuxrc
 312 determines what is needed to (1) mount the normal root file-system
 313 (i.e., device type, device drivers, file system) and (2) the
 314 distribution media (e.g. CD-ROM, network, tape, ...).
 315 This can be
 316 done by asking the user, by auto-probing, or by using a hybrid
 317 approach.
 318 .IP 3.
 319 The executable
 320 .I /linuxrc
 321 loads the necessary modules from the initial root file-system.
 322 .IP 4.
 323 The executable
 324 .I /linuxrc
 325 creates and populates the root file system.
 326 (At this stage the normal root file system does not have to be a
 327 completed system yet.)
 328 .IP 5.
 329 The executable
 330 .IR /linuxrc " sets " /proc/sys/kernel/real-root-dev,
 331 unmount
 332 .IR /proc ", "
 333 the normal root file system and any other file
 334 systems it has mounted, and then terminates.
 335 .PP
 336 6. The kernel then mounts the normal root file system.
 337 .IP 7.
 338 Now that the file system is accessible and intact,
 339 the boot loader can be installed.
 340 .IP 8.
 341 The boot loader is configured to load into
 342 .I /dev/initrd
 343 a file system with the set of modules that was used to bring up the system.
 344 (e.g. Device
 345 .I /dev/ram0
 346 can be modified, then unmounted, and finally, the image is written from
 347 .I /dev/ram0
 348 to a file.)
 349 .IP 9.
 350 The system is now bootable and additional installation tasks can be
 351 performed.
 352 .PP
 353 The key role of
 354 .I /dev/initrd
 355 in the above is to re-use the configuration data during normal system operation
 356 without requiring initial kernel selection, a large generic kernel or,
 357 recompiling the kernel.
 358 .PP
 359 A second scenario is for installations where Linux runs on systems with
 360 different hardware configurations in a single administrative network.
 361 In such cases, it may be desirable to use only a small set of kernels
 362 (ideally only one) and to keep the system-specific part of configuration
 363 information as small as possible.
 364 In this case, create a common file
 365 with all needed modules.
 366 Then, only the
 367 .I /linuxrc
 368 file or a file executed by
 369 .I /linuxrc
 370 would be different.
 371 .PP
 372 A third scenario is more convenient recovery disks.
 373 Because information like the location of the root file-system
 374 partition is not needed at boot time, the system loaded from
 375 .I /dev/initrd
 376 can use a dialog and/or auto-detection followed by a
 377 possible sanity check.
 378 .PP
 379 Last but not least, Linux distributions on CD-ROM may use
 380 .B initrd
 381 for easy installation from the CD-ROM.
 382 The distribution can use
 383 .B LOADLIN
 384 to directly load
 385 .I /dev/initrd
 386 from CD-ROM without the need of any floppies.
 387 The distribution could also use a
 388 .B LILO
 389 boot floppy and then bootstrap a bigger ram disk via
 390 .IR /dev/initrd " from the CD-ROM."
 391 .\"
 392 .\"
 393 .\"
 394 .SH NOTES
 395 .IP 1. 3
 396 With the current kernel, any file systems that remain mounted when
 397 .IR /dev/ram0 " is moved from " / " to " /initrd
 398 continue to be accessible.
 399 However, the
 400 .I /proc/mounts
 401 entries are not updated.
 402 .IP 2.
 403 With the current kernel, if directory
 404 .IR /initrd " does not exist, then "
 405 .I /dev/ram0
 406 will
 407 .B not
 408 be fully unmounted if
 409 .I /dev/ram0
 410 is used by any process or has any file-system mounted on it.
 411 If
 412 .IR /dev/ram0 " is
 413 .B not
 414 fully unmounted, "
 415 then
 416 .I /dev/ram0
 417 will remain in memory.
 418 .IP 3.
 419 Users of
 420 .I /dev/initrd
 421 should not depend on the behavior give in the above notes.
 422 The behavior may change in future versions of the Linux kernel.
 423 .\"
 424 .\"
 425 .\"
 426 .\" .SH AUTHORS
 427 .\" The kernel code for device
 428 .\" .BR initrd
 429 .\" was written by Werner Almesberger <almesber@lrc.epfl.ch> and
 430 .\" Hans Lermen <lermen@elserv.ffm.fgan.de>.
 431 .\" The code for
 432 .\" .BR initrd
 433 .\" was added to the baseline Linux kernel in development version 1.3.73.
 434 .SH "SEE ALSO"
 435 .BR chown (1),
 436 .BR mknod (1),
 437 .BR ram (4),
 438 .BR freeramdisk (8),
 439 .BR rdev (8)
 440
 441 The documentation file
 442 .I initrd.txt
 443 in the kernel source package, the LILO documentation,
 444 the LOADLIN documentation, the SYSLINUX documentation.