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 Output directory of the build process of FAI - being the chroot
  61 used for building the ISO.
  62
  63   -F::
  64
  65 Force execution and do not prompt for / display summary of configuration
  66 details.
  67
  68   -h::
  69
  70 Display short usage information and exit.
  71
  72   -v::
  73
  74 Increase verbosity in the build process.
  75
  76 How to get your own live-cd - the easy, fast and simple way
  77 -----------------------------------------------------------
  78
  79 To get a small, Debian-stable and grml based live-cd using /dev/shm/
  80 as build and output directory:
  81
  82   # grml-live
  83
  84 To get a small Debian-unstable and grml-small based live-cd using /grml as build
  85 and output directory:
  86
  87   # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /grml
  88
  89 [NOTE]
  90
  91 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
  92 you have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm" and use
  93 /dev/shm as build and output directory - resulting in very fast build process.
  94 But please be aware of the fact that rebooting your system will result in an
  95 empty /dev/shm, so please another directory for $CHROOT_TARGET, $BUILD_TARGET
  96 and $ISO_TARGET if you plan to create more persistent output. :)
  97
  98 Features
  99 --------
 100
 101 * create a grml-/Debian-based Linux Live-CD with one single command
 102
 103 * class based concept, providing a maximum of flexibility
 104
 105 * supports integration of own hooks, scripts and configuration
 106
 107 * supports use and integration of own Software and/or Kernels via use of Debian
 108 repositories
 109
 110 * native support of FAI features
 111
 112 * multi-arch support (work in progress)
 113
 114 The class concept
 115 -----------------
 116
 117 grml-live uses FAI and its class based concept for adjusting configuration
 118 according to your needs. This gives you flexibility and strength without losing
 119 the simplicity in the build process.
 120
 121 The main and base class provided by grml-live is named GRMLBASE. It's strongly
 122 recommended to **always** use the class GRMLBASE when building an ISO using
 123 grml-live as well as the architecture dependend class (being 'I386' for x86_32
 124 currently only). The following files and directories are relevant for class GRML
 125 by default:
 126
 127   /etc/grml/fai/config/scripts/GRMLBASE/
 128   /etc/grml/fai/config/debconf/GRMLBASE
 129   /etc/grml/fai/config/class/GRMLBASE.var
 130   /etc/grml/fai/config/hooks/instsoft.GRMLBASE
 131   /etc/grml/fai/config/package_config/GRMLBASE
 132
 133 Take a look at the next section for information about the concept of those
 134 files/directories.
 135
 136 If you want to use your own configuration, extend an existing configuration
 137 and/or add additional packages to your ISO just invent a new class. For example
 138 if you want to use your own class named "FOOBAR" just extend CLASSES="GRMLBASE"
 139 inside /etc/grml/grml-live.conf to CLASSES="GRMLBASE,FOOBAR" or invoke grml-live
 140 using the classes option: "grml-live -c GRMLBASE,FOOBAR ...".
 141
 142 More details regarding the class concept can be found in the documentation of
 143 FAI (available at /usr/share/doc/fai-doc/).
 144
 145 Files
 146 -----
 147
 148 Notice that grml-live ships FAI configuration files that do not use the same
 149 namespace as the FAI packages itself.  This ensures that grml-live does not
 150 clash with your usual FAI configuration, so instead of /etc/fai/fai.conf
 151 (package fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details
 152 see below. To get an idea how another configuration or example files could look
 153 like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 154 fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides
 155 documentation regarding configuration possibilities.
 156
 157   /usr/sbin/grml-live
 158
 159 Script for the main build process (being a wrapper around FAI currently).
 160 Requires root permissions for execution.
 161
 162   /etc/grml/fai/fai.conf
 163
 164 Main configuration file which specifies where all the configuration files and
 165 scripts for FAI/grml-live can be found. By default it is
 166 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
 167 out-of-the-box so you shouldn't have to configure anything in this file.
 168
 169   /etc/grml/fai/make-fai-nfsroot.conf
 170
 171 TODO: documentation
 172
 173   /etc/grml/fai/NFSROOT
 174
 175 TODO: documentation
 176
 177   /etc/grml/fai/apt/sources.list
 178
 179 This file specifies which mirrors should be used for retreiving the Debian
 180 packages used for creating the ISO. If you want to use a local mirror you have
 181 to adjust this file.
 182
 183   /etc/grml/fai/config/
 184
 185 The main directory for configuration of FAI/grml-live. More details below.
 186
 187   /etc/grml/fai/config/class/
 188
 189 This directory contains files which specify main configuration variables for the
 190 FAI classes.
 191
 192   /etc/grml/fai/config/debconf/
 193
 194 This directory provides the files for preseeding/configuration of debconf
 195 through files.
 196
 197   /etc/grml/fai/config/hooks/
 198
 199 This directory provides files for customizing the build process through hooks.
 200 Hooks are user defined programs or scripts, which are called during the
 201 installation process.
 202
 203   /etc/grml/fai/config/package_config/
 204
 205 File with lists of software packages to be installed or removed.  The different
 206 classes describe what should find its way to your ISO.  When running 'fai -v -C
 207 /etc/grml/fai -cGRMLBASE dirinstall ...' only the files from the directory GRML/
 208 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRMLBASE,FOOBAR dirinstall
 209 ...' then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So
 210 just create a new class to adjust it to your needs. Please notice that the
 211 directory GRML contains a package list defining a minimum but still reasonable
 212 package configuration.
 213
 214   /etc/grml/fai/config/scripts/
 215
 216 Scripts for customising the ISO within build process.
 217
 218   /etc/grml/fai/files/
 219
 220 This directory provides files used inside the scripts of
 221 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
 222 files please refer to the source of the scripts.
 223
 224   /etc/grml/fai/live-initramfs/
 225
 226 This directory provides the files used for building the initramfs/initrd via
 227 live-initramfs(8).
 228
 229 Requirements for the build system
 230 ---------------------------------
 231
 232 * any Debian based system should be sufficient (if not please send a bug
 233 report), for example a grml2hd harddisk installation ships all you need
 234
 235 * enough free disk space; at least 800MB are required for a minimal grml-live
 236 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
 237 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
 238 temporary files)
 239
 240 * fast network access for retreiving the Debian packages used for creating the
 241 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 242 as possiblbe)
 243
 244 Known TODOs
 245 -----------
 246
 247 * make sure the suite-target adjusts the mirror definitions according (working
 248 also vice versa!)
 249
 250 * do not use /dev/shm/ als default target directory (which one do we want to use
 251 instead?)
 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 /////////////////////////////////////