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 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 GRML. It's strongly
  91 recommended to **always** use the class GRML 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/GRML/
  97   /etc/grml/fai/config/debconf/GRML
  98   /etc/grml/fai/config/class/GRML.var
  99   /etc/grml/fai/config/hooks/instsoft.GRML
 100   /etc/grml/fai/config/package_config/GRML
 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="GRML" inside
 108 /etc/grml/grml-live.conf to CLASSES="GRML,FOOBAR" or invoke grml-live using
 109 the classes option: "grml-live -c GRML,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 -cGRML dirinstall ...' only the files from the directory GRML/
 177 will be taken, if you use 'fai -v -C /etc/grml/fai -cGRML,FOOBAR dirinstall ...'
 178 then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So just
 179 create a new class to adjust it to your needs. Please notice that the directory
 180 GRML contains a package list defining a minimum but still reasonable package
 181 configuration.
 182
 183   /etc/grml/fai/config/scripts/
 184
 185 Scripts for customising the ISO within build process.
 186
 187   /etc/grml/fai/live-initramfs/
 188
 189 This directory provides the files used for building the initramfs/initrd via
 190 live-initramfs(8).
 191
 192 Requirements for the build system
 193 ---------------------------------
 194
 195 * any Debian based system should be sufficient (if not please send a bug
 196 report), for example a grml2hd harddisk installation ships all you need
 197
 198 * enough free disk space; at least 800MB are required for a minimal grml-live
 199 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
 200 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
 201 temporary files)
 202
 203 * fast network access for retreiving the Debian packages used for creating the
 204 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 205 as possiblbe)
 206
 207 Known TODOs
 208 -----------
 209
 210 * extend the grml-live wrapper script so it runs all the necessary command in a
 211 single run (boot/isolinux, mksquashfs and mkisofs stuff is missing currently)
 212
 213 * really support signed apt repositories
 214
 215 * explain (and provide configuration for) the use of NFSROOT
 216
 217 * support setting stuff like ISO name, version,... (especially for stuff inside
 218 x86_files/boot/isolinux)
 219
 220 * identify all packages that are arch specific
 221
 222 * support different flavours and architectures of Debian (currently it defaults
 223 to Debian/stable x86_32)
 224
 225 * use hooks of FAI in grml-live script?
 226
 227 * the GRML class(es) should send output as used inside FAI as well (so it's not
 228 as verbose unless you specify it)
 229
 230 * provide possibility for cleanup of all created build directories
 231
 232 * support nocolor-option for /etc/grml/fai/grml/grml_cleanup_chroot
 233
 234 Bugs
 235 ----
 236
 237 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 238 link:http://grml.org/contact/[to the grml-team]!
 239
 240 Authors
 241 -------
 242 Michael Prokop <mika@grml.org>.
 243
 244 /////////////////////////////////////
 245 // vim:ai tw=80 ft=asciidoc expandtab
 246 /////////////////////////////////////