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 [-a <architecture>] [-c <classe[s]>] [-C <configfile>] [-g
  14 <grml_name>] [-i <iso_name> ] [-o <output_directory>] [-r <release_name>] [-s
  15 <suite>] [-t <template_directory>] [-v <version_number>] [-bBFhquVz]
  16
  17 CAUTION: Please check out <<current_state,the 'Current state of grml-live with
  18 squashfs-tools and kernel' section>> for details about current state of involved
  19 tools before starting with grml-live or if you encounter any problems.
  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), apt-cacher(1) and approx(8). To avoid downloading the
  50 base system again and again check out FAI's NFSROOT (see FAQ of this document
  51 for details).
  52
  53 Options
  54 -------
  55
  56   -a **ARCHITECTURE**::
  57
  58 Use the specified architecture instead of the currently running one.  This
  59 allows building a 32bit system on a 64bit host (though you can't build a 64bit
  60 system on a 32bit system/kernel of course). Please notice that real
  61 crosscompiling (like building a ppc system on x86) isn't possible due to the
  62 nature and the need of working in a chroot. Currently supported values: i386
  63 and amd64.
  64
  65   -b::
  66
  67 Build the ISO without updating the chroot via FAI. This option is useful for
  68 example when working on stable releases: if you have a working base
  69 system/chroot and do not want to execute any further updates (via "-u" option)
  70 but intend to only build the ISO.
  71
  72   -B::
  73
  74 Build the ISO without touching the chroot at all. This option is useful if
  75 you modified anything that FAI or grml-live might adjust via grml's FAI
  76 scripts.  It's like the '-b' option but even more advanced. Use only if you
  77 really know that you do not want to update the chroot.
  78
  79   -c **CLASSES**::
  80
  81 Specify the CLASSES to be used for building the ISO via FAI.  By default only
  82 the classes GRMLBASE, GRML_MEDIUM and I386 are assumed, resulting in a small base
  83 system (being about ~180MB total ISO size). If using a non-I386 system (like
  84 amd64) you should specify the appropriate architecture as well. Additionally you
  85 can specify a class providing a grml-kernel (see
  86 <<classes,the 'CLASSES' section in this document>> for details about available classes).
  87 So instead of GRML_MEDIUM you can also use GRML_SMALL and GRML_FULL.
  88
  89   -C **CONFIGURATION_FILE**::
  90
  91 The specified file is used as configuration file for grml-live. By default
  92 /etc/grml/grml-live.conf is used as default configuration. If a file named
  93 /etc/grml/grml-live.local exists it is used as well (sourced after reading
  94 /etc/grml/grml-live.conf meant as main file for local configuration). As a last
  95 option the specified configuration file is sourced so it is possible to override
  96 settings of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local.
  97 Please notice that all configuration files have to be adjusted during execution
  98 of grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
  99 your own configuration file (usually /etc/grml/grml-live.local). Please also
 100 notice that the configuration file specified via this option is **not** (yet)
 101 supported inside the scripts/hooks/classes at /etc/grml/fai/config. Instead use
 102 /etc/grml/grml-live.local for configuration stuff used inside
 103 /etc/grml/fai/config.
 104
 105   -F::
 106
 107 Force execution and do not prompt for acknowledgment of configuration.
 108
 109   -g **GRML_NAME**::
 110
 111 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
 112 Please do NOT use blanks and any special characters like '/', ';' inside
 113 GRML_NAME, otherwise you might notice problems while booting.
 114
 115   -h::
 116
 117 Display short usage information and exit.
 118
 119   -i **ISO_NAME**::
 120
 121 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
 122 by default.
 123
 124   -I **CHROOT_INSTALL**::
 125
 126 Specify name of source directory which provides files that should become part of
 127 the chroot/ISO. Not enabled by default. Note: the files are installed under '/'
 128 in the chroot so you have to create the rootfs structure on your own.
 129
 130   -n::
 131
 132 Skip creation of the ISO file. This option is useful if you want to build/update
 133 the chroot and/or recreate the squashfs file without building an ISO file.
 134
 135   -o **OUTPUT_DIRECTORY**::
 136
 137 Main output directory of the build process of FAI.  Some directories are created
 138 inside this target directory, being: grml_cd (where the files for creating the
 139 ISO are located, including the compressed squashfs file), grml_chroot (the
 140 chroot system) and grml_isos (where the resulting ISO is stored).
 141
 142   -q::
 143
 144 Build the ISO without (re-)creating the squashfs compressed file using mksquashfs.
 145 This option is useful if you just want to update parts outside the chroot in the ISO.
 146 Consider combining this option with the build-only option '-b'.
 147
 148   -r **RELEASENAME**::
 149
 150 Specify name of the release.
 151
 152   -s **SUITE**::
 153
 154 Specify the Debian suite you want to use for your live-system.  Defaults to
 155 "lenny" (being current Debian/stable). Supported values are: etch, lenny, sid.
 156 Debian "squeeze" (current Debian/testing) requires base.tgz
 157 (/etc/grml/fai/config/basefiles/....tar.gz) or a recent version of debootstrap.
 158
 159   -t **TEMPLATE_DIRECTORY**::
 160
 161 Specify place of the templates used for building the ISO. By default
 162 (and if not manually specified) this is /usr/share/grml-live/templates/.
 163
 164   -u::
 165
 166 Update existing chroot instead of rebuilding it from scratch. This option is
 167 based on the softupdate feature of FAI.
 168
 169   -v **VERSION_NUMBER**::
 170
 171 Specify version number of the release.
 172
 173   -V::
 174
 175 Increase verbosity in the build process.
 176
 177   -z::
 178
 179 Use ZLIB instead of LZMA compression in mksquashfs part of the build process.
 180
 181 [[usage-examples]]
 182 Usage examples
 183 --------------
 184
 185 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
 186 as build and output directory just run:
 187
 188   # grml-live
 189
 190 To get a small Debian-unstable and grml-small based Live-CD using
 191 /home/mika/grml-live as build and output directory just use:
 192
 193   # grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
 194
 195 To get a medium sized, Debian-unstable and grml-based Live-CD for i386
 196 architecture using /grml/grml-live as build and output directory just run:
 197
 198   # grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
 199
 200 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
 201 output directory and use grml_0.0-3.iso as ISO name (placed inside
 202 /tmp/grml_isos) just invoke:
 203
 204   # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
 205
 206 [NOTE]
 207
 208 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
 209 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
 210 and use /dev/shm as build and output directory - resulting in very fast build
 211 process.  But please be aware of the fact that rebooting your system will result
 212 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
 213 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
 214
 215 [[main-features]]
 216 Main features of grml-live
 217 --------------------------
 218
 219 * create a grml-/Debian-based Linux Live-CD with one single command
 220
 221 * class based concept, providing a maximum of flexibility
 222
 223 * supports integration of own hooks, scripts and configuration
 224
 225 * supports use and integration of own Software and/or Kernels via simple use of
 226 Debian repositories
 227
 228 * native support of FAI features
 229
 230 * multi-arch support (work in progress)
 231
 232 [[class-concept]]
 233 The class concept
 234 -----------------
 235
 236 grml-live uses FAI and its class based concept for adjusting configuration and
 237 setup according to your needs. This gives you flexibility and strength without
 238 losing the simplicity in the build process.
 239
 240 The main and base class provided by grml-live is named GRMLBASE. It's strongly
 241 recommended to **always** use the class GRMLBASE when building an ISO using
 242 grml-live, as well as the architecture dependent class which provides the kernel
 243 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
 244 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
 245 relevant for class GRMLBASE by default:
 246
 247   /etc/grml/fai/config/scripts/GRMLBASE/
 248   /etc/grml/fai/config/debconf/GRMLBASE
 249   /etc/grml/fai/config/class/GRMLBASE.var
 250   /etc/grml/fai/config/hooks/instsoft.GRMLBASE
 251   /etc/grml/fai/config/package_config/GRMLBASE
 252
 253 Take a look at the next section for information about the concept of those
 254 files/directories.
 255
 256 If you want to use your own configuration, extend an existing configuration
 257 and/or add additional packages to your ISO just invent a new class (or extend an
 258 existing one). For example if you want to use your own class named "FOOBAR" just
 259 set CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.local or
 260 invoke grml-live using the classes option: "grml-live -c
 261 GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
 262
 263 More details regarding the class concept can be found in the documentation of
 264 FAI itself (being available at /usr/share/doc/fai-doc/).
 265
 266 [[X7]]
 267 [[classes]]
 268 Available classes
 269 -----------------
 270
 271 The package selection part of the classes can be found in
 272 /etc/grml/fai/config/package_config whereas some further classes are defined for
 273 example in /etc/grml/fai/config/scripts/ so specific feature sets can be
 274 selected. The following classes are predefined:
 275
 276 * DEBORPHAN: get rid of all packages listed in output of Deborphan
 277
 278 * GRMLBASE: the main class responsible for getting a minimal subset of what's
 279 defining a grml system. Important parts of the buildprocess are specified in
 280 this class as well, so unless you have a really good reason you should always
 281 use this class.
 282
 283 * GRML_FORENSIC: tools for forensic investigations which has been created
 284 by people from link:http://www.forensic-geeks.org/[forensic-geeks.org].
 285
 286 * GRML_FULL: full featured grml, also known as the "normal", full grml.
 287
 288 * GRML_MEDIUM: medium sized grml version, known as grml-medium
 289
 290 * GRML_POWERPC: grml for PowerPC architecture, not supported yet (still work in
 291 progress)
 292
 293 * GRML_SMALL: minimum sized grml version, known as grml-small
 294
 295 * LATEX: LaTeX(-related) packages like auctex, texlive,...
 296 (which used to be shipped by grml before the LaTeX removal)
 297
 298 * LATEX_CLEANUP: get rid of several very large LaTeX directories
 299 (like some /usr/share/doc/texlive-*, /usr/share/doc/texmf,...)
 300
 301 * LOCALES: use full featured locales setup (see /etc/locale.gen.grml). This
 302 avoids to get rid of /usr/share/locale - which happens by default otherwise - as
 303 well.
 304
 305 * NO_ONLINE: do not run scripts during the chroot build process which require a
 306 network connection
 307
 308 * RELEASE: run some specific scripts and commands to provide the workflow for an
 309 official grml release
 310
 311 * REMOVE_DOCS: get rid of documentation directories (like /usr/share/doc,
 312 /usr/share/man/, /usr/share/info,...)
 313
 314 * XORG: providing important packages for use with a base grml-featured X.org
 315 setup
 316
 317 [[files]]
 318 Files
 319 -----
 320
 321 Notice that grml-live ships FAI configuration files that do not use the same
 322 namespace as the FAI packages itself. This ensures that grml-live does not clash
 323 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
 324 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
 325 below. To get an idea how another configuration or example files could look like
 326 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 327 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
 328 provides documentation regarding configuration possibilities.
 329
 330   /usr/sbin/grml-live
 331
 332 Script for the main build process. Requires root permissions for execution.
 333
 334   /etc/grml/grml-live.conf
 335
 336 Main configuration file for grml-live which should be considered as a reference
 337 configuration file only. Please use /etc/grml/grml-live.local for local
 338 configuration instead.
 339
 340   /etc/grml/grml-live.local
 341
 342 All the local configuration should go to this file. This file overrides any
 343 defaults of grml-live. Configurations via /etc/grml/grml-live.local are prefered
 344 over the ones from /etc/grml/grml-live.conf. If you want to override settings
 345 from /etc/grml/grml-live.local as well you have to specify them on the grml-live
 346 commandline.
 347
 348   /etc/grml/fai/fai.conf
 349
 350 Main configuration file for FAI which specifies where all the configuration
 351 files and scripts for FAI/grml-live can be found. By default it is set to
 352 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
 353 out-of-the-box so you shouldn't have to configure anything in this file.
 354
 355   /etc/grml/fai/make-fai-nfsroot.conf
 356
 357 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
 358 anything inside this file. If you want to modify NFSROOT though you can adjust
 359 it there.
 360
 361   /etc/grml/fai/NFSROOT
 362
 363 This file specifies the package list for creating the NFSROOT.
 364
 365   /etc/grml/fai/apt/sources.list
 366
 367 This file specifies which mirrors should be considered for retrieving the Debian
 368 packages when creating the main chroot (including all the software you would
 369 like to see included). Important: this file should *not* be adjusted manually!
 370 Instead use the GRML_LIVE_SOURCES variable inside /etc/grml/grml-live.conf or
 371 /etc/grml/grml-live.local which modifies /etc/grml/fai/apt/sources.list
 372 on-the-fly via grml-live then. If you want to generally adjust apt configuration
 373 check out /etc/grml/fai/files/etc/apt instead.
 374
 375   /etc/grml/fai/config/
 376
 377 The main directory for configuration of FAI/grml-live. More details below.
 378
 379   /etc/grml/fai/config/class/
 380
 381 This directory contains files which specify main configuration variables for the
 382 FAI classes.
 383
 384   /etc/grml/fai/config/debconf/
 385
 386 This directory provides the files for preseeding/configuration of debconf
 387 through files.
 388
 389   /etc/grml/fai/config/hooks/
 390
 391 This directory provides files for customising the build process through hooks.
 392 Hooks are user defined programs or scripts, which are called during the
 393 installation process.
 394
 395   /etc/grml/fai/config/package_config/
 396
 397 Directory with lists of software packages to be installed or removed.  The
 398 different classes describe what should find its way to your ISO.  When running
 399 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
 400 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
 401 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
 402 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
 403 adjust the package selection according to your needs.  Please notice that the
 404 directory GRMLBASE contains a package list defining a minimum but still
 405 reasonable package configuration.
 406
 407   /etc/grml/fai/config/scripts/
 408
 409 Scripts for customising the ISO within the build process.
 410
 411   /etc/grml/fai/files/
 412
 413 This directory provides files used inside the scripts of
 414 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
 415 files please refer to the source of the scripts.
 416
 417   /etc/grml/fai/live-initramfs/
 418
 419 This directory provides the files used for building the initramfs/initrd via
 420 live-initramfs(8).
 421
 422 [[log-files]]
 423 Available log files
 424 -------------------
 425
 426 grml-live itself logs to /var/log/grml-live.log. Unless you set ZERO_LOGFILE in
 427 /etc/grml/grml-live.conf the output is appended to the file. If you set the
 428 ZERO_LOGFILE configuration option the logfile will be truncated on each new
 429 invocation of grml-live.
 430
 431 The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the
 432 default being /var/log/fai/grml/.
 433
 434 If you are using the grml-live buildd you will find the logs of the grml-live
 435 run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
 436
 437 [[requirements]]
 438 Requirements for the build system
 439 ---------------------------------
 440
 441 * any Debian based system should be sufficient (if it doesn't work it's a bug,
 442 please send us a bug report then) [a usual
 443 link:http://grml.org/grml2hd/[grml2hd] harddisk installation (using grml or
 444 grml-medium) ships all you need]. Check out <<deploy-on-debian,How do I deploy
 445 grml-live on a plain Debian installation>> for details how to set up grml-live
 446 on a plain, original Debian system.
 447
 448 * enough free disk space; at least 800MB are required for a minimal grml-live
 449 run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
 450 [$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
 451 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
 452 total free disk space
 453
 454 * fast network access for retrieving the Debian packages used for creating the
 455 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 456 as possible)
 457
 458 For further information see next section.
 459
 460 [[X8]]
 461 [[current_state]]
 462 Current state of grml-live with squashfs-tools and kernel
 463 ---------------------------------------------------------
 464
 465 To make it easier to track problems this section documents current state of
 466 grml-live playing together with squashfs-tools / squashfs-lzma-tools (for
 467 building the compressed file) and the kernel version. Documentation of this
 468 section is up2date by 04nd of august 2009, please report any bugs you
 469 encounter.
 470
 471 Using squashfs-lzma-tools 3.3-1 on the build system
 472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 473
 474 squashfs-lzma-tools from the grml repository supports kernel 2.6.26-grml[64] and
 475 2.6.28-grml[64] using both lzma and zlib (-nolzma) compression. It's the
 476 recommended package for building ISOs with grml-live currently!
 477
 478 The packages can be downloaded from
 479 link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/].
 480
 481 [NOTE]
 482 Please use squashfs-lzma-tools 3.3-1 if you want to remaster grml release
 483 2008.11 or 2009.05.
 484
 485 Using squashfs-tools 1:3.3-7 on the build system
 486 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 487
 488 squashfs-tools 1:3.3-7 is available via the official Debian/unstable and
 489 Debian/testing (Lenny) pool running:
 490
 491   # aptitude install squashfs-tools=1:3.3-7
 492
 493 or directly via downloading the files
 494 http://grml.org/squashfs/squashfs-tools_3.3-7_i386.deb (for x86) or
 495 http://grml.org/squashfs/squashfs-tools_3.3-7_amd64.deb (for amd64) [both build
 496 on and for Debian/etch but working with testing and unstable as well].
 497
 498 Please notice that squashfs-tools 1:3.3-7 does NOT support LZMA compression at
 499 all (so you won't be able to remaster release 2008.11 and 2009.05 using LZMA for
 500 example). The -nolzma option of mksquashfs is not available therefore (even
 501 though grml-live will deactivate it for you automatically anyway). Please use
 502 squashfs-lzma-tools instead.
 503
 504 * Kernel 2.6.23-grml: does NOT work, please use squashfs-tools 1:3.2r2-9exp1
 505                       instead if you still want to use kernel 2.6.23 (not
 506                       recommended)
 507 * Kernel 2.6.26-grml: works (without LZMA compression only of course!)
 508 * Kernel 2.6.28-grml: works (without LZMA compression only of course!)
 509
 510 Using squashfs-tools 1:3.2r2-9exp1 on the build system
 511 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 512
 513 squashfs-tools 1:3.2r2-9exp1 is available via the grml-testing repository,
 514 running:
 515
 516   # aptitude install squashfs-tools=1:3.2r2-9exp1
 517
 518 or directly via downloading the files
 519 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_i386.deb (for x86) or
 520 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_amd64.deb (for amd64).
 521
 522 Using with ZLIB compression (SQUASHFS_OPTIONS='-nolzma' or -z
 523 option in grml-live cmdline):
 524
 525 * Kernel 2.6.23-grml: works
 526 * Kernel 2.6.26-grml: works
 527 * Kernel 2.6.28-grml: supposed to work (not verified though)
 528
 529 Using with LZMA compression:
 530
 531 * Kernel 2.6.23-grml: works
 532 * Kernel 2.6.26-grml: does NOT work, please use zlib mode instead or switch
 533   to Debian package squashfs-lzma-tools (see section above).
 534 * Kernel 2.6.28-grml: does NOT work, please use zlib mode instead or switch
 535   to Debian package squashfs-lzma-tools (see section above).
 536
 537 [[faq]]
 538 FAQ
 539 ---
 540
 541 [[deploy-on-debian]]
 542 How do I deploy grml-live on a plain Debian installation?
 543 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 544
 545 The easiest way to get a running grml-live setup is to install grml or
 546 grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you
 547 don't want to run it on a physical system). Of course using grml-live on a
 548 plain, original Debian installation is supported as well. So there we go.
 549
 550 What we have: plain, original Debian Lenny (5.0).
 551
 552 What we want: build a grml-medium ISO based on Debian/squeeze for the i386
 553 architecture using grml-live.
 554
 555 [IMPORTANT]
 556
 557 If you encounter any problems while booting the resulting ISO please be aware of
 558 <<current_state,the 'current state of grml-live with squashfs-tools and kernel'
 559 section>>.
 560
 561 Instructions
 562 ^^^^^^^^^^^^
 563
 564   # adjust sources.list:
 565   cat >> /etc/apt/sources.list << EOF
 566
 567   # grml stable repository:
 568     deb     http://deb.grml.org/ grml-stable  main
 569     deb-src http://deb.grml.org/ grml-stable  main
 570
 571   # grml testing/development repository:
 572     deb     http://deb.grml.org/ grml-testing main
 573     deb-src http://deb.grml.org/ grml-testing main
 574   EOF
 575
 576   # adjust apt-pinning (only prefer squashfs stuff from grml):
 577   cat >> /etc/apt/preferences << EOF
 578   Package: *
 579   Pin: origin deb.grml.org
 580   Pin-Priority: 1
 581
 582   Package: squashfs-tools
 583   Pin: origin deb.grml.org
 584   Pin-Priority: 996
 585
 586   Package: squashfs-lzma-tools
 587   Pin: origin deb.grml.org
 588   Pin-Priority: 996
 589   EOF
 590
 591   # get keyring for apt:
 592   apt-get update
 593   apt-get --allow-unauthenticated install grml-debian-keyring
 594
 595   # install basefile so we don't have to build basic chroot from scratch:
 596   mkdir -p /etc/grml/fai/config/basefiles/
 597   mv base.tgz /etc/grml/fai/config/basefiles/I386.tar.gz
 598
 599   # install relevant tools:
 600   apt-get -o APT::Install-Recommends=false install grml-live squashfs-lzma-tools
 601
 602   # adjust grml-live configuration for our needs:
 603   cat > /etc/grml/grml-live.local << EOF
 604   # consider using lzma only for space reasons (resulting in longer
 605   # build time but smaller ISO):
 606   SQUASHFS_OPTIONS="-nolzma"
 607   # install local files into the chroot
 608   CHROOT_INSTALL="/etc/grml/fai/chroot_install"
 609   ## adjust if necessary (defaults to /grml/grml-live):
 610   ## OUTPUT="/srv/grml-live"
 611   FAI_DEBOOTSTRAP="squeeze http://cdn.debian.net/debian/"
 612   ARCH="i386"
 613   CLASSES="GRMLBASE,GRML_MEDIUM,I386"
 614   ZERO_LOGFILE='1'
 615   # ZERO_FAI_LOGFILE='1'
 616   GRML_LIVE_SOURCES="
 617   deb http://deb.grml.org/            grml-stable  main
 618   deb http://deb.grml.org/            grml-testing main
 619   deb http://cdn.debian.net/debian squeeze main contrib non-free
 620   "
 621   EOF
 622
 623   # just optional(!) - upgrade FAI to latest available version:
 624   cat >> /etc/apt/sources.list << EOF
 625   # fai:
 626     deb http://www.informatik.uni-koeln.de/fai/download lenny koeln
 627   EOF
 628
 629   # get gpg key of FAI repos and install current FAI version:
 630   gpg -a --recv-keys AB9B66FD; gpg -a --export AB9B66FD | apt-key add -
 631   apt-get update
 632   apt-get install fai-client fai-server fai-doc
 633
 634 That's it. Now invoking 'grml-live -V' should build the ISO.  If everything
 635 worked as expected the last line of the shell output should look like:
 636
 637   [*] Successfully finished execution of grml-live [running 687 seconds]
 638
 639 and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.
 640
 641 [[fai-on-etch]]
 642 Help, I'm using Debian etch and I don't have FAI version >3.2
 643 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 644
 645   wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.8_all.deb \
 646        http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.8_all.deb \
 647        http://www.informatik.uni-koeln.de/fai/download/etch/fai-doc_3.2.8_all.deb
 648   dpkg -i fai-client_3.2.8_all.deb fai-server_3.2.8_all.deb fai-doc_3.2.8_all.deb
 649
 650 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
 651 further details.
 652
 653 [[how-to-debug]]
 654 I've problems with the build process. How to start debugging?
 655 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 656
 657 Check out the logs inside /var/log/fai/... If you think it's a bug in grml-live
 658 send a copy of your config, logs and the commandline with a short problem
 659 description to <mika@grml.org>:
 660
 661   # history | grep grml-live > /etc/grml/grml_live.cmdline
 662   # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
 663             /etc/grml/grml-buildd.conf /var/log/fai /etc/grml/fai
 664   -> finally mail grml_live_problem.tar.gz to <mika@grml.org>
 665
 666 If you need help with grml-live or would like to see new features as part of
 667 grml-live you can get commercial support via
 668 link:http://grml-solutions.com/[Grml Solutions].
 669
 670 [[install-local-files]]
 671 How to I install further files into the chroot/ISO?
 672 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 673
 674 Just point the configuration variable CHROOT_INSTALL to the directory which
 675 provides the files you would like to install. Note that the files are installed
 676 under '/' in the chroot - so you have to create the rootfs structure on your
 677 own. Usage example:
 678
 679   echo "CHROOT_INSTALL=\$GRML_FAI_CONFIG/chroot_install" >> /etc/grml/grml-live.local
 680   mkdir -p /etc/grml/fai/chroot_install/usr/src/
 681   wget example.org/foo.tar.gz
 682   mv foo.tar.gz /etc/grml/fai/chroot_install/usr/src/
 683   grml-live ...
 684
 685 [[local-debian-mirror]]
 686 Can I use my own (local) Debian mirror?
 687 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 688
 689 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
 690 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
 691 your needs. Please don't forget that you should use the grml servers as well
 692 (see default configuration) so all the grml packages can be downloaded as well.
 693
 694 If you want to use a local (for example NFS mount) mirror additionally, just
 695 adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as
 696 well.
 697
 698 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
 699 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
 700 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
 701 files will be adjusted during runtime automatically.
 702
 703 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
 704 taken as first entry in the generated sources.list so it's prefered over
 705 non-local mirrors. Using a fallback mirror (via providing several mirrors in
 706 GRML_LIVE_SOURCES as used by default) is a recommended setting.
 707
 708 [[add-additional-debian-packages]]
 709 How do I add additional Debian package(s) to my CD/ISO?
 710 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 711
 712 Just create a new class (using the package_config directory):
 713
 714   # cat > /etc/grml/fai/config/package_config/MIKA << EOF
 715   PACKAGES aptitude
 716
 717   vim
 718   another_name_of_a_debian_package
 719   and_another_one
 720   EOF
 721
 722 and specify it when invoking grml-live then:
 723
 724   # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
 725
 726 [[reset-grml-live-configuration]]
 727 I fscked up my grml-live configuration. How do I reset it to the defaults?
 728 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 729
 730 Notice: this deletes all your grml-live configuration files. If that's really
 731 what you are searching for just run:
 732
 733   rm -rf /etc/grml/fai /etc/grml/grml-live.conf
 734   dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
 735
 736 [NOTE]
 737
 738 If you don't control your /etc using a version control system (VCS) yet it's a
 739 good chance to start using it now. Check out
 740 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/]
 741 for more details how to maintain /etc using the mercurial VCS.
 742
 743 [[create-a-base-tgz]]
 744 How do I create a base.tgz for use as NFSROOT?
 745 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 746
 747 First of all build the chroot system:
 748
 749   mkdir /tmp/nfsroot && cd /tmp/nfsroot
 750   debootstrap lenny /tmp/nfsroot/ http://cdn.debian.net/debian
 751   tar zcf base.tgz ./
 752
 753 Then check out where your NFSROOT is located:
 754
 755   # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
 756   NFSROOT=/grml/fai/nfsroot
 757
 758 So as /grml/fai/nfsroot is your NFSROOT place the file under
 759 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
 760
 761   mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 762
 763 or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
 764 Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
 765
 766 Now running "grml-live ..." will use this file as main system instead of
 767 executing debootstrap. Check out the output for the following lines if using
 768 NFSROOT:
 769
 770   [...]
 771   Calling task_extrbase
 772   Unpacking Debian base archive
 773   Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 774   Calling task_mirror
 775   [...]
 776
 777 or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
 778
 779   [...]
 780   ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
 781   /grml-live/grml-live_20071029.22138/grml_chroot//
 782   [...]
 783
 784 [[apt-cacher]]
 785 Set up apt-cacher / apt-cacher-ng for use with grml-live
 786 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 787
 788 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
 789 FAI_DEBOOTSTRAP:
 790
 791   # cat /etc/grml/grml-live.conf
 792   [...]
 793   GRML_LIVE_SOURCES="
 794   deb http://localhost:3142/deb.grml.org grml-stable  main
 795   deb http://localhost:3142/deb.grml.org grml-testing main
 796   deb http://localhost:3142/cdn.debian.net/debian lenny main contrib non-free
 797   "
 798   [...]
 799   FAI_DEBOOTSTRAP="lenny http://localhost:3142/cdn.debian.net/debian lenny main contrib non-free"
 800
 801 Make sure apt-cacher / apt-cacher-ng is running ('/etc/init.d/apt-cacher
 802 restart' or '/etc/init.d/apt-cacher-ng restart'). That's it.  All downloaded
 803 files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then.
 804
 805 [[approx]]
 806 Set up approx for use with grml-live
 807 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 808
 809 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
 810 FAI_DEBOOTSTRAP:
 811
 812   # cat /etc/grml/grml-live.conf
 813   [...]
 814   GRML_LIVE_SOURCES="
 815   deb http://localhost:9999/grml            grml-stable  main
 816   deb http://localhost:9999/grml            grml-testing main
 817   deb http://localhost:9999/debian lenny    main contrib non-free
 818   "
 819   FAI_DEBOOTSTRAP="lenny http://localhost:9999/debian"
 820
 821 Configure approx:
 822
 823   # cat /etc/approx/approx.conf
 824   [...]
 825   debian http://ftp.at.debian.org/debian
 826   grml   http://deb.grml.org/
 827
 828 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
 829 All downloaded files will be cached in /var/cache/approx now.
 830
 831 [[question]]
 832 I've a question which isn't answered by this document
 833 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 834
 835 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
 836 a mail: <mika@grml.org>
 837
 838 [[download]]
 839 Download / install grml-live as a Debian package
 840 ------------------------------------------------
 841
 842 Debian packages are available through the grml-repository at
 843 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org].  If you want to
 844 build a Debian package on your own (using for example a specific version or the
 845 current development tree), just execute:
 846
 847   git clone git://git.grml.org/grml-live
 848   cd grml-live
 849   debuild -us -uc
 850
 851 [[source]]
 852 Source
 853 ------
 854
 855 The source of grml-live is available at
 856 link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git]
 857
 858 [[todo-list]]
 859 TODO list
 860 ---------
 861
 862 Check out the link:http://git.grml.org/?p=grml-live.git;a=blob;f=TODO;hb=HEAD[TODO file].
 863
 864 [[bugs]]
 865 Bugs
 866 ----
 867
 868 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 869 link:http://grml.org/contact/[to the grml-team]!
 870
 871 [[authors]]
 872 Authors
 873 -------
 874 Michael Prokop <mika@grml.org>
 875
 876 /////////////////////////////////////
 877 // vim:ai tw=80 ft=asciidoc expandtab
 878 /////////////////////////////////////