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! This document is growing as requested. If you have questions which
19 aren't answered by this document yet please let me know: <mika@grml.org>!
20 This document currently applies to grml-live version 0.7.
21 *******************************************************************************
26 grml-live provides the build system for creating a grml and Debian based Linux
27 Live-CD. The build system is based on
28 link:http://www.informatik.uni-koeln.de/fai/[FAI] (Fully Automatic
29 Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
30 system based on the class concept of FAI (see later sections for further
31 details) and provides the framework to be able to generate a full-featured ISO.
32 It does not use all the FAI features by default though and you don't have to
33 know FAI to be able to use it.
35 The use of FAI gives you the flexibility to choose the packages you would like
36 to include on your very own Linux Live-CD without having to deal with all the
37 details of a build process.
39 CAUTION: grml-live does **not** use /etc/fai for configuration but instead
40 provides and uses /etc/grml/fai. This ensures that it does not clash with
41 default FAI configuration and packages, so you can use grml-live and FAI
42 completely independent at the same time!
46 Please notice that you should have a fast network connection as all the Debian
47 packages will be downloaded and installed via network. If you want to use a
48 local mirror (strongly recommended if you plan to use grml-live more than once)
49 checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
50 debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
51 sample configuration), apt-cacher(1) and approx(8). To avoid downloading the
52 base system again and again check out FAI's NFSROOT (see FAQ of this document
60 Use the specified architecture instead of the currently running one. This
61 allows building a 32bit system on a 64bit host (though you can't build a 64bit
62 system on a 32bit system/kernel of course). Please notice that real
63 crosscompiling (like building a ppc system on x86) isn't possible due to the
64 nature and the need of working in a chroot. Currently supported values: i386
69 Build the ISO without updating the chroot via FAI. This option is useful for
70 example when working on stable releases: if you have a working base
71 system/chroot and do not want to execute any further updates (via "-u" option)
72 but intend to only build the ISO.
76 Specify the CLASSES to be used for building the ISO via FAI. By default only
77 the classes GRMLBASE, GRML_SMALL and I386 are assumed, resulting in a small base
78 system (being about ~150MB total ISO size). If using a non-I386 system (like
79 amd64) you should specify the appropriate architecture as well. Additionally you
80 can specify a class providing a grml-kernel (see
81 /etc/grml/fai/config/package_config/ for a full list). So instead of GRML_SMALL
82 you can also use GRML_MEDIUM and GRML_FULL instead.
84 -C **CONFIGURATION_FILE**::
86 The specified file is used as configuration file for grml-live. By default
87 /etc/grml/grml-live.conf is used for main configuration. If a file named
88 /etc/grml/grml-live.local exists it is used as well (sourced after reading
89 /etc/grml/grml-live.conf to allow overriding settings). As a last option the
90 specified configuration file is sourced so it is possible to override settings
91 of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local. Please
92 notice that all configuration files have to be adjusted during execution of
93 grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
94 your own configuration file. Please also notice that the configuration file
95 specified via this option is **not** (yet) supported inside the
96 scripts/hooks/classes at /etc/grml/fai/config. Instead use
97 /etc/grml/grml-live.conf and/or /etc/grml/grml-live.local for configuration
98 stuff used inside /etc/grml/fai/config.
102 Force execution and do not prompt for acknowledgment of configuration.
106 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
107 Please do NOT use blanks and any characters like '-', '/', ';' inside GRML_NAME,
108 otherwise you might notice problems with booting.
112 Display short usage information and exit.
116 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
119 -o **OUTPUT_DIRECTORY**::
121 Main output directory of the build process of FAI. Some directories are created
122 inside this target directory, being: grml_cd (where the files for creating the
123 ISO are located, including the compressed squashfs file), grml_chroot (the
124 chroot system) and grml_isos (where the resulting ISO is stored).
128 Specify name of the release.
132 Specify the Debian suite you want to use for your live-system. Defaults to
133 "etch" (being current Debian/stable). Supported values are: etch, lenny, sid.
135 -t **TEMPLATE_DIRECTORY**::
137 Specify place of the templates used for building the ISO. By default
138 (and if not manually specified) this is /usr/share/grml-live/templates/.
142 Update existing chroot instead of rebuilding it from scratch. This option is
143 based on the softupdate feature of FAI.
145 -v **VERSION_NUMBER**::
147 Specify version number of the release.
151 Increase verbosity in the build process.
155 Use ZLIB instead of LZMA compression in mksquashfs part of the build process.
160 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
161 as build and output directory just run:
165 To get a small Debian-unstable and grml-small based Live-CD using
166 /home/mika/grml-live as build and output directory just use:
168 # grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
170 To get a medium sized, Debian-unstable and grml-based Live-CD for i386
171 architecture using /grml/grml-live as build and output directory just run:
173 # grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
175 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
176 output directory and use grml_0.0-3.iso as ISO name (placed inside
177 /tmp/grml_isos) just invoke:
179 # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
183 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
184 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
185 and use /dev/shm as build and output directory - resulting in very fast build
186 process. But please be aware of the fact that rebooting your system will result
187 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
188 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
190 Main features of grml-live
191 --------------------------
193 * create a grml-/Debian-based Linux Live-CD with one single command
195 * class based concept, providing a maximum of flexibility
197 * supports integration of own hooks, scripts and configuration
199 * supports use and integration of own Software and/or Kernels via simple use of
202 * native support of FAI features
204 * multi-arch support (work in progress)
209 grml-live uses FAI and its class based concept for adjusting configuration and
210 setup according to your needs. This gives you flexibility and strength without
211 losing the simplicity in the build process.
213 The main and base class provided by grml-live is named GRMLBASE. It's strongly
214 recommended to **always** use the class GRMLBASE when building an ISO using
215 grml-live, as well as the architecture dependent class which provides the kernel
216 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
217 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
218 relevant for class GRMLBASE by default:
220 /etc/grml/fai/config/scripts/GRMLBASE/
221 /etc/grml/fai/config/debconf/GRMLBASE
222 /etc/grml/fai/config/class/GRMLBASE.var
223 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
224 /etc/grml/fai/config/package_config/GRMLBASE
226 Take a look at the next section for information about the concept of those
229 If you want to use your own configuration, extend an existing configuration
230 and/or add additional packages to your ISO just invent a new class (or extend an
231 existing one). For example if you want to use your own class named "FOOBAR" just
232 extend CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.conf to
233 CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" or invoke grml-live using the classes
234 option: "grml-live -c GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
236 More details regarding the class concept can be found in the documentation of
237 FAI itself (being available at /usr/share/doc/fai-doc/).
242 Documentation to be done...
247 Notice that grml-live ships FAI configuration files that do not use the same
248 namespace as the FAI packages itself. This ensures that grml-live does not clash
249 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
250 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
251 below. To get an idea how another configuration or example files could look like
252 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
253 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
254 provides documentation regarding configuration possibilities.
258 Script for the main build process. Requires root permissions for execution.
260 /etc/grml/grml-live.conf
262 Main configuration file for grml-live. All the important steps can be configured
265 /etc/grml/fai/fai.conf
267 Main configuration file for FAI which specifies where all the configuration
268 files and scripts for FAI/grml-live can be found. By default it is set to
269 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
270 out-of-the-box so you shouldn't have to configure anything in this file.
272 /etc/grml/fai/make-fai-nfsroot.conf
274 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
275 anything inside this file. If you want to modify NFSROOT though you can adjust
278 /etc/grml/fai/NFSROOT
280 This file specifies the package list for creating the NFSROOT.
282 /etc/grml/fai/apt/sources.list
284 This file specifies which mirrors should be used for retreiving the Debian
285 packages used for creating the main chroot (including all the software you would
286 like to see included). If you want to use a local mirror you either have to
287 adjust this file or use the GRML_LIVE_SOURCES variable inside
288 /etc/grml/grml-live.conf which modifies /etc/grml/fai/apt/sources.list
291 /etc/grml/fai/config/
293 The main directory for configuration of FAI/grml-live. More details below.
295 /etc/grml/fai/config/class/
297 This directory contains files which specify main configuration variables for the
300 /etc/grml/fai/config/debconf/
302 This directory provides the files for preseeding/configuration of debconf
305 /etc/grml/fai/config/hooks/
307 This directory provides files for customising the build process through hooks.
308 Hooks are user defined programs or scripts, which are called during the
309 installation process.
311 /etc/grml/fai/config/package_config/
313 Directory with lists of software packages to be installed or removed. The
314 different classes describe what should find its way to your ISO. When running
315 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
316 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
317 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
318 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
319 adjust the package selection according to your needs. Please notice that the
320 directory GRMLBASE contains a package list defining a minimum but still
321 reasonable package configuration.
323 /etc/grml/fai/config/scripts/
325 Scripts for customising the ISO within the build process.
329 This directory provides files used inside the scripts of
330 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
331 files please refer to the source of the scripts.
333 /etc/grml/fai/live-initramfs/
335 This directory provides the files used for building the initramfs/initrd via
341 grml-live itself logs to /var/log/grml-live.log. Unless you set ZERO_LOGFILE in
342 /etc/grml/grml-live.conf the output is appended to the file. If you set the
343 ZERO_LOGFILE configuration option the logfile will be truncated on each new
344 invocation of grml-live.
346 The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the
347 default being /var/log/fai/grml/.
349 If you are using the grml-live buildd you will find the logs of the grml-live
350 run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
352 Requirements for the build system
353 ---------------------------------
355 * any Debian based system should be sufficient (if not it's a bug, so please
356 send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
357 harddisk installation ships all you need]
359 * enough free disk space; at least 800MB are required for a minimal grml-live
360 run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
361 [$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
362 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
363 total free disk space
365 * fast network access for retreiving the Debian packages used for creating the
366 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
372 Help, I'm using Debian etch and I don't have FAI version >3.2
373 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
375 wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.5_all.deb \
376 http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.5_all.deb \
377 http://www.informatik.uni-koeln.de/fai/download/etch/fai-doc_3.2.5_all.deb
378 dpkg -i fai-client_3.2.5_all.deb fai-server_3.2.5_all.deb fai-doc_3.2.5_all.deb
380 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
383 I've problems with the build process. How to start debugging?
384 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
386 Check out the logs inside /var/log/fai/... If you don't have the time to debug
387 the problem in further detail or don't know how to proceed just send a copy of
388 your config, logs and the commandline with a short problem description to
391 # history | grep grml-live > /etc/grml/grml_live.cmdline
392 # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
393 /etc/grml/grml-buildd.conf /var/log/fai /etc/grml/fai
395 Can I use my own (local) Debian mirror?
396 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
398 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
399 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
400 your needs. Please don't forget that you should use the grml servers as well
401 (see default configuration) so all the grml packages can be downloaded as well.
403 If you want to use a local (for example NFS mount) mirror additionally, just
404 adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as
407 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
408 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
409 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
410 files will be adjusted during runtime automatically.
412 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
413 taken as first entry in the generated sources.list so it's prefered over
414 non-local mirrors. Using a fallback mirror (via providing several mirrors in
415 GRML_LIVE_SOURCES as used by default) is a recommended setting.
417 How do I add additional Debian package(s) to my CD/ISO?
418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
420 Just create a new class (using the package_config directory):
422 # cat > /etc/grml/fai/config/package_config/MIKA << EOF
426 another_name_of_a_debian_package
430 and specify it when invoking grml-live then:
432 # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
434 I fscked up my grml-live configuration. How do I reset it to the defaults?
435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
437 Notice: this deletes all your grml-live configuration files. If that's really
438 what you are searching for just run:
440 rm -rf /etc/grml/fai /etc/grml/grml-live.conf
441 dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
445 If you don't control your /etc using a version control system (VCS) yet it's a
446 good chance to start using it now. Check out
447 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/]
448 for more details how to maintain /etc using the mercurial VCS.
450 How do I create a base.tgz for use as NFSROOT?
451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
453 First of all build the chroot system:
455 mkdir /tmp/nfsroot && cd /tmp/nfsroot
456 debootstrap etch /tmp/nfsroot/ http://ftp.de.debian.org/debian
459 Then check out where your NFSROOT is located:
461 # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
462 NFSROOT=/grml/fai/nfsroot
464 So as /grml/fai/nfsroot is your NFSROOT place the file under
465 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
467 mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
469 or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
470 Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
472 Now running "grml-live ..." will use this file as main system instead of
473 executing debootstrap. Check out the output for the following lines if using
477 Calling task_extrbase
478 Unpacking Debian base archive
479 Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
483 or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
486 ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
487 /grml-live/grml-live_20071029.22138/grml_chroot//
490 Set up apt-cacher for use with grml-live
491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
493 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
496 # cat /etc/grml/grml-live.conf
499 deb http://localhost:3142/deb.grml.org grml-stable main
500 deb http://localhost:3142/deb.grml.org grml-testing main
501 deb http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free
504 FAI_DEBOOTSTRAP="etch http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free"
506 Make sure apt-cacher is running (/etc/init.d/apt-cacher restart). That's it.
507 All downloaded files will be cached in /var/cache/apt-cacher/ now.
509 Set up approx for use with grml-live
510 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
512 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
515 # cat /etc/grml/grml-live.conf
518 deb http://localhost:9999/grml grml-stable main
519 deb http://localhost:9999/grml grml-testing main
520 deb http://localhost:9999/debian etch main contrib non-free
522 FAI_DEBOOTSTRAP="etch http://localhost:9999/debian"
526 # cat /etc/approx/approx.conf
528 debian http://ftp.at.debian.org/debian
529 grml http://deb.grml.org/
531 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
532 All downloaded files will be cached in /var/cache/approx now.
534 I've a question which isn't answered by this document
535 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
537 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
538 a mail: <mika@grml.org>
540 Download / install grml-live as a Debian package
541 ------------------------------------------------
543 Debian packages are available through the grml-repository at
544 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to
545 build a Debian package on your own (using for example a specific version or the
546 current development tree), just execute:
548 hg clone http://hg.grml.org/grml-live
555 The source of grml-live is available at
556 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
561 Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
567 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
568 link:http://grml.org/contact/[to the grml-team]!
572 Michael Prokop <mika@grml.org>.
574 /////////////////////////////////////
575 // vim:ai tw=80 ft=asciidoc expandtab
576 /////////////////////////////////////