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