7 grml-live - build framework based on FAI for generating a grml and Debian based
8 Linux Live system (CD/ISO)
13 grml-live [-c <classe[s]>] [-i <iso_name> ] [-r <release_name>]
14 [-s <suite>] [-t <target_directory>] [-v <version_number>] [-Fvh]
16 *******************************************************************************
17 Important! This document is growing as requested. If you have questions which
18 aren't answered by this document yet please let me know: <mika@grml.org>!
19 *******************************************************************************
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://www.informatik.uni-koeln.de/fai/[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 /etc/grml/fai. This ensures that it does not clash with
39 default FAI configuration and packages, so you can use grml-live and FAI
40 completely independent at the same time!
44 Please notice that you should have a fast network connection as all the Debian
45 packages will be downloaded and installed via network. If you want to use a
46 local mirror (strongly recommended if you plan to use grml-live more than once)
47 checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
48 debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
49 sample configuration) and approx(8). To avoid downloading the base system again
50 and again check out FAI's NFSROOT (see FAQ of this document for details).
57 Specify the CLASSES to be used for building the ISO via FAI. By default only
58 the classes GRMLBASE and I386 are assumed, resulting in a small base system
59 (being about ~150MB total ISO size) for x86 (32bit).
63 Force execution and do not prompt for acknowledgment of configuration.
67 Display short usage information and exit.
71 Specify name of ISO which will be available inside $TARGET_DIRECTORY/grml_isos
76 Specify name of the release. (Notice: the output of the release name is limited
81 Specify the Debian suite you want to use for your live-system. Defaults to
82 "etch" (being current Debian/stable). Supported values are: etch, lenny, sid,
83 stable, testing, unstable.
85 -t **TARGET_DIRECTORY**::
87 Main output directory of the build process of FAI. Some directories are created
88 inside this target directory, being: grml_cd (where the files for creating the
89 ISO are located, including the compressed squashfs file), grml_chroot (the
90 chroot system) and grml_isos (where the resulting ISO is stored).
92 -v **VERSION_NUMBER**::
94 Specify version number of the release. (Notice: the output of the version number
95 is limited to 5 characters. So "1.0-1" is fine, but "1.0.0.1" will be stripped
100 Increase verbosity in the build process.
105 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
106 as build and output directory just run:
110 To get a small Debian-unstable and grml-small based Live-CD using
111 /home/mika/grml-live as build and output directory just use:
113 # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
115 To get a smal, Debian-unstable and grml-based Live-CD using /tmp as build and
116 output directory and use grml_0.0-3.iso as ISO name (placed inside
117 /tmp/grml_isos) just invoke:
119 # grml-live -t /tmp -c GRMLBASE,I386 -s sid -v -i grml_0.0-3.iso
123 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
124 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
125 and use /dev/shm as build and output directory - resulting in very fast build
126 process. But please be aware of the fact that rebooting your system will result
127 in an empty /dev/shm, so please another directory for $CHROOT_TARGET,
128 $BUILD_TARGET and $ISO_TARGET if you plan to create more persistent output. :)
130 Main features of grml-live
131 --------------------------
133 * create a grml-/Debian-based Linux Live-CD with one single command
135 * class based concept, providing a maximum of flexibility
137 * supports integration of own hooks, scripts and configuration
139 * supports use and integration of own Software and/or Kernels via simple use of
142 * native support of FAI features
144 * multi-arch support (work in progress)
149 grml-live uses FAI and its class based concept for adjusting configuration and
150 setup according to your needs. This gives you flexibility and strength without
151 losing the simplicity in the build process.
153 The main and base class provided by grml-live is named GRMLBASE. It's strongly
154 recommended to **always** use the class GRMLBASE when building an ISO using
155 grml-live, as well as the architecture dependend class which provides the kernel
156 (being 'I386' for x86_32 currently only). The following files and directories
157 are relevant for class GRMLBASE by default:
159 /etc/grml/fai/config/scripts/GRMLBASE/
160 /etc/grml/fai/config/debconf/GRMLBASE
161 /etc/grml/fai/config/class/GRMLBASE.var
162 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
163 /etc/grml/fai/config/package_config/GRMLBASE
165 Take a look at the next section for information about the concept of those
168 If you want to use your own configuration, extend an existing configuration
169 and/or add additional packages to your ISO just invent a new class (or extend an
170 existing one). For example if you want to use your own class named "FOOBAR" just
171 extend CLASSES="GRMLBASE,I386" inside /etc/grml/grml-live.conf to
172 CLASSES="GRMLBASE,I386,FOOBAR" or invoke grml-live using the classes option:
173 "grml-live -c GRMLBASE,I386,FOOBAR ...".
175 More details regarding the class concept can be found in the documentation of
176 FAI itself (being available at /usr/share/doc/fai-doc/).
181 Notice that grml-live ships FAI configuration files that do not use the same
182 namespace as the FAI packages itself. This ensures that grml-live does not clash
183 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
184 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
185 below. To get an idea how another configuration or example files could look like
186 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
187 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
188 provides documentation regarding configuration possibilities.
192 Script for the main build process. Requires root permissions for execution.
194 /etc/grml/grml-live.conf
196 Main configuration file for grml-live. All the important steps can be configured
199 /etc/grml/fai/fai.conf
201 Main configuration file for FAI which specifies where all the configuration
202 files and scripts for FAI/grml-live can be found. By default it is set to
203 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
204 out-of-the-box so you shouldn't have to configure anything in this file.
206 /etc/grml/fai/make-fai-nfsroot.conf
208 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
209 anything inside this file. If you want to modify NFSROOT though you can adjust
212 /etc/grml/fai/NFSROOT
214 This file specifies the package list for creating the NFSROOT.
216 /etc/grml/fai/apt/sources.list
218 This file specifies which mirrors should be used for retreiving the Debian
219 packages used for creating the main chroot (including all the software you would
220 like to see included). If you want to use a local mirror you either have to
221 adjust this file or use the GRML_LIVE_SOURCES variable inside
222 /etc/grml/grml-live.conf which modifies /etc/grml/fai/apt/sources.list
225 /etc/grml/fai/config/
227 The main directory for configuration of FAI/grml-live. More details below.
229 /etc/grml/fai/config/class/
231 This directory contains files which specify main configuration variables for the
234 /etc/grml/fai/config/debconf/
236 This directory provides the files for preseeding/configuration of debconf
239 /etc/grml/fai/config/hooks/
241 This directory provides files for customising the build process through hooks.
242 Hooks are user defined programs or scripts, which are called during the
243 installation process.
245 /etc/grml/fai/config/package_config/
247 Directory with lists of software packages to be installed or removed. The
248 different classes describe what should find its way to your ISO. When running
249 "grml-live -c GRMLBASE,I386 ..." only the files from the directories GRMLBASE
250 and I386 will be taken, if you use 'grml-live -c GRMLBASE,I386,FOOBAR ...' then
251 the files of GRMLBASE, I386 **plus** the files from FOOBAR will be taken. So
252 just create a new class to adjust the package selection according to your needs.
253 Please notice that the directory GRMLBASE contains a package list defining a
254 minimum but still reasonable package configuration.
256 /etc/grml/fai/config/scripts/
258 Scripts for customising the ISO within the build process.
262 This directory provides files used inside the scripts of
263 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
264 files please refer to the source of the scripts.
266 /etc/grml/fai/live-initramfs/
268 This directory provides the files used for building the initramfs/initrd via
271 Requirements for the build system
272 ---------------------------------
274 * any Debian based system should be sufficient (if not it's a bug, so please
275 send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
276 harddisk installation ships all you need]
278 * enough free disk space; at least 800MB are required for a minimal grml-live
279 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
280 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
281 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
282 total free disk space
284 * fast network access for retreiving the Debian packages used for creating the
285 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
291 Help, I'm using Debian etch and I don't have FAI version >3.2
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294 wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.1_all.deb \
295 http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.1_all.deb
296 dpkg -i fai-client_3.2.1_all.deb fai-server_3.2.1_all.deb
298 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
301 I've problems with the build process. How to start debugging?
302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
304 Check out the logs inside /var/log/fai/dirinstall/... If you don't have the time
305 to debug the problem in further detail or don't know how to proceed just send a
306 copy of your config, logs and the commandline with a short problem description
309 # history | grep grml-live > /etc/grml/grml_live.cmdline
310 # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
311 /var/log/fai/dirinstall /etc/grml/fai
313 Can I use my own (local) Debian mirror?
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
316 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
317 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
318 your needs. Please don't forget that you should use the grml servers as well
319 (see default configuration) so all the grml packages can be downloaded as well.
321 If you want to use a local (for example NFS mount) mirror additionally, just
322 adjust MIRROR_DIRECTORY and MIRROR_SOURCES insede /etc/grml/grml-live.conf as
325 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
326 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
327 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
328 files will be adjusted during runtime automatically.
330 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
331 taken as first entry in the generated sources.list so it's prefered over
332 non-local mirrors. Using a fallback mirror (via providing several mirrors in
333 GRML_LIVE_SOURCES as used by default) is a recommended setting.
335 How do I add additional Debian package(s) to my CD/ISO?
336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
338 Just create a new class (using the package_config directory):
340 # cat > /etc/grml/fai/config/package_config/MIKA << EOF
344 another_name_of_a_debian_package
348 and specify it when invoking grml-live then:
350 # grml-live -c GRMLBASE,I386,MIKA
352 I fscked up my grml-live configuration. How do I reset it to the defaults?
353 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
355 Notice: this deletes all your grml-live configuration files. If that's really
356 what you are searching for just run:
358 rm -rf /etc/grml/fai /etc/grml/grml-live.conf
359 dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
363 If you don't control your /etc using a version control system (VCS) yet it's a
364 good chance to start using it now. Check out
365 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/]
366 for more details how to maintain /etc using the mercurial VCS.
368 How do I create a base.tgz for use as NFSROOT?
369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371 First of all build the chroot system:
373 mkdir /tmp/nfsroot && cd /tmp/nfsroot
374 debootstrap etch /tmp/nfsroot/ http://ftp.de.debian.org/debian
377 Then check out where your NFSROOT is located:
379 # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
380 NFSROOT=/grml/fai/nfsroot
382 So as /grml/fai/nfsroot is your NFSROOT place the file under
383 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
385 mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
387 Now running "grml-live ..." will use this file as main system instead of
388 executing debootstrap. Check out the output for the following lines:
391 Calling task_extrbase
392 Unpacking Debian base archive
393 Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
397 I've a question which isn't answered by this document
398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
400 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
401 a mail: <mika@grml.org>
406 * support something like a directory /etc/grml/fai/packages to install
407 additional Debian packages without the need for a Debian repository
409 * document the available classes in more detail (GRMLBASE, LATEX_CLEANUP,
410 NO_ONLINE, REMOVE_DOCS, GRML_SMALL,...)
412 * add a check to make sure $TARGET is mounted rw,suid,dev?
414 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
415 that are arch specific so we have a clean package list in all classes)
417 * support different grml-flavours through classes right out-of-the-box (being:
418 grml and grml-small (done), each for x86, amd64 and ppc)
420 * support signed apt repositories (currently it's deactivated via FAI's
421 FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
423 * support "final builds" (including stuff like generating md5sums, gpg,... -
424 create a grml_release-directory including all the details about the build
425 process like dpkg selection, logs,...)
427 * the grml-live class(es) should send output to stdout and stderr as used inside
428 FAI as well (so it's not as verbose unless you specify it, make it configurable
429 though); check for errors inside the logs then as well
431 * provide possibility for cleanup of all created build directories and
432 a smart summary of the buildprocess (including "took ... minutes/seconds to
435 * check out how FAI_DEBMIRROR of /etc/grml/fai/fai.conf could be merged with our
436 MIRROR_DIRECTORY and MIRROR_SOURCES feature of /etc/grml/grml-live.conf
438 * support hooks to allow further customisation of the build process
443 * Provide all upcoming grml releases based on grml-live.
445 * Provide a console interface (using dialog) for easy and common use of
448 * Provide a graphical interface (for example using pygtk) for easy and common
451 Download / install grml-live as a Debian package
452 ------------------------------------------------
454 Debian packages will be available through the grml-repository at
455 link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
456 considers grml-live as stable enough. In the meantime just build the package on
459 hg clone http://hg.grml.org/grml-live
466 The source of grml-live is available at
467 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
472 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
473 link:http://grml.org/contact/[to the grml-team]!
477 Michael Prokop <mika@grml.org>.
479 /////////////////////////////////////
480 // vim:ai tw=80 ft=asciidoc expandtab
481 /////////////////////////////////////