man lb config (1): Create config directory

SYNOPSIS

lb config [live-build options]

DESCRIPTION

lb config is a high-level command (porcelain) of live-build(7), the Debian Live tool suite.

lb config populates the configuration directory for live-build. By default, this directory is named 'config' and is created in the current directory where lb config was executed.

Note: Currently lb config tries to be smart and sets defaults for some options depending on the setting of other options (e.g. which linux packages to be used depending on if a lenny system gets build or not). This means that when generating a new configuration, you should call lb config only once with all options specified. Calling it several times with only a subset of the options each can result in non working configurations. This is also caused by the fact that lb config called with one option only changes that option, and leaves everything else as is unless its not defined. However, lb config does warn about know impossible or likely impossible combinations that would lead to non working live systems. If unsure, remove config/{binary,bootstrap,chroot,common,source} and call lb config again.

OPTIONS

In addition to its specific options lb config understands all generic live-build options. See live-build(7) for a complete list of all generic live-build options.

--apt apt|aptitude: defines if apt-get or aptitude is used to install packages when building the image. The default is apt.
--apt-ftp-proxy URL: sets the ftp proxy to be used by apt. By default, this is empty but if the host has the environment variable ftp_proxy set, apt-ftp-proxy gets automatically set to the value of ftp_proxy.
--apt-http-proxy URL: sets the http proxy to be used by apt. By default, this is empty but if the host has the environment variable http_proxy set, apt-http-proxy gets automatically set to the value of http_proxy.
--apt-pdiffs true|false: defines whether apt should use incremental package indices feature or not. This is true by default.
--apt-options OPTION|"OPTIONS": defines the default options that will be appended to every apt call that is made inside chroot during the building of the image. By default, this is set to --yes to allow non-interactive installation of packages.
--aptitude-options OPTION|"OPTIONS": defines the default options that will be appended to every aptitude call that is made inside chroot during building of the image. By default, this is set to --assume-yes to allow non-interactive installation of packages.
--apt-pipeline DEPTH: sets the depth of the apt/aptitude pipeline. In cases where the remote server is not RFC conforming or buggy (such as Squid 2.0.2) this option can be a value from 0 to 5 indicating how many outstanding requests APT should send. A value of zero MUST be specified if the remote host does not properly linger on TCP connections - otherwise data corruption will occur. Hosts which require this are in violation of RFC 2068. By default, live-build does not set this option.
--apt-recommends true|false: defines if apt should install recommended packages automatically. By default, this is true except in emdebian mode.
--apt-secure true|false: defines if apt should check repository signatures. This is true by default.
-a|--architecture ARCHITECTURE: defines the architecture of the to be build image. By default, this is set to the host architecture. Note that you cannot cross build for another architecture if your host system is not able to execute binaries for the target architecture natively. For example, building amd64 images on i386 and vice versa is possible if you have a 64bit capable i386 processor and the right kernel. But building powerpc images on an i386 system is not possible.
-b|--binary-images iso|iso-hybrid|net|tar|usb-hdd: defines the image type to build. By default, for images using syslinux this is set to iso-hybrid to build CD/DVD images that may also be used like usb-hdd images, for legacy lenny and non-syslinux images, it defaults to iso.
--binary-filesystem fat16|fat32|ext2: defines the filesystem to be used in the image type. This only has an effect if the selected binary image type does allow to choose a filesystem. For example, when selection iso the resulting CD/DVD has always the filesystem ISO9660. When building usb-hdd images for usb sticks, this is active. Note that it defaults to fat16 on all architectures except sparc where it defaults to ext2. Also note that if you choose fat16 and your resulting binary image gets bigger than 2GB, the binary filesystem automatically gets switched to fat32.
--binary-indices true|false|none: defines if the resulting images should have binary indices or not and defaults to true. If set to none, no indices are included at all.
--bootappend-install PARAMETER|"PARAMETERS": sets boot parameters specific to debian-installer, if included.
--bootappend-live PARAMETER|"PARAMETERS": sets boot parameters specific to debian-live. A complete list of boot parameters can be found, for etch, in the manpage of casper, for all other distributions in the manpage of live-initramfs. On the images, a list of all parameters (without comments) is included in the /parameters.txt.
--bootloader grub|syslinux|yaboot: defines which bootloader is being used in the generated image. This has only an effect if the selected binary image type does allow to choose the bootloader. For example, if you build a iso, always syslinux (or more precise, isolinux) is being used. Also note that some combinations of binary images types and bootloaders may be possible but live-build does not support them yet. lb config will fail to create such a not yet supported configuration and give a explanation about it. For usb-hdd images on amd64 and i386, the default is syslinux. yaboot is only used on powerpc.
--bootstrap cdebootstrap|cdebootstrap-static|debootstrap|copy: defines which program is used to bootstrap the Debian chroot, default is debootstrap. Note that if you set the bootstrap program to copy, then your host system is copied. This can be useful if you want to convert/clone your existing host system into a live system, however, make sure you do have enough free space as this can, depending on your host system, get quite big.
--bootstrap-config FILE: sets a custom configuration file for the boostrap programm of choice and is empty by default. Refer to the documentation of debootstrap or cdebootstrap for more information about that. When the bootstrap program is set to copy, this has no effect.
-f|--bootstrap-flavour minimal|standard: defines if the bootstrap program should bootstrap the standard system (all packages of priority required and important, which is the default) or a minimal system (only packages of priority required, plus apt).
--bootstrap-keyring PACKAGE: sets the archive keyring package to be used. Default is debian-archive-keyring.
--cache true|false: defines globally if any cache should be used at all. Different caches can be controlled through the their own options.
--cache-indices true|false: defines if downloaded package indices and lists should be cached which is false by default. Enabling it would allow to rebuild an image completely offline, however, you would not get updates anymore then.
--cache-packages true|false: defines if downloaded packages files should be cached which is true by default. Disabling it does save space consumption in your build directory, but remember that you will cause much unnecessary traffic if you do a couple of rebuilds. In general you should always leave it true, however, in some particular rare build setups, it can be faster to refetch packages from the local network mirror rather than to utilize the local disk.
--cache-stages true|false|STAGE|"STAGES": sets which stages should be cached. By default set to bootstrap. As an exception to the normal stage names, also rootfs can be used here which does only cache the generated root filesystem in filesystem.{dir,ext*,squashfs}. This is useful during development if you want to rebuild the binary stage but not regenerate the root filesystem all the time.
--checksums md5|sha1|sha256|none: defines if the binary image should contain a file called md5sums.txt, sha1sums.txt and/or sha256sums.txt. These lists all files on the image together with their checksums. This in turn can be used by live-initramfs' built-in integrity-check to verify the medium if specified at boot prompt. In general, this should not be false and is an important feature of live system released to the public. However, during development of very big images it can save some time by not calculating the checksums.
--build-with-chroot true|false: defines whatever live-build should use the tools from within the chroot to build the binary image or not by using and including the host systems tools. This is a very dangerous option, using the tools of the host system can lead to tainted and even non-bootable images if the host systems version of the required tools (mainly these are the bootloaders such as syslinux, grub and yaboot, and the auxiliary tools such as dosfstools, genisoimage, squashfs-tools and others) do not exactly match what is present at build-time in the target distribution. Never do disable this option unless you are exactly sure what you are doing and have completely understood its consequences.
--chroot-filesystem ext2|ext3|squashfs|plain|jffs2: defines which filesystem type should be used for the root filesystem image. If you use plain, then no filesystem image is created and the root filesystem content is copied on the binary image filesystem as flat files. Depending on what binary filesystem you have chosen, it may not be possible to build with a plain root filesystem, e.g. fat16/fat32 and plain don't work as Linux does not support to run on them.
--clean: minimizes config directory by automatically removing unused and thus empty subdirectories.
-c|--conffile FILE: using a user specified alternative configuration file in addition to the normally used one in the config directory.
--debconf-frontend dialog|editor|noninteractive|readline: defines what value the debconf frontend should be set to inside the chroot. Note that setting it to anything by noninteractive, which is the default, makes your build asking questions during the build.
--debconf-nowarnings true|false: defines if warnings of debconf should be displayed or not. Warnings from debconf are generally very rare and by default, we skipp them, if any, in order to keep the build process entirely non interactive.
--debconf-priority low|medium|high|critical: defines what value the debconf priority should be set to inside the chroot. By default, it is set to critical, which means that almost no questions are displayed. Note that this only has an effect if you use any debconf frontend different from noninteractive.
--debian-installer true|cdrom|netinst|netboot|businesscard|live|false: defines which type, if any, of the debian-installer should be included in the resulting binary image. By default, no installer is included. All available flavours except live are the identical configurations used on the installer media produced by regular debian-cd. When live is chosen, the live-installer udeb is included so that debian-installer will behave different than usual - instead of installing the Debian system from packages from the medium or the network, it installs the live system to the disk.
--debian-installer-distribution daily|CODENAME: defines the distribution where the debian-installer files should be taken out from. Normally, this should be set to the same distribution as the live system. However, some times, one wants to use a newer or even daily built installer.
--debian-installer-preseedfile FILE|URL: sets the filename or URL for an optionally used and included preseeding file for debian-installer.
--debian-installer-gui true|false: defines if the debian-installer graphical GTK interface should be true or not. In Debian mode and for most versions of Ubuntu, this option is true, whereas otherwise false, by default.
--debug: turn on debugging informational messages.
-d|--distribution CODENAME: defines the distribution of the resulting live system and must be a valid, supported, lowercase codename for the chosen mode (e.g. in Debian mode, squeeze for the Squeeze distribution, etc.)
--dump: prepares a report of the currently present live system configuration and the version of live-build used. This is useful to provide if you submit bug reports, we do get all informations required for us to locate and replicate an error.
-e|--encryption false|aes128|aes192|aes256: defines if the root filesystem should be encrypted or not. By default, this is false.
--fdisk fdisk|fdisk.dist: sets the filename of the fdisk binary from the host system that should be used. This is autodetected and does generally not need any customization.
--force: forces re-execution of already run stages. Use only if you know what you are doing. It is generally safer to use lb clean to clean up before re-executing lb build.
--grub-splash FILE: defines the name of an optional to be included splash screen graphic for the grub bootloader.
--gzip-options OPTION|"OPTIONS": defines the default options that will be appended to (almost) every gzip call during the building of the image. By default, this is set to --best to use highest (but slowest) compression. Dynamically, if the host system supports it, also --rsyncable is added.
--hooks FILE: defines which hooks available in /usr/share/live/build/examples/hooks should be activated. Normally, there are no hooks executed. Make sure you know and understood the hook before you enable it.
--hostname NAME: sets the hostname of the live system.
--ignore-system-defaults: lb config by default reads system defaults from /etc/live/build.conf and /etc/live/build.d when generating a new live system config directory. This is useful if you want to set global settings, such as mirror locations, and don't want to specify them all of the time.
--includes PATH|none: sets the path to the includes that live-build is going to use, e.g. additional minimal documentation that you want to have on all live systems. By default, this is set to /usr/share/live/build/includes/. Choose none to disable inclusion of documentation.
--initramfs auto|none|live-boot|live-initramfs|casper: sets the name of package that contains the live system specific initramfs modification. By default, auto is used, which means that at build time of the image rather than on configuration time, the value will be expanded to casper when building Ubuntu systems, to live-initramfs for legacy Lenny, and to live-boot for Squeeze and newer. Using 'none' is useful if the resulting system image should not be a live image (experimental).
--interactive shell: defines if after the chroot stage and before the beginning of the binary stage, a interactive shell login should be spawned in the chroot in order to allow you to do manual customizations. Once you close the shell with logout or exit, the build will continue as usual. Note that it's strongly discouraged to use this for anything other than testing. Modifications that should be present in all builds of a live system should be properly made through hooks. Everything else destroys the beauty of being able to completely automate the build process and making it non-interactive. By default, this is of course false.
--isohybrid-options OPTION|"OPTIONS": defines options to pass to isohybrid.
--iso-application NAME: sets the APPLICATION field in the header of a resulting CD/DVD image and defaults to "Debian Live" in debian mode, and to "Emdebian Live" in emdebian mode, and "Ubuntu Live" in ubuntu mode.
--iso-preparer NAME: sets the PREPARER field in the header of a resulting CD/DVD image. By default this is set to "live-build VERSION; http://packages.qa.debian.org/live-build", whereas VERSION is expanded to the version of live-build that was used to build the image.
--iso-publisher NAME: sets the PUBLISHED field in the header of a resulting CD/DVD image. By default, this is set to 'Debian Live project; http:/live.debian.net/; [email protected]'. Remember to change this to the appropriate values at latest when you distributing custom and unofficial images.
--iso-volume NAME: sets the VOLUME field in the header of a resulting CD/DVD and defaults to '(MODE) (DISTRIBUTION) (DATE)' whereas MODE is expanded to the name of the mode in use, DISTRIBUTION the distribution name, and DATE with the current date and time of the generation. When running in debian-release mode however, it will instead default to 'Debian (VERSION) (ARCHITECTURE) live' where VERSION becomes the numerical version of the release being built and ARCHITECTURE becomes the name of the architecture.
--jffs2-eraseblock SIZE: sets the eraseblock size for a JFFS2 (Second Journalling Flash File System) filesystem. The default is 64 KiB. If you use an erase block size different than the erase block size of the target MTD device, JFFS2 may not perform optimally. If the SIZE specified is below 4096, the units are assumed to be KiB.
--keyring-packages PACKAGE|"PACKAGES": sets the keyring package or additional keyring packages. By default this is set to debian-archive-keyring.
-l|--language LANGUAGE: experimental option to set the language of a live system by installing l10n related packages. If syslinux is used, this also selects the corresponding syslinux template files if they exist. It doesn't enable generation of the correct locales through setting the right boot parameters; those need to be done through the bootappend-live parameter.
-k|--linux-flavours FLAVOUR|"FLAVOURS": sets the kernel flavours to be installed. Note that in case you specify more than that the first will be configured the default kernel that gets booted.
--linux-packages "PACKAGES": sets the internal name of the kernel packages naming scheme. If you use Debian kernel packages, you will not have to adjust it. If you decide to use custom kernel packages that do not follow the Debian naming scheme, remember to set this option to the stub of the packages only (for Debian this is linux-image-2.6), so that STUB-FLAVOUR results in a valid package name (for Debian e.g. linux-image-2.6-486). Preferably you use the meta package name, if any, for the stub, so that your configuration is ABI independent. Also don't forget that you have to include stubs of the binary modules packages for legacy Lenny builds for unionfs or aufs, and squashfs if you built them out-of-tree.
--losetup losetup|losetup.orig: sets the filename of the losetup binary from the host system that should be used. This is autodetected and does generally not need any customization.
--memtest memtest86+|memtest86|none: defines if memtest, memtest86+ or no memory tester at all should be included as secondary bootloader configuration. This is only available on amd64 and i386 and defaults to memtest86+.
-m|--mirror-bootstrap URL: sets the location of the Debian package mirror that should be used to bootstrap from. This defaults to http://ftp.de.debian.org/debian/ which may not be a good default if you live outside of Europe.
--mirror-chroot URL: sets the location of the Debian package mirror that will be used to fetch the packages in order to build the live system. By default, this is set to the value of --mirror-bootstrap.
--mirror-chroot-security URL: sets the location of the Debian security package mirror that will be used to fetch the packages in order to build the live system. By default, this points to http://security.debian.org/debian/.
--mirror-chroot-volatile URL: sets the location of the Debian volatile package mirror that will be used to fetch packages in order to build the live system. By default, this is set to the value of --mirror-chroot.
--mirror-chroot-backports URL: sets the location of the Debian backports package mirror that will be used to fetch packages in order to build the live system. By default, this points to http://backports.debian.org/debian-backports/.
--mirror-binary URL: sets the location of the Debian package mirror that should end up configured in the final image and which is the one a user would see and use. This has not necessarily to be the same that is used to build the image, e.g. if you use a local mirror but want to have an official mirror in the image. By default, 'http://cdn.debian.net/debian/' is used.
--mirror-binary-security URL: sets the location of the Debian security package mirror that should end up configured in the final image. By default, 'http://cdn.debian.net/debian-security/' is used.
--mirror-binary-volatile URL: sets the location of the Debian volatile package mirror that should end up configured in the final image. By default, the value of --mirror-binary is used.
--mirror-binary-backports URL: sets the location of the Debian backports package mirror that should end up configured in the final image. By default, 'http://backports.debian.org/debian-backports/' is used.
--mirror-debian-installer URL: sets the location of the mirror that will be used to fetch the Debian installer images. By default, this points to the same mirror used to build the live system, i.e. the value of --mirror-bootstrap.
--mode debian|emdebian|ubuntu: defines a global mode to load project specific defaults. By default this is set to debian.
--net-root-filesystem nfs|cfs: defines the filesystem that will be configured in the bootloader configuration for your netboot image. This defaults to nfs.
--net-root-mountoptions OPTIONS: sets additional options for mounting the root filesystem in netboot images and is by default empty.
--net-root-path PATH: sets the file path that will be configured in the bootloader configuration for your netboot image. This defaults to /srv/debian-live in debian mode and to /srv/emebian-live when being in emdebian mode, and /srv/ubuntu-live when in ubuntu mode.
--net-root-server IP|HOSTNAME: sets the IP or hostname that will be configured in the bootloader configuration for the root filesystem of your netboot image. This defaults to 192.168.1.1.
--net-cow-filesystem nfs|cfs: defines the filesystem type for the copy-on-write layer and defaults to nfs.
--net-cow-mountoptions OPTIONS: sets additional options for mounting the copy-on-write layer in netboot images and is by default empty.
--net-cow-path PATH: defines the path to client writable filesystem. Anywhere that client_mac_address is specified in the path live-initramfs will substitute the MAC address of the client delimited with hyphens.

: Example:
/export/hosts/client_mac_address
/export/hosts/00-16-D3-33-92-E8
--net-cow-server IP|HOSTNAME: sets the IP or hostname that will be configured in the bootloader configuration for the copy-on-write filesystem of your netboot image and is by default empty.
--net-tarball bzip2|gzip|tar|none: defines the format of the netboot image. Choosing tar results in a not compressed tarball, bzip2 and gzip in a bzip2 resp. gzip compressed tarball. Choosing none leads to no tarball at all, the plain binary directory is considered the output in this case. Default is gzip.
-p|--packages-lists LIST|"LISTS": defines which lists available in /usr/share/live/build/lists should be used. By default, this is set to standard. Note that in case you have local packages lists, you don't need to list them here. Putting them into config/chroot_local-packageslists is enough (the filename needs to have the .list suffix though).
--packages PACKAGE|"PACKAGES": defines one or more packages to be installed in the live system. This is a quick and convenient place to add a few packages when building an image (limited by the max length of shell). Packages that should be permanently installed should be put into a local packages list.
--quiet: reduces the verbosity of messages output by lb build.
-r|--repositories REPOSITORY|"REPOSITORIES": enables one of available third-party repository configurations in /usr/share/live/build/repositories.
--root-command sudo: controls if live-build should use sudo internally to build the live image. Note that this is not well tested and that you should, when relying on sudo, call the individual live-build command with sudo itself.
--use-fakeroot true|false: controls if live-build should utilize fakeroot and fakechroot to try and avoid requiring root privileges where possible. By default, this option is false.
--archive-areas ARCHIVE_AREA|"ARCHIVE_AREAS": defines which package archive areas of a Debian packages archive should be used for configured Debian package mirrors. By default, this is set to main. Remember to check the licenses of each packages with respect to their redistributability in your jurisdiction when enabling contrib or non-free with this mechanism.
--security true|false: defines if the security repositories specified in the security mirror options should be used or not.
--source true|false: defines if a corresponding source image to the binary image should be build. By default this is false because most people do not require this and would require to download quite a few source packages. However, once you start distributing your live image, you should make sure you build it with a source image alongside.
-s|--source-images iso|net|tar|usb-hdd: defines the image type for the source image. Default is tar.
--symlinks true|false: defines if the symlink hack should be true or false. The symlink hack converts all absolute symlinks to relative ones. By default this is false and in general there is no need or gain to enable it. If you are in a special situation that requires this, you will know.
--syslinux-splash FILE: defines the file of the syslinux splash graphic that should be used instead of the default one.
--syslinux-timeout SECONDS: defines the timeout the syslinux bootloader should wait for input from the user at the bootprompt prior booting the default kernel. This defaults to 0 which means it will wait forever.
--syslinux-menu true|false: defines if syslinux should be make use of the vgamenu capabilities or not.
--sysvinit true|false: defines if the sysvinit hack should be true or false. The sysvinit hack disables all non-essential services from starting up at bootup in order to reduce overall boottime. By default this is false and in general there you don't want to enable it.
--tasksel aptitude|tasksel: selects which program is used to install tasks. By default, this is set to tasksel.
--tasks TASK|"TASKS": defines one or more package tasks to be installed in the live system. This is a quick and convenient way to get a reasonable default selection of packages suitable for most users when building an image, but it results in quite big images. If you want to have finer grained package selections, local packages lists should be used instead.
--templates PATH: sets the path to the templates that live-build is going to use, e.g. for bootloaders. By default, this is set to /usr/share/live/build/templates/.
--virtual-root-size MB: defines what size the virtual-hdd image should be. Note that although the default is set to 10000 (= 10GB), it will not need 10GB space on your hard disk as the files are created as sparse files.
--volatile true|false: defines if Debian volatile package archives should be included in the image or not.
--backports true|false: defines if Debian backports package archives should be included in the image or not.
--exposed-root true|false: defines whether to expose the root filesystem as read only and not covered by the union filesystem. This has useful implications for certain speciality setups such as LTSP. By default, this option is false.
--username NAME: sets the name of the account of the default user in the live system.
--verbose: increases the verbosity of messages output by lb build.
--win32-loader true|false: defines if win32-loader should be included in the binary image or not.

ENVIRONMENT

Currently, command line switches can also be specified through the corresponding environment variable. However, this generally should not be relied upon, as it is an implementation detail that is subject to change in future releases. For options applying directly to live-build, environment variables are named LB_FOO, meaning, e.g. --apt-ftp-proxy becomes LB_APT_FTP_PROXY (the exception being internal options such as --debug). For options passed to another program, as in APT_OPTIONS or GZIP_OPTIONS, no LB_ prefix is used.

FILES

auto/config
/etc/live/build.conf, /etc/live/build.d: An optional, global configuration file for lb config variables. It is useful to specify a few system wide defaults, like LB_MIRROR_BOOTSTRAP. This feature can be false by specifying the --ignore-system-defaults option.

HOMEPAGE

More information about live-build and the Debian Live project can be found on the homepage at <http://live.debian.net/> and in the manual at <http://live.debian.net/manual/>.

BUGS

Bugs can be reported by submitting a bug report for the live-build package in the Debian Bug Tracking System at <http://bugs.debian.org/> or by writing a mail to the Debian Live mailing list at <[email protected]>.

AUTHOR

live-build was written by Daniel Baumann <[email protected]> for the Debian project.