NAME

geninit - modular initramfs creation utility

SYNOPSIS

Usage: geninit [ options ]

DESCRIPTION

geninit is a tool for creating cpio archives to be used as an initial ramfs during system bootstrap. It features a modular design, making it easy to tailor the image to the system's hardware and software needs.

OPTIONS

-b basedir

Specify a base directory other than /. This might be useful when mounting another system from a rescue CD. geninit will attempt to use as much as possible from the guest system, drawing only from the host system when necessary.

-c config-file

Use an alterate config file. Defaults to /etc/geninit.conf.

-g imagename

Specify the absolute path of the generated initramfs. If not specified, and in the absence of the -p option, a dry-run will be performed and no image will be created.

-H builder

Display the help message for a builder. A list of available builders can be generated with the -L option.

-h

Display the help message and quit.

-k kernel

Specify an alternate kernel version to create an image for. The kernel can be specified as an exact version (such as 2.6.38-ARCH), or provided as a path to the kernel bzImage itself. By default, this is the currently loaded kernel.

-L

List all available builders for use in the builders array in the config file.

-p preset

Specify a preset file to drive image creation. This is any file named with a .preset extension in /etc/geninit.d. An example preset file is packaged with geninit for explanatory purpose.

-S builders

A comma delimited list of builders to skip during image creation.

-s

Save the temporary workspace after the build process. This is useful for debugging purposes.

-t path

Specify an alterate version to the temporary directory used as a workspace. This needs to be a writeable directory with a minimum of 20mb free.

-z compression

Override the compression method specified by the config file. geninit supports compression via gzip, bzip2, lzma, xz, and lzop. You can also use none to disable compression. Please note that your kernel must have support for this method. geninit will not make this check for you! If in doubt, gzip is a safe choice.

EXAMPLES

geninit

Perform a dry run against the currently loaded kernel. Although a temporary workspace is created, no bootable image is generated from this operation.

geninit -k /boot/vmlinuz26 -g /boot/initramfs-ARCH

Create an image for the kernel located at /boot/vmlinuz26 called /boot/initramfs-ARCH, described by the default config file.

geninit -b /mnt -p kernel26

Build an image, or images, as described in /mnt/etc/geninit.d/kernel26.preset.

KERNEL COMMAND LINE

geninit pays special attention to some parameters on the kernel cmdline. In addition to the ensuing list, some hooks may look for environment variables. Refer to the help for individual builders for more information.

break

Request a shell during the early userspace process. This occurs after all hooks have been run, but prior to the root device being mounted.

init=path

An optional parameter to specify an alternate init system for userspace. If not specified, this defaults to /sbin/init.

root=device

The root device to be mounted before leaving early userspace. This can take a number of different formats, such as:

root=/dev/sda2
root=LABEL=root
root=UUID=037b9d94-148e-4ee4-8d38-67bfe15bb535
root=MAJOR:MINOR

This parameter, for obvious reasons, must be specified.

rootflags=flags

A comma separated list of filesystem specific options passed directly to the final parameter of mount(2) when mounting the root device. Do not attempt to pass flags such as rw or relatime here.

rw

Specifies that the root device should be mounted as read-write. This is usually a bad idea. geninit will default to mounting the root device as read-only. It is up to your init to remount the device read-write (which usually occurs after a fsck has been performed).

BUILDERS

Builders are bash scripts that are executed during build time in order to add functionality to the image. They are sourced from geninit's config file, and run in array index order. Builders may draw in an additional hookscript for use at runtime.

At a minimum, builders must define a function called build, which contains instructions on what geninit should add to the image. See the BUILDER API section for documentation on the available methods for adding files. Additionally, a builder should also include a helpmsg function, which describes the features and/or functionality provided by the builder. This is called via geninit's -H option.

HOOKS

Hooks are executed during the bootstrap process in order to facilitate finding and/or mounting of the root device. They run under Busybox's almquist shell. In addition to any variables sourced from the kernel cmdline, the following variables may be available from within the environment that hooks run in:

UDEVPID

When set, contains the PID of the udev daemon process.

FDINIT

A numerical value describing a file descriptor which can be used to communicate with the parent process (init). The preferred method of setting variables in init is via the initexport function defined by libinit.

LIBINIT

A small shell library called libinit is included by the base builder. Hooks can use functions defined in this library by sourcing it from /libinit. The following functions are defined by libinit:

msg format [message]

Sends a formatted message to standard output, provided that the kernel parameter 'quiet' was not passed. Messages are prefixed with ":: ".

err format [message]

Sends a formatted message to standard error. Messages are prefixed with "error: ".

poll_device device [timeout]

Waits up to timeout seconds for the specified device, which is a block device or a symlink to a block device. This functions returns 0 when the device shows up, and 1 when it does not.

initexport key=val...

Set a variable in init's environment. Any number of whitespace delimited key=value pairs can be exported via a single invocation.

BUILDER API

geninit features a small API intended for use by builders. These are base directory aware functions with error checking and are the recommended method of adding files to the cpio image from builders. Leading path components, if not already created, will be added implicitly. If, for some reason, you need to override the base directory and specify a truly absolute path, you can prefix a source argument with a '@'.

add_binary source [path]

Add a binary file, specified by the absolute path to its source. Unless specified, the path on the image will be the same as the source. Files will be scanned for library dependencies which will also be added to the image.

add_dir path [mode]

Add a directory, specified by its absolute path on the image. Unless specified, the permissions of the directory will be 755.

add_checked_modules class...

Add one or more classifications of modules to the image, specified as a directory relative to /lib/modules/KERNELVERSION/kernel, e.g. 'drivers/scsi' or 'crypto'. Modules can be filtered by name by adding glob (including extended glob) patterns to the MODFILTER array prior to calling add_checked_modules. This filter is cleared after the parsing of each hook, although you are free to call unset from within the builder, if desired.

Additionally, if the autodetect builder is used as part of image generation, only the intersection of the autodetect module list and the results of the add_checked_modules call will be added to the resulting image.

all_all_modules class...

Similar to add_checked_modules, excepting that no comparison against the autodetected module list is performed.

add_file source [path]

Add a plain file, specified by the absolute path to its source. Unless specified, the path on the image will be the same as the source. No type checking of the file is done.

add_module module_name

Add a kernel module to the image, specified by its name (with or without extension). Modules will be scanned for dependencies and firmware which will also be added to the image.

add_path_to_file file

Add all leading path components to a file to the image.

add_pipe path [mode]

Add a FIFO device to the image, specified by its absolute path. Unless specified, the permissions of the FIFO will be 644.

add_symlink target link

Add a symlink to the image, located at the absolute path specified by link, and pointing to the path specified by target.

use_hookscript

Indicate that a script should be added to be run during bootstrap. geninit will look to add a script by the same name as the builder.

FILES AND DIRECTORIES

/etc/geninit.conf

Default config file

/etc/geninit.d

Location of geninit preset files

/usr/share/geninit/geninit.api

Builder API file

/usr/share/geninit/builders

Location of builders

/usr/share/geninit/hooks

Location of hookscripts

AUTHOR

Dave Reisner <d@falconindy.com>