6 grml-live - build process script for generating a (grml based) Linux Live-ISO
10 grml-live [-c <classe[s]>] [-t <target_directory>] [-F] [-h|--help]
12 *******************************************************************************
13 Important! grml-live is under heavy construction, though your feedback is highly
14 appreciated. This document is growing as requested. If you have questions which
15 aren't answered by this document yet please let me (mika@grml.org) know!
16 *******************************************************************************
21 grml-live provides the build system for creating (a grml based) live-cd. The
22 build system is based on link:http://www.informatik.uni-koeln.de/fai/[FAI]
23 (Fully Automatic Installation).
25 FAI uses a class based system. This gives you the flexibility to choose the
26 packages you would like to include on your very own Linux live-cd without having
27 to deal with all the details of a build process.
29 CAUTION: grml-live does not use /etc/fai for configuration but instead provides
30 and uses /etc/grml/fai. This ensures that it does not clash with default FAI
31 configuration and packages, so you can use grml-live and FAI completely
36 Please notice that you should have a fast network connection as all the Debian
37 packages will be installed via network. If you want to use a local mirror
38 (strongly recommended!) checkout mkdebmirror (see
39 /usr/share/doc/grml-live/examples/mkdebmirror), debmirror(1), reprepro(1) (see
40 /usr/share/doc/grml-live/examples/reprepro/ for a sample configuration) and
41 approx(8). To avoid downloading of the base system check out FAI's NFSROOT (check
42 docs for ../fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz).
49 Specify the CLASSES to be used for building the ISO via fai. By default only
50 the classes GRMLBASE and I386 are assumed, resulting in a small base system
51 (being about ~150MB ISO size).
55 Specify the Debian suite you want to use for your live-system. Defaults to
56 "etch"; support values are: etch, lenny, sid, stable, testing, unstable.
58 -t **TARGET_DIRECTORY**::
60 Main output directory of the build process of FAI. Three directories are
61 created inside the target directory, being: grml_cd/ - where the files for
62 creating the ISO are located (including the compressed squashfs file),
63 grml_chroot/ - the generated chroot system and grml_isos/ - where the resulting
68 Force execution and do not prompt for / display summary of configuration
73 Display short usage information and exit.
77 Increase verbosity in the build process.
79 How to get your own live-cd - the easy, fast and simple way
80 -----------------------------------------------------------
82 To get a small, Debian-stable and grml based live-cd using /grml/grml-live
83 as build and output directory:
87 To get a small Debian-unstable and grml-small based live-cd using
88 /home/mika/grml-live as build and output directory:
90 # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
94 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
95 you have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm" and use
96 /dev/shm as build and output directory - resulting in very fast build process.
97 But please be aware of the fact that rebooting your system will result in an
98 empty /dev/shm, so please another directory for $CHROOT_TARGET, $BUILD_TARGET
99 and $ISO_TARGET if you plan to create more persistent output. :)
104 * create a grml-/Debian-based Linux Live-CD with one single command
106 * class based concept, providing a maximum of flexibility
108 * supports integration of own hooks, scripts and configuration
110 * supports use and integration of own Software and/or Kernels via use of Debian
113 * native support of FAI features
115 * multi-arch support (work in progress)
120 grml-live uses FAI and its class based concept for adjusting configuration
121 according to your needs. This gives you flexibility and strength without losing
122 the simplicity in the build process.
124 The main and base class provided by grml-live is named GRMLBASE. It's strongly
125 recommended to **always** use the class GRMLBASE when building an ISO using
126 grml-live as well as the architecture dependend class (being 'I386' for x86_32
127 currently only). The following files and directories are relevant for class GRML
130 /etc/grml/fai/config/scripts/GRMLBASE/
131 /etc/grml/fai/config/debconf/GRMLBASE
132 /etc/grml/fai/config/class/GRMLBASE.var
133 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
134 /etc/grml/fai/config/package_config/GRMLBASE
136 Take a look at the next section for information about the concept of those
139 If you want to use your own configuration, extend an existing configuration
140 and/or add additional packages to your ISO just invent a new class. For example
141 if you want to use your own class named "FOOBAR" just extend CLASSES="GRMLBASE"
142 inside /etc/grml/grml-live.conf to CLASSES="GRMLBASE,FOOBAR" or invoke grml-live
143 using the classes option: "grml-live -c GRMLBASE,FOOBAR ...".
145 More details regarding the class concept can be found in the documentation of
146 FAI (available at /usr/share/doc/fai-doc/).
151 Notice that grml-live ships FAI configuration files that do not use the same
152 namespace as the FAI packages itself. This ensures that grml-live does not
153 clash with your usual FAI configuration, so instead of /etc/fai/fai.conf
154 (package fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details
155 see below. To get an idea how another configuration or example files could look
156 like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
157 fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides
158 documentation regarding configuration possibilities.
162 Script for the main build process (being a wrapper around FAI currently).
163 Requires root permissions for execution.
165 /etc/grml/fai/fai.conf
167 Main configuration file which specifies where all the configuration files and
168 scripts for FAI/grml-live can be found. By default it is
169 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
170 out-of-the-box so you shouldn't have to configure anything in this file.
172 /etc/grml/fai/make-fai-nfsroot.conf
176 /etc/grml/fai/NFSROOT
180 /etc/grml/fai/apt/sources.list
182 This file specifies which mirrors should be used for retreiving the Debian
183 packages used for creating the ISO. If you want to use a local mirror you have
186 /etc/grml/fai/config/
188 The main directory for configuration of FAI/grml-live. More details below.
190 /etc/grml/fai/config/class/
192 This directory contains files which specify main configuration variables for the
195 /etc/grml/fai/config/debconf/
197 This directory provides the files for preseeding/configuration of debconf
200 /etc/grml/fai/config/hooks/
202 This directory provides files for customizing the build process through hooks.
203 Hooks are user defined programs or scripts, which are called during the
204 installation process.
206 /etc/grml/fai/config/package_config/
208 File with lists of software packages to be installed or removed. The different
209 classes describe what should find its way to your ISO. When running 'fai -v -C
210 /etc/grml/fai -cGRMLBASE dirinstall ...' only the files from the directory GRML/
211 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRMLBASE,FOOBAR dirinstall
212 ...' then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So
213 just create a new class to adjust it to your needs. Please notice that the
214 directory GRML contains a package list defining a minimum but still reasonable
215 package configuration.
217 /etc/grml/fai/config/scripts/
219 Scripts for customising the ISO within build process.
223 This directory provides files used inside the scripts of
224 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
225 files please refer to the source of the scripts.
227 /etc/grml/fai/live-initramfs/
229 This directory provides the files used for building the initramfs/initrd via
232 Requirements for the build system
233 ---------------------------------
235 * any Debian based system should be sufficient (if not please send a bug
236 report), for example a grml2hd harddisk installation ships all you need
238 * enough free disk space; at least 800MB are required for a minimal grml-live
239 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
240 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
243 * fast network access for retreiving the Debian packages used for creating the
244 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
250 * make sure the suite-target adjusts the mirror definitions according (working
251 also vice versa!) and you can define the mirror more central (without having to
252 deal with /etc/grml/grml-live.conf, /etc/grml/fai/make-fai-nfsroot.conf and
253 /etc/grml/fai/apt/sources.list; debootstrap [FAI_DEBOOTSTRAP] vs. apt inside
254 chroot [sources.list] as well)
256 * make sure $TARGET is mounted rw,suid,dev
258 * write a step-by-step guide **how** to adjust **what** at **which** place
260 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
261 that are arch specific so we have a clean package list in all classes)
263 * support different grml-flavours through classes right out-of-the-box (being:
264 grml, grml64, grml-small (in progress) for at least x86, amd64 and ppc)
266 * support signed apt repositories (currently it's deactivated via FAI's
267 FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
269 * explain (and provide configuration for) use of NFSROOT
271 * support setting stuff like ISO name, version,... on-the-fly (especially for
272 stuff inside boot/isolinux/*)
274 * support "final builds" (including stuff like generating md5sums, gpg,...)
276 * the grml-live class(es) should send output as used inside FAI as well (so it's
277 not as verbose unless you specify it, make it configurable)
279 * provide possibility for cleanup of all created build directories and
280 a smart summary of the buildprocess (including "took ... minutes/seconds to
283 * support hooks to allow further customisation of the build process
285 * test the package on non-grml systems (and maybe even non-Debian) as well
290 Debian packages will be available through the grml-repository at
291 link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
292 considers grml-live as stable enough. In the meantime just build the package on
295 hg clone http://hg.grml.org/grml-live
302 The source of grml-live is available at
303 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
308 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
309 link:http://grml.org/contact/[to the grml-team]!
313 Michael Prokop <mika@grml.org>.
315 /////////////////////////////////////
316 // vim:ai tw=80 ft=asciidoc expandtab
317 /////////////////////////////////////