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