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.
  50 By default only the class GRML is assumed, resulting in a small base system (being
  51 about ~170MB 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.  The following files and directories are relevant for class GRML by
 100 default:
 101
 102   /etc/grml/fai/config/scripts/GRML/
 103   /etc/grml/fai/config/debconf/GRML
 104   /etc/grml/fai/config/class/GRML.var
 105   /etc/grml/fai/config/hooks/instsoft.GRML
 106   /etc/grml/fai/config/package_config/GRML
 107
 108 Take a look at the next section for information about the concept of those
 109 files/directories.
 110
 111 If you want to use your own configuration, extend an existing configuration
 112 and/or add additional packages to your ISO just invent a new class. For example
 113 if you want to use your own class named "FOOBAR" just extend CLASSES="GRML" inside
 114 /etc/grml/grml-live.conf to CLASSES="GRML,FOOBAR" or invoke grml-live using
 115 the classes option: "grml-live -c GRML,FOOBAR ...".
 116
 117 More details regarding the class concept can be found in the documentation of
 118 FAI (available at /usr/share/doc/fai-doc/).
 119
 120 Files
 121 -----
 122
 123 Notice that grml-live ships FAI configuration files that do not use the same
 124 namespace as the FAI packages itself.  This ensures that grml-live does not
 125 clash with your usual FAI configuration, so instead of /etc/fai/fai.conf
 126 (package fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details
 127 see below. To get an idea how another configuration or example files could look
 128 like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 129 fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides
 130 documentation regarding configuration possibilities.
 131
 132   /usr/sbin/grml-live
 133
 134 Script for the main build process (being a wrapper around FAI currently).
 135 Requires root permissions for execution.
 136
 137   /etc/grml/fai/fai.conf
 138
 139 Main configuration file which specifies where all the configuration files and
 140 scripts for FAI/grml-live can be found. By default it is
 141 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
 142 out-of-the-box so you shouldn't have to configure anything in this file.
 143
 144   /etc/grml/fai/make-fai-nfsroot.conf
 145
 146 TODO
 147
 148   /etc/grml/fai/NFSROOT
 149
 150 TODO
 151
 152   /etc/grml/fai/apt/sources.list
 153
 154 This file specifies which mirrors should be used for retreiving the Debian
 155 packages used for creating the ISO. If you want to use a local mirror you have
 156 to adjust this file.
 157
 158   /etc/grml/fai/config/
 159
 160 The main directory for configuration of FAI/grml-live. More details below.
 161
 162   /etc/grml/fai/config/class/
 163
 164 This directory contains files which specify main configuration variables for the
 165 FAI classes.
 166
 167   /etc/grml/fai/config/debconf/
 168
 169 This directory provides the files for preseeding/configuration of debconf
 170 through files.
 171
 172   /etc/grml/fai/config/hooks/
 173
 174 This directory provides files for customizing the build process through hooks.
 175 Hooks are user defined programs or scripts, which are called during the
 176 installation process.
 177
 178   /etc/grml/fai/config/package_config/
 179
 180 File with lists of software packages to be installed or removed.  The different
 181 classes describe what should find its way to your ISO.  When running 'fai -v -C
 182 /etc/grml/fai -cGRML dirinstall ...' only the files from the directory GRML/
 183 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRML,FOOBAR dirinstall ...'
 184 then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So just
 185 create a new class to adjust it to your needs. Please notice that the directory
 186 GRML contains a package list defining a minimum but still reasonable package
 187 configuration.
 188
 189   /etc/grml/fai/config/scripts/
 190
 191 Scripts for customising the ISO within build process.
 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 1GB are required for a minimal grml-live run
 205
 206 * fast network access for retreiving the Debian packages used for creating the
 207 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 208 as possiblbe)
 209
 210 Known TODOs
 211 -----------
 212
 213 * extend the grml-live wrapper script so it runs all the necessary command in a
 214 single run (boot/isolinux, mksquashfs and mkisofs stuff is missing currently)
 215
 216 * really support signed apt repositories
 217
 218 * explain (and provide configuration for) the use of NFSROOT
 219
 220 * support setting stuff like ISO name, version,...
 221
 222 * support different flavours and architectures of Debian (currently it defaults
 223 to Debian/stable x86_32)
 224
 225 Bugs
 226 ----
 227
 228 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 229 link:http://grml.org/contact/[to the grml-team]!
 230
 231 Authors
 232 -------
 233 Michael Prokop <mika@grml.org>.
 234