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 [NOTE]
  85
  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. :)
  92
  93 The class concept
  94 -----------------
  95
  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.
  99
 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
 104 by default:
 105
 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
 111
 112 Take a look at the next section for information about the concept of those
 113 files/directories.
 114
 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 ...".
 120
 121 More details regarding the class concept can be found in the documentation of
 122 FAI (available at /usr/share/doc/fai-doc/).
 123
 124 Files
 125 -----
 126
 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.
 135
 136   /usr/sbin/grml-live
 137
 138 Script for the main build process (being a wrapper around FAI currently).
 139 Requires root permissions for execution.
 140
 141   /etc/grml/fai/fai.conf
 142
 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.
 147
 148   /etc/grml/fai/make-fai-nfsroot.conf
 149
 150 TODO: documentation
 151
 152   /etc/grml/fai/NFSROOT
 153
 154 TODO: documentation
 155
 156   /etc/grml/fai/apt/sources.list
 157
 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
 160 to adjust this file.
 161
 162   /etc/grml/fai/config/
 163
 164 The main directory for configuration of FAI/grml-live. More details below.
 165
 166   /etc/grml/fai/config/class/
 167
 168 This directory contains files which specify main configuration variables for the
 169 FAI classes.
 170
 171   /etc/grml/fai/config/debconf/
 172
 173 This directory provides the files for preseeding/configuration of debconf
 174 through files.
 175
 176   /etc/grml/fai/config/hooks/
 177
 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.
 181
 182   /etc/grml/fai/config/package_config/
 183
 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.
 192
 193   /etc/grml/fai/config/scripts/
 194
 195 Scripts for customising the ISO within build process.
 196
 197   /etc/grml/fai/files/
 198
 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.
 202
 203   /etc/grml/fai/live-initramfs/
 204
 205 This directory provides the files used for building the initramfs/initrd via
 206 live-initramfs(8).
 207
 208 Requirements for the build system
 209 ---------------------------------
 210
 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
 213
 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
 217 temporary files)
 218
 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
 221 as possiblbe)
 222
 223 Known TODOs
 224 -----------
 225
 226 * make sure the suite-target adjusts the mirror definitions according (working
 227 also vice versa!)
 228
 229 * do not use /dev/shm/ als default target directory (which one do we want to use
 230 instead?)
 231
 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)
 234
 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)
 237
 238 * support signed apt repositories (currently it's deactivated via FAI's
 239 FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
 240
 241 * explain (and provide configuration for) use of NFSROOT
 242
 243 * support setting stuff like ISO name, version,... on-the-fly (especially for
 244 stuff inside boot/isolinux/*)
 245
 246 * support "final builds" (including stuff like generating md5sums, gpg,...)
 247
 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)
 250
 251 * provide possibility for cleanup of all created build directories and
 252 a smart summary of the buildprocess (including "took ... minutes/seconds to
 253 build...)
 254
 255 * support hooks to allow further customisation of the build process
 256
 257 * test the package on non-grml systems (and maybe even non-Debian) as well
 258
 259 Debian package
 260 --------------
 261
 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
 265 your own:
 266
 267   hg clone http://hg.grml.org/grml-live
 268   cd grml-live
 269   debuild -us -uc
 270
 271 Source
 272 ------
 273
 274 The source of grml-live is available at
 275 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
 276
 277 Bugs
 278 ----
 279
 280 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 281 link:http://grml.org/contact/[to the grml-team]!
 282
 283 Authors
 284 -------
 285 Michael Prokop <mika@grml.org>.
 286
 287 /////////////////////////////////////
 288 // vim:ai tw=80 ft=asciidoc expandtab
 289 /////////////////////////////////////