7 grml-live - build framework for generating a grml and Debian based Linux Live
13 grml-live [-c <classe[s]>] [-t <target_directory>] [-F] [-h|--help]
15 *******************************************************************************
16 Important! grml-live is under heavy construction, though your feedback is highly
17 appreciated. 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 section for further details)
29 and provides all the details to be able to generate a full-featured ISO. It does
30 not use all the FAI features by default though and you don't have to know FAI to
33 The use of FAI behind the curtains gives you the flexibility to choose the
34 packages you would like to include on your very own Linux live-cd without having
35 to deal with all the 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 installed via network. If you want to use a local mirror
46 (strongly recommended!) checkout mkdebmirror (see
47 /usr/share/doc/grml-live/examples/mkdebmirror), debmirror(1), reprepro(1) (see
48 /usr/share/doc/grml-live/examples/reprepro/ for a sample configuration) and
49 approx(8). To avoid downloading of the base system check out FAI's NFSROOT (check
50 docs for ../fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz).
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 ISO size).
63 Specify the Debian suite you want to use for your live-system. Defaults to
64 "etch"; support values are: etch, lenny, sid, stable, testing, unstable.
66 -t **TARGET_DIRECTORY**::
68 Main output directory of the build process of FAI. Three directories are
69 created inside the target directory, being: grml_cd/ - where the files for
70 creating the ISO are located (including the compressed squashfs file),
71 grml_chroot/ - the generated chroot system and grml_isos/ - where the resulting
76 Force execution and do not prompt for / display summary of configuration
81 Display short usage information and exit.
85 Increase verbosity in the build process.
87 How to get your own live-cd - the easy, fast and simple way
88 -----------------------------------------------------------
90 To get a small, Debian-stable and grml based live-cd using /grml/grml-live
91 as build and output directory:
95 To get a small Debian-unstable and grml-small based live-cd using
96 /home/mika/grml-live as build and output directory:
98 # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
102 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
103 you have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm" and use
104 /dev/shm as build and output directory - resulting in very fast build process.
105 But please be aware of the fact that rebooting your system will result in an
106 empty /dev/shm, so please another directory for $CHROOT_TARGET, $BUILD_TARGET
107 and $ISO_TARGET if you plan to create more persistent output. :)
112 * create a grml-/Debian-based Linux Live-CD with one single command
114 * class based concept, providing a maximum of flexibility
116 * supports integration of own hooks, scripts and configuration
118 * supports use and integration of own Software and/or Kernels via use of Debian
121 * native support of FAI features
123 * multi-arch support (work in progress)
128 grml-live uses FAI and its class based concept for adjusting configuration
129 according to your needs. This gives you flexibility and strength without losing
130 the simplicity in the build process.
132 The main and base class provided by grml-live is named GRMLBASE. It's strongly
133 recommended to **always** use the class GRMLBASE when building an ISO using
134 grml-live as well as the architecture dependend class (being 'I386' for x86_32
135 currently only). The following files and directories are relevant for class GRML
138 /etc/grml/fai/config/scripts/GRMLBASE/
139 /etc/grml/fai/config/debconf/GRMLBASE
140 /etc/grml/fai/config/class/GRMLBASE.var
141 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
142 /etc/grml/fai/config/package_config/GRMLBASE
144 Take a look at the next section for information about the concept of those
147 If you want to use your own configuration, extend an existing configuration
148 and/or add additional packages to your ISO just invent a new class. For example
149 if you want to use your own class named "FOOBAR" just extend CLASSES="GRMLBASE"
150 inside /etc/grml/grml-live.conf to CLASSES="GRMLBASE,FOOBAR" or invoke grml-live
151 using the classes option: "grml-live -c GRMLBASE,FOOBAR ...".
153 More details regarding the class concept can be found in the documentation of
154 FAI (available at /usr/share/doc/fai-doc/).
159 Notice that grml-live ships FAI configuration files that do not use the same
160 namespace as the FAI packages itself. This ensures that grml-live does not
161 clash with your usual FAI configuration, so instead of /etc/fai/fai.conf
162 (package fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details
163 see below. To get an idea how another configuration or example files could look
164 like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
165 fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides
166 documentation regarding configuration possibilities.
170 Script for the main build process (being a wrapper around FAI currently).
171 Requires root permissions for execution.
173 /etc/grml/fai/fai.conf
175 Main configuration file which specifies where all the configuration files and
176 scripts for FAI/grml-live can be found. By default it is
177 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
178 out-of-the-box so you shouldn't have to configure anything in this file.
180 /etc/grml/fai/make-fai-nfsroot.conf
184 /etc/grml/fai/NFSROOT
188 /etc/grml/fai/apt/sources.list
190 This file specifies which mirrors should be used for retreiving the Debian
191 packages used for creating the ISO. If you want to use a local mirror you have
194 /etc/grml/fai/config/
196 The main directory for configuration of FAI/grml-live. More details below.
198 /etc/grml/fai/config/class/
200 This directory contains files which specify main configuration variables for the
203 /etc/grml/fai/config/debconf/
205 This directory provides the files for preseeding/configuration of debconf
208 /etc/grml/fai/config/hooks/
210 This directory provides files for customizing the build process through hooks.
211 Hooks are user defined programs or scripts, which are called during the
212 installation process.
214 /etc/grml/fai/config/package_config/
216 File with lists of software packages to be installed or removed. The different
217 classes describe what should find its way to your ISO. When running 'fai -v -C
218 /etc/grml/fai -cGRMLBASE dirinstall ...' only the files from the directory GRML/
219 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRMLBASE,FOOBAR dirinstall
220 ...' then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So
221 just create a new class to adjust it to your needs. Please notice that the
222 directory GRML contains a package list defining a minimum but still reasonable
223 package configuration.
225 /etc/grml/fai/config/scripts/
227 Scripts for customising the ISO within build process.
231 This directory provides files used inside the scripts of
232 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
233 files please refer to the source of the scripts.
235 /etc/grml/fai/live-initramfs/
237 This directory provides the files used for building the initramfs/initrd via
240 Requirements for the build system
241 ---------------------------------
243 * any Debian based system should be sufficient (if not please send a bug
244 report), for example a grml2hd harddisk installation ships all you need
246 * enough free disk space; at least 800MB are required for a minimal grml-live
247 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
248 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
251 * fast network access for retreiving the Debian packages used for creating the
252 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
258 * make sure the suite-target adjusts the mirror definitions according (working
259 also vice versa!) and you can define the mirror more central (without having to
260 deal with /etc/grml/grml-live.conf, /etc/grml/fai/make-fai-nfsroot.conf and
261 /etc/grml/fai/apt/sources.list; debootstrap [FAI_DEBOOTSTRAP] vs. apt inside
262 chroot [sources.list] as well)
264 * document the available classes in more detail
266 * make sure $TARGET is mounted rw,suid,dev
268 * write a step-by-step guide **how** to adjust **what** at **which** place
270 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
271 that are arch specific so we have a clean package list in all classes)
273 * support different grml-flavours through classes right out-of-the-box (being:
274 grml, grml64, grml-small (in progress) for at least x86, amd64 and ppc)
276 * support signed apt repositories (currently it's deactivated via FAI's
277 FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
279 * explain (and provide configuration for) use of NFSROOT
281 * support setting stuff like ISO name, version,... on-the-fly (especially for
282 stuff inside boot/isolinux/*)
284 * support "final builds" (including stuff like generating md5sums, gpg,...)
286 * the grml-live class(es) should send output as used inside FAI as well (so it's
287 not as verbose unless you specify it, make it configurable)
289 * provide possibility for cleanup of all created build directories and
290 a smart summary of the buildprocess (including "took ... minutes/seconds to
293 * support hooks to allow further customisation of the build process
295 * test the package on non-grml systems (and maybe even non-Debian) as well
300 Debian packages will be available through the grml-repository at
301 link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
302 considers grml-live as stable enough. In the meantime just build the package on
305 hg clone http://hg.grml.org/grml-live
312 The source of grml-live is available at
313 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
318 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
319 link:http://grml.org/contact/[to the grml-team]!
323 Michael Prokop <mika@grml.org>.
325 /////////////////////////////////////
326 // vim:ai tw=80 ft=asciidoc expandtab
327 /////////////////////////////////////