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