summaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorDave Reisner <dreisner@archlinux.org>2012-11-22 23:29:48 +0100
committerDave Reisner <dreisner@archlinux.org>2012-11-24 00:01:34 +0100
commit3c961b3bc3cbffa7537575c8ea85d016a0342f24 (patch)
treefb168bd640663cbc1a21db808ae7f27c17123879 /man
parentf85d28014134076217904885ea339e2f4c438df1 (diff)
downloadmkinitcpio-3c961b3bc3cbffa7537575c8ea85d016a0342f24.tar.gz
mkinitcpio-3c961b3bc3cbffa7537575c8ea85d016a0342f24.tar.xz
build: move manpages to subdir
Signed-off-by: Dave Reisner <dreisner@archlinux.org>
Diffstat (limited to 'man')
-rw-r--r--man/lsinitcpio.1.txt68
-rw-r--r--man/mkinitcpio.8.txt297
-rw-r--r--man/mkinitcpio.conf.5.txt82
3 files changed, 447 insertions, 0 deletions
diff --git a/man/lsinitcpio.1.txt b/man/lsinitcpio.1.txt
new file mode 100644
index 0000000..98bd756
--- /dev/null
+++ b/man/lsinitcpio.1.txt
@@ -0,0 +1,68 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+lsinitcpio(1)
+=============
+
+Name
+----
+lsinitcpio - Examine an initramfs
+
+Synopsis
+--------
+'lsinitcpio' [action] [options] 'image'
+
+Description
+-----------
+Examines the contents of an initcpio image. Without any options, 'lsinitcpio'
+simply lists the contents of an image.
+
+Actions
+-------
+*-a, \--analyze*::
+ Analyze the contents of the specified image and print output in human
+ readable form.
+
+*-c, \--config*::
+ Show the configuration file the given image was built with.
+
+*-l, \--list*::
+ List the contents of the archive. This is the default action. Pass the *-v*
+ flag for more detailed results.
+
+*-x, \--extract*::
+ Extract the given image to the current working directory.
+
+Options
+-------
+
+*-h, \--help*::
+ Output a short overview of available command-line switches.
+
+*-n, \--nocolor*::
+ Disable color output.
+
+*-V, \--version*::
+ Display version information.
+
+*-v, \--verbose*::
+ Be more verbose. In particular, show long style output when listing
+ the contents of an image, and show files as they are extracted when
+ the *-x* option is given.
+
+Bugs
+----
+Upon writing this manpage, there were no noticeable bugs present. Please visit
+<http://bugs.archlinux.org/> for an up to date list.
+
+See Also
+--------
+*mkinitcpio*(8)
+
+Authors
+-------
+lsinitcpio was created by Dave Reisner <dreisner@archlinux.org>
+
+Copyright
+---------
+Copyright (c) Arch Linux 2011-2012
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
diff --git a/man/mkinitcpio.conf.5.txt b/man/mkinitcpio.conf.5.txt
new file mode 100644
index 0000000..c2519c9
--- /dev/null
+++ b/man/mkinitcpio.conf.5.txt
@@ -0,0 +1,82 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+mkinitcpio.conf(5)
+==================
+
+Name
+----
+mkinitcpio.conf - mkinitcpio configuration file
+
+Synopsis
+--------
+/etc/mkinitcpio.conf
+
+Description
+-----------
+mkinitcpio will attempt to read from a config file each time it is invoked,
+`/etc/mkinitcpio.conf' by default. This file defines several variables which
+describe the contents of the image to be generated.
+
+Variables
+---------
+*MODULES*::
+
+ Defines additional modules, space delimited, which should be added to the
+ image. Dependencies (including other modules and necessary firmware), will
+ also be added to the image. At runtime, the modules in this array which
+ were successfully added to the image will be explicitly loaded.
+
+*FILES*::
+
+ Defines additional files, space delimited, which should be added to the image.
+ Files are added as is, and parent directories will be added if needed. Files
+ specified in this variable will override previously added files of the same
+ path.
+
+*BINARIES*::
+
+ Defines additional binaries, space delimited, which should be added to the
+ image. These are assumed to be dynamic ELF binaries, and necessary shared
+ library dependencies will automatically be added. However, it is not
+ considered an error to specify a non-ELF binary in this variable. Parent
+ directories will be added if needed. Files specified in this variable will
+ override previously added files of the same path.
+
+*HOOKS*::
+
+ This variable defines the hooks which will be run during the build process.
+ Order is important, as it defines the order in which hooks will be run
+ during bootup. Use mkinitcpio's '-L' flag to list all available hooks,
+ and the '-H' flag to display the help text for a specific hook.
+
+*COMPRESSION*::
+
+ Defines a program to filter the generated image through. As of linux 2.6.38,
+ the kernel understands the compression formats yielded by the *gzip*, *bzip2*,
+ *lzop*, *lzma*, and *xz* compressors. If unspecified, this setting defaults to
+ *gzip* compression. In order to create an uncompressed image, define this
+ variable as *cat*.
++
+It's not hard to realize that a filter such as a *tac* or *rev* will cause
+*mkinitcpio* to report success but generate a useless image. Similarly, using a
+compression program not listed above may generate an equally useless image,
+despite being "valid".
+
+*COMPRESSION_OPTIONS*::
+
+ Defines additional options to be passed to the compression program. This option
+ is generally not used. It can be potentially dangerous and may cause
+ invalid images to be generated without any sign of an error.
+
+See Also
+--------
+*mkinitcpio*(8)
+
+Authors
+-------
+mkinitcpio is created and maintained by the Arch Linux Developer community.
+
+Copyright
+---------
+Copyright (c) Arch Linux 2006-2012