mksinitramfs - create an initramfs archive
mksinitramfs [-c <directory>] [-f] [-i <directory>] [-k] [-o <file>] [-p <profile>] [-v]
mksinitramfs [-x <file>]
mksinitramfs is a tool to build an initramfs archive. The contents of the initramfs are controlled by configuration scripts, you need to create these scripts as described in the CONFIGURATION section below.
mksinitramfs will NOT scan your system for required programs, modules etc. that are required to boot, you need to know the requirements and write your configuration scripts to reflect these. The name initramfs-simple just means that the mksinitramfs script does not do a lot of work, not that it is easy to create a working initramfs with it.
If you are looking for a simpler way, try initramfs-tools or yaird, if one of these works for you, there is no need to use mksinitramfs.
initramfs-simple is not a replacement for yaird or initramfs-tools!
Furthermore, this manual assumes that you know what an initramfs archive is, what it is used for and how you can create it manually. As said before, mksinitramfs will not do much work for you, it basically glues the configuration scripts you wrote together and builds the archive based on the configuration. If you do not know what this is all about, you should read up on that topic before you continue.
-c <directory>
Set the configuration directory. This must be set to the top level configuration directory, not to the config.d or a profile directory, see section CONFIGURATION below for details on the directory structure. The default value is /usr/local/etc/initramfs-simple.
-f
Use this option if you do not want the predefined functions to be included in the initramfs. See the CONFIGURATION section below for details. Default is to include the functions.
-i <directory>
Set the initramfs-simple data directory. Default value is /usr/local/share/initramfs-simple.
-k
Use this if you do not want the temporary directory to be deleted after the initramfs archive has been created. Default is to delete the directory.
-o <file>
Set the file name of the initramfs archive that should be created. The file must not yet exist. Default value is initramfs to create an archive with that name in the current directory.
-p <profile>
Set the name of the configuration profile to use, see the CONFIGURATION section below for details. This is unset by default.
-x <file>
Use this option to extract the already existing initramfs archive <file> to the current directory. If this option is specified all other command line options will be silently ignored.
-v
Turn on verbose output. Default is not to print anything (with a few exceptions).
The way mksinitramfs does its work is pretty simple: the script looks in the in the configuration scripts directory (config.d by default, see below) for so called hook scripts and init scripts, and processes them in alphabetical order. These scripts actually put together the content of the initramfs archive. All content must be placed in a temporary directory created by mksinitramfs. After processing is completed, mksinitramfs does some final checks and creates the archive from everything in that directory.
Note: The mktemp(1) utility is used to create the temporary directory by running mktemp -t -d initramfs-simple.XXXX. See the appropriate documentation for details about the location.
mksinitramfs supports profiles to easily switch between different configurations. A profile may be selected with the -p <profile> command line option.
By default, no profile is used. In that case mksinitramfs will use the hook and init scripts in the config.d subdirectory of the configuration directory (see section OPTIONS for default value).
If you want to use profiles, create another directory in the configuration directory and name it <profile>.config.d, use the profile name together with the -p command line option to make mksinitramfs use the configuration scripts in that directory.
Note that you may also create symbolic links to other directories. For example, you may create a link called second.config.d that points to some other directory (which must not necessarily be placed in the configuration directory) and use that profile by running mksinitramfs -p second. In the hook scripts you may perform different actions based on the current profile's name (see HOOK SCRIPTS for details).
Hook scripts are bash(1) scripts used to copy files and create directories in the temporary directory that will be compressed to an initramfs archive at the end of the process.
In order to be included in the build process, hook scripts must have the extension .hook and the executable bit must be set. That way you can easily disable a certain script by unsetting the executable bit.
The scripts are sourced by the mksinitramfs script. In this script set -e is enabled, so make sure that no command will fail, even if this would not affect the build process.
You must make sure that your hook scripts copy all necessary files to the temporary directory, including every required executable, module, configuration file etc., mkinitramfs is not able to determine if your initramfs will work correctly!
You may use the following predefined functions in your hook scripts:
copyExec
Copies a binary executable file and all required libraries to run it to the temporary directory. The first argument must be the full path to the executable that should be copied. The second argument must be the full path of the destination file (including the file name!) relative to the temporary directory. The second argument is optional, if it is not set, the destination path will be the same as the source path. All required parent directories will be created if necessary.
Examples: Use copyExec /bin/bash to copy /bin/bash to <tempdir>/bin/bash, so you will have a /bin/bash binary available in your initramfs environment. If you want /bin/bash to be available in your initramfs, but under the name /usr/bin/shell, use copyExec /bin/bash /usr/bin/shell.
If an error occurs, this function will exit with exit code 2. Note that an already existing destination file will be an error, unless you set the variable $EXISTINGOK to 1 before calling this function.
You should always use copyExec to copy binary executable files to the temporary directory, unless you don't want the required libraries to be included or you want to include them yourself!
error
Prints an error message to STDERR and exits. It is recommended that you use this function if something goes wrong in your hook scripts. If the first parameter is a numeric value, it will be used as exit code and the remaining arguments will be printed. Otherwise all arguments will be printed and the exit code will be 1. Note that no clean up is done, you will have to remove the temporary directory by yourself.
isDirectory
Returns true if the first argument is a directory or a symbolic link to a directory, false otherwise.
isNumeric
Returns true if the first argument is numeric, ie. consists only of digits 0-9. Returns false otherwise.
stripFile
This function will remove all "#" comments and empty lines from the files specified as arguments. You may use any number of arguments, but processing will stop at the first empty argument, so do not put one between regular file names. The file names must be specified relative to the temporary directory. The function only removes comments that start with a # character, leading whitespace characters are ignored. Do not use stripFile on files that use another comment syntax! Note that this may work for most files, but you may encounter problems, for example with multi-line strings, so make sure that the modified files still work as expected! After all comments and empty lines are removed a new line is appended to the modified files.
Warning: When in doubt, do not use this function!
verbose
All arguments are printed to STDOUT if the -v command line option was specified, otherwise this function does nothing. The return value is always 0.
The following shell variables will be available, some of them only if the appropriate command line option was used. You must not change them, except it is mentioned to be safe.
$CONF
Contains the full path to the current hook script.
$CONFDIR
The top level configuration directory. See the -c command line option for details.
$CONFIGD
The path to the config.d directory, this is either $CONFDIR/config.d if no profile is used, or $CONFDIR/$PROFILE.config.d if a profile is used.
$DESTDIR
The full path to the temporary directory, in other words the root directory of your initramfs.
$EXISTINGOK
Set this variable to 1 if you want copyExec to ignore already existing files. If $EXISTINGOK is set to any other value, or not set at all (default), copyExec will cause an error if a target file exists and mksinitramfs will quit.
$KEEPTMP
If this is set to y mksinitramfs will not delete the temporary directory. All other values will result in the directory to be removed after the archive has been built, the initial value is n unless the -k command line option was used. You may change $KEEPTMP if you wish to do so.
$NOFUNCS
If set to n (default), two files containing probably useful shell functions are included in the initramfs. This can be changed by the -f command line option, in that case the value of $NOFUNCS will be y. Changing this will not have any effect since the two files will be copied before the hook scripts are processed. (You may delete the scripts, though.) See the INIT SCRIPTS section below for details.
$OUTFILE
Contains the name of the output file, ie. the actual initramfs archive that will be generated. May be set by the -o command line option, and you may change it in the hook scripts.
$PROFILE
The name of the current profile as specified using the -p command line option.
$VERBOSE
Set to y if the -v command line option was used, set to n otherwise. Change $VERBOSE to change the verbosity setting.
Some example hook scripts are available, location depends on your installation. Take a look at them to get an idea about their usage.
You already know how an initramfs works, if not, make yourself familiar with this before reading on. The kernel, when booting with an initramfs, tries to execute a command named /init in the initramfs environment after extracting the archive's content to RAM. This command may be a binary executable file, but usually it is just a more or less simple shell script that performs all necessary actions to make the root filesystem available, mounts it and switches the root to it.
mksinitramfs will use the init scripts in the configuration scripts directory (ie. the same folder your hook scripts are placed in) to create this /init script in the temporary directory.
In order to be processed by mksinitramfs your init scripts must have the extension .init and they must be executable. You can easily disable certain scripts by unsetting their executable bit.
The actual processing is simple: mksinitramfs does nothing more than appending all init scripts in alphabetical order to the /init script. The executable bit for /init is set automatically.
Your scripts may source the file /usr/share/initramfs-simple/functions/init-functions to use some functions and variables defined in this file. This file, and another one sourced by it, will be included in the initramfs automatically, you may disable this with the -f command line option. If your /init script sources the init-functions file the following functions will be available:
dbg
Prints a message depending on the current debug level. The current debug level must be set in the $DBGLVL variable before calling this function, the default value is 0. You may, for example, change it by kernel command line parameters at boot time. The first parameter may be the debug level of the message, the message will be printed if it is less or equal the value of $DBGLVL. All remaining arguments are the actual message to be printed. If the first argument is not a numeric value, all arguments will be printed regardless of the debug level. This function always returns 0.
error
Use this function whenever an error occurs that will prevent your init script from working correctly! It will check the $SHONERR variable, if this is set to 0, the system will be shut down, otherwise a shell will be opened and you may try to solve the problem manually and then continue the boot process. Make sure you include a /bin/sh and a /bin/halt executable in your initramfs. If the first argument is a numeric value it overrides the value of $SHONERR. The remaining arguments will be printed before the shell is executed. If the first argument is not a numeric value all arguments will be printed before the shell is executed. In case the system is shut down only a hard coded message will be printed. Note: the device file /dev/console must be available when this function is called and a shell should be opened! This function always returns 0.
isDirectory, isNumeric
These are the same functions as described in the HOOK SCRIPTS section, see above for details.
Additionally, when init-scripts is sourced, the following variables may be used:
$CRED, $CGRN, $CRST
The are set to escape sequences to change the text color to red or green, or reset the text color. You may use them to easily print colored messages, eg. echo "${CGRN}success${CRST}" would print a green success message, and reset the text color to the default.
$DBGLVL
The current debug level, default value is 0. Used by the dbg function to determine if a message should be printed or not. The higher the value is the more output may be printed. See function dbg for details.
$SHONERR
If this is set to 0 (default), then the system will be shut down if the error function is called, any other value will result in a shell being opened to allow the user to fix the error manually. See the error function for details.
Some example init scripts are available, location depends on your installation. Take a look at them to get an idea about their usage.
None known. If you encounter a bug please report it to the author.
Stefan Göbel - mail@ntworks.net
Copyright © 2008 Stefan Göbel
mksinitramfs is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
mksinitramfs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with initramfs-simple. If not, see <http://www.gnu.org/licenses/>.