X-Git-Url: https://git.grml.org/?p=grml-live.git;a=blobdiff_plain;f=docs%2Fgrml-live.txt;h=133badfc8e9cefddaabb4353e15a2cb73f794930;hp=a430a1216006e90894bf3a643a076a3cff9c10d5;hb=aa74c00b81b8b2e6dcaaa2401e1defd1525d11b2;hpb=b0f14af53e9c397e5809583f9d69fd804e9d08bc diff --git a/docs/grml-live.txt b/docs/grml-live.txt index a430a12..133badf 100644 --- a/docs/grml-live.txt +++ b/docs/grml-live.txt @@ -4,25 +4,22 @@ grml-live(8) Name ---- -grml-live - build framework based on FAI for generating a grml and Debian based +grml-live - build framework based on FAI for generating a Grml and Debian based Linux Live system (CD/ISO) Synopsis -------- -grml-live [-a ] [-c ] [-C ] [-g -] [-i ] [-o ] [-r ] [-s -] [-t ] [-v ] [-U ] [ --AbBFnNquVz] - -CAUTION: Please check out <> for details about current state of involved -tools before starting with grml-live or if you encounter any problems. +grml-live [-a ] [-c ] [-C ] [ +-e ] [-g ] [-i ] [ +-o ] [-r ] [-s ] [ +-t ] [-v ] [-U ] [ +-w ] [-AbBFnNqQuVz] Description ----------- -grml-live provides the build system for creating a grml and Debian based Linux +grml-live provides the build system for creating a Grml and Debian based Linux Live-CD. The build system is based on link:http://fai-project.org/[FAI] (Fully Automatic Installation). grml-live uses the "fai dirinstall" feature to generate a chroot @@ -37,7 +34,7 @@ details of a build process. CAUTION: grml-live does **not** use /etc/fai for configuration but instead 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 +(unless overridden 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! @@ -46,19 +43,18 @@ completely independent at the same time! Please notice that you should have a fast network connection as all the Debian packages will be downloaded and installed via network. If you want to use a local mirror (strongly recommended if you plan to use grml-live more than once) -checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror), -debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a +checkout debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a sample configuration), apt-cacher(1) and approx(8). To avoid downloading the -base system again and again check out FAI's NFSROOT (see FAQ of this document -for details). +base system again and again check out <>. 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. +Clean up all output directories before running the build process. After finishing, +clean up the Chroot target and Build target directories. -a **ARCHITECTURE**:: @@ -79,7 +75,7 @@ but intend to only build the ISO. -B:: Build the ISO without touching the chroot at all. This option is useful if -you modified anything that FAI or grml-live might adjust via grml's FAI +you modified anything that FAI or grml-live might adjust via Grml's FAI scripts. It's like the '-b' option but even more advanced. Use only if you really know that you do not want to update the chroot. @@ -87,12 +83,10 @@ really know that you do not want to update the chroot. Specify the CLASSES to be used for building the ISO via FAI. By default only the classes GRMLBASE, GRML_FULL and I386/AMD64 (depending on system -architecture) are assumed, resulting in a small base system (being about ~180MB -total ISO size). If using a non-I386 system (like AMD64) you should specify the -appropriate architecture as well. Additionally you can specify a class providing -a grml-kernel (see <> for -details about available classes). So instead of GRML_FULL you can also use -GRML_SMALL and GRML_FULL. +architecture) are assumed. Additionally you can specify a class providing a +(grml-)kernel (see <> for +details about available classes). So instead of GRML_FULL you can also use e.g. +GRML_SMALL. [IMPORTANT] All class names should be written in uppercase letters. Do not use a dash, use @@ -136,6 +130,11 @@ 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. + -e **EXTRACT_ISO_NAME**:: + +The squashfs inside the specified ISO will be extracted and used as the chroot. +This option is useful for remastering, in combination with -A and -b or -u. + -F:: Force execution and do not prompt for acknowledgment of configuration. @@ -201,9 +200,10 @@ Specify name of the release. -s **SUITE**:: -Specify the Debian suite you want to use for your live-system. Defaults to -"squeeze" (being current Debian/stable). Supported values are: etch, lenny, -squeeze, sid. Debian "squeeze" requires a recent base.tgz +Specify the Debian suite you want to use for your live-system. If unset defaults +to "testing". Supported values are: stable, testing, unstable (or their +corresponding release names like "stretch"). Please be aware that recent Debian +suites might require a recent base.tgz (${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of debootstrap. @@ -212,11 +212,6 @@ debootstrap. Specify place of the templates used for building the ISO. By default (and if not manually specified) this is /usr/share/grml-live/templates/. - -T **CHROOT_ARCHIVE**:: - -Unpack chroot tar archive before starting. Most useful in combination with --A and -b or -u. - -u:: Update existing chroot instead of rebuilding it from scratch. This option is @@ -234,6 +229,22 @@ Specify version number of the release. Increase verbosity in the build process. + -w **DATE**:: + +The wayback machine. Build the system using Debian archives from the specified +date. Valid date formats are yyyymmddThhmmssZ or simply yyyymmdd. To learn +which snapshots exist, i.e. which date strings are valid, simply browse the +lists on http://snapshot.debian.org/. If there is no import at the exact time +you specified you will get the latest available timestamp which is before the +time you specified. +This option is useful especially for release and debugging builds - for example +if you know that the Debian archive was in a good state on a specific date but +you want to build it on another day in the future, where the archive might not +be as needed anymore. Please be aware that this is restricted to the plain +Debian repositories only, as referred to in /etc/apt/sources.list.d/debian.list +(so neither the Grml repositories nor any further custom ones are affected by +the wayback machine). + -z:: Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process. @@ -242,41 +253,29 @@ Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process. Usage examples -------------- -To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live +To get a Debian-stable and Grml-based Live-CD using ./grml as build and output directory just run: # grml-live -To get a small Debian-unstable and grml-small based Live-CD using -/home/mika/grml-live as build and output directory just use: - - # grml-live -s sid -c GRMLBASE,GRML_SMALL,AMD64 -o /home/mika/grml-live - -To get a medium sized, Debian-unstable and grml-based Live-CD for amd64 -architecture using /grml/grml-live as build and output directory just run: +To get a 64bit Debian-testing and grml-small based Live-CD using /srv/grml-live +as build and output directory use the following command line on your amd64 +system: - # grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64 - -To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and -output directory and use grml_0.0-3.iso as ISO name (placed inside -/tmp/grml_isos) just invoke: - - # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,AMD64 -s sid -i grml_0.0-3.iso + # grml-live -s testing -c GRMLBASE,GRML_SMALL,AMD64 -o /srv/grml-live [NOTE] -If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually -you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm" -and use /dev/shm as build and output directory - resulting in very fast build -process. But please be aware of the fact that rebooting your system will result -in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT, -$BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :) +If you have enough RAM, just run "mount -t tmpfs none /media/ramdisk" to get a +tmpfs ("RAMDISK"), and use /media/ramdisk as build and output directory - this +results in a very fast build process. Note that these files will be gone when +rebooting. [[main-features]] Main features of grml-live -------------------------- -* create a grml-/Debian-based Linux Live-CD with one single command +* create a Grml-/Debian-based Linux Live-CD with one single command * class based concept, providing a maximum of flexibility @@ -287,8 +286,6 @@ Debian repositories * native support of FAI features -* multi-arch support (work in progress) - [[class-concept]] The class concept ----------------- @@ -301,7 +298,7 @@ The main and base class provided by grml-live is named GRMLBASE. It's strongly recommended to **always** use the class GRMLBASE when building an ISO using grml-live, as well as the architecture dependent class which provides the kernel (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like -GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are +GRML_SMALL or GRML_FULL). The following files and directories are relevant for class GRMLBASE by default: ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/ @@ -333,25 +330,35 @@ ${GRML_FAI_CONFIG}/config/package_config whereas some further classes are define 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 +* DEBORPHAN: get rid of all packages listed in output of deborphan + +* FILE_RC: instead of using systemd as init system use file-rc instead. file-rc +was the init system used by Grml until and including stable release 2014.11, +starting with beginning of 2016 Grml switched to systemd instead. If you want to +build a live system in the old style using file-rc instead of systemd then enable +this class. Please notice that the Grml team no longer provides support for it +though. + +* FRESHCLAM: execute freshclam (if it's present) to update clamav definitions +(increases resulting ISO size ~70MB). By default it's skipped to avoid bigger +ISO size. * GRMLBASE: the main class responsible for getting a minimal subset of what's defining a Grml system. Important parts of the buildprocess are specified in this class as well, so unless you have a really good reason you should always -use this class. - -* GRML_FULL: full featured grml, also known as the "normal", full grml as -introduced in november 2011 (~350MB ISO size). +use this class. Please be aware that using *just* the GRMLBASE class won't be +enough, because the kernel packages (e.g. linux-image-*) are chosen in further +GRML_* classes (to provide maximum flexibility with kernel selection). If you +don't want to use the existing GRML_FULL or GRML_SMALL classes, define your own +CLASS file choosing the kernel package you want to use (and don't forget to +include your CLASS in the arguments of grml-live's -c... command line option). -* GRML_MEDIUM: medium sized grml version, used to be known as grml-medium -until november 2011 (~220MB ISO size). +* GRML_FULL: full featured Grml, also known as the "normal", full grml as +introduced in December 2011 (~750 ISO size). -* GRML_SMALL: minimum sized grml version, known as grml-small (~110MB ISO +* GRML_SMALL: minimum sized Grml version, known as grml-small (~360MB ISO size). -* GRML_XL: large size Grml version, used to be known as "full grml" until -november 2011 (~700MB ISO size). - * LATEX: LaTeX(-related) packages like auctex, texlive,... (which used to be shipped by grml before the LaTeX removal) @@ -417,26 +424,6 @@ 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. - ${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. - - ${GRML_FAI_CONFIG}/NFSROOT - -This file specifies the package list for creating the NFSROOT. - - ${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 ${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 ${GRML_FAI_CONFIG}/config/files instead. - ${GRML_FAI_CONFIG}/config/ The main directory for configuration of FAI/grml-live. More details below. @@ -462,7 +449,7 @@ installation process. 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 "grml-live -c GRMLBASE,GRML_SMALL,AMD64 ..." only the configuration of GRMLBASE, -GRML_SMALL and and AMD64 will be taken. If you use 'grml-live -c +GRML_SMALL and AMD64 will be taken. If you use 'grml-live -c GRMLBASE,GRML_SMALL,AMD64,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL, AMD64 **plus** the files from FOOBAR will be taken. So just create a new class to adjust the package selection according to your needs. Please notice that the @@ -482,40 +469,29 @@ live-initramfs(8). Available log files ------------------- -grml-live itself logs to /var/log/grml-live.log. Unless you set PRESERVE_LOGFILE -in your grml-live configuration the file is cleared on each new invocation of -grml-live. - -The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the -default being /var/log/fai/grml/. +Starting with grml-live version 0.17.0 you should find log files in a directory +named 'grml_logs' in the output directory (next to grml_isos, grml_chroot,...). -If you are using the grml-live buildd you will find the logs of the grml-live -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 -manpage. +grml-live versions before 0.17.0 used to log into /var/log/grml-live.log +and /var/log/fai/grml. [[requirements]] Requirements for the build system --------------------------------- * any Debian based system should be sufficient (if it doesn't work it's a bug, -please send us a bug report then) [a usual -link:http://grml.org/grml2hd/[grml2hd] harddisk installation (using grml or -grml-medium) ships all you need]. Check out <> for details how to set up grml-live on a plain, original Debian system. -* enough free disk space; at least 800MB are required for a minimal grml-live -run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target -[$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some -temporary files), if you plan to use GRML_FULL you should have at least 4GB of -total free disk space +* enough free disk space; at least ~2GB are required for a minimal grml-live +run (\~1GB for the chroot [$CHROOT_OUTPUT], \~400MB for the build target +[$BUILD_OUTPUT], \~35MB for the netboot files and \~350MB for the resulting ISO +[$ISO_OUTPUT] plus some temporary files), if you plan to use GRML_FULL you +should have at least 4GB of total free disk space * fast network access for retrieving the Debian packages used for creating the -chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far -as possible) +chroot (check out "local mirror" to workaround this problem as far as possible) For further information see next section. @@ -524,225 +500,8 @@ For further information see next section. Current state of grml-live with squashfs-tools and kernel --------------------------------------------------------- -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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Whereas the ZLIB compression is much faster in the build process, the LZMA -compression provides a smaller resulting ISO. If you're wondering: the official -Grml builds use the LZMA compression. - -Squashfs-tools was introduced in Debian and once provided support for LZMA -compression. Sadly LZMA compression within squashfs-tools became unsupported and -therefore squashfs-lzma-tools[4] had to be introduced and maintained by the Grml -team. Different kernel versions provide different squashfs file formats. Kernel -versions until 2.6.28-grml[64] used the 3.x file format but those outdated -kernels aren't supported by grml-live automatically anymore nowdays (manual -handling through SQUASHFS_BINARY possible though). Kernel versions -2.6.31-grml[64] and 2.6.33-grml[64] use openwrt's squashfs lzma file format -version 4. Kernel versions starting with 2.6.35-grml[64] use the mainline ondisk -file format version 4. - -If you're wondering which package supports what, here's a short overview: - -* squashfs-lzma-tools4 4.0-x: ZLIB as default, LZMA support via '-comp lzma' -option (enabled by grml-live by default), file format version 4 (mainline -version), package maintained and available from Grml, recommended for current -grml-live builds featuring kernels >=2.6.35-grml[64] - -* squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via '-lzma' option -(enabled by grml-live by default), file format version 4 (openwrt style), -package maintained and available from Grml, recommended for any grml-live builds -with kernel versions 2.6.31-grml[64] and 2.6.33-grml[64] - -* squashfs-tools 1:4.0-x: ZLIB as default, no LZMA support/options, file format -version 4, package maintained and available from Debian, recommended only for -ZLIB-only builds of any grml-live builds with kernel versions >=2.6.31-grml[64] - -Outdated, JFTR: - -* squashfs-tools 1:3.3-7: ZLIB as default, no LZMA support/options, file format -version 3 - -* squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via '-nolzma' -option, file format version 3 - -* squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via '-nolzma' option, -file format version 3 - -Now, depending on the kernel version you want to use you need different versions -of squashfs-tools/squashfs-lzma-tools[4]. Yes, that's a mess (don't ask how much -this sucks for us developers) - though we're putting lots of effort into our -toolchain to automatically handle this for you through the grml-live build -system and provide proper documentation. The situation is supposed to calm down -with the recent integration of the squashfs file format 4 in the mainline -kernel. Support for LZMA is pending and as soon as it's available mainline this -should dramatically simplify the situation for developers as well as users. - -[TIP] -If you want to force usage of a specific mksquashfs binary just set the -SQUASHFS_BINARY configuration/environment variable. Set SQUASHFS_OPTIONS for -customizing the options that should be used by the mksquashfs binary during -build process. - -Using squashfs-lzma-tools4 4.0-1 on the build system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -squashfs-lzma-tools4 4.0-1 is available via the Grml repositories. It provides -the mksquashfs-lzma4 and unsquashfs-lzma4 binaries. The package does NOT -conflict with neither Debian's squashfs-tools package nor Grml's -squashfs-lzma-tools package, so you can install all of them at the same time and -the build system will try to figure out the best matching binary automatically -for you. - -The packages can be downloaded from -link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/] - -It provides support for the new squashfs file format version 4 (as available in -mainline, so *not* the one being used by squashfs-lzma-tools and kernel -2.6.33-grml) and therefore requires kernel versions starting with -2.6.35-grml[64]. It supports LZMA as well as ZLIB compression. Just use the -defaults for enabling LZMA or use grml-live's '-z' option if you want to use -ZLIB compression instead. - -* Kernel 2.6.31-grml[64]: works with ZLIB compression, fails with LZMA -* Kernel 2.6.33-grml[64]: works with ZLIB compression, fails with LZMA -* Kernel 2.6.35-grml[64]: works with ZLIB *and* LZMA compression -* Kernel 2.6.36-grml[64]: works with ZLIB *and* LZMA compression - -[NOTE] -squashfs-tools >=4.1-1 and/or squashfs-lzma-tools4 are the recommended package -for building up2date ISOs with grml-live! Please use other squashfs-* packages -only if you want to build live systems providing kernel versions older than -2.6.35-grml*. Use squashfs-tools >=4.1-1 or squashfs-lzma-tools4 from Grml if -you want to remaster any Grml releases MORE RECENT than 2010.04. - -Using squashfs-lzma-tools 4.0-2 on the build system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -squashfs-lzma-tools 4.0-2 is available via the Grml repositories. It provides -the mksquashfs-lzma and unsquashfs-lzma binaries. The package does NOT conflict -with Debian's squashfs-tools package (you can install both of them at the same -time). - -The packages can be downloaded from -link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools/] - -It provides support for the new squashfs file format version 4 (based on openwrt -patches, this is *not* the mainline file format that's being used by kernel -2.6.35-grml and squashfs-lzma-tools4!) and therefore requires kernel versions -newer than 2.6.28-grml[64]. It supports LZMA as well as ZLIB compression. Just -use the defaults for enabling LZMA or use grml-live's '-z' option if you want to -use ZLIB instead. - -* Kernel \<=2.6.28-grml[64]: does not work -* Kernel 2.6.31-grml[64]: works -* Kernel 2.6.33-grml[64]: works -* Kernel 2.6.35-grml[64]: works for ZLIB compression, fails for LZMA - -[NOTE] -Please use squashfs-lzma-tools >=4.0-2 from Grml only if you want to remaster -Grml releases 2009.10 and 2010.04 or live systems with their according kernel -versions. - -Using squashfs-tools 1:4.0-X on the build system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -squashfs-tools >=1:4.0-1 is available in Debian/unstable and Debian/testing. It -provides the mksquashfs and unsquashfs binaries. The package does NOT conflict -neither with the squashfs-lzma-tools 4.0-2 package nor with the -squashfs-lzma-tools4 package (so you can install all of them at the same time). - -The packages can be downloaded from -link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/] - -It provides support for the new squashfs file format version 4 and therefore -requires kernel versions newer than 2.6.28-grml[64]. - -It does NOT support LZMA compression (dropped with -link:http://packages.debian.org/changelogs/pool/main/s/squashfs-tools/current/changelog[version -1:3.3-4] and not yet re-integrated yet, see -link:http://bugs.debian.org/594595[#594595]). If you need LZMA support please -use Grml's squashfs-lzma-tools[4] (see sections above) instead. - -* Kernels \<=2.6.28-grml[64]: does not work -* Kernel 2.6.31-grml[64]: works (ZLIB only) -* Kernel 2.6.33-grml[64]: works (ZLIB only) -* Kernel 2.6.35-grml[64]: works (ZLIB only) -* Kernel 2.6.36-grml[64]: works (ZLIB only) - -[NOTE] -Please use squashfs-tools between 4.0-1 and 4.1-1 only if you want to remaster -Grml releases starting with 2009.10 using the ZLIB compression, please use other -squashfs packages otherwise instead. - -Outdated, JFTR: - -Using squashfs-lzma-tools 3.3-1 on the build system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -squashfs-lzma-tools 3.3-1 from the Grml repository supports kernel -2.6.26-grml[64] and 2.6.28-grml[64] using both LZMA and ZLIB (-nolzma) -compression. - -The packages can be downloaded from -link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/]. - -[NOTE] -Please use squashfs-lzma-tools 3.3-1 only if you want to remaster Grml releases -2008.11 or 2009.05. - -Using squashfs-tools 1:3.3-7 on the build system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -squashfs-tools 1:3.3-7 is available through -http://grml.org/squashfs/squashfs-tools_3.3-7_i386.deb (for x86) or -http://grml.org/squashfs/squashfs-tools_3.3-7_amd64.deb (for amd64) [both build -on and for Debian/etch but working with testing and unstable as well]. - -Please notice that squashfs-tools 1:3.3-7 does NOT support LZMA compression at -all (so you won't be able to remaster release 2008.11 and 2009.05 using LZMA for -example). The -nolzma option of mksquashfs is not available therefore (even -though grml-live will deactivate it for you automatically anyway). Please use -squashfs-lzma-tools instead. - -* Kernel 2.6.23-grml: does NOT work, please use squashfs-tools 1:3.2r2-9exp1 - instead if you still want to use kernel 2.6.23 (not - recommended) -* Kernel 2.6.26-grml: works (without LZMA compression only of course!) -* Kernel 2.6.28-grml: works (without LZMA compression only of course!) - -Using squashfs-tools 1:3.2r2-9exp1 on the build system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -squashfs-tools 1:3.2r2-9exp1 is available via the grml-testing repository, -running: - - # aptitude install squashfs-tools=1:3.2r2-9exp1 - -or directly via downloading the files -http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_i386.deb (for x86) or -http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_amd64.deb (for amd64). - -Using with ZLIB compression (SQUASHFS_OPTIONS='-nolzma' or -z -option in grml-live cmdline): - -* Kernel 2.6.23-grml: works -* Kernel 2.6.26-grml: works -* Kernel 2.6.28-grml: supposed to work (not verified though) - -Using with LZMA compression: - -* Kernel 2.6.23-grml: works -* Kernel 2.6.26-grml: does NOT work, please use ZLIB mode instead or switch - to Debian package squashfs-lzma-tools 3.3-1 (see section above). -* Kernel 2.6.28-grml: does NOT work, please use ZLIB mode instead or switch - to Debian package squashfs-lzma-tools 3.3-1 (see section above). -////////////////////////////////////////////////////////////////////////////////// +Use squashfs-tools >=4.2-1 to build Grml (based) ISOs featuring kernel version +2.6.38-grml[64] or newer. [[faq]] FAQ @@ -752,21 +511,14 @@ FAQ How do I deploy grml-live on a plain Debian installation? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The easiest way to get a running grml-live setup is to install Grml or -grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you -don't want to run it on a physical system). Of course using grml-live on a -plain, original Debian installation is supported as well. So there we go. +The easiest way to get a running grml-live setup is to just use Grml. +Of course using grml-live on a plain, original Debian installation is supported +as well. So there we go. -What we have: plain, original Debian Lenny (5.0). +What we have: plain, original Debian stretch (9.x). -What we want: build a grml-medium ISO based on Debian/squeeze for the amd64 -architecture using grml-live. - -[IMPORTANT] - -If you encounter any problems while booting the resulting ISO please be aware of -<>. +What we want: build a Grml ISO based on Debian/stretch for the amd64 architecture +using grml-live. Instructions ^^^^^^^^^^^^ @@ -783,17 +535,6 @@ Instructions # deb-src http://deb.grml.org/ grml-testing main EOF - # adjust apt-pinning (only prefer squashfs stuff from grml): - cat >> /etc/apt/preferences << EOF - Package: * - Pin: origin deb.grml.org - Pin-Priority: 1 - - Package: squashfs-tools - Pin: origin deb.grml.org - Pin-Priority: 996 - EOF - # get keyring for apt: apt-get update apt-get --allow-unauthenticated install grml-debian-keyring @@ -801,12 +542,11 @@ Instructions # optionally(!) install basefile so we don't have to build basic # chroot from scratch, grab from http://daily.grml.org/ # mkdir -p /etc/grml/fai/config/basefiles/ - # mv base.tgz /etc/grml/fai/config/basefiles/I386.tar.gz - # mv base64.tgz /etc/grml/fai/config/basefiles/AMD64.tar.gz + # mv I386.tar.gz /etc/grml/fai/config/basefiles/ + # mv AMD64.tar.gz /etc/grml/fai/config/basefiles/ # install relevant tools - # please check out http://grml.org/grml-live/#current_state when encountering problems! - apt-get -o APT::Install-Recommends=false install grml-live squashfs-tools + apt-get --no-install-recommends install grml-live # adjust grml-live configuration for our needs: cat > /etc/grml/grml-live.local << EOF @@ -815,30 +555,23 @@ Instructions # SQUASHFS_OPTIONS="-comp gzip -b 256k" ## want to use a specific squashfs binary? # SQUASHFS_BINARY='/usr/bin/mksquashfs' - # install local files into the chroot - CHROOT_INSTALL="/etc/grml/fai/chroot_install" - ## adjust if necessary (defaults to /grml/grml-live): + ## install local files into the chroot + # CHROOT_INSTALL="/etc/grml/fai/chroot_install" + ## adjust if necessary (defaults to ./grml/): ## OUTPUT="/srv/grml-live" - FAI_DEBOOTSTRAP="squeeze http://cdn.debian.net/debian/" - ARCH="i386" + FAI_DEBOOTSTRAP="stretch http://ftp.debian.org/debian/" + # ARCH="amd64" CLASSES="GRMLBASE,GRML_FULL,AMD64" - # PRESERVE_LOGFILE='1' - # ZERO_FAI_LOGFILE='1' - GRML_LIVE_SOURCES=" - deb http://deb.grml.org/ grml-stable main - deb http://deb.grml.org/ grml-testing main - deb http://cdn.debian.net/debian squeeze main contrib non-free - " EOF # just optional(!) - upgrade FAI to latest available version: - cat >> /etc/apt/sources.list << EOF - # fai: - deb http://fai-project.org/download lenny koeln + cat >> /etc/apt/sources.list.d/fai.list << EOF + deb http://jenkins.grml.org/debian fai main + deb-src http://jenkins.grml.org/debian fai main EOF # get gpg key of FAI repos and install current FAI version: - gpg -a --recv-keys AB9B66FD; gpg -a --export AB9B66FD | apt-key add - + wget -O - http://jenkins.grml.org/debian/C525F56752D4A654.asc | sudo apt-key add - apt-get update apt-get install fai-client fai-server fai-doc @@ -865,57 +598,13 @@ configuration files, scripts and hooks will be taken from your I've problems with the build process. How to start debugging? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Check out the logs inside /var/log/fai/... If you think it's a bug in grml-live -send a copy of your config, logs and the commandline with a short problem -description to : - - # history | grep grml-live > /etc/grml/grml_live.cmdline - # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \ - /etc/grml/grml_live.cmdline /etc/grml/grml-buildd.conf \ - /var/log/fai /etc/grml/fai - -> finally mail grml_live_problem.tar.gz to +Check out the logs inside the directory 'grml_logs' next to your grml_chroot, +grml_isos,... directories. If you need help with grml-live or would like to see new features as part of grml-live you can get commercial support via link:http://grml-solutions.com/[Grml Solutions]. -[[lzma-vs-zlib]] -How much is the difference between LZMA and ZLIB compression? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ISO size (bs = blocksize): - -[width="45%",cols="3,^2,^2"] -|============================================================ -|ISO |LZMA (256kB bs) |ZLIB -|grml_sid |666M | 771M -|grml_squeeze |659M | 761M -|grml_lenny |624M | 723M -|grml64_sid |677M | 791M -|grml64_squeeze |671M | 785M -|grml64_lenny |639M | 745M -|grml-medium_sid |208M | 236M -|grml-medium_squeeze |206M | 234M -|grml-medium_lenny |193M | 220M -|grml64-medium_sid |213M | 245M -|grml64-medium_squeeze |213M | 244M -|grml64-medium_lenny |201M | 231M -|grml-small_sid |102M | 118M -|grml-small_squeeze |101M | 117M -|grml-small_lenny |97M | 112M -|grml64-small_sid |103M | 120M -|grml64-small_squeeze |103M | 120M -|grml64-small_lenny |99M | 116M -|============================================================ - -Build time of grml-medium's squashfs file (depends on your system, though just -to get the ratio between the different options): - -* 10 minutes and 4 seconds with LZMA default blocksize (128k) -* 7 minutes 27 seconds with LZMA and blocksize 256k -* 6 minutes and 8 seconds with LZMA blocksize 512k -* 1 minute and 40 seconds with ZLIB - [[install-local-files]] How do I install further files into the chroot/ISO? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -937,7 +626,7 @@ Can I use my own (local) Debian mirror? Yes. Set up an according sources.list configuration as class file in ${GRML_FAI_CONFIG}/config/files/etc/apt/sources.list.d/ and adjust the variable -FAI_DEBOOTSTRAP (if not already using NFSROOT's base.tgz) inside +FAI_DEBOOTSTRAP (if not already using a base.tgz) inside /etc/grml/grml-live.conf[.local]. If you're setting up your own class file don't forget to include the class name in the class list (grml-live -c ...). @@ -955,7 +644,7 @@ How do I add additional Debian package(s) to my CD/ISO? Just create a new class (using the package_config directory): # cat > /etc/grml/fai/config/package_config/MIKA << EOF - PACKAGES aptitude + PACKAGES install vim another_name_of_a_debian_package @@ -976,60 +665,9 @@ what you are searching for just run: rm -rf /etc/grml/fai /etc/grml/grml-live.conf dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb -[NOTE] - -If you don't control your /etc using a version control system (VCS) yet it's a -good chance to start using it now. Check out -link:http://michael-prokop.at/blog/2007/03/14/maintain-etc-with-mercurial-on-debian/[http://michael-prokop.at/blog/2007/03/14/maintain-etc-with-mercurial-on-debian/] -for more details how to maintain /etc using the mercurial VCS. - -[[create-a-base-tgz]] -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 squeeze /tmp/nfsroot/ http://cdn.debian.net/debian - tar zcf base.tgz ./ - -Then check out where your NFSROOT is located: - - # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf - NFSROOT=/grml/fai/nfsroot - -So as /grml/fai/nfsroot is your NFSROOT place the file under -/grml/fai/nfsroot/live/filesystem.dir/var/tmp/: - - mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz - -or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead. -Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds. - -Now running "grml-live ..." will use this file as main system instead of -executing debootstrap. Check out the output for the following lines if using -NFSROOT: - - [...] - Calling task_extrbase - Unpacking Debian base archive - Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz - Calling task_mirror - [...] - -or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for: - - [...] - ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to - /grml-live/grml-live_20071029.22138/grml_chroot// - [...] - -[TIP] -Existing base.tgz can be found at http://daily.grml.org/ - [[apt-cacher]] Set up apt-cacher-ng for use with grml-live -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Make sure /etc/grml/grml-live.local provides according APT_PROXY and FAI_DEBOOTSTRAP: @@ -1038,150 +676,156 @@ FAI_DEBOOTSTRAP: [...] APT_PROXY="http://localhost:3142/" [...] - FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free" + FAI_DEBOOTSTRAP="stretch http://localhost:3142/ftp.debian.org/debian stretch main contrib non-free" 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and -FAI_DEBOOTSTRAP: - - # cat /etc/grml/grml-live.conf - [...] - GRML_LIVE_SOURCES=" - deb http://localhost:9999/grml grml-stable main - deb http://localhost:9999/grml grml-testing main - deb http://localhost:9999/debian squeeze main contrib non-free - " - FAI_DEBOOTSTRAP="squeeze http://localhost:9999/debian" - -Configure approx: - - # cat /etc/approx/approx.conf - [...] - debian http://ftp.at.debian.org/debian - grml http://deb.grml.org/ - -Don't forget to restart approx (/etc/init.d/approx restart). That's it. -All downloaded files will be cached in /var/cache/approx now. - [[revert_manifold]] How do I revert the manifold feature from an ISO? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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: +The so-called manifold feature Grml ISOs can, but by default do not, use allows +one to use the same ISO for CD boot and USB boot. If you notice any problems +when booting manifold-crafted media, just revert the manifold feature running: % dd if=/dev/zero of=grml.iso bs=512 count=1 conv=notrunc To switch from manifold to isohybrid mode (an alternative approach provided by -syslinux) then just execute: +syslinux, used by default for official Grml images) then just execute: % isohybrid grml.iso -[[basetgz]] +[[create-a-base-tgz]] How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +[[basetgz]] -Execute the following commands (requires root): +First of all create the chroot using debootstrap (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 * + BASECHROOT='/tmp/basefile' # path where the chroot gets generated + SUITE='stretch' # using the current stable release should always work + debootstrap --exclude=info,tasksel,tasksel-data "$SUITE" "$BASECHROOT" http://ftp.debian.org/debian + tar -C "$BASECHROOT" --exclude='var/cache/apt/archives/*.deb' -zcf "${SUITE}".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). +[TIP] +By default debootstrap builds a chroot matching the architecture of the running +host system. If you're using an amd64 system and want to build an i386 base.tgz +then invoke debootstrap using the '--arch i386' option. Disclaimer: building an +AMD64 base.tgz won't work if you are using a 32bit kernel system of course. -[[autobuild]] -How do I set up an autobuild environment? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note +that it needs to be uppercase letters matching the class names, so: e.g. +AMD64.tar.gz for amd64 and I386.tar.gz for i386). -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. +Then executing grml-live should use this file as base system instead of executing +debootstrap. Check out the output for something like: -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: + [...] + ftar: extracting //etc/grml/fai/config/basefiles///AMD64.tar.gz to /srv/grml64_testing/grml_chroot// + [...] + +[[localrepos]] +How to use your own local repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 +Let's assume you have Debian package(s) in your filesystem inside +`/home/foobar/local-packages` and want to provide them to your grml-live build. +This can be achieved either 1) through a bind mount (using the MIRROR_DIRECTORY +configuration) or 2) by serving a repository via HTTP. -Execute 'visudo' to update sudo configuration and add the following line: +Serving via bind mount / MIRROR_DIRECTORY +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - grml-live-git ALL=NOPASSWD: /usr/bin/apt-get +Make sure to create an according sources.list configuration file, e.g. using +your own class name `CUSTOM`: -Switch to user grml-live-git and configure the rest: + # cat > /etc/grml/fai/config/files/etc/apt/sources.list.d/local-packages.list/CUSTOM << EOF + deb file:///home/foobar/local-packages ./ + EOF + +Add the according MIRROR_DIRECTORY configuration to your grml-live configuration: - 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)" + # echo "MIRROR_DIRECTORY='/home/foobar/packages'" >> /etc/grml/grml-live.local -Finally install a cron job (as user grml-live-git) like: +Make sure the local directory looks like a mirror: - 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 + % cd /home/foobar/packages + % dpkg-scanpackages . /dev/null | gzip > Packages.gz -Tip: To find out the build date of the installed grml-live package just execute: +Finally invoke grml-live with your class name (`CUSTOM` in this example) added +to the list of classes on the command line (see grml-live option `-c`). - % apt-cache policy grml-live | grep 'Installed.*autobuild' - Installed: 0.13.1~autobuild1300450381 +Serving a repository via HTTP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -and run "date -ud @$STRING" where $STRING is the number behind the "autobuild", -like: +Make sure to create an according sources.list configuration file, e.g. using +your own class name `CUSTOM`: - % date -ud @1300450081 - Fri Mar 18 12:08:01 UTC 2011 + # cat > /etc/grml/fai/config/files/etc/apt/sources.list.d/local-packages.list/CUSTOM << EOF + deb http://127.0.0.1:8000/ ./ + EOF -[[question]] -I've a question which isn't answered by this document -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Make sure the local directory is served via HTTP on the according IP address and +port. For the `http://127.0.0.1:8000/` example from above it should be enough to +just invoke: -Don't hesitate to contact the author: + % cd /home/foobar/packages + % dpkg-scanpackages . /dev/null | gzip > Packages.gz + % python -m SimpleHTTPServer 8000 + +[TIP] +Of course you can also use a real Debian repository setup using tools like +reprepro(1) and/or using a real web server, though for quick debugging sessions +python's SimpleHTTPServer in combination with dpkg-scanpackages from package +dpkg-dev is a simple and easy approach. + +Finally invoke grml-live with your class name (`CUSTOM` in this example) added +to the list of classes on the command line (see grml-live option `-c`). [[download]] Download / install grml-live as a Debian package ------------------------------------------------ -Debian packages are available through the grml-repository at -link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to -build a Debian package on your own (using for example a specific version or the -current development tree), just execute: +Stable Debian packages are available through the grml-repository at +link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org] and the latest +Git commits are available as Debian packages from +link:http://jenkins.grml.org/job/grml-live-binaries/[jenkins.grml.org]. +If you want to build a Debian package on your own (using for example a specific +version or the current development tree), just execute: git clone git://git.grml.org/grml-live cd grml-live debuild -us -uc +[[run-from-git]] +Run grml-live directly from git +------------------------------- + +In case you want to run grml-live directly from the git repository checkout +(after making sure all dependencies are installed), you should set +`GRML_FAI_CONFIG` so that a) it finds the according FAI configuration files and +b) does not use the config files of an possibly installed `grml-live` package. +Usage example: + + # export GRML_FAI_CONFIG=$(pwd)/etc/grml/fai + # export SCRIPTS_DIRECTORY=$(pwd)/scripts + # export TEMPLATE_DIRECTORY=$(pwd)/templates + # ./grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64 + [[source]] Source ------ The source of grml-live is available at -link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git] - -[[todo-list]] -TODO list ---------- - -Check out the link:http://git.grml.org/?p=grml-live.git;a=blob;f=TODO;hb=HEAD[TODO file]. +link:https://github.com/grml/grml-live/[https://github.com/grml/grml-live/] [[bugs]] Bugs ---- Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes -link:http://grml.org/contact/[to the grml-team]! +link:http://grml.org/contact/[to the Grml team]! [[documentation]] Documentation