7 grml-live - build framework based on FAI for generating a grml and Debian based
8 Linux Live system (CD/ISO)
13 grml-live [-a <architecture>] [-c <classe[s]>] [-C <configfile>] [-g
14 <grml_name>] [-i <iso_name> ] [-o <output_directory>] [-r <release_name>] [-s
15 <suite>] [-t <template_directory>] [-v <version_number>] [-bBFnNquVz]
17 CAUTION: Please check out <<current_state,the 'Current state of grml-live with
18 squashfs-tools and kernel' section>> for details about current state of involved
19 tools before starting with grml-live or if you encounter any problems.
24 grml-live provides the build system for creating a grml and Debian based Linux
25 Live-CD. The build system is based on
26 link:http://fai-project.org/[FAI] (Fully Automatic
27 Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
28 system based on the class concept of FAI (see later sections for further
29 details) and provides the framework to be able to generate a full-featured ISO.
30 It does not use all the FAI features by default though and you don't have to
31 know FAI to be able to use it.
33 The use of FAI gives you the flexibility to choose the packages you would like
34 to include on your very own Linux Live-CD without having to deal with all the
35 details of a build process.
37 CAUTION: grml-live does **not** use /etc/fai for configuration but instead
38 provides and uses ${GRML_FAI_CONFIG} which is pointing to /etc/grml/fai by default
39 (unless overriden using the ''-D'' option). This ensures that it does not clash
40 with default FAI configuration and packages, so you can use grml-live and FAI
41 completely independent at the same time!
45 Please notice that you should have a fast network connection as all the Debian
46 packages will be downloaded and installed via network. If you want to use a
47 local mirror (strongly recommended if you plan to use grml-live more than once)
48 checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
49 debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
50 sample configuration), apt-cacher(1) and approx(8). To avoid downloading the
51 base system again and again check out FAI's NFSROOT (see FAQ of this document
59 Use the specified architecture instead of the currently running one. This
60 allows building a 32bit system on a 64bit host (though you can't build a 64bit
61 system on a 32bit system/kernel of course). Please notice that real
62 crosscompiling (like building a ppc system on x86) isn't possible due to the
63 nature and the need of working in a chroot. Currently supported values: i386
68 Build the ISO without updating the chroot via FAI. This option is useful for
69 example when working on stable releases: if you have a working base
70 system/chroot and do not want to execute any further updates (via "-u" option)
71 but intend to only build the ISO.
75 Build the ISO without touching the chroot at all. This option is useful if
76 you modified anything that FAI or grml-live might adjust via grml's FAI
77 scripts. It's like the '-b' option but even more advanced. Use only if you
78 really know that you do not want to update the chroot.
82 Specify the CLASSES to be used for building the ISO via FAI. By default only
83 the classes GRMLBASE, GRML_MEDIUM and I386 are assumed, resulting in a small base
84 system (being about ~180MB total ISO size). If using a non-I386 system (like
85 AMD64) you should specify the appropriate architecture as well. Additionally you
86 can specify a class providing a grml-kernel (see
87 <<classes,the 'CLASSES' section in this document>> for details about available classes).
88 So instead of GRML_MEDIUM you can also use GRML_SMALL and GRML_FULL.
91 All class names should be written in uppercase letters. Do not use a dash, use
92 an underscore. So do not use "amd64" but "AMD64", do not use "FOO BAR" but
96 -C **CONFIGURATION_FILE**::
98 The specified file is used as configuration file for grml-live. By default
99 /etc/grml/grml-live.conf is used as default configuration. If a file named
100 /etc/grml/grml-live.local exists it is used as well (sourced after reading
101 /etc/grml/grml-live.conf meant as main file for local configuration). As a last
102 option the specified configuration file is sourced so it is possible to override
103 settings of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local.
104 Please notice that all configuration files have to be adjusted during execution
105 of grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
106 your own configuration file (usually /etc/grml/grml-live.local). Please also
107 notice that the configuration file specified via this option is **not** (yet)
108 supported inside the scripts/hooks/classes at ${GRML_FAI_CONFIG}/config. Instead use
109 /etc/grml/grml-live.local for configuration stuff used inside
110 ${GRML_FAI_CONFIG}/config.
114 Use specified date as build date information on the ISO instead of the default.
115 The default is the date when grml-live is being executed (retrieved via
116 executing 'date +%Y-%m-%d'). The information is stored inside the file
117 /GRML/grml-version on the ISO, /etc/grml_version in the squashfs file and in all
118 the bootsplash related files. This option is useful if you want to provide an
119 ISO with release information for a specific date but have to build it in
120 advance. Usage example: '-d 2009-10-30'
122 -D **CONFIGURATION_DIRECTORY**::
124 The specified directory is used as configuration directory for grml-live and its
125 FAI. By default /etc/grml/fai is used as default configuration directory. If
126 you want to have different configuration scripts, package definitions, etc. with
127 without messing with the global configuration under /etc/grml/fai provided by
128 grml-live this option provides you the option to use your own configuration
129 directory. This directory is what's being referred to as ${GRML_FAI_CONFIG}
130 throughout this documentation.
134 Force execution and do not prompt for acknowledgment of configuration.
138 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
139 Please do NOT use blanks and any special characters like '/', ';' inside
140 GRML_NAME, otherwise you might notice problems while booting.
144 Display short usage information and exit.
148 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
151 -I **CHROOT_INSTALL**::
153 Specify name of source directory which provides files that should become part of
154 the chroot/ISO. Not enabled by default. Note: the files are installed under '/'
155 in the chroot so you have to create the rootfs structure on your own.
159 Skip creation of the ISO file. This option is useful if you want to build/update
160 the chroot and/or recreate the squashfs file without building an ISO file.
164 Bootstrap the chroot without building bootloader, squashfs, or finalizing the
165 ISO. Use this option if installation of some packages fails, you want to run
166 custom commands or similar.
167 The main use of this option is to save time by skipping stages which aren't
168 necessary for bootstrapping the chroot and which would get executed more than
169 once when iterating through the initial bootstrapping.
170 Alternatively, use this option as a test run of grml-live. Once you are
171 satisfied with the state of your grml_chroot, use grml-live **-u** to build the
172 remaining stages and finalize the ISO.
174 -o **OUTPUT_DIRECTORY**::
176 Main output directory of the build process of FAI. Some directories are created
177 inside this target directory, being: grml_cd (where the files for creating the
178 ISO are located, including the compressed squashfs file), grml_chroot (the
179 chroot system) and grml_isos (where the resulting ISO is stored).
183 Build the ISO without (re-)creating the squashfs compressed file using mksquashfs.
184 This option is useful if you just want to update parts outside the chroot in the ISO.
185 Consider combining this option with the build-only option '-b'.
189 Specify name of the release.
193 Specify the Debian suite you want to use for your live-system. Defaults to
194 "squeeze" (being current Debian/stable). Supported values are: etch, lenny,
195 squeeze, sid. Debian "squeeze" requires a recent base.tgz
196 (${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of
199 -t **TEMPLATE_DIRECTORY**::
201 Specify place of the templates used for building the ISO. By default
202 (and if not manually specified) this is /usr/share/grml-live/templates/.
206 Update existing chroot instead of rebuilding it from scratch. This option is
207 based on the softupdate feature of FAI.
209 -v **VERSION_NUMBER**::
211 Specify version number of the release.
215 Increase verbosity in the build process.
219 Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process.
225 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
226 as build and output directory just run:
230 To get a small Debian-unstable and grml-small based Live-CD using
231 /home/mika/grml-live as build and output directory just use:
233 # grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
235 To get a medium sized, Debian-unstable and grml-based Live-CD for i386
236 architecture using /grml/grml-live as build and output directory just run:
238 # grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
240 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
241 output directory and use grml_0.0-3.iso as ISO name (placed inside
242 /tmp/grml_isos) just invoke:
244 # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
248 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
249 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
250 and use /dev/shm as build and output directory - resulting in very fast build
251 process. But please be aware of the fact that rebooting your system will result
252 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
253 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
256 Main features of grml-live
257 --------------------------
259 * create a grml-/Debian-based Linux Live-CD with one single command
261 * class based concept, providing a maximum of flexibility
263 * supports integration of own hooks, scripts and configuration
265 * supports use and integration of own Software and/or Kernels via simple use of
268 * native support of FAI features
270 * multi-arch support (work in progress)
276 grml-live uses FAI and its class based concept for adjusting configuration and
277 setup according to your needs. This gives you flexibility and strength without
278 losing the simplicity in the build process.
280 The main and base class provided by grml-live is named GRMLBASE. It's strongly
281 recommended to **always** use the class GRMLBASE when building an ISO using
282 grml-live, as well as the architecture dependent class which provides the kernel
283 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
284 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
285 relevant for class GRMLBASE by default:
287 ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/
288 ${GRML_FAI_CONFIG}/config/debconf/GRMLBASE
289 ${GRML_FAI_CONFIG}/config/class/GRMLBASE.var
290 ${GRML_FAI_CONFIG}/config/hooks/instsoft.GRMLBASE
291 ${GRML_FAI_CONFIG}/config/package_config/GRMLBASE
293 Take a look at the next section for information about the concept of those
296 If you want to use your own configuration, extend an existing configuration
297 and/or add additional packages to your ISO just invent a new class (or extend an
298 existing one). For example if you want to use your own class named "FOOBAR" just
299 set CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" inside /etc/grml/grml-live.local
300 or invoke grml-live using the classes option: "grml-live -c
301 GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
303 More details regarding the class concept can be found in the documentation of
304 FAI itself (being available at /usr/share/doc/fai-doc/).
311 The package selection part of the classes can be found in
312 ${GRML_FAI_CONFIG}/config/package_config whereas some further classes are defined for
313 example in ${GRML_FAI_CONFIG}/config/scripts/ so specific feature sets can be
314 selected. The following classes are predefined:
316 * DEBORPHAN: get rid of all packages listed in output of Deborphan
318 * GRMLBASE: the main class responsible for getting a minimal subset of what's
319 defining a grml system. Important parts of the buildprocess are specified in
320 this class as well, so unless you have a really good reason you should always
323 * GRML_FULL: full featured grml, also known as the "normal", full grml.
325 * GRML_MEDIUM: medium sized grml version, known as grml-medium
327 * GRML_POWERPC: grml for PowerPC architecture, not supported yet (still work in
330 * GRML_SMALL: minimum sized grml version, known as grml-small
332 * LATEX: LaTeX(-related) packages like auctex, texlive,...
333 (which used to be shipped by grml before the LaTeX removal)
335 * LATEX_CLEANUP: get rid of several very large LaTeX directories
336 (like some /usr/share/doc/texlive-*, /usr/share/doc/texmf,...)
338 * LOCALES: use full featured locales setup (see /etc/locale.gen.grml). This
339 avoids to get rid of /usr/share/locale - which happens by default otherwise - as
342 * NO_ONLINE: do not run scripts during the chroot build process which require a
345 * RELEASE: run some specific scripts and commands to provide the workflow for an
346 official grml release
348 * REMOVE_DOCS: get rid of documentation directories (like /usr/share/doc,
349 /usr/share/man/, /usr/share/info,...)
351 * XORG: providing important packages for use with a base grml-featured X.org
358 Notice that grml-live ships FAI configuration files that do not use the same
359 namespace as the FAI packages itself. This ensures that grml-live does not clash
360 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
361 fai-client) grml uses ${GRML_FAI_CONFIG}/fai.conf instead. For more details see
362 below. To get an idea how another configuration or example files could look like
363 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
364 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
365 provides documentation regarding configuration possibilities.
369 Script for the main build process. Requires root permissions for execution.
371 /etc/grml/grml-live.conf
373 Main configuration file for grml-live which should be considered as a reference
374 configuration file only. Please use /etc/grml/grml-live.local for local
375 configuration instead.
377 /etc/grml/grml-live.local
379 All the local configuration should go to this file. This file overrides any
380 defaults of grml-live. Configurations via /etc/grml/grml-live.local are preferred
381 over the ones from /etc/grml/grml-live.conf. If you want to override settings
382 from /etc/grml/grml-live.local as well you have to specify them on the grml-live
385 ${GRML_FAI_CONFIG}/fai.conf
387 Main configuration file for FAI which specifies where all the configuration
388 files and scripts for FAI/grml-live can be found. By default the configuration
389 variables are FAI_CONFIG_SRC=file:///etc/grml/fai/config and
390 GRML_FAI_CONFIG=/etc/grml/fai/config - both pointing to a directory shipped by
391 grml-live out-of-the-box so you shouldn't have to configure anything in this
394 ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf
396 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
397 anything inside this file. If you want to modify NFSROOT though you can adjust
400 ${GRML_FAI_CONFIG}/NFSROOT
402 This file specifies the package list for creating the NFSROOT.
404 ${GRML_FAI_CONFIG}/apt/sources.list
406 This file specifies which mirrors should be considered for retrieving the Debian
407 packages when creating the main chroot (including all the software you would
408 like to see included). Important: this file should *not* be adjusted manually!
409 Instead use the GRML_LIVE_SOURCES variable inside /etc/grml/grml-live.conf or
410 /etc/grml/grml-live.local which modifies ${GRML_FAI_CONFIG}/apt/sources.list
411 on-the-fly via grml-live then. If you want to generally adjust apt configuration
412 use FAI's fcopy command with ${GRML_FAI_CONFIG}/config/files instead.
414 ${GRML_FAI_CONFIG}/config/
416 The main directory for configuration of FAI/grml-live. More details below.
418 ${GRML_FAI_CONFIG}/config/class/
420 This directory contains files which specify main configuration variables for the
423 ${GRML_FAI_CONFIG}/config/debconf/
425 This directory provides the files for preseeding/configuration of debconf
428 ${GRML_FAI_CONFIG}/config/hooks/
430 This directory provides files for customising the build process through hooks.
431 Hooks are user defined programs or scripts, which are called during the
432 installation process.
434 ${GRML_FAI_CONFIG}/config/package_config/
436 Directory with lists of software packages to be installed or removed. The
437 different classes describe what should find its way to your ISO. When running
438 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
439 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
440 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
441 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
442 adjust the package selection according to your needs. Please notice that the
443 directory GRMLBASE contains a package list defining a minimum but still
444 reasonable package configuration.
446 ${GRML_FAI_CONFIG}/config/scripts/
448 Scripts for customising the ISO within the build process.
450 ${GRML_FAI_CONFIG}/live-initramfs/
452 This directory provides the files used for building the initramfs/initrd via
459 grml-live itself logs to /var/log/grml-live.log. Unless you set PRESERVE_LOGFILE
460 in your grml-live configuration the file is cleared on each new invocation of
463 The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the
464 default being /var/log/fai/grml/.
466 If you are using the grml-live buildd you will find the logs of the grml-live
467 run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
469 If you want to store build information in a database just install the
470 grml-live-db Debian package. Further details available in the grml-live-db
474 Requirements for the build system
475 ---------------------------------
477 * any Debian based system should be sufficient (if it doesn't work it's a bug,
478 please send us a bug report then) [a usual
479 link:http://grml.org/grml2hd/[grml2hd] harddisk installation (using grml or
480 grml-medium) ships all you need]. Check out <<deploy-on-debian,How do I deploy
481 grml-live on a plain Debian installation>> for details how to set up grml-live
482 on a plain, original Debian system.
484 * enough free disk space; at least 800MB are required for a minimal grml-live
485 run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
486 [$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
487 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
488 total free disk space
490 * fast network access for retrieving the Debian packages used for creating the
491 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
494 For further information see next section.
498 Current state of grml-live with squashfs-tools and kernel
499 ---------------------------------------------------------
501 Use squashfs-tools >=4.2-1 (available from Grml repositories as well as from
502 Debian/unstable) to build Grml (based) ISOs featuring kernel version
505 ////////////////////////////////////////////////////////////////////////////////
506 Difference between squashfs-lzma-tools, squashfs-lzma-tools4 and squashfs-tools
507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
509 Whereas the ZLIB compression is much faster in the build process, the LZMA
510 compression provides a smaller resulting ISO. If you're wondering: the official
511 Grml builds use the LZMA compression.
513 Squashfs-tools was introduced in Debian and once provided support for LZMA
514 compression. Sadly LZMA compression within squashfs-tools became unsupported and
515 therefore squashfs-lzma-tools[4] had to be introduced and maintained by the Grml
516 team. Different kernel versions provide different squashfs file formats. Kernel
517 versions until 2.6.28-grml[64] used the 3.x file format but those outdated
518 kernels aren't supported by grml-live automatically anymore nowdays (manual
519 handling through SQUASHFS_BINARY possible though). Kernel versions
520 2.6.31-grml[64] and 2.6.33-grml[64] use openwrt's squashfs lzma file format
521 version 4. Kernel versions starting with 2.6.35-grml[64] use the mainline ondisk
522 file format version 4.
524 If you're wondering which package supports what, here's a short overview:
526 * squashfs-lzma-tools4 4.0-x: ZLIB as default, LZMA support via '-comp lzma'
527 option (enabled by grml-live by default), file format version 4 (mainline
528 version), package maintained and available from Grml, recommended for current
529 grml-live builds featuring kernels >=2.6.35-grml[64]
531 * squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via '-lzma' option
532 (enabled by grml-live by default), file format version 4 (openwrt style),
533 package maintained and available from Grml, recommended for any grml-live builds
534 with kernel versions 2.6.31-grml[64] and 2.6.33-grml[64]
536 * squashfs-tools 1:4.0-x: ZLIB as default, no LZMA support/options, file format
537 version 4, package maintained and available from Debian, recommended only for
538 ZLIB-only builds of any grml-live builds with kernel versions >=2.6.31-grml[64]
542 * squashfs-tools 1:3.3-7: ZLIB as default, no LZMA support/options, file format
545 * squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via '-nolzma'
546 option, file format version 3
548 * squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via '-nolzma' option,
549 file format version 3
551 Now, depending on the kernel version you want to use you need different versions
552 of squashfs-tools/squashfs-lzma-tools[4]. Yes, that's a mess (don't ask how much
553 this sucks for us developers) - though we're putting lots of effort into our
554 toolchain to automatically handle this for you through the grml-live build
555 system and provide proper documentation. The situation is supposed to calm down
556 with the recent integration of the squashfs file format 4 in the mainline
557 kernel. Support for LZMA is pending and as soon as it's available mainline this
558 should dramatically simplify the situation for developers as well as users.
561 If you want to force usage of a specific mksquashfs binary just set the
562 SQUASHFS_BINARY configuration/environment variable. Set SQUASHFS_OPTIONS for
563 customizing the options that should be used by the mksquashfs binary during
566 Using squashfs-lzma-tools4 4.0-1 on the build system
567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
569 squashfs-lzma-tools4 4.0-1 is available via the Grml repositories. It provides
570 the mksquashfs-lzma4 and unsquashfs-lzma4 binaries. The package does NOT
571 conflict with neither Debian's squashfs-tools package nor Grml's
572 squashfs-lzma-tools package, so you can install all of them at the same time and
573 the build system will try to figure out the best matching binary automatically
576 The packages can be downloaded from
577 link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/]
579 It provides support for the new squashfs file format version 4 (as available in
580 mainline, so *not* the one being used by squashfs-lzma-tools and kernel
581 2.6.33-grml) and therefore requires kernel versions starting with
582 2.6.35-grml[64]. It supports LZMA as well as ZLIB compression. Just use the
583 defaults for enabling LZMA or use grml-live's '-z' option if you want to use
584 ZLIB compression instead.
586 * Kernel 2.6.31-grml[64]: works with ZLIB compression, fails with LZMA
587 * Kernel 2.6.33-grml[64]: works with ZLIB compression, fails with LZMA
588 * Kernel 2.6.35-grml[64]: works with ZLIB *and* LZMA compression
589 * Kernel 2.6.36-grml[64]: works with ZLIB *and* LZMA compression
592 squashfs-tools >=4.1-1 and/or squashfs-lzma-tools4 are the recommended package
593 for building up2date ISOs with grml-live! Please use other squashfs-* packages
594 only if you want to build live systems providing kernel versions older than
595 2.6.35-grml*. Use squashfs-tools >=4.1-1 or squashfs-lzma-tools4 from Grml if
596 you want to remaster any Grml releases MORE RECENT than 2010.04.
598 Using squashfs-lzma-tools 4.0-2 on the build system
599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
601 squashfs-lzma-tools 4.0-2 is available via the Grml repositories. It provides
602 the mksquashfs-lzma and unsquashfs-lzma binaries. The package does NOT conflict
603 with Debian's squashfs-tools package (you can install both of them at the same
606 The packages can be downloaded from
607 link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools/]
609 It provides support for the new squashfs file format version 4 (based on openwrt
610 patches, this is *not* the mainline file format that's being used by kernel
611 2.6.35-grml and squashfs-lzma-tools4!) and therefore requires kernel versions
612 newer than 2.6.28-grml[64]. It supports LZMA as well as ZLIB compression. Just
613 use the defaults for enabling LZMA or use grml-live's '-z' option if you want to
616 * Kernel \<=2.6.28-grml[64]: does not work
617 * Kernel 2.6.31-grml[64]: works
618 * Kernel 2.6.33-grml[64]: works
619 * Kernel 2.6.35-grml[64]: works for ZLIB compression, fails for LZMA
622 Please use squashfs-lzma-tools >=4.0-2 from Grml only if you want to remaster
623 Grml releases 2009.10 and 2010.04 or live systems with their according kernel
626 Using squashfs-tools 1:4.0-X on the build system
627 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
629 squashfs-tools >=1:4.0-1 is available in Debian/unstable and Debian/testing. It
630 provides the mksquashfs and unsquashfs binaries. The package does NOT conflict
631 neither with the squashfs-lzma-tools 4.0-2 package nor with the
632 squashfs-lzma-tools4 package (so you can install all of them at the same time).
634 The packages can be downloaded from
635 link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/]
637 It provides support for the new squashfs file format version 4 and therefore
638 requires kernel versions newer than 2.6.28-grml[64].
640 It does NOT support LZMA compression (dropped with
641 link:http://packages.debian.org/changelogs/pool/main/s/squashfs-tools/current/changelog[version
642 1:3.3-4] and not yet re-integrated yet, see
643 link:http://bugs.debian.org/594595[#594595]). If you need LZMA support please
644 use Grml's squashfs-lzma-tools[4] (see sections above) instead.
646 * Kernels \<=2.6.28-grml[64]: does not work
647 * Kernel 2.6.31-grml[64]: works (ZLIB only)
648 * Kernel 2.6.33-grml[64]: works (ZLIB only)
649 * Kernel 2.6.35-grml[64]: works (ZLIB only)
650 * Kernel 2.6.36-grml[64]: works (ZLIB only)
653 Please use squashfs-tools between 4.0-1 and 4.1-1 only if you want to remaster
654 Grml releases starting with 2009.10 using the ZLIB compression, please use other
655 squashfs packages otherwise instead.
659 Using squashfs-lzma-tools 3.3-1 on the build system
660 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
662 squashfs-lzma-tools 3.3-1 from the Grml repository supports kernel
663 2.6.26-grml[64] and 2.6.28-grml[64] using both LZMA and ZLIB (-nolzma)
666 The packages can be downloaded from
667 link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/].
670 Please use squashfs-lzma-tools 3.3-1 only if you want to remaster Grml releases
673 Using squashfs-tools 1:3.3-7 on the build system
674 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
676 squashfs-tools 1:3.3-7 is available through
677 http://grml.org/squashfs/squashfs-tools_3.3-7_i386.deb (for x86) or
678 http://grml.org/squashfs/squashfs-tools_3.3-7_amd64.deb (for amd64) [both build
679 on and for Debian/etch but working with testing and unstable as well].
681 Please notice that squashfs-tools 1:3.3-7 does NOT support LZMA compression at
682 all (so you won't be able to remaster release 2008.11 and 2009.05 using LZMA for
683 example). The -nolzma option of mksquashfs is not available therefore (even
684 though grml-live will deactivate it for you automatically anyway). Please use
685 squashfs-lzma-tools instead.
687 * Kernel 2.6.23-grml: does NOT work, please use squashfs-tools 1:3.2r2-9exp1
688 instead if you still want to use kernel 2.6.23 (not
690 * Kernel 2.6.26-grml: works (without LZMA compression only of course!)
691 * Kernel 2.6.28-grml: works (without LZMA compression only of course!)
693 Using squashfs-tools 1:3.2r2-9exp1 on the build system
694 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
696 squashfs-tools 1:3.2r2-9exp1 is available via the grml-testing repository,
699 # aptitude install squashfs-tools=1:3.2r2-9exp1
701 or directly via downloading the files
702 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_i386.deb (for x86) or
703 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_amd64.deb (for amd64).
705 Using with ZLIB compression (SQUASHFS_OPTIONS='-nolzma' or -z
706 option in grml-live cmdline):
708 * Kernel 2.6.23-grml: works
709 * Kernel 2.6.26-grml: works
710 * Kernel 2.6.28-grml: supposed to work (not verified though)
712 Using with LZMA compression:
714 * Kernel 2.6.23-grml: works
715 * Kernel 2.6.26-grml: does NOT work, please use ZLIB mode instead or switch
716 to Debian package squashfs-lzma-tools 3.3-1 (see section above).
717 * Kernel 2.6.28-grml: does NOT work, please use ZLIB mode instead or switch
718 to Debian package squashfs-lzma-tools 3.3-1 (see section above).
719 //////////////////////////////////////////////////////////////////////////////////
726 How do I deploy grml-live on a plain Debian installation?
727 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
729 The easiest way to get a running grml-live setup is to install Grml or
730 grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you
731 don't want to run it on a physical system). Of course using grml-live on a
732 plain, original Debian installation is supported as well. So there we go.
734 What we have: plain, original Debian Lenny (5.0).
736 What we want: build a grml-medium ISO based on Debian/squeeze for the i386
737 architecture using grml-live.
741 If you encounter any problems while booting the resulting ISO please be aware of
742 <<current_state,the 'current state of grml-live with squashfs-tools and kernel'
748 # adjust sources.list:
749 cat >> /etc/apt/sources.list << EOF
751 # grml stable repository:
752 deb http://deb.grml.org/ grml-stable main
753 # deb-src http://deb.grml.org/ grml-stable main
755 # grml testing/development repository:
756 deb http://deb.grml.org/ grml-testing main
757 # deb-src http://deb.grml.org/ grml-testing main
760 # adjust apt-pinning (only prefer squashfs stuff from grml):
761 cat >> /etc/apt/preferences << EOF
763 Pin: origin deb.grml.org
766 Package: squashfs-tools
767 Pin: origin deb.grml.org
771 # get keyring for apt:
773 apt-get --allow-unauthenticated install grml-debian-keyring
775 # optionally(!) install basefile so we don't have to build basic
776 # chroot from scratch, grab from http://daily.grml.org/
777 # mkdir -p /etc/grml/fai/config/basefiles/
778 # mv base.tgz /etc/grml/fai/config/basefiles/I386.tar.gz
779 # mv base64.tgz /etc/grml/fai/config/basefiles/AMD64.tar.gz
781 # install relevant tools
782 # please check out http://grml.org/grml-live/#current_state when encountering problems!
783 apt-get -o APT::Install-Recommends=false install grml-live squashfs-tools
785 # adjust grml-live configuration for our needs:
786 cat > /etc/grml/grml-live.local << EOF
787 ## want a faster build process and don't need smaller ISOs?
788 ## if so use zlib compression
789 # SQUASHFS_OPTIONS="-comp gzip -b 256k"
790 ## want to use a specific squashfs binary?
791 # SQUASHFS_BINARY='/usr/bin/mksquashfs'
792 # install local files into the chroot
793 CHROOT_INSTALL="/etc/grml/fai/chroot_install"
794 ## adjust if necessary (defaults to /grml/grml-live):
795 ## OUTPUT="/srv/grml-live"
796 FAI_DEBOOTSTRAP="squeeze http://cdn.debian.net/debian/"
798 CLASSES="GRMLBASE,GRML_MEDIUM,I386"
799 # PRESERVE_LOGFILE='1'
800 # ZERO_FAI_LOGFILE='1'
802 deb http://deb.grml.org/ grml-stable main
803 deb http://deb.grml.org/ grml-testing main
804 deb http://cdn.debian.net/debian squeeze main contrib non-free
808 # just optional(!) - upgrade FAI to latest available version:
809 cat >> /etc/apt/sources.list << EOF
811 deb http://fai-project.org/download lenny koeln
814 # get gpg key of FAI repos and install current FAI version:
815 gpg -a --recv-keys AB9B66FD; gpg -a --export AB9B66FD | apt-key add -
817 apt-get install fai-client fai-server fai-doc
819 That's it. Now invoking 'grml-live -V' should build the ISO. If everything
820 worked as expected the last line of the shell output should look like:
822 [*] Successfully finished execution of grml-live [running 687 seconds]
824 and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.
826 [[grml_fai_config_variable]]
827 What is $GRML_FAI_CONFIG?
828 ~~~~~~~~~~~~~~~~~~~~~~~~~
830 The variable '$GRML_FAI_CONFIG' is pointing to the directory /etc/grml/fai by
831 default. To provide you a maximum of flexibility you can set up your own
832 configuration directory (e.g. based on /etc/grml/fai) and use this directory
833 running grml-live with the '-D <config_dir>' option. Now '$GRML_FAI_CONFIG'
834 points to the specified directory instead of using /etc/grml/fai and all the
835 configuration files, scripts and hooks will be taken from your
836 '$GRML_FAI_CONFIG' directory.
839 I've problems with the build process. How to start debugging?
840 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
842 Check out the logs inside /var/log/fai/... If you think it's a bug in grml-live
843 send a copy of your config, logs and the commandline with a short problem
844 description to <mika@grml.org>:
846 # history | grep grml-live > /etc/grml/grml_live.cmdline
847 # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
848 /etc/grml/grml_live.cmdline /etc/grml/grml-buildd.conf \
849 /var/log/fai /etc/grml/fai
850 -> finally mail grml_live_problem.tar.gz to <mika@grml.org>
852 If you need help with grml-live or would like to see new features as part of
853 grml-live you can get commercial support via
854 link:http://grml-solutions.com/[Grml Solutions].
857 How much is the difference between LZMA and ZLIB compression?
858 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
860 ISO size (bs = blocksize):
862 [width="45%",cols="3,^2,^2"]
863 |============================================================
864 |ISO |LZMA (256kB bs) |ZLIB
865 |grml_sid |666M | 771M
866 |grml_squeeze |659M | 761M
867 |grml_lenny |624M | 723M
868 |grml64_sid |677M | 791M
869 |grml64_squeeze |671M | 785M
870 |grml64_lenny |639M | 745M
871 |grml-medium_sid |208M | 236M
872 |grml-medium_squeeze |206M | 234M
873 |grml-medium_lenny |193M | 220M
874 |grml64-medium_sid |213M | 245M
875 |grml64-medium_squeeze |213M | 244M
876 |grml64-medium_lenny |201M | 231M
877 |grml-small_sid |102M | 118M
878 |grml-small_squeeze |101M | 117M
879 |grml-small_lenny |97M | 112M
880 |grml64-small_sid |103M | 120M
881 |grml64-small_squeeze |103M | 120M
882 |grml64-small_lenny |99M | 116M
883 |============================================================
885 Build time of grml-medium's squashfs file (depends on your system, though just
886 to get the ratio between the different options):
888 * 10 minutes and 4 seconds with LZMA default blocksize (128k)
889 * 7 minutes 27 seconds with LZMA and blocksize 256k
890 * 6 minutes and 8 seconds with LZMA blocksize 512k
891 * 1 minute and 40 seconds with ZLIB
893 [[install-local-files]]
894 How do I install further files into the chroot/ISO?
895 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
897 Just point the configuration variable CHROOT_INSTALL to the directory which
898 provides the files you would like to install. Note that the files are installed
899 under '/' in the chroot - so you have to create the rootfs structure on your
902 echo "CHROOT_INSTALL=\$GRML_FAI_CONFIG/chroot_install" >> /etc/grml/grml-live.local
903 mkdir -p /etc/grml/fai/chroot_install/usr/src/
904 wget example.org/foo.tar.gz
905 mv foo.tar.gz /etc/grml/fai/chroot_install/usr/src/
908 [[local-debian-mirror]]
909 Can I use my own (local) Debian mirror?
910 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
912 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
913 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
914 your needs. Please don't forget that you should use the grml servers as well
915 (see default configuration) so all the grml packages can be downloaded as well.
917 If you want to use a local (for example NFS mount) mirror additionally, just
918 adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as
921 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
922 ${GRML_FAI_CONFIG}/apt/sources.list and ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf will be
923 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
924 files will be adjusted during runtime automatically.
926 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
927 taken as first entry in the generated sources.list so it's preferred over
928 non-local mirrors. Using a fallback mirror (via providing several mirrors in
929 GRML_LIVE_SOURCES as used by default) is a recommended setting.
931 [[add-additional-debian-packages]]
932 How do I add additional Debian package(s) to my CD/ISO?
933 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
935 Just create a new class (using the package_config directory):
937 # cat > /etc/grml/fai/config/package_config/MIKA << EOF
941 another_name_of_a_debian_package
945 and specify it when invoking grml-live then:
947 # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
949 [[reset-grml-live-configuration]]
950 I fscked up my grml-live configuration. How do I reset it to the defaults?
951 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
953 Notice: this deletes all your grml-live configuration files. If that's really
954 what you are searching for just run:
956 rm -rf /etc/grml/fai /etc/grml/grml-live.conf
957 dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
961 If you don't control your /etc using a version control system (VCS) yet it's a
962 good chance to start using it now. Check out
963 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/]
964 for more details how to maintain /etc using the mercurial VCS.
966 [[create-a-base-tgz]]
967 How do I create a base.tgz for use as NFSROOT?
968 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
970 First of all build the chroot system:
972 mkdir /tmp/nfsroot && cd /tmp/nfsroot
973 debootstrap squeeze /tmp/nfsroot/ http://cdn.debian.net/debian
976 Then check out where your NFSROOT is located:
978 # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
979 NFSROOT=/grml/fai/nfsroot
981 So as /grml/fai/nfsroot is your NFSROOT place the file under
982 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
984 mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
986 or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
987 Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
989 Now running "grml-live ..." will use this file as main system instead of
990 executing debootstrap. Check out the output for the following lines if using
994 Calling task_extrbase
995 Unpacking Debian base archive
996 Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
1000 or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
1003 ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
1004 /grml-live/grml-live_20071029.22138/grml_chroot//
1008 Existing base.tgz can be found at http://daily.grml.org/
1011 Set up apt-cacher / apt-cacher-ng for use with grml-live
1012 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1014 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
1017 # cat /etc/grml/grml-live.conf
1020 deb http://localhost:3142/deb.grml.org grml-stable main
1021 deb http://localhost:3142/deb.grml.org grml-testing main
1022 deb http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free
1025 FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free"
1027 Make sure apt-cacher / apt-cacher-ng is running ('/etc/init.d/apt-cacher
1028 restart' or '/etc/init.d/apt-cacher-ng restart'). That's it. All downloaded
1029 files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then.
1032 Set up approx for use with grml-live
1033 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1035 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
1038 # cat /etc/grml/grml-live.conf
1041 deb http://localhost:9999/grml grml-stable main
1042 deb http://localhost:9999/grml grml-testing main
1043 deb http://localhost:9999/debian squeeze main contrib non-free
1045 FAI_DEBOOTSTRAP="squeeze http://localhost:9999/debian"
1049 # cat /etc/approx/approx.conf
1051 debian http://ftp.at.debian.org/debian
1052 grml http://deb.grml.org/
1054 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
1055 All downloaded files will be cached in /var/cache/approx now.
1058 How do I revert the manifold feature from an ISO?
1059 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1061 The so called manifold feature Grml ISOs use by default allows one to use the same
1062 ISO for CD boot and USB boot. If you notice any problems when booting just
1063 revert the manifold feature running:
1065 % dd if=/dev/zero of=grml.iso bs=512 count=1 conv=notrunc
1067 To switch from manifold to isohybrid mode (an alternative approach provided by
1068 syslinux) then just execute:
1070 % isohybrid grml.iso
1073 How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz)
1074 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1076 Execute the following commands (requires root):
1078 ARCH='amd64' # replace with i386 if necessary
1079 SUITE='squeeze' # using the current stable release should always work
1080 debootstrap --arch "$ARCH" --exclude=info,tasksel,tasksel-data "$SUITE" "$ARCH" http://debian.netcologne.de/debian
1082 rm var/cache/apt/archives/*.deb
1083 tar zcf ../"${ARCH}".tar.gz *
1085 And finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note
1086 that it needs to be uppercase letters matching the class names, so: AMD64.tar.gz
1087 for amd64 and I386.tar.gz for i386).
1090 How do I set up an autobuild environment?
1091 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1093 If you want to set up a system like link:http://daily.grml.org/[daily.grml.org]
1094 the Debian package grml-live-buildd provides all you need to start. Start with
1095 figuring out the cron job script /usr/share/grml-live/buildd/cronjob.sh.
1097 If you want to automatically update the grml-live Debian package on your build
1098 system based on the git tree of grml-live (so you get bleeding edge of
1099 development which might is interesting for services like daily.grml.org) the
1100 provided release_helper.sh script provides everything you need. Execute as root:
1102 echo "deb file:/home/grml-live-git/grml-live.build-area/ ./" >> /etc/apt/sources.list.d/grml-live.list
1103 adduser --disabled-login --disabled-password grml-live-git
1105 Execute 'visudo' to update sudo configuration and add the following line:
1107 grml-live-git ALL=NOPASSWD: /usr/bin/apt-get
1109 Switch to user grml-live-git and configure the rest:
1112 mkdir grml-live.build-area
1113 git clone git://git.grml.org/grml-live.git
1114 git config --global user.name "Grml-Live Git Autobuild"
1115 git config --global user.email "grml-live-git@$(hostname)"
1117 Finally install a cron job (as user grml-live-git) like:
1119 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
1121 Tip: To find out the build date of the installed grml-live package just execute:
1123 % apt-cache policy grml-live | grep 'Installed.*autobuild'
1124 Installed: 0.13.1~autobuild1300450381
1126 and run "date -ud @$STRING" where $STRING is the number behind the "autobuild",
1129 % date -ud @1300450081
1130 Fri Mar 18 12:08:01 UTC 2011
1133 I've a question which isn't answered by this document
1134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1136 Don't hesitate to contact the author: <mika@grml.org>
1139 Download / install grml-live as a Debian package
1140 ------------------------------------------------
1142 Debian packages are available through the grml-repository at
1143 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to
1144 build a Debian package on your own (using for example a specific version or the
1145 current development tree), just execute:
1147 git clone git://git.grml.org/grml-live
1155 The source of grml-live is available at
1156 link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git]
1162 Check out the link:http://git.grml.org/?p=grml-live.git;a=blob;f=TODO;hb=HEAD[TODO file].
1168 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
1169 link:http://grml.org/contact/[to the grml-team]!
1175 The most recent grml-live documentation is available online at
1176 http://grml.org/grml-live/ and for offline reading also available
1177 in different formats:
1179 * http://grml.org/grml-live/grml-live.epub
1180 * http://grml.org/grml-live/grml-live.pdf
1185 Michael Prokop <mika@grml.org>
1187 /////////////////////////////////////
1188 // vim:ai tw=80 ft=asciidoc expandtab
1189 /////////////////////////////////////