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]>] [-g <grml_name>] [-i <iso_name> ]
14 [-o <output_directory>] [-r <release_name>] [-s <suite>] [-t
15 <template_directory>] [-v <version_number>] [-bFVhuz]
17 *******************************************************************************
18 Important: squashfs-tools in Debian (version 1:3.3-6 for example) currently
19 don't work as expected for grml-live. Please install grml's version 1:3.2r2-9exp1 from
20 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_i386.deb (for x86) or
21 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_amd64.deb (for amd64)
22 on your build-system instead.
23 *******************************************************************************
25 *******************************************************************************
26 Notice! This document is growing as requested. If you have questions which
27 aren't answered by this document yet please let me know: <mika@grml.org>!
28 *******************************************************************************
33 grml-live provides the build system for creating a grml and Debian based Linux
34 Live-CD. The build system is based on
35 link:http://www.informatik.uni-koeln.de/fai/[FAI] (Fully Automatic
36 Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
37 system based on the class concept of FAI (see later sections for further
38 details) and provides the framework to be able to generate a full-featured ISO.
39 It does not use all the FAI features by default though and you don't have to
40 know FAI to be able to use it.
42 The use of FAI gives you the flexibility to choose the packages you would like
43 to include on your very own Linux Live-CD without having to deal with all the
44 details of a build process.
46 CAUTION: grml-live does **not** use /etc/fai for configuration but instead
47 provides and uses /etc/grml/fai. This ensures that it does not clash with
48 default FAI configuration and packages, so you can use grml-live and FAI
49 completely independent at the same time!
53 Please notice that you should have a fast network connection as all the Debian
54 packages will be downloaded and installed via network. If you want to use a
55 local mirror (strongly recommended if you plan to use grml-live more than once)
56 checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
57 debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
58 sample configuration), apt-cacher(1) and approx(8). To avoid downloading the
59 base system again and again check out FAI's NFSROOT (see FAQ of this document
67 Use the specified architecture instead of the currently running one. This
68 allows building a 32bit system on a 64bit host (though you can't build a 64bit
69 system on a 32bit system/kernel of course). Please notice that real
70 crosscompiling (like building a ppc system on x86) isn't possible due to the
71 nature and the need of working in a chroot. Currently supported values: i386
76 Build the ISO without updating the chroot via FAI. This option is useful for
77 example when working on stable releases: if you have a working base
78 system/chroot and do not want to execute any further updates (via "-u" option)
79 but intend to only build the ISO.
83 Specify the CLASSES to be used for building the ISO via FAI. By default only
84 the classes GRMLBASE, GRML_SMALL and I386 are assumed, resulting in a small base
85 system (being about ~150MB total ISO size). If using a non-I386 system (like
86 amd64) you should specify the appropriate architecture as well. Additionally you
87 can specify a class providing a grml-kernel (see
88 <<X7,the 'CLASSES' section in this document>> for details about available classes).
89 So instead of GRML_SMALL you can also use GRML_MEDIUM and GRML_FULL.
91 -C **CONFIGURATION_FILE**::
93 The specified file is used as configuration file for grml-live. By default
94 /etc/grml/grml-live.conf is used for main configuration. If a file named
95 /etc/grml/grml-live.local exists it is used as well (sourced after reading
96 /etc/grml/grml-live.conf to allow overriding settings). As a last option the
97 specified configuration file is sourced so it is possible to override settings
98 of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local. Please
99 notice that all configuration files have to be adjusted during execution of
100 grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
101 your own configuration file. Please also notice that the configuration file
102 specified via this option is **not** (yet) supported inside the
103 scripts/hooks/classes at /etc/grml/fai/config. Instead use
104 /etc/grml/grml-live.conf and/or /etc/grml/grml-live.local for configuration
105 stuff used inside /etc/grml/fai/config.
109 Force execution and do not prompt for acknowledgment of configuration.
113 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
114 Please do NOT use blanks and any special characters like '/', ';' inside
115 GRML_NAME, otherwise you might notice problems with booting.
119 Display short usage information and exit.
123 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
126 -o **OUTPUT_DIRECTORY**::
128 Main output directory of the build process of FAI. Some directories are created
129 inside this target directory, being: grml_cd (where the files for creating the
130 ISO are located, including the compressed squashfs file), grml_chroot (the
131 chroot system) and grml_isos (where the resulting ISO is stored).
135 Specify name of the release.
139 Specify the Debian suite you want to use for your live-system. Defaults to
140 "etch" (being current Debian/stable). Supported values are: etch, lenny, sid.
142 -t **TEMPLATE_DIRECTORY**::
144 Specify place of the templates used for building the ISO. By default
145 (and if not manually specified) this is /usr/share/grml-live/templates/.
149 Update existing chroot instead of rebuilding it from scratch. This option is
150 based on the softupdate feature of FAI.
152 -v **VERSION_NUMBER**::
154 Specify version number of the release.
158 Increase verbosity in the build process.
162 Use ZLIB instead of LZMA compression in mksquashfs part of the build process.
167 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
168 as build and output directory just run:
172 To get a small Debian-unstable and grml-small based Live-CD using
173 /home/mika/grml-live as build and output directory just use:
175 # grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
177 To get a medium sized, Debian-unstable and grml-based Live-CD for i386
178 architecture using /grml/grml-live as build and output directory just run:
180 # grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
182 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
183 output directory and use grml_0.0-3.iso as ISO name (placed inside
184 /tmp/grml_isos) just invoke:
186 # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
190 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
191 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
192 and use /dev/shm as build and output directory - resulting in very fast build
193 process. But please be aware of the fact that rebooting your system will result
194 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
195 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
197 Main features of grml-live
198 --------------------------
200 * create a grml-/Debian-based Linux Live-CD with one single command
202 * class based concept, providing a maximum of flexibility
204 * supports integration of own hooks, scripts and configuration
206 * supports use and integration of own Software and/or Kernels via simple use of
209 * native support of FAI features
211 * multi-arch support (work in progress)
216 grml-live uses FAI and its class based concept for adjusting configuration and
217 setup according to your needs. This gives you flexibility and strength without
218 losing the simplicity in the build process.
220 The main and base class provided by grml-live is named GRMLBASE. It's strongly
221 recommended to **always** use the class GRMLBASE when building an ISO using
222 grml-live, as well as the architecture dependent class which provides the kernel
223 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
224 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
225 relevant for class GRMLBASE by default:
227 /etc/grml/fai/config/scripts/GRMLBASE/
228 /etc/grml/fai/config/debconf/GRMLBASE
229 /etc/grml/fai/config/class/GRMLBASE.var
230 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
231 /etc/grml/fai/config/package_config/GRMLBASE
233 Take a look at the next section for information about the concept of those
236 If you want to use your own configuration, extend an existing configuration
237 and/or add additional packages to your ISO just invent a new class (or extend an
238 existing one). For example if you want to use your own class named "FOOBAR" just
239 extend CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.conf to
240 CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" or invoke grml-live using the classes
241 option: "grml-live -c GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
243 More details regarding the class concept can be found in the documentation of
244 FAI itself (being available at /usr/share/doc/fai-doc/).
250 The package selection part of the classes can be found in
251 /etc/grml/fai/config/package_config whereas some further classes are defined for
252 example in /etc/grml/fai/config/scripts/ so specific feature sets can be
253 selected. The following classes are predefined:
256 * GRMLBASE: the main class responsible for getting a minimal subset of what's
257 defining a grml system. Important parts of the buildprocess are specified in
258 this class as well, so unless you have a really good reason you should always
260 * GRML_FORENSIC: tools for forensic investigations which has been created
261 by people from link:http://www.forensic-geeks.org/[forensic-geeks.org].
262 * GRML_FULL: full featured grml, also know as the "normal", full grml.
276 Notice that grml-live ships FAI configuration files that do not use the same
277 namespace as the FAI packages itself. This ensures that grml-live does not clash
278 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
279 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
280 below. To get an idea how another configuration or example files could look like
281 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
282 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
283 provides documentation regarding configuration possibilities.
287 Script for the main build process. Requires root permissions for execution.
289 /etc/grml/grml-live.conf
291 Main configuration file for grml-live. All the important steps can be configured
294 /etc/grml/fai/fai.conf
296 Main configuration file for FAI which specifies where all the configuration
297 files and scripts for FAI/grml-live can be found. By default it is set to
298 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
299 out-of-the-box so you shouldn't have to configure anything in this file.
301 /etc/grml/fai/make-fai-nfsroot.conf
303 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
304 anything inside this file. If you want to modify NFSROOT though you can adjust
307 /etc/grml/fai/NFSROOT
309 This file specifies the package list for creating the NFSROOT.
311 /etc/grml/fai/apt/sources.list
313 This file specifies which mirrors should be used for retreiving the Debian
314 packages used for creating the main chroot (including all the software you would
315 like to see included). If you want to use a local mirror you either have to
316 adjust this file or use the GRML_LIVE_SOURCES variable inside
317 /etc/grml/grml-live.conf which modifies /etc/grml/fai/apt/sources.list
320 /etc/grml/fai/config/
322 The main directory for configuration of FAI/grml-live. More details below.
324 /etc/grml/fai/config/class/
326 This directory contains files which specify main configuration variables for the
329 /etc/grml/fai/config/debconf/
331 This directory provides the files for preseeding/configuration of debconf
334 /etc/grml/fai/config/hooks/
336 This directory provides files for customising the build process through hooks.
337 Hooks are user defined programs or scripts, which are called during the
338 installation process.
340 /etc/grml/fai/config/package_config/
342 Directory with lists of software packages to be installed or removed. The
343 different classes describe what should find its way to your ISO. When running
344 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
345 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
346 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
347 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
348 adjust the package selection according to your needs. Please notice that the
349 directory GRMLBASE contains a package list defining a minimum but still
350 reasonable package configuration.
352 /etc/grml/fai/config/scripts/
354 Scripts for customising the ISO within the build process.
358 This directory provides files used inside the scripts of
359 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
360 files please refer to the source of the scripts.
362 /etc/grml/fai/live-initramfs/
364 This directory provides the files used for building the initramfs/initrd via
370 grml-live itself logs to /var/log/grml-live.log. Unless you set ZERO_LOGFILE in
371 /etc/grml/grml-live.conf the output is appended to the file. If you set the
372 ZERO_LOGFILE configuration option the logfile will be truncated on each new
373 invocation of grml-live.
375 The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the
376 default being /var/log/fai/grml/.
378 If you are using the grml-live buildd you will find the logs of the grml-live
379 run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
381 Requirements for the build system
382 ---------------------------------
384 * any Debian based system should be sufficient (if not it's a bug, so please
385 send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
386 harddisk installation ships all you need]
388 * enough free disk space; at least 800MB are required for a minimal grml-live
389 run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
390 [$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
391 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
392 total free disk space
394 * fast network access for retreiving the Debian packages used for creating the
395 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
401 Help, I'm using Debian etch and I don't have FAI version >3.2
402 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
404 wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.6_all.deb \
405 http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.6_all.deb \
406 http://www.informatik.uni-koeln.de/fai/download/etch/fai-doc_3.2.6_all.deb
407 dpkg -i fai-client_3.2.6_all.deb fai-server_3.2.6_all.deb fai-doc_3.2.6_all.deb
409 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
412 I've problems with the build process. How to start debugging?
413 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
415 Check out the logs inside /var/log/fai/... If you don't have the time to debug
416 the problem in further detail or don't know how to proceed just send a copy of
417 your config, logs and the commandline with a short problem description to
420 # history | grep grml-live > /etc/grml/grml_live.cmdline
421 # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
422 /etc/grml/grml-buildd.conf /var/log/fai /etc/grml/fai
424 Can I use my own (local) Debian mirror?
425 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
427 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
428 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
429 your needs. Please don't forget that you should use the grml servers as well
430 (see default configuration) so all the grml packages can be downloaded as well.
432 If you want to use a local (for example NFS mount) mirror additionally, just
433 adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as
436 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
437 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
438 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
439 files will be adjusted during runtime automatically.
441 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
442 taken as first entry in the generated sources.list so it's prefered over
443 non-local mirrors. Using a fallback mirror (via providing several mirrors in
444 GRML_LIVE_SOURCES as used by default) is a recommended setting.
446 How do I add additional Debian package(s) to my CD/ISO?
447 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
449 Just create a new class (using the package_config directory):
451 # cat > /etc/grml/fai/config/package_config/MIKA << EOF
455 another_name_of_a_debian_package
459 and specify it when invoking grml-live then:
461 # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
463 I fscked up my grml-live configuration. How do I reset it to the defaults?
464 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
466 Notice: this deletes all your grml-live configuration files. If that's really
467 what you are searching for just run:
469 rm -rf /etc/grml/fai /etc/grml/grml-live.conf
470 dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
474 If you don't control your /etc using a version control system (VCS) yet it's a
475 good chance to start using it now. Check out
476 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/]
477 for more details how to maintain /etc using the mercurial VCS.
479 How do I create a base.tgz for use as NFSROOT?
480 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
482 First of all build the chroot system:
484 mkdir /tmp/nfsroot && cd /tmp/nfsroot
485 debootstrap etch /tmp/nfsroot/ http://ftp.de.debian.org/debian
488 Then check out where your NFSROOT is located:
490 # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
491 NFSROOT=/grml/fai/nfsroot
493 So as /grml/fai/nfsroot is your NFSROOT place the file under
494 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
496 mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
498 or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
499 Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
501 Now running "grml-live ..." will use this file as main system instead of
502 executing debootstrap. Check out the output for the following lines if using
506 Calling task_extrbase
507 Unpacking Debian base archive
508 Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
512 or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
515 ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
516 /grml-live/grml-live_20071029.22138/grml_chroot//
519 Set up apt-cacher for use with grml-live
520 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
522 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
525 # cat /etc/grml/grml-live.conf
528 deb http://localhost:3142/deb.grml.org grml-stable main
529 deb http://localhost:3142/deb.grml.org grml-testing main
530 deb http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free
533 FAI_DEBOOTSTRAP="etch http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free"
535 Make sure apt-cacher is running (/etc/init.d/apt-cacher restart). That's it.
536 All downloaded files will be cached in /var/cache/apt-cacher/ now.
538 Set up approx for use with grml-live
539 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
541 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
544 # cat /etc/grml/grml-live.conf
547 deb http://localhost:9999/grml grml-stable main
548 deb http://localhost:9999/grml grml-testing main
549 deb http://localhost:9999/debian etch main contrib non-free
551 FAI_DEBOOTSTRAP="etch http://localhost:9999/debian"
555 # cat /etc/approx/approx.conf
557 debian http://ftp.at.debian.org/debian
558 grml http://deb.grml.org/
560 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
561 All downloaded files will be cached in /var/cache/approx now.
563 I've a question which isn't answered by this document
564 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
566 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
567 a mail: <mika@grml.org>
569 Download / install grml-live as a Debian package
570 ------------------------------------------------
572 Debian packages are available through the grml-repository at
573 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to
574 build a Debian package on your own (using for example a specific version or the
575 current development tree), just execute:
577 hg clone http://hg.grml.org/grml-live
584 The source of grml-live is available at
585 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
590 Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
596 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
597 link:http://grml.org/contact/[to the grml-team]!
601 Michael Prokop <mika@grml.org>.
603 /////////////////////////////////////
604 // vim:ai tw=80 ft=asciidoc expandtab
605 /////////////////////////////////////