X-Git-Url: https://git.grml.org/?p=grml-live.git;a=blobdiff_plain;f=docs%2Fgrml-live.txt;h=966f8ace7d4e0e68f6c293da631b2593064dff5a;hp=3d94ea1a8d8529dafaca756721334e4f8caf146b;hb=b63a5f16ac3f03eb93220fd26ab188e50314f5d0;hpb=1360256a71a6b33ee342a70b06adac11b3903b0a diff --git a/docs/grml-live.txt b/docs/grml-live.txt index 3d94ea1..966f8ac 100644 --- a/docs/grml-live.txt +++ b/docs/grml-live.txt @@ -12,7 +12,8 @@ Synopsis grml-live [-a ] [-c ] [-C ] [-g ] [-i ] [-o ] [-r ] [-s -] [-t ] [-v ] [-bBFhquVz] +] [-t ] [-v ] [-U ] [ +-AbBFnNquVz] CAUTION: Please check out <> for details about current state of involved @@ -35,8 +36,9 @@ to include on your very own Linux Live-CD without having to deal with all the details of a build process. CAUTION: grml-live does **not** use /etc/fai for configuration but instead -provides and uses /etc/grml/fai. This ensures that it does not clash with -default FAI configuration and packages, so you can use grml-live and FAI +provides and uses ${GRML_FAI_CONFIG} which is pointing to /etc/grml/fai by default +(unless overriden using the ''-D'' option). This ensures that it does not clash +with default FAI configuration and packages, so you can use grml-live and FAI completely independent at the same time! [NOTE] @@ -53,6 +55,11 @@ for details). Options ------- + -A:: + +Clean up output directories before attempting the build. Packs the chroot +into a tar archive, and removes chroot and iso build directories before exiting. + -a **ARCHITECTURE**:: Use the specified architecture instead of the currently running one. This @@ -104,9 +111,9 @@ Please notice that all configuration files have to be adjusted during execution of grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for your own configuration file (usually /etc/grml/grml-live.local). Please also notice that the configuration file specified via this option is **not** (yet) -supported inside the scripts/hooks/classes at /etc/grml/fai/config. Instead use +supported inside the scripts/hooks/classes at ${GRML_FAI_CONFIG}/config. Instead use /etc/grml/grml-live.local for configuration stuff used inside -/etc/grml/fai/config. +${GRML_FAI_CONFIG}/config. -d **DATE**:: @@ -118,6 +125,16 @@ the bootsplash related files. This option is useful if you want to provide an ISO with release information for a specific date but have to build it in advance. Usage example: '-d 2009-10-30' + -D **CONFIGURATION_DIRECTORY**:: + +The specified directory is used as configuration directory for grml-live and its +FAI. By default /etc/grml/fai is used as default configuration directory. If +you want to have different configuration scripts, package definitions, etc. with +without messing with the global configuration under /etc/grml/fai provided by +grml-live this option provides you the option to use your own configuration +directory. This directory is what's being referred to as ${GRML_FAI_CONFIG} +throughout this documentation. + -F:: Force execution and do not prompt for acknowledgment of configuration. @@ -148,6 +165,18 @@ in the chroot so you have to create the rootfs structure on your own. Skip creation of the ISO file. This option is useful if you want to build/update the chroot and/or recreate the squashfs file without building an ISO file. + -N:: + +Bootstrap the chroot without building bootloader, squashfs, or finalizing the +ISO. Use this option if installation of some packages fails, you want to run +custom commands or similar. +The main use of this option is to save time by skipping stages which aren't +necessary for bootstrapping the chroot and which would get executed more than +once when iterating through the initial bootstrapping. +Alternatively, use this option as a test run of grml-live. Once you are +satisfied with the state of your grml_chroot, use grml-live **-u** to build the +remaining stages and finalize the ISO. + -o **OUTPUT_DIRECTORY**:: Main output directory of the build process of FAI. Some directories are created @@ -168,9 +197,9 @@ Specify name of the release. -s **SUITE**:: Specify the Debian suite you want to use for your live-system. Defaults to -"lenny" (being current Debian/stable). Supported values are: etch, lenny, sid. -Debian "squeeze" (current Debian/testing) requires base.tgz -(/etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz) or a recent version of +"squeeze" (being current Debian/stable). Supported values are: etch, lenny, +squeeze, sid. Debian "squeeze" requires a recent base.tgz +(${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of debootstrap. -t **TEMPLATE_DIRECTORY**:: @@ -183,6 +212,10 @@ Specify place of the templates used for building the ISO. By default Update existing chroot instead of rebuilding it from scratch. This option is based on the softupdate feature of FAI. + -U **USERNAME**:: + +Sets ownership of all build output files to specified username before exiting. + -v **VERSION_NUMBER**:: Specify version number of the release. @@ -193,7 +226,7 @@ Increase verbosity in the build process. -z:: -Use ZLIB instead of LZMA compression in mksquashfs part of the build process. +Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process. [[usage-examples]] Usage examples @@ -261,11 +294,11 @@ grml-live, as well as the architecture dependent class which provides the kernel GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are relevant for class GRMLBASE by default: - /etc/grml/fai/config/scripts/GRMLBASE/ - /etc/grml/fai/config/debconf/GRMLBASE - /etc/grml/fai/config/class/GRMLBASE.var - /etc/grml/fai/config/hooks/instsoft.GRMLBASE - /etc/grml/fai/config/package_config/GRMLBASE + ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/ + ${GRML_FAI_CONFIG}/config/debconf/GRMLBASE + ${GRML_FAI_CONFIG}/config/class/GRMLBASE.var + ${GRML_FAI_CONFIG}/config/hooks/instsoft.GRMLBASE + ${GRML_FAI_CONFIG}/config/package_config/GRMLBASE Take a look at the next section for information about the concept of those files/directories. @@ -286,8 +319,8 @@ Available classes ----------------- The package selection part of the classes can be found in -/etc/grml/fai/config/package_config whereas some further classes are defined for -example in /etc/grml/fai/config/scripts/ so specific feature sets can be +${GRML_FAI_CONFIG}/config/package_config whereas some further classes are defined for +example in ${GRML_FAI_CONFIG}/config/scripts/ so specific feature sets can be selected. The following classes are predefined: * DEBORPHAN: get rid of all packages listed in output of Deborphan @@ -335,7 +368,7 @@ Files Notice that grml-live ships FAI configuration files that do not use the same namespace as the FAI packages itself. This ensures that grml-live does not clash with your usual FAI configuration, so instead of /etc/fai/fai.conf (package -fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see +fai-client) grml uses ${GRML_FAI_CONFIG}/fai.conf instead. For more details see below. To get an idea how another configuration or example files could look like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html @@ -359,56 +392,56 @@ over the ones from /etc/grml/grml-live.conf. If you want to override settings from /etc/grml/grml-live.local as well you have to specify them on the grml-live commandline. - /etc/grml/fai/fai.conf + ${GRML_FAI_CONFIG}/fai.conf Main configuration file for FAI which specifies where all the configuration files and scripts for FAI/grml-live can be found. By default the configuration variables are FAI_CONFIG_SRC=file:///etc/grml/fai/config and -FAI_CONFIGDIR=/etc/grml/fai/config - both pointing to a directory shipped by +GRML_FAI_CONFIG=/etc/grml/fai/config - both pointing to a directory shipped by grml-live out-of-the-box so you shouldn't have to configure anything in this file. - /etc/grml/fai/make-fai-nfsroot.conf + ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf This file is used by make-fai-nfsroot(8) only. Usually you don't have to change anything inside this file. If you want to modify NFSROOT though you can adjust it there. - /etc/grml/fai/NFSROOT + ${GRML_FAI_CONFIG}/NFSROOT This file specifies the package list for creating the NFSROOT. - /etc/grml/fai/apt/sources.list + ${GRML_FAI_CONFIG}/apt/sources.list This file specifies which mirrors should be considered for retrieving the Debian packages when creating the main chroot (including all the software you would like to see included). Important: this file should *not* be adjusted manually! Instead use the GRML_LIVE_SOURCES variable inside /etc/grml/grml-live.conf or -/etc/grml/grml-live.local which modifies /etc/grml/fai/apt/sources.list +/etc/grml/grml-live.local which modifies ${GRML_FAI_CONFIG}/apt/sources.list on-the-fly via grml-live then. If you want to generally adjust apt configuration -use FAI's fcopy command with /etc/grml/fai/config/files instead. +use FAI's fcopy command with ${GRML_FAI_CONFIG}/config/files instead. - /etc/grml/fai/config/ + ${GRML_FAI_CONFIG}/config/ The main directory for configuration of FAI/grml-live. More details below. - /etc/grml/fai/config/class/ + ${GRML_FAI_CONFIG}/config/class/ This directory contains files which specify main configuration variables for the FAI classes. - /etc/grml/fai/config/debconf/ + ${GRML_FAI_CONFIG}/config/debconf/ This directory provides the files for preseeding/configuration of debconf through files. - /etc/grml/fai/config/hooks/ + ${GRML_FAI_CONFIG}/config/hooks/ This directory provides files for customising the build process through hooks. Hooks are user defined programs or scripts, which are called during the installation process. - /etc/grml/fai/config/package_config/ + ${GRML_FAI_CONFIG}/config/package_config/ Directory with lists of software packages to be installed or removed. The different classes describe what should find its way to your ISO. When running @@ -420,11 +453,11 @@ adjust the package selection according to your needs. Please notice that the directory GRMLBASE contains a package list defining a minimum but still reasonable package configuration. - /etc/grml/fai/config/scripts/ + ${GRML_FAI_CONFIG}/config/scripts/ Scripts for customising the ISO within the build process. - /etc/grml/fai/live-initramfs/ + ${GRML_FAI_CONFIG}/live-initramfs/ This directory provides the files used for building the initramfs/initrd via live-initramfs(8). @@ -441,7 +474,7 @@ The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the default being /var/log/fai/grml/. If you are using the grml-live buildd you will find the logs of the grml-live -run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr. +run at /var/log/grml-buildd.log. If you want to store build information in a database just install the grml-live-db Debian package. Further details available in the grml-live-db @@ -475,9 +508,9 @@ For further information see next section. Current state of grml-live with squashfs-tools and kernel --------------------------------------------------------- -Use squashfs-tools >=4.1-1 (available from Grml repositories as well as from -Debian/experimental) to build Grml (based) ISOs featuring kernel version -2.6.36-grml[64]. +Use squashfs-tools >=4.2-1 (available from Grml repositories as well as from +Debian/unstable) to build Grml (based) ISOs featuring kernel version +2.6.38-grml[64]. //////////////////////////////////////////////////////////////////////////////// Difference between squashfs-lzma-tools, squashfs-lzma-tools4 and squashfs-tools @@ -800,17 +833,17 @@ worked as expected the last line of the shell output should look like: and the ISO can be found inside /grml-live/grml-live/grml_isos/ then. -[[fai-on-etch]] -Help, I'm using Debian etch and I don't have FAI version >3.2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +[[grml_fai_config_variable]] +What is $GRML_FAI_CONFIG? +~~~~~~~~~~~~~~~~~~~~~~~~~ - wget http://fai-project.org/download/etch/fai-client_3.2.8_all.deb \ - http://fai-project.org/download/etch/fai-server_3.2.8_all.deb \ - http://fai-project.org/download/etch/fai-doc_3.2.8_all.deb - dpkg -i fai-client_3.2.8_all.deb fai-server_3.2.8_all.deb fai-doc_3.2.8_all.deb - -or check out the link:http://fai-project.org/[FAI-homepage] for -further details. +The variable '$GRML_FAI_CONFIG' is pointing to the directory /etc/grml/fai by +default. To provide you a maximum of flexibility you can set up your own +configuration directory (e.g. based on /etc/grml/fai) and use this directory +running grml-live with the '-D ' option. Now '$GRML_FAI_CONFIG' +points to the specified directory instead of using /etc/grml/fai and all the +configuration files, scripts and hooks will be taken from your +'$GRML_FAI_CONFIG' directory. [[how-to-debug]] I've problems with the build process. How to start debugging? @@ -868,7 +901,7 @@ to get the ratio between the different options): * 1 minute and 40 seconds with ZLIB [[install-local-files]] -How to I install further files into the chroot/ISO? +How do I install further files into the chroot/ISO? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Just point the configuration variable CHROOT_INSTALL to the directory which @@ -896,7 +929,7 @@ adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as well. Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from -/etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be +${GRML_FAI_CONFIG}/apt/sources.list and ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf will be taken. If you customise the variables in /etc/grml/grml-live.conf then the two files will be adjusted during runtime automatically. @@ -905,6 +938,9 @@ taken as first entry in the generated sources.list so it's preferred over non-local mirrors. Using a fallback mirror (via providing several mirrors in GRML_LIVE_SOURCES as used by default) is a recommended setting. +If you want to use a HTTP Proxy (like apt-cacher-ng), set APT_PROXY. Example: +APT_PROXY="http://localhost:3142/" + [[add-additional-debian-packages]] How do I add additional Debian package(s) to my CD/ISO? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -947,7 +983,7 @@ How do I create a base.tgz for use as NFSROOT? First of all build the chroot system: mkdir /tmp/nfsroot && cd /tmp/nfsroot - debootstrap lenny /tmp/nfsroot/ http://cdn.debian.net/debian + debootstrap squeeze /tmp/nfsroot/ http://cdn.debian.net/debian tar zcf base.tgz ./ Then check out where your NFSROOT is located: @@ -985,25 +1021,20 @@ or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for: Existing base.tgz can be found at http://daily.grml.org/ [[apt-cacher]] -Set up apt-cacher / apt-cacher-ng for use with grml-live +Set up apt-cacher-ng for use with grml-live ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and +Make sure /etc/grml/grml-live.local provides according APT_PROXY and FAI_DEBOOTSTRAP: - # cat /etc/grml/grml-live.conf + # cat /etc/grml/grml-live.local [...] - GRML_LIVE_SOURCES=" - deb http://localhost:3142/deb.grml.org grml-stable main - deb http://localhost:3142/deb.grml.org grml-testing main - deb http://localhost:3142/cdn.debian.net/debian lenny main contrib non-free - " + APT_PROXY="http://localhost:3142/" [...] - FAI_DEBOOTSTRAP="lenny http://localhost:3142/cdn.debian.net/debian lenny main contrib non-free" + FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free" -Make sure apt-cacher / apt-cacher-ng is running ('/etc/init.d/apt-cacher -restart' or '/etc/init.d/apt-cacher-ng restart'). That's it. All downloaded -files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then. +Make sure apt-cacher-ng is running ('/etc/init.d/apt-cacher-ng restart'). +That's it. All downloaded files will be cached in /var/cache/apt-cacher-ng then. [[approx]] Set up approx for use with grml-live @@ -1017,9 +1048,9 @@ FAI_DEBOOTSTRAP: GRML_LIVE_SOURCES=" deb http://localhost:9999/grml grml-stable main deb http://localhost:9999/grml grml-testing main - deb http://localhost:9999/debian lenny main contrib non-free + deb http://localhost:9999/debian squeeze main contrib non-free " - FAI_DEBOOTSTRAP="lenny http://localhost:9999/debian" + FAI_DEBOOTSTRAP="squeeze http://localhost:9999/debian" Configure approx: @@ -1035,7 +1066,7 @@ All downloaded files will be cached in /var/cache/approx now. How do I revert the manifold feature from an ISO? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The so called manifold feature Grml ISOs use by default allows to use the same +The so called manifold feature Grml ISOs use by default allows one to use the same ISO for CD boot and USB boot. If you notice any problems when booting just revert the manifold feature running: @@ -1046,6 +1077,66 @@ syslinux) then just execute: % isohybrid grml.iso +[[basetgz]] +How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Execute the following commands (requires root): + + ARCH='amd64' # replace with i386 if necessary + SUITE='squeeze' # using the current stable release should always work + debootstrap --arch "$ARCH" --exclude=info,tasksel,tasksel-data "$SUITE" "$ARCH" http://debian.netcologne.de/debian + cd "$ARCH" + rm var/cache/apt/archives/*.deb + tar zcf ../"${ARCH}".tar.gz * + +And finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note +that it needs to be uppercase letters matching the class names, so: AMD64.tar.gz +for amd64 and I386.tar.gz for i386). + +[[autobuild]] +How do I set up an autobuild environment? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to set up a system like link:http://daily.grml.org/[daily.grml.org] +the Debian package grml-live-buildd provides all you need to start. Start with +figuring out the cron job script /usr/share/grml-live/buildd/cronjob.sh. + +If you want to automatically update the grml-live Debian package on your build +system based on the git tree of grml-live (so you get bleeding edge of +development which might is interesting for services like daily.grml.org) the +provided release_helper.sh script provides everything you need. Execute as root: + + echo "deb file:/home/grml-live-git/grml-live.build-area/ ./" >> /etc/apt/sources.list.d/grml-live.list + adduser --disabled-login --disabled-password grml-live-git + +Execute 'visudo' to update sudo configuration and add the following line: + + grml-live-git ALL=NOPASSWD: /usr/bin/apt-get + +Switch to user grml-live-git and configure the rest: + + su - grml-live-git + mkdir grml-live.build-area + git clone git://git.grml.org/grml-live.git + git config --global user.name "Grml-Live Git Autobuild" + git config --global user.email "grml-live-git@$(hostname)" + +Finally install a cron job (as user grml-live-git) like: + + 30 00 * * * cd /home/grml-live-git/grml-live.git/ && env AUTOBUILD=1 scripts/release_helper.sh >/home/grml-live-git/grml-live-build.log + +Tip: To find out the build date of the installed grml-live package just execute: + + % apt-cache policy grml-live | grep 'Installed.*autobuild' + Installed: 0.13.1~autobuild1300450381 + +and run "date -ud @$STRING" where $STRING is the number behind the "autobuild", +like: + + % date -ud @1300450081 + Fri Mar 18 12:08:01 UTC 2011 + [[question]] I've a question which isn't answered by this document ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~