diff options
Diffstat (limited to 'man/mkinitcpio.8.txt')
| -rw-r--r-- | man/mkinitcpio.8.txt | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/man/mkinitcpio.8.txt b/man/mkinitcpio.8.txt new file mode 100644 index 0000000..f19250f --- /dev/null +++ b/man/mkinitcpio.8.txt @@ -0,0 +1,297 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +mkinitcpio(8) +============= + +Name +---- +mkinitcpio - Create an initial ramdisk environment + +Synopsis +-------- +'mkinitcpio' [options] + +Description +----------- +Creates an initial ramdisk environment for booting the linux kernel. The +initial ramdisk is in essence a very small environment (early userspace) which +loads various kernel modules and sets up necessary things before handing over +control to init. This makes it possible to have, for example, encrypted root +filesystems and root filesystems on a software RAID array. mkinitcpio allows +for easy extension with custom hooks, has autodetection at runtime, and many +other features. + +Options +------- +*-A, \--addhooks* 'hooks':: + Add the additional 'hooks' to the image. These will be processed in order + after all other hooks from the config file. Multiple hooks should be + comma-separated. This option can be specified multiple times. + +*-c, \--config* 'config':: + Use 'config' file to generate the ramdisk. Default: /etc/mkinitcpio.conf + +*-g, \--generate* 'filename':: + Generate a CPIO image as 'filename'. Default: no; this means nothing will be + written to the filesystem unless this option is specified. + +*-H, \--hookhelp* 'hookname':: + Output help for hookname 'hookname'. + +*-h, \--help*:: + Output a short overview of available command-line switches. + +*-k, \--kernel* 'kernelversion':: + Use 'kernelversion', instead of the current running kernel. This may be a + path to a kernel image or a specific kernel version. + +*-L, \--listhooks*:: + List all available hooks. + +*-M, \--automods*:: + Display modules found via autodetection. mkinitcpio will automatically try to + determine which kernel modules are needed to start your computer. This option + lists which modules were detected. + +*-n, \--nocolor*:: + Disable color output. + +*-p, \--preset* 'preset':: + Build initramfs image(s) according to specified 'preset'. This may be a file in + /etc/mkinitcpio.d (without the .preset extension) or a full, absolute path to a + file. + +*-r, \--moduleroot* 'root':: + Specifies the root directory to find modules in, defaulting to '/'. + +*-S, \--skiphooks* 'hooks':: + Skip 'hooks' when generating the image. Multiple hooks should be comma-separated. + This option can be specified multiple times. + +*-s, \--save*:: + Saves the build directory for the initial ramdisk. Default: no; This means + the directory will not be retained if this option isn't specified. Useful for + debugging purposes. + +*-t, \--builddir* 'tmpdir':: + Use 'tmpdir' as the temporary build directory instead of /tmp. 'tmpdir' + must exist. The 'TMPDIR' environment variable is also honored to set this + location, but the command line option will take precedence. + +*-V, \--version*:: + Display version information. + +*-v, \--verbose*:: + Verbose output. Outputs more information about what's happening during + creation of the ramdisk. + +*-z, \--compress* 'compress':: + Override the compression method with the 'compress' program. + +About Presets +------------- +A preset is a pre-defined definition on how to create an initial ramdisk. +Instead of specifying the configuration file and which output file, every time +you generate a new initial ramdisk, you define a preset and use the -p switch +to generate an initial ramdisk according to your preset. Presets are located in +/etc/mkinitcpio.d + +About Install Hooks +------------------- +Install hooks are bash scripts which are sourced during mkinitcpio runtime in +order to add modules, binaries, and other files to the image. A variety of +functions exist to facilitate this. + +*add_module* 'modname':: + + Adds the module specified by 'modname' to the image. Dependencies are derived + and added automatically. + +*add_binary* 'binary' [ 'destination' ] [ 'mode' ]:: + + Adds a binary to the image. The argument 'binary' need not be an absolute + path and, if needed, a lookup will be performed. If the binary is a dynamically + linked ELF binary, dependencies will be automatically added. Optionally, a + destination within the initramfs image as well as a file mode can be specified. + By default, the destintation and mode be taken from the source derived from + 'binary'. + +*add_file* 'path' [ 'destination' ] [ 'mode' ]:: + + Adds a file and any needed parent directories to the image. Optionally, a + destination within the initramfs image as well as a file mode can be specified. + By default, the destination and mode will be taken from the source and mode of + the file specified by the 'path'. + +*add_dir* 'path':: + + Adds a directory and its parents to the image. + +*add_full_dir* 'directory':: + + Recursively adds a directory to the image by walking the given path and + calling *add_file*, *add_dir*, and *add_symlink* accordingly. This function + will not follow symlinks, nor will it add the targets of symlinks. + +*add_symlink* 'path' [ 'link-target' ]:: + + Adds a symlink to the image at the specified `path`, optionally pointing to + the specified `link-target`. If the `link-target` is not provided, it is assumed + that this symlink exists in the real filesystem, and the target will be read + using readlink. There is no checking done to ensure that the target of the + symlink exists, and symlinks will not be followed recursively. + +*add_all_modules* [ '-f filter' ] *pattern*:: + + Adds modules to the image, without regard for the autodetect whitelist. *pattern* + should be a subdirectory within the kernel tree describing a subset of modules to + be included. Further refinement can be provided via the -f flag with an extended + regular expression. + +*add_checked_modules* [ '-f filter' ] *pattern*:: + + Similar to *add_all_modules* with the constraint that only modules matching the + whitelist generated by the autodetect hook will be added to the image. If the + autodetect hook is not present in the image, this function is identical to + *add_all_modules*. + +*add_runscript* [ 'scriptname' ]:: + + Adds a runtime hook to the image, which is a busybox ash compatible shell + script. The name of the script is guaranteed to match the name of the hook the + script is called from. + +About Runtime Hooks +------------------- +Runtime hooks added to the image via the *add_runscript* function from an +install hook are able to provide extra functionality during early userspace. +Specific functions in these files will run at different times. A hook can +define one or more of these. At each hook point, hooks are run in the order +that they are defined in the HOOKS variable, except for cleanup hooks which are +run in reverse. + +*run_earlyhook*:: + + Functions of this name will be run once the API mounts have been setup and the + kernel command line has been parsed. Daemons needed for early userspace should + be started from this hook point. + +*run_hook*:: + + Functions of this name will be run after any early hooks, and after user + defined modules have been installed. This is the most common hook point, and + functionality such as scanning for LVM volumes and mapping encrypted volumes + should be performed here. + +*run_latehook*:: + + Functions of this name will be run after root has been mounted. This is generally + used for further necessary setup in the real root, such as mounting other system + partitions. + +*run_cleanuphook*:: + + Functions of this name are run as late as possible. Any daemons started + from a run_earlyhook function should be shut down here in preparation for + switching to the real root. + +Early Init Environment +---------------------- +mkinitcpio gives special treatment to certain environment variables passed on +the kernel command line: + +*break*['=<premount|postmount>']:: + If specified, mkinitcpio will start a shell during early init. The optional + parameter controls when this occurs: when 'premount' or no parameter are + specified, the shell will be launched prior to mounting root. If 'postmount' + is specified, the shell will be launched after mounting root. + +*disablehooks=*'hooklist':: + This is a comma separated list of hooks which will be skipped during early + init. + +*earlymodules=*'modulelist':: + This is a comma separated list of modules which will be loaded prior to any + others. This is generally not needed, and usually points to a configuration + or kernel problem. + +*quiet*:: + Causes mkinitcpio to output fewer messages during boot. Errors will not be + suppressed. + +*ro*:: + Specifies that root should be mounted with readonly permissions. This is the + default behavior. + +*rw*:: + Specifies that root should be mounted with readwrite permissions. This is + generally only useful if your initramfs uses the 'fsck' hook. + +*root=*'rootdevice':: + This variable describes the root partition which early init will mount + before passing control to the real init. mkinitcpio understands a variety of + formats, the most basic of which is the path to the block device, either + directly such as '/dev/sda2', or using a udev symlink such as + '/dev/disk/by-label/CorsairF80-root'. Support for identification by LABEL or + UUID tags are also supported, such as, 'LABEL=CorsairF80-root'. As of + util-linux 2.22, PARTUUID is also supported. Identification via hex encoded + major/minor device ID is supported for legacy reasons, but should not be used. + +*rootdelay=*'seconds':: + Sets the delay, in seconds, that mkinitcpio is willing to wait for the root + device to show up, if it is not available immediately. This defaults to 5 + seconds. If an invalid integer is passed, this variable will have no effect. + +These are only the variables that the core of mkinitcpio honor. Additional +hooks may look for other environment variables and should be documented by the +help output for the hook. + +Files +----- +'/etc/mkinitcpio.conf':: + Default configuration file for mkinitcpio. + +'/etc/mkinitcpio.d':: + Folder containing mkinitcpio presets. + +'/usr/lib/initcpio/install':: +'/lib/initcpio/install':: + Search path for build time hooks. + +'/usr/lib/initcpio/hooks':: +'/lib/initcpio/hooks':: + Search path for early userspace runtime hooks. + +Examples +-------- +*mkinitcpio*:: + Perform a 'dry-run'. This will generate an initial ramdisk but will not + write anything. Use -g to create the real image. + +*mkinitcpio -p linux*:: + Create an initial ramdisk based on the 'linux' preset. + +*mkinitcpio -g /boot/initramfs-linux.img -k /boot/vmlinuz-linux*:: + Create an initial ramdisk for the kernel at /boot/vmlinuz-linux. The + resulting image will be written to /boot/initramfs-linux.img. + +See also +-------- +A more thorough article on configuring mkinitcpio: +<http://wiki.archlinux.org/index.php/Mkinitcpio> + +*initrd*(4), *lsinitcpio*(1), *mkinitcpio.conf*(5) + +Bugs +---- +Upon writing this manpage, there were no noticeable bugs present. Please visit +<http://bugs.archlinux.org/> for an up to date list. + +Authors +------- +mkinitcpio is created and maintained by the Arch Linux Developer community. + +Copyright +--------- +Copyright (c) Arch Linux 2006-2012 |