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>] [-FVhu]
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.0.6.
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. 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.
67 Specify the CLASSES to be used for building the ISO via FAI. By default only
68 the classes GRMLBASE, GRML_SMALL and I386 are assumed, resulting in a small base
69 system (being about ~150MB total ISO size). If using a non-I386 system (like
70 amd64) you should specify the appropriate architecture as well. Additionally you
71 can specify a class providing a grml-kernel (see
72 /etc/grml/fai/config/package_config/ for a full list). So instead of GRML_SMALL
73 you can also use GRML_MEDIUM and GRML_FULL instead.
77 Force execution and do not prompt for acknowledgment of configuration.
81 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
85 Display short usage information and exit.
89 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
92 -o **OUTPUT_DIRECTORY**::
94 Main output directory of the build process of FAI. Some directories are created
95 inside this target directory, being: grml_cd (where the files for creating the
96 ISO are located, including the compressed squashfs file), grml_chroot (the
97 chroot system) and grml_isos (where the resulting ISO is stored).
101 Specify name of the release.
105 Specify the Debian suite you want to use for your live-system. Defaults to
106 "etch" (being current Debian/stable). Supported values are: etch, lenny, sid.
108 -t **TEMPLATE_DIRECTORY**::
110 Specify place of the templates used for building the ISO. By default
111 (and if not manually specified) this is /usr/share/grml-live/templates/.
115 Update existing chroot instead of rebuilding it from scratch. This option is
116 based on the softupdate feature of FAI.
118 -v **VERSION_NUMBER**::
120 Specify version number of the release.
124 Increase verbosity in the build process.
129 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
130 as build and output directory just run:
134 To get a small Debian-unstable and grml-small based Live-CD using
135 /home/mika/grml-live as build and output directory just use:
137 # grml-live -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
139 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
140 output directory and use grml_0.0-3.iso as ISO name (placed inside
141 /tmp/grml_isos) just invoke:
143 # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
147 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
148 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
149 and use /dev/shm as build and output directory - resulting in very fast build
150 process. But please be aware of the fact that rebooting your system will result
151 in an empty /dev/shm, so please another directory for $CHROOT_OUTPUT,
152 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
154 Main features of grml-live
155 --------------------------
157 * create a grml-/Debian-based Linux Live-CD with one single command
159 * class based concept, providing a maximum of flexibility
161 * supports integration of own hooks, scripts and configuration
163 * supports use and integration of own Software and/or Kernels via simple use of
166 * native support of FAI features
168 * multi-arch support (work in progress)
173 grml-live uses FAI and its class based concept for adjusting configuration and
174 setup according to your needs. This gives you flexibility and strength without
175 losing the simplicity in the build process.
177 The main and base class provided by grml-live is named GRMLBASE. It's strongly
178 recommended to **always** use the class GRMLBASE when building an ISO using
179 grml-live, as well as the architecture dependent class which provides the kernel
180 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
181 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
182 relevant for class GRMLBASE by default:
184 /etc/grml/fai/config/scripts/GRMLBASE/
185 /etc/grml/fai/config/debconf/GRMLBASE
186 /etc/grml/fai/config/class/GRMLBASE.var
187 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
188 /etc/grml/fai/config/package_config/GRMLBASE
190 Take a look at the next section for information about the concept of those
193 If you want to use your own configuration, extend an existing configuration
194 and/or add additional packages to your ISO just invent a new class (or extend an
195 existing one). For example if you want to use your own class named "FOOBAR" just
196 extend CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.conf to
197 CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" or invoke grml-live using the classes
198 option: "grml-live -c GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
200 More details regarding the class concept can be found in the documentation of
201 FAI itself (being available at /usr/share/doc/fai-doc/).
206 Documentation to be done...
211 Notice that grml-live ships FAI configuration files that do not use the same
212 namespace as the FAI packages itself. This ensures that grml-live does not clash
213 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
214 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
215 below. To get an idea how another configuration or example files could look like
216 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
217 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
218 provides documentation regarding configuration possibilities.
222 Script for the main build process. Requires root permissions for execution.
224 /etc/grml/grml-live.conf
226 Main configuration file for grml-live. All the important steps can be configured
229 /etc/grml/fai/fai.conf
231 Main configuration file for FAI which specifies where all the configuration
232 files and scripts for FAI/grml-live can be found. By default it is set to
233 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
234 out-of-the-box so you shouldn't have to configure anything in this file.
236 /etc/grml/fai/make-fai-nfsroot.conf
238 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
239 anything inside this file. If you want to modify NFSROOT though you can adjust
242 /etc/grml/fai/NFSROOT
244 This file specifies the package list for creating the NFSROOT.
246 /etc/grml/fai/apt/sources.list
248 This file specifies which mirrors should be used for retreiving the Debian
249 packages used for creating the main chroot (including all the software you would
250 like to see included). If you want to use a local mirror you either have to
251 adjust this file or use the GRML_LIVE_SOURCES variable inside
252 /etc/grml/grml-live.conf which modifies /etc/grml/fai/apt/sources.list
255 /etc/grml/fai/config/
257 The main directory for configuration of FAI/grml-live. More details below.
259 /etc/grml/fai/config/class/
261 This directory contains files which specify main configuration variables for the
264 /etc/grml/fai/config/debconf/
266 This directory provides the files for preseeding/configuration of debconf
269 /etc/grml/fai/config/hooks/
271 This directory provides files for customising the build process through hooks.
272 Hooks are user defined programs or scripts, which are called during the
273 installation process.
275 /etc/grml/fai/config/package_config/
277 Directory with lists of software packages to be installed or removed. The
278 different classes describe what should find its way to your ISO. When running
279 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
280 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
281 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
282 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
283 adjust the package selection according to your needs. Please notice that the
284 directory GRMLBASE contains a package list defining a minimum but still
285 reasonable package configuration.
287 /etc/grml/fai/config/scripts/
289 Scripts for customising the ISO within the build process.
293 This directory provides files used inside the scripts of
294 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
295 files please refer to the source of the scripts.
297 /etc/grml/fai/live-initramfs/
299 This directory provides the files used for building the initramfs/initrd via
305 grml-live itself logs to /var/log/grml-live.log. Unless you set ZERO_LOGFILE in
306 /etc/grml/grml-live.conf the output is appended to the file. If you set the
307 ZERO_LOGFILE configuration option the logfile will be truncated on a new
308 invocation of grml-live.
310 The FAI part of grml-live logs to /var/log/fai/dirinstall/$HOSTNAME - so the
311 default being /var/log/fai/dirinstall/grml.
313 If you are using the update option of grml-live (option -u) the logs are
314 available at /var/log/fai/current.
316 Requirements for the build system
317 ---------------------------------
319 * any Debian based system should be sufficient (if not it's a bug, so please
320 send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
321 harddisk installation ships all you need]
323 * enough free disk space; at least 800MB are required for a minimal grml-live
324 run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
325 [$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
326 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
327 total free disk space
329 * fast network access for retreiving the Debian packages used for creating the
330 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
336 Help, I'm using Debian etch and I don't have FAI version >3.2
337 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
339 wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.1_all.deb \
340 http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.1_all.deb
341 dpkg -i fai-client_3.2.1_all.deb fai-server_3.2.1_all.deb
343 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
346 I've problems with the build process. How to start debugging?
347 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
349 Check out the logs inside /var/log/fai/dirinstall/... If you don't have the time
350 to debug the problem in further detail or don't know how to proceed just send a
351 copy of your config, logs and the commandline with a short problem description
354 # history | grep grml-live > /etc/grml/grml_live.cmdline
355 # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
356 /var/log/fai/dirinstall /etc/grml/fai
358 Can I use my own (local) Debian mirror?
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
361 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
362 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
363 your needs. Please don't forget that you should use the grml servers as well
364 (see default configuration) so all the grml packages can be downloaded as well.
366 If you want to use a local (for example NFS mount) mirror additionally, just
367 adjust MIRROR_DIRECTORY and MIRROR_SOURCES insede /etc/grml/grml-live.conf as
370 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
371 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
372 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
373 files will be adjusted during runtime automatically.
375 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
376 taken as first entry in the generated sources.list so it's prefered over
377 non-local mirrors. Using a fallback mirror (via providing several mirrors in
378 GRML_LIVE_SOURCES as used by default) is a recommended setting.
380 How do I add additional Debian package(s) to my CD/ISO?
381 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
383 Just create a new class (using the package_config directory):
385 # cat > /etc/grml/fai/config/package_config/MIKA << EOF
389 another_name_of_a_debian_package
393 and specify it when invoking grml-live then:
395 # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
397 I fscked up my grml-live configuration. How do I reset it to the defaults?
398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
400 Notice: this deletes all your grml-live configuration files. If that's really
401 what you are searching for just run:
403 rm -rf /etc/grml/fai /etc/grml/grml-live.conf
404 dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
408 If you don't control your /etc using a version control system (VCS) yet it's a
409 good chance to start using it now. Check out
410 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/]
411 for more details how to maintain /etc using the mercurial VCS.
413 How do I create a base.tgz for use as NFSROOT?
414 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
416 First of all build the chroot system:
418 mkdir /tmp/nfsroot && cd /tmp/nfsroot
419 debootstrap etch /tmp/nfsroot/ http://ftp.de.debian.org/debian
422 Then check out where your NFSROOT is located:
424 # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
425 NFSROOT=/grml/fai/nfsroot
427 So as /grml/fai/nfsroot is your NFSROOT place the file under
428 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
430 mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
432 or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
433 Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
435 Now running "grml-live ..." will use this file as main system instead of
436 executing debootstrap. Check out the output for the following lines if using
440 Calling task_extrbase
441 Unpacking Debian base archive
442 Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
446 or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
449 ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
450 /grml-live/grml-live_20071029.22138/grml_chroot//
453 Set up apt-cacher for use with grml-live
454 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
456 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
459 # cat /etc/grml/grml-live.conf
462 deb http://localhost:3142/deb.grml.org grml-stable main
463 deb http://localhost:3142/deb.grml.org grml-testing main
464 deb http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free
467 FAI_DEBOOTSTRAP="etch http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free"
469 Make sure apt-cacher is running (/etc/init.d/apt-cacher restart). That's it.
470 All downloaded files will be cached in /var/cache/apt-cacher/ now.
472 Set up approx for use with grml-live
473 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
475 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
478 # cat /etc/grml/grml-live.conf
481 deb http://localhost:9999/grml grml-stable main
482 deb http://localhost:9999/grml grml-testing main
483 deb http://localhost:9999/debian etch main contrib non-free
485 FAI_DEBOOTSTRAP="etch http://localhost:9999/debian"
489 # cat /etc/approx/approx.conf
491 debian http://ftp.at.debian.org/debian
492 grml http://deb.grml.org/
494 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
495 All downloaded files will be cached in /var/cache/approx now.
497 I've a question which isn't answered by this document
498 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
501 a mail: <mika@grml.org>
503 Download / install grml-live as a Debian package
504 ------------------------------------------------
506 Debian packages are available through the grml-repository at
507 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to
508 build a Debian package on your own (using for example a specific version or the
509 current development tree), just execute:
511 hg clone http://hg.grml.org/grml-live
518 The source of grml-live is available at
519 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
524 Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
530 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
531 link:http://grml.org/contact/[to the grml-team]!
535 Michael Prokop <mika@grml.org>.
537 /////////////////////////////////////
538 // vim:ai tw=80 ft=asciidoc expandtab
539 /////////////////////////////////////