docs/grml-live.txt

   1 grml-live(8)
   2 ============
   3
   4 Name
   5 ----
   6 grml-live - build process script for generating a (grml based) Linux Live-ISO
   7
   8 Synopsis
   9 --------
  10 grml-live [-c <classe[s]>] [-t <target_directory>] [-F] [-h|--help]
  11
  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 *******************************************************************************
  17
  18 Description
  19 -----------
  20
  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).
  24
  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.
  28
  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
  32 independent!
  33
  34 [NOTE]
  35
  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).
  43
  44 Options
  45 -------
  46
  47   -c **CLASSES**::
  48
  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).
  52
  53   -s **SUITE**::
  54
  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.
  57
  58   -t **TARGET_DIRECTORY**::
  59
  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
  64 ISO is stored.
  65
  66   -F::
  67
  68 Force execution and do not prompt for / display summary of configuration
  69 details.
  70
  71   -h::
  72
  73 Display short usage information and exit.
  74
  75   -v::
  76
  77 Increase verbosity in the build process.
  78
  79 How to get your own live-cd - the easy, fast and simple way
  80 -----------------------------------------------------------
  81
  82 To get a small, Debian-stable and grml based live-cd using /grml/grml-live
  83 as build and output directory:
  84
  85   # grml-live
  86
  87 To get a small Debian-unstable and grml-small based live-cd using
  88 /home/mika/grml-live as build and output directory:
  89
  90   # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
  91
  92 [NOTE]
  93
  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. :)
 100
 101 Features
 102 --------
 103
 104 * create a grml-/Debian-based Linux Live-CD with one single command
 105
 106 * class based concept, providing a maximum of flexibility
 107
 108 * supports integration of own hooks, scripts and configuration
 109
 110 * supports use and integration of own Software and/or Kernels via use of Debian
 111 repositories
 112
 113 * native support of FAI features
 114
 115 * multi-arch support (work in progress)
 116
 117 The class concept
 118 -----------------
 119
 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.
 123
 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
 128 by default:
 129
 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
 135
 136 Take a look at the next section for information about the concept of those
 137 files/directories.
 138
 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 ...".
 144
 145 More details regarding the class concept can be found in the documentation of
 146 FAI (available at /usr/share/doc/fai-doc/).
 147
 148 Files
 149 -----
 150
 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.
 159
 160   /usr/sbin/grml-live
 161
 162 Script for the main build process (being a wrapper around FAI currently).
 163 Requires root permissions for execution.
 164
 165   /etc/grml/fai/fai.conf
 166
 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.
 171
 172   /etc/grml/fai/make-fai-nfsroot.conf
 173
 174 TODO: documentation
 175
 176   /etc/grml/fai/NFSROOT
 177
 178 TODO: documentation
 179
 180   /etc/grml/fai/apt/sources.list
 181
 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
 184 to adjust this file.
 185
 186   /etc/grml/fai/config/
 187
 188 The main directory for configuration of FAI/grml-live. More details below.
 189
 190   /etc/grml/fai/config/class/
 191
 192 This directory contains files which specify main configuration variables for the
 193 FAI classes.
 194
 195   /etc/grml/fai/config/debconf/
 196
 197 This directory provides the files for preseeding/configuration of debconf
 198 through files.
 199
 200   /etc/grml/fai/config/hooks/
 201
 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.
 205
 206   /etc/grml/fai/config/package_config/
 207
 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.
 216
 217   /etc/grml/fai/config/scripts/
 218
 219 Scripts for customising the ISO within build process.
 220
 221   /etc/grml/fai/files/
 222
 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.
 226
 227   /etc/grml/fai/live-initramfs/
 228
 229 This directory provides the files used for building the initramfs/initrd via
 230 live-initramfs(8).
 231
 232 Requirements for the build system
 233 ---------------------------------
 234
 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
 237
 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
 241 temporary files)
 242
 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
 245 as possiblbe)
 246
 247 Known TODOs
 248 -----------
 249
 250 * make sure the suite-target adjusts the mirror definitions according (working
 251 also vice versa!)
 252
 253 * add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
 254 that are arch specific so we have a clean package list in all classes)
 255
 256 * support different grml-flavours through classes right out-of-the-box (being:
 257 grml, grml64, grml-small (in progress) for at least x86, amd64 and ppc)
 258
 259 * support signed apt repositories (currently it's deactivated via FAI's
 260 FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
 261
 262 * explain (and provide configuration for) use of NFSROOT
 263
 264 * support setting stuff like ISO name, version,... on-the-fly (especially for
 265 stuff inside boot/isolinux/*)
 266
 267 * support "final builds" (including stuff like generating md5sums, gpg,...)
 268
 269 * the grml-live class(es) should send output as used inside FAI as well (so it's
 270 not as verbose unless you specify it, make it configurable)
 271
 272 * provide possibility for cleanup of all created build directories and
 273 a smart summary of the buildprocess (including "took ... minutes/seconds to
 274 build...)
 275
 276 * support hooks to allow further customisation of the build process
 277
 278 * test the package on non-grml systems (and maybe even non-Debian) as well
 279
 280 Debian package
 281 --------------
 282
 283 Debian packages will be available through the grml-repository at
 284 link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
 285 considers grml-live as stable enough. In the meantime just build the package on
 286 your own:
 287
 288   hg clone http://hg.grml.org/grml-live
 289   cd grml-live
 290   debuild -us -uc
 291
 292 Source
 293 ------
 294
 295 The source of grml-live is available at
 296 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
 297
 298 Bugs
 299 ----
 300
 301 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 302 link:http://grml.org/contact/[to the grml-team]!
 303
 304 Authors
 305 -------
 306 Michael Prokop <mika@grml.org>.
 307
 308 /////////////////////////////////////
 309 // vim:ai tw=80 ft=asciidoc expandtab
 310 /////////////////////////////////////