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