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