From e79816383bfa5c8a82f6bc3816617327745dd54a Mon Sep 17 00:00:00 2001 From: Dave Reisner Date: Thu, 17 May 2012 21:34:55 -0400 Subject: manpage: expand doc on build and runtime hooks Fully document the recommended API for install hooks, and the various hook points available for early userspace hooks. Signed-off-by: Dave Reisner --- mkinitcpio.8.txt | 108 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 98 insertions(+), 10 deletions(-) (limited to 'mkinitcpio.8.txt') diff --git a/mkinitcpio.8.txt b/mkinitcpio.8.txt index 070cfeb..9b95f5a 100644 --- a/mkinitcpio.8.txt +++ b/mkinitcpio.8.txt @@ -83,13 +83,6 @@ Options *-z, \--compress* 'compress':: Override the compression method with the 'compress' program. -About Hooks ------------ -A hook is a script that executes in the initial ramdisk. Scripts are listed in -order of execution as a space separated string in the *HOOKS* variable in the -mkinitcpio configuration file. Hooks can, for example, set up the udev device -filesystem, load IDE modules, etc. - About Presets ------------- A preset is a pre-defined definition on how to create an initial ramdisk. @@ -98,6 +91,97 @@ 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 desintation 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_path* 'path':: + + Recursively adds a path to the image. This will inherently call *add_file* + and *add_dir* accordingly. + +*add_all_modules* [ '-f filter' ] *pattern*:: + + add 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 guarenteed to match the name of the hook the + script is called. It *can* be overriden, but this is not recommended, as this + only exists for legacy compatability. + +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 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 @@ -157,9 +241,13 @@ Files '/etc/mkinitcpio.d':: Folder containing mkinitcpio presets. -'/usr/lib/initcpio':: -'/lib/initcpio':: - Files related to creating an initial ramdisk. +'/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 -------- -- cgit v1.2.3-24-g4f1b