docs/grml-live.txt

   1 grml-live(8)
   2 ============
   3
   4 Name
   5 ----
   6
   7 grml-live - build framework based on FAI for generating a grml and Debian based
   8 Linux Live system (CD/ISO)
   9
  10 Synopsis
  11 --------
  12
  13 grml-live [-c <classe[s]>] [-i <iso_name> ] [-r <release_name>]
  14 [-s <suite>] [-t <target_directory>] [-v <version_number>] [-Fvh]
  15
  16 *******************************************************************************
  17 Important! This document is growing as requested. If you have questions which
  18 aren't answered by this document yet please let me know: <mika@grml.org>!
  19 *******************************************************************************
  20
  21 Description
  22 -----------
  23
  24 grml-live provides the build system for creating a grml and Debian based Linux
  25 Live-CD. The build system is based on
  26 link:http://www.informatik.uni-koeln.de/fai/[FAI] (Fully Automatic
  27 Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
  28 system based on the class concept of FAI (see later sections for further
  29 details) and provides the framework to be able to generate a full-featured ISO.
  30 It does not use all the FAI features by default though and you don't have to
  31 know FAI to be able to use it.
  32
  33 The use of FAI gives you the flexibility to choose the packages you would like
  34 to include on your very own Linux Live-CD without having to deal with all the
  35 details of a build process.
  36
  37 CAUTION: grml-live does **not** use /etc/fai for configuration but instead
  38 provides and uses /etc/grml/fai. This ensures that it does not clash with
  39 default FAI configuration and packages, so you can use grml-live and FAI
  40 completely independent at the same time!
  41
  42 [NOTE]
  43
  44 Please notice that you should have a fast network connection as all the Debian
  45 packages will be downloaded and installed via network. If you want to use a
  46 local mirror (strongly recommended if you plan to use grml-live more than once)
  47 checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
  48 debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
  49 sample configuration) and approx(8). To avoid downloading the base system again
  50 and again check out FAI's NFSROOT (see FAQ of this document for details).
  51
  52 Options
  53 -------
  54
  55   -c **CLASSES**::
  56
  57 Specify the CLASSES to be used for building the ISO via FAI.  By default only
  58 the classes GRMLBASE and I386 are assumed, resulting in a small base system
  59 (being about ~150MB total ISO size) for x86 (32bit).
  60
  61   -F::
  62
  63 Force execution and do not prompt for acknowledgment of configuration.
  64
  65   -h::
  66
  67 Display short usage information and exit.
  68
  69   -i **ISO_NAME**::
  70
  71 Specify name of ISO which will be available inside $TARGET_DIRECTORY/grml_isos
  72 by default.
  73
  74   -r **RELEASENAME**::
  75
  76 Specify name of the release. (Notice: the output of the release name is limited
  77 to 30 characters.)
  78
  79   -s **SUITE**::
  80
  81 Specify the Debian suite you want to use for your live-system.  Defaults to
  82 "etch" (being current Debian/stable). Supported values are: etch, lenny, sid,
  83 stable, testing, unstable.
  84
  85   -t **TARGET_DIRECTORY**::
  86
  87 Main output directory of the build process of FAI.  Some directories are created
  88 inside this target directory, being: grml_cd (where the files for creating the
  89 ISO are located, including the compressed squashfs file), grml_chroot (the
  90 chroot system) and grml_isos (where the resulting ISO is stored).
  91
  92   -v **VERSION_NUMBER**::
  93
  94 Specify version number of the release. (Notice: the output of the version number
  95 is limited to 5 characters. So "1.0-1" is fine, but "1.0.0.1" will be stripped
  96 to "1.0.0" then.)
  97
  98   -V::
  99
 100 Increase verbosity in the build process.
 101
 102 Usage examples
 103 --------------
 104
 105 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
 106 as build and output directory just run:
 107
 108   # grml-live
 109
 110 To get a small Debian-unstable and grml-small based Live-CD using
 111 /home/mika/grml-live as build and output directory just use:
 112
 113   # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
 114
 115 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
 116 output directory and use grml_0.0-3.iso as ISO name (placed inside
 117 /tmp/grml_isos) just invoke:
 118
 119   # grml-live -t /tmp -c GRMLBASE,I386 -s sid -i grml_0.0-3.iso
 120
 121 [NOTE]
 122
 123 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
 124 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
 125 and use /dev/shm as build and output directory - resulting in very fast build
 126 process.  But please be aware of the fact that rebooting your system will result
 127 in an empty /dev/shm, so please another directory for $CHROOT_TARGET,
 128 $BUILD_TARGET and $ISO_TARGET if you plan to create more persistent output. :)
 129
 130 Main features of grml-live
 131 --------------------------
 132
 133 * create a grml-/Debian-based Linux Live-CD with one single command
 134
 135 * class based concept, providing a maximum of flexibility
 136
 137 * supports integration of own hooks, scripts and configuration
 138
 139 * supports use and integration of own Software and/or Kernels via simple use of
 140 Debian repositories
 141
 142 * native support of FAI features
 143
 144 * multi-arch support (work in progress)
 145
 146 The class concept
 147 -----------------
 148
 149 grml-live uses FAI and its class based concept for adjusting configuration and
 150 setup according to your needs. This gives you flexibility and strength without
 151 losing the simplicity in the build process.
 152
 153 The main and base class provided by grml-live is named GRMLBASE. It's strongly
 154 recommended to **always** use the class GRMLBASE when building an ISO using
 155 grml-live, as well as the architecture dependend class which provides the kernel
 156 (being 'I386' for x86_32 currently only). The following files and directories
 157 are relevant for class GRMLBASE by default:
 158
 159   /etc/grml/fai/config/scripts/GRMLBASE/
 160   /etc/grml/fai/config/debconf/GRMLBASE
 161   /etc/grml/fai/config/class/GRMLBASE.var
 162   /etc/grml/fai/config/hooks/instsoft.GRMLBASE
 163   /etc/grml/fai/config/package_config/GRMLBASE
 164
 165 Take a look at the next section for information about the concept of those
 166 files/directories.
 167
 168 If you want to use your own configuration, extend an existing configuration
 169 and/or add additional packages to your ISO just invent a new class (or extend an
 170 existing one). For example if you want to use your own class named "FOOBAR" just
 171 extend CLASSES="GRMLBASE,I386" inside /etc/grml/grml-live.conf to
 172 CLASSES="GRMLBASE,I386,FOOBAR" or invoke grml-live using the classes option:
 173 "grml-live -c GRMLBASE,I386,FOOBAR ...".
 174
 175 More details regarding the class concept can be found in the documentation of
 176 FAI itself (being available at /usr/share/doc/fai-doc/).
 177
 178 Files
 179 -----
 180
 181 Notice that grml-live ships FAI configuration files that do not use the same
 182 namespace as the FAI packages itself. This ensures that grml-live does not clash
 183 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
 184 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
 185 below. To get an idea how another configuration or example files could look like
 186 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 187 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
 188 provides documentation regarding configuration possibilities.
 189
 190   /usr/sbin/grml-live
 191
 192 Script for the main build process. Requires root permissions for execution.
 193
 194   /etc/grml/grml-live.conf
 195
 196 Main configuration file for grml-live. All the important steps can be configured
 197 at this stage.
 198
 199   /etc/grml/fai/fai.conf
 200
 201 Main configuration file for FAI which specifies where all the configuration
 202 files and scripts for FAI/grml-live can be found. By default it is set to
 203 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
 204 out-of-the-box so you shouldn't have to configure anything in this file.
 205
 206   /etc/grml/fai/make-fai-nfsroot.conf
 207
 208 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
 209 anything inside this file. If you want to modify NFSROOT though you can adjust
 210 it there.
 211
 212   /etc/grml/fai/NFSROOT
 213
 214 This file specifies the package list for creating the NFSROOT.
 215
 216   /etc/grml/fai/apt/sources.list
 217
 218 This file specifies which mirrors should be used for retreiving the Debian
 219 packages used for creating the main chroot (including all the software you would
 220 like to see included). If you want to use a local mirror you either have to
 221 adjust this file or use the GRML_LIVE_SOURCES variable inside
 222 /etc/grml/grml-live.conf which modifies /etc/grml/fai/apt/sources.list
 223 on-the-fly then.
 224
 225   /etc/grml/fai/config/
 226
 227 The main directory for configuration of FAI/grml-live. More details below.
 228
 229   /etc/grml/fai/config/class/
 230
 231 This directory contains files which specify main configuration variables for the
 232 FAI classes.
 233
 234   /etc/grml/fai/config/debconf/
 235
 236 This directory provides the files for preseeding/configuration of debconf
 237 through files.
 238
 239   /etc/grml/fai/config/hooks/
 240
 241 This directory provides files for customising the build process through hooks.
 242 Hooks are user defined programs or scripts, which are called during the
 243 installation process.
 244
 245   /etc/grml/fai/config/package_config/
 246
 247 Directory with lists of software packages to be installed or removed.  The
 248 different classes describe what should find its way to your ISO.  When running
 249 "grml-live -c GRMLBASE,I386 ..." only the files from the directories GRMLBASE
 250 and I386 will be taken, if you use 'grml-live -c GRMLBASE,I386,FOOBAR ...' then
 251 the files of GRMLBASE, I386 **plus** the files from FOOBAR will be taken. So
 252 just create a new class to adjust the package selection according to your needs.
 253 Please notice that the directory GRMLBASE contains a package list defining a
 254 minimum but still reasonable package configuration.
 255
 256   /etc/grml/fai/config/scripts/
 257
 258 Scripts for customising the ISO within the build process.
 259
 260   /etc/grml/fai/files/
 261
 262 This directory provides files used inside the scripts of
 263 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
 264 files please refer to the source of the scripts.
 265
 266   /etc/grml/fai/live-initramfs/
 267
 268 This directory provides the files used for building the initramfs/initrd via
 269 live-initramfs(8).
 270
 271 Requirements for the build system
 272 ---------------------------------
 273
 274 * any Debian based system should be sufficient (if not it's a bug, so please
 275 send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
 276 harddisk installation ships all you need]
 277
 278 * enough free disk space; at least 800MB are required for a minimal grml-live
 279 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
 280 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
 281 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
 282 total free disk space
 283
 284 * fast network access for retreiving the Debian packages used for creating the
 285 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 286 as possiblbe)
 287
 288 FAQ
 289 ---
 290
 291 Help, I'm using Debian etch and I don't have FAI version >3.2
 292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 293
 294   wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.1_all.deb \
 295        http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.1_all.deb
 296   dpkg -i fai-client_3.2.1_all.deb fai-server_3.2.1_all.deb
 297
 298 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
 299 further details.
 300
 301 I've problems with the build process. How to start debugging?
 302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 303
 304 Check out the logs inside /var/log/fai/dirinstall/... If you don't have the time
 305 to debug the problem in further detail or don't know how to proceed just send a
 306 copy of your config, logs and the commandline with a short problem description
 307 to <mika@grml.org>:
 308
 309   # history | grep grml-live > /etc/grml/grml_live.cmdline
 310   # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
 311             /var/log/fai/dirinstall /etc/grml/fai
 312
 313 Can I use my own (local) Debian mirror?
 314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 315
 316 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
 317 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
 318 your needs. Please don't forget that you should use the grml servers as well
 319 (see default configuration) so all the grml packages can be downloaded as well.
 320
 321 If you want to use a local (for example NFS mount) mirror additionally, just
 322 adjust MIRROR_DIRECTORY and MIRROR_SOURCES insede /etc/grml/grml-live.conf as
 323 well.
 324
 325 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
 326 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
 327 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
 328 files will be adjusted during runtime automatically.
 329
 330 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
 331 taken as first entry in the generated sources.list so it's prefered over
 332 non-local mirrors. Using a fallback mirror (via providing several mirrors in
 333 GRML_LIVE_SOURCES as used by default) is a recommended setting.
 334
 335 How do I add additional Debian package(s) to my CD/ISO?
 336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 337
 338 Just create a new class (using the package_config directory):
 339
 340   # cat > /etc/grml/fai/config/package_config/MIKA << EOF
 341   PACKAGES aptitude
 342
 343   vim
 344   another_name_of_a_debian_package
 345   and_another_one
 346   EOF
 347
 348 and specify it when invoking grml-live then:
 349
 350   # grml-live -c GRMLBASE,I386,MIKA
 351
 352 I fscked up my grml-live configuration. How do I reset it to the defaults?
 353 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 354
 355 Notice: this deletes all your grml-live configuration files. If that's really
 356 what you are searching for just run:
 357
 358   rm -rf /etc/grml/fai /etc/grml/grml-live.conf
 359   dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
 360
 361 [NOTE]
 362
 363 If you don't control your /etc using a version control system (VCS) yet it's a
 364 good chance to start using it now. Check out
 365 link:http://michael-prokop.at/blog/2007/03/14/maintain-etc-with-mercurial-on-debian/[http://michael-prokop.at/blog/2007/03/14/maintain-etc-with-mercurial-on-debian/]
 366 for more details how to maintain /etc using the mercurial VCS.
 367
 368 How do I create a base.tgz for use as NFSROOT?
 369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 370
 371 First of all build the chroot system:
 372
 373   mkdir /tmp/nfsroot && cd /tmp/nfsroot
 374   debootstrap etch /tmp/nfsroot/ http://ftp.de.debian.org/debian
 375   tar zcf base.tgz ./
 376
 377 Then check out where your NFSROOT is located:
 378
 379   # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
 380   NFSROOT=/grml/fai/nfsroot
 381
 382 So as /grml/fai/nfsroot is your NFSROOT place the file under
 383 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
 384
 385   mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 386
 387 Now running "grml-live ..." will use this file as main system instead of
 388 executing debootstrap. Check out the output for the following lines:
 389
 390   [...]
 391   Calling task_extrbase
 392   Unpacking Debian base archive
 393   Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 394   Calling task_mirror
 395   [...]
 396
 397 I've a question which isn't answered by this document
 398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 399
 400 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
 401 a mail: <mika@grml.org>
 402
 403 Download / install grml-live as a Debian package
 404 ------------------------------------------------
 405
 406 Debian packages are available through the grml-repository at
 407 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org].  If you want to
 408 build a Debian package on your own (using for example a specific version or the
 409 current development tree), just execute:
 410
 411   hg clone http://hg.grml.org/grml-live
 412   cd grml-live
 413   debuild -us -uc
 414
 415 Source
 416 ------
 417
 418 The source of grml-live is available at
 419 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
 420
 421 TODO list
 422 ---------
 423
 424 Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
 425 for details.
 426
 427 Bugs
 428 ----
 429
 430 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 431 link:http://grml.org/contact/[to the grml-team]!
 432
 433 Authors
 434 -------
 435 Michael Prokop <mika@grml.org>.
 436
 437 /////////////////////////////////////
 438 // vim:ai tw=80 ft=asciidoc expandtab
 439 /////////////////////////////////////