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 GRML and I386 are assumed, resulting in a small base system (being
  51 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   additional_arguments_for_fai::
  67
  68 Any additional argument(s) to grml-live will be given to the FAI commandline
  69 (being basically "fai dirinstall ...).  This might become a temporary solution
  70 (due to security reasons), if you need an option please let us know so we can
  71 implement it.
  72
  73 How to get your own live-cd - the easy, fast and simple way
  74 -----------------------------------------------------------
  75
  76 To get a small, Debian-stable and grml based live-cd:
  77
  78   # TARGET="/grml/grml_uncompressed"
  79   # CDDIR="/grml/grml_cd"
  80   # grml-live -c GRML -t $TARGET
  81   # mksquashfs $TARGET/* $CDDIR/live/grml.squashfs -noappend
  82   # cd $CDDIR
  83   # mkisofs -V "my personal grml" -l -r -J -no-emul-boot -boot-load-size 4 \
  84             -boot-info-table -c boot/isolinux/boot.cat \
  85             -b boot/isolinux/isolinux.bin -o /grml/grml.iso .
  86
  87 (TODO: provide the content of /grml/chroot/grml_cd through the package
  88 grml-live, in the meanwhile get the content from a current grml-ISO)
  89
  90 The class concept
  91 -----------------
  92
  93 grml-live uses FAI and its class based concept for adjusting configuration
  94 according to your needs. This gives you flexibility and strength without losing
  95 the simplicity in the build process.
  96
  97 The main and base class provided by grml-live is named GRML. It's strongly
  98 recommended to **always** use the class GRML when building an ISO using
  99 grml-live as well as the architecture dependend class (being 'I386' for x86_32
 100 currently only). The following files and directories are relevant for class GRML
 101 by default:
 102
 103   /etc/grml/fai/config/scripts/GRML/
 104   /etc/grml/fai/config/debconf/GRML
 105   /etc/grml/fai/config/class/GRML.var
 106   /etc/grml/fai/config/hooks/instsoft.GRML
 107   /etc/grml/fai/config/package_config/GRML
 108
 109 Take a look at the next section for information about the concept of those
 110 files/directories.
 111
 112 If you want to use your own configuration, extend an existing configuration
 113 and/or add additional packages to your ISO just invent a new class. For example
 114 if you want to use your own class named "FOOBAR" just extend CLASSES="GRML" inside
 115 /etc/grml/grml-live.conf to CLASSES="GRML,FOOBAR" or invoke grml-live using
 116 the classes option: "grml-live -c GRML,FOOBAR ...".
 117
 118 More details regarding the class concept can be found in the documentation of
 119 FAI (available at /usr/share/doc/fai-doc/).
 120
 121 Files
 122 -----
 123
 124 Notice that grml-live ships FAI configuration files that do not use the same
 125 namespace as the FAI packages itself.  This ensures that grml-live does not
 126 clash with your usual FAI configuration, so instead of /etc/fai/fai.conf
 127 (package fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details
 128 see below. To get an idea how another configuration or example files could look
 129 like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 130 fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides
 131 documentation regarding configuration possibilities.
 132
 133   /usr/sbin/grml-live
 134
 135 Script for the main build process (being a wrapper around FAI currently).
 136 Requires root permissions for execution.
 137
 138   /etc/grml/fai/fai.conf
 139
 140 Main configuration file which specifies where all the configuration files and
 141 scripts for FAI/grml-live can be found. By default it is
 142 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
 143 out-of-the-box so you shouldn't have to configure anything in this file.
 144
 145   /etc/grml/fai/make-fai-nfsroot.conf
 146
 147 TODO
 148
 149   /etc/grml/fai/NFSROOT
 150
 151 TODO
 152
 153   /etc/grml/fai/apt/sources.list
 154
 155 This file specifies which mirrors should be used for retreiving the Debian
 156 packages used for creating the ISO. If you want to use a local mirror you have
 157 to adjust this file.
 158
 159   /etc/grml/fai/config/
 160
 161 The main directory for configuration of FAI/grml-live. More details below.
 162
 163   /etc/grml/fai/config/class/
 164
 165 This directory contains files which specify main configuration variables for the
 166 FAI classes.
 167
 168   /etc/grml/fai/config/debconf/
 169
 170 This directory provides the files for preseeding/configuration of debconf
 171 through files.
 172
 173   /etc/grml/fai/config/hooks/
 174
 175 This directory provides files for customizing the build process through hooks.
 176 Hooks are user defined programs or scripts, which are called during the
 177 installation process.
 178
 179   /etc/grml/fai/config/package_config/
 180
 181 File with lists of software packages to be installed or removed.  The different
 182 classes describe what should find its way to your ISO.  When running 'fai -v -C
 183 /etc/grml/fai -cGRML dirinstall ...' only the files from the directory GRML/
 184 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRML,FOOBAR dirinstall ...'
 185 then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So just
 186 create a new class to adjust it to your needs. Please notice that the directory
 187 GRML contains a package list defining a minimum but still reasonable package
 188 configuration.
 189
 190   /etc/grml/fai/config/scripts/
 191
 192 Scripts for customising the ISO within build process.
 193
 194   /etc/grml/fai/live-initramfs/
 195
 196 This directory provides the files used for building the initramfs/initrd via
 197 live-initramfs(8).
 198
 199 Requirements for the build system
 200 ---------------------------------
 201
 202 * any Debian based system should be sufficient (if not please send a bug
 203 report), for example a grml2hd harddisk installation ships all you need
 204
 205 * enough free disk space, at least 700MB are required for a minimal grml-live
 206 run (~400MB for the chroot [$CHROOT_TARGET], ~150MB for the build target
 207 [$BUILD_TARGET] and ~150MB for the resulting ISO [$ISO_TARGET]).
 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 * extend the grml-live wrapper script so it runs all the necessary command in a
 217 single run (boot/isolinux, mksquashfs and mkisofs stuff is missing currently)
 218
 219 * really support signed apt repositories
 220
 221 * explain (and provide configuration for) the use of NFSROOT
 222
 223 * support setting stuff like ISO name, version,... (especially for stuff inside
 224 x86_files/boot/isolinux)
 225
 226 * identify all packages that are arch specific
 227
 228 * support different flavours and architectures of Debian (currently it defaults
 229 to Debian/stable x86_32)
 230
 231 * use hooks of FAI in grml-live script?
 232
 233 * the GRML class(es) should send output as used inside FAI as well (so it's not
 234 as verbose unless you specify it)
 235
 236 * provide possibility for cleanup of all created build directories
 237
 238 Bugs
 239 ----
 240
 241 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 242 link:http://grml.org/contact/[to the grml-team]!
 243
 244 Authors
 245 -------
 246 Michael Prokop <mika@grml.org>.
 247