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 Output directory of the build process of FAI - being the chroot
61 used for building the ISO.
65 Force execution and do not prompt for / display summary of configuration
70 Display short usage information and exit.
74 Increase verbosity in the build process.
76 How to get your own live-cd - the easy, fast and simple way
77 -----------------------------------------------------------
79 To get a small, Debian-stable and grml based live-cd using /dev/shm/
80 as build and output directory:
86 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
87 you have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm" and use
88 /dev/shm as build and output directory - resulting in very fast build process.
89 But please be aware of the fact that rebooting your system will result in an
90 empty /dev/shm, so please another directory for $CHROOT_TARGET, $BUILD_TARGET
91 and $ISO_TARGET if you plan to create more persistent output. :)
96 grml-live uses FAI and its class based concept for adjusting configuration
97 according to your needs. This gives you flexibility and strength without losing
98 the simplicity in the build process.
100 The main and base class provided by grml-live is named GRMLBASE. It's strongly
101 recommended to **always** use the class GRMLBASE when building an ISO using
102 grml-live as well as the architecture dependend class (being 'I386' for x86_32
103 currently only). The following files and directories are relevant for class GRML
106 /etc/grml/fai/config/scripts/GRMLBASE/
107 /etc/grml/fai/config/debconf/GRMLBASE
108 /etc/grml/fai/config/class/GRMLBASE.var
109 /etc/grml/fai/config/hooks/instsoft.GRMLBASE
110 /etc/grml/fai/config/package_config/GRMLBASE
112 Take a look at the next section for information about the concept of those
115 If you want to use your own configuration, extend an existing configuration
116 and/or add additional packages to your ISO just invent a new class. For example
117 if you want to use your own class named "FOOBAR" just extend CLASSES="GRMLBASE"
118 inside /etc/grml/grml-live.conf to CLASSES="GRMLBASE,FOOBAR" or invoke grml-live
119 using the classes option: "grml-live -c GRMLBASE,FOOBAR ...".
121 More details regarding the class concept can be found in the documentation of
122 FAI (available at /usr/share/doc/fai-doc/).
127 Notice that grml-live ships FAI configuration files that do not use the same
128 namespace as the FAI packages itself. This ensures that grml-live does not
129 clash with your usual FAI configuration, so instead of /etc/fai/fai.conf
130 (package fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details
131 see below. To get an idea how another configuration or example files could look
132 like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
133 fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides
134 documentation regarding configuration possibilities.
138 Script for the main build process (being a wrapper around FAI currently).
139 Requires root permissions for execution.
141 /etc/grml/fai/fai.conf
143 Main configuration file which specifies where all the configuration files and
144 scripts for FAI/grml-live can be found. By default it is
145 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
146 out-of-the-box so you shouldn't have to configure anything in this file.
148 /etc/grml/fai/make-fai-nfsroot.conf
152 /etc/grml/fai/NFSROOT
156 /etc/grml/fai/apt/sources.list
158 This file specifies which mirrors should be used for retreiving the Debian
159 packages used for creating the ISO. If you want to use a local mirror you have
162 /etc/grml/fai/config/
164 The main directory for configuration of FAI/grml-live. More details below.
166 /etc/grml/fai/config/class/
168 This directory contains files which specify main configuration variables for the
171 /etc/grml/fai/config/debconf/
173 This directory provides the files for preseeding/configuration of debconf
176 /etc/grml/fai/config/hooks/
178 This directory provides files for customizing the build process through hooks.
179 Hooks are user defined programs or scripts, which are called during the
180 installation process.
182 /etc/grml/fai/config/package_config/
184 File with lists of software packages to be installed or removed. The different
185 classes describe what should find its way to your ISO. When running 'fai -v -C
186 /etc/grml/fai -cGRMLBASE dirinstall ...' only the files from the directory GRML/
187 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRMLBASE,FOOBAR dirinstall
188 ...' then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So
189 just create a new class to adjust it to your needs. Please notice that the
190 directory GRML contains a package list defining a minimum but still reasonable
191 package configuration.
193 /etc/grml/fai/config/scripts/
195 Scripts for customising the ISO within build process.
199 This directory provides files used inside the scripts of
200 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
201 files please refer to the source of the scripts.
203 /etc/grml/fai/live-initramfs/
205 This directory provides the files used for building the initramfs/initrd via
208 Requirements for the build system
209 ---------------------------------
211 * any Debian based system should be sufficient (if not please send a bug
212 report), for example a grml2hd harddisk installation ships all you need
214 * enough free disk space; at least 800MB are required for a minimal grml-live
215 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
216 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
219 * fast network access for retreiving the Debian packages used for creating the
220 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
226 * make sure the suite-target adjusts the mirror definitions according (working
229 * do not use /dev/shm/ als default target directory (which one do we want to use
232 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
233 that are arch specific so we have a clean package list in all classes)
235 * support different grml-flavours through classes right out-of-the-box (being:
236 grml, grml64, grml-small (in progress) for at least x86, amd64 and ppc)
238 * support signed apt repositories (currently it's deactivated via FAI's
239 FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
241 * explain (and provide configuration for) use of NFSROOT
243 * support setting stuff like ISO name, version,... on-the-fly (especially for
244 stuff inside boot/isolinux/*)
246 * support "final builds" (including stuff like generating md5sums, gpg,...)
248 * the grml-live class(es) should send output as used inside FAI as well (so it's
249 not as verbose unless you specify it, make it configurable)
251 * provide possibility for cleanup of all created build directories and
252 a smart summary of the buildprocess (including "took ... minutes/seconds to
255 * support hooks to allow further customisation of the build process
257 * test the package on non-grml systems (and maybe even non-Debian) as well
262 Debian packages will be available through the grml-repository at
263 link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
264 considers grml-live as stable enough. In the meantime just build the package on
267 hg clone http://hg.grml.org/grml-live
274 The source of grml-live is available at
275 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
280 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
281 link:http://grml.org/contact/[to the grml-team]!
285 Michael Prokop <mika@grml.org>.
287 /////////////////////////////////////
288 // vim:ai tw=80 ft=asciidoc expandtab
289 /////////////////////////////////////