.TH DEBIRF "1" "Dec 2011" "debirf 0.32" "User Commands" .SH NAME debirf \- build an initrd to boot a full Debian system entirely from RAM .SH SYNOPSIS .B debirf [options] [args] .SH DESCRIPTION .PP \fBdebirf\fP (DEBian on Initial Ram Filesystem) is a set of tools designed to create and prepare a kernel and initial ram filesystem that can run a full-blown Debian environment entirely from RAM. .PP \fBdebirf\fP has various subcommands (see \fBSUBCOMMANDS\fP) which act on a specified debirf profile (see \fBPROFILES\fP). .PP The debirf system is outlined at: .PP http://cmrg.fifthhorseman.net/wiki/debirf .PD .SH EXAMPLES .PP Make a stock debirf rescue image using the default settings: .nf $ tar xzf /usr/share/doc/debirf/example-profiles/rescue.tgz $ debirf make rescue .fi .PP Make a debirf rescue image, specifying the mirror and a local HTTP proxy: .nf $ tar xzf /usr/share/doc/debirf/example-profiles/rescue.tgz $ DEBIRF_MIRROR=http://ftp.debian.org/debian http_proxy=http://127.0.0.1:3128/ debirf make rescue .fi .SH SUBCOMMANDS \fBdebirf\fP takes various subcommands: .PD .TP .B make [options] PROFILE Create a debirf system based on profile PROFILE. This will create the root for the profile, run all modules on the root, and then generate the kernel image (see \fBKERNEL\fP) and debirf initramfs. This subcommand takes various options (see \fBOPTIONS\fP). .TP .B enter PROFILE Chroot into root of profile PROFILE, with full profile environment. .TP .B makeiso PROFILE Create a bootable CD-ROM image from the kernel and initramfs in PROFILE. This requires a bootloader to be available. If grub-mkrescue (in the grub-common package on debian) is available, it will be used. Otherwise, isolinux is used if it is available. You may use the \fBDEBIRF_ISO_BOOTLOADER\fP environment variable to specify a preference manually (see below). .TP .B help Output a brief usage summary. .PD .SH OPTIONS (for make subcommand only) .PP .TP \fB\-c\fR, \fB\-\-check-vars\fR check variables before make .TP \fB\-n\fR, \fB\-\-new\fR create new root, even if old one exists .TP \fB\-o\fR, \fB\-\-overwrite\fR debootstrap on top of old root if it exists .TP \fB\-s\fR, \fB\-\-skip\fR skip debootstrap step altogether if old root exists .TP \fB\-r\fR, \fB\-\-root-build\fR use real chroot to build instead of fakechroot (requires superuser privileges or CAP_SYS_CHROOT) .TP \fB\-w\fR, \fB\-\-no-warning\fR skip superuser warning .TP \fB\-i\fR, \fB\-\-initrd-only\fR remake initramfs from existing root (skip debootstrap and module stages) .TP \fB\-k\fR, \fB\-\-kernel-deb=KERNEL\fR install KERNEL .deb, instead of default kernel .PD .SH PROFILES .PP A debirf profile is a directory containing a debirf.conf config file and a modules sub-directory (see \fBMODULES\fP). .PD .SH PACKAGE INCLUDES/EXCLUDES .PP If the profile directory includes a 'packages' file, it is interpreted as a list of packages to include/exclude during the debootstrap stage. Packages should be specified one per line, with a '+' prefix to indicate inclusion during debootstrap, or a '-' prefix to indicate exclusion. .PD .SH MODULES .PP \fBModules\fP are used to configure the debirf system, and can be used to extend the capabilities of debirf. Modules are bash shell scripts that are executed in alpha-numeric order by \fBrun-parts\fP in a chroot in the debirf root during the module stage of the debirf build. The module stage is right after the debirf debootstrap stage, and right before the initramfs archive is created. All shell variables beginning with "DEBIRF_", including those defined in the \fIdebirf.conf\fP file, are available to the modules. .PP Modules may specify packages to be included/excluded during the debootstrap stage with special '#DEBIRF_PACKAGE>' comments anywhere in the module. Lines beginning with '#DEBIRF_PACKAGE>+' specify packages to include, and lines beginning with '#DEBIRF_PACKAGE>-' indicate packages to exclude. Only one package should be specified per comment line (no spaces). So for instance, the lines: .nf #DEBIRF_PACKAGE>+emacs #DEBIRF_PACKAGE>+ed #DEBIRF_PACKAGE>-nano .fi would include the packages .B emacs and .BR ed , and would exclude the package .BR nano . .PP \fBNOTE:\fP Some modules are more important to the proper functioning of debirf than others, and the ordering of modules is important. Some modules may depend on certain other modules having already been, or not yet been, run. For instance, the module that cleans the debirf apt cache ("z1_clean_root") should be the last module run at the end of the module stage. .PD .SH KERNEL .PP The \fBdebirf\fP "install-kernel" module will try to pick the most up-to-date kernel for the suite you are installing (versions 2.6 only), with the arch determined by the kernel running on the host build system. .PP .SH FUNCTIONS .PP A set of pre-defined bash shell functions are available to the modules to fasciliate configuring the debirf system: .PD 1 .TP .B debirf_exec Execute within debirf root (\fBDEBIRF_ROOT\fP) with chroot. .TP .B msg Output a message to standard out during the build process. .TP .B failure Cause debirf script to fail with , and to stderr. .TP .B debirf_info_sh Write one line of sh code to the \fIdebirf.info\fP file on the debirf root. .TP .B debirf_info_comment Write one line of comment to the \fIdebirf.info\fP file on the debirf root. .RE .PD .SH ENVIRONMENT .PP The following environment variables are used by debirf: .PD 1 .TP .B DEBIRF_LABEL debirf label (default: debirf) .TP .B DEBIRF_BUILDD where to build the debirf (default: ./) .TP .B DEBIRF_ARCH architecture to build (default is the architecture of the build machine) .TP .B DEBIRF_SUITE suite to build from (default determined from lsb_release, otherwise "sid") .TP .B DEBIRF_DISTRO distro for suite (default determined from lsb_release, otherwise "debian") .TP .B DEBIRF_MIRROR mirror to pull suite (default determined by DEBIRF_DISTRO) .TP .B DEBIRF_KEYRING keyring to verify debootstrap (default determined by DEBIRF_DISTRO) .TP .B DEBIRF_KERNEL_FLAVOR the flavor of kernel debirf should install. Supply everything from a typical debian package name after the version number. e.g. 486, vserver-686-bigmem, openvz-amd64. (default chosen based on currently-running kernel) .TP .B DEBIRF_ISO_BOOTLOADER whether to use "grub" or "isolinux" as the El Torito bootloader for \fBdebirf makeiso\fR. if not specified, "grub" is the default. .PD .SH FILES .PD 1 .TP $DEBIRF_PROFILE/debirf.conf Debirf profile configuration file. Contains values for the various debirf environment variables (see \fBENVIRONMENT\fP). Variables specified in the debirf.conf override those specified on the command line. .TP $DEBIRF_ROOT/etc/debirf/debirf.info File that stores various information about the debirf build. This is a bash-sourceable file. .PD .SH AUTHOR Written by Jameson Rollins and Daniel Kahn Gillmor. .SH "BUGS" Debirf does not work as a non-privileged user across different versions of libc. . In particular, this means that you probably won't be able to build an image from a different version of the operating system than you're using without building as root. (see http://bugs.debian.org/650242) .PP Please report bugs in debirf via the debian BTS: http://bugs.debian.org/ .SH COPYRIGHT Copyright \(co 2007-2011 Jameson Rollins and Daniel Kahn Gillmor .br This is free software. You may redistribute copies of it under the terms of the GNU General Public License . There is NO WARRANTY, to the extent permitted by law. .SH "SEE ALSO" .BR /usr/share/doc/debirf/README, .BR debootstrap (8), .BR fakechroot (1)