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>] [-bBFnNquVz]
  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://fai-project.org/[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 ${GRML_FAI_CONFIG} which is pointing to /etc/grml/fai by default
  39 (unless overriden using the ''-D'' option). This ensures that it does not clash
  40 with default FAI configuration and packages, so you can use grml-live and FAI
  41 completely independent at the same time!
  42
  43 [NOTE]
  44
  45 Please notice that you should have a fast network connection as all the Debian
  46 packages will be downloaded and installed via network. If you want to use a
  47 local mirror (strongly recommended if you plan to use grml-live more than once)
  48 checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
  49 debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
  50 sample configuration), apt-cacher(1) and approx(8). To avoid downloading the
  51 base system again and again check out FAI's NFSROOT (see FAQ of this document
  52 for details).
  53
  54 Options
  55 -------
  56
  57   -a **ARCHITECTURE**::
  58
  59 Use the specified architecture instead of the currently running one.  This
  60 allows building a 32bit system on a 64bit host (though you can't build a 64bit
  61 system on a 32bit system/kernel of course). Please notice that real
  62 crosscompiling (like building a ppc system on x86) isn't possible due to the
  63 nature and the need of working in a chroot. Currently supported values: i386
  64 and amd64.
  65
  66   -b::
  67
  68 Build the ISO without updating the chroot via FAI. This option is useful for
  69 example when working on stable releases: if you have a working base
  70 system/chroot and do not want to execute any further updates (via "-u" option)
  71 but intend to only build the ISO.
  72
  73   -B::
  74
  75 Build the ISO without touching the chroot at all. This option is useful if
  76 you modified anything that FAI or grml-live might adjust via grml's FAI
  77 scripts.  It's like the '-b' option but even more advanced. Use only if you
  78 really know that you do not want to update the chroot.
  79
  80   -c **CLASSES**::
  81
  82 Specify the CLASSES to be used for building the ISO via FAI.  By default only
  83 the classes GRMLBASE, GRML_MEDIUM and I386 are assumed, resulting in a small base
  84 system (being about ~180MB total ISO size). If using a non-I386 system (like
  85 AMD64) you should specify the appropriate architecture as well. Additionally you
  86 can specify a class providing a grml-kernel (see
  87 <<classes,the 'CLASSES' section in this document>> for details about available classes).
  88 So instead of GRML_MEDIUM you can also use GRML_SMALL and GRML_FULL.
  89
  90 [IMPORTANT]
  91 All class names should be written in uppercase letters. Do not use a dash, use
  92 an underscore. So do not use "amd64" but "AMD64", do not use "FOO BAR" but
  93 "FOO_BAR".
  94
  95
  96   -C **CONFIGURATION_FILE**::
  97
  98 The specified file is used as configuration file for grml-live. By default
  99 /etc/grml/grml-live.conf is used as default configuration. If a file named
 100 /etc/grml/grml-live.local exists it is used as well (sourced after reading
 101 /etc/grml/grml-live.conf meant as main file for local configuration). As a last
 102 option the specified configuration file is sourced so it is possible to override
 103 settings of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local.
 104 Please notice that all configuration files have to be adjusted during execution
 105 of grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
 106 your own configuration file (usually /etc/grml/grml-live.local). Please also
 107 notice that the configuration file specified via this option is **not** (yet)
 108 supported inside the scripts/hooks/classes at ${GRML_FAI_CONFIG}/config. Instead use
 109 /etc/grml/grml-live.local for configuration stuff used inside
 110 ${GRML_FAI_CONFIG}/config.
 111
 112   -d **DATE**::
 113
 114 Use specified date as build date information on the ISO instead of the default.
 115 The default is the date when grml-live is being executed (retrieved via
 116 executing 'date +%Y-%m-%d'). The information is stored inside the file
 117 /GRML/grml-version on the ISO, /etc/grml_version in the squashfs file and in all
 118 the bootsplash related files. This option is useful if you want to provide an
 119 ISO with release information for a specific date but have to build it in
 120 advance. Usage example: '-d 2009-10-30'
 121
 122   -D **CONFIGURATION_DIRECTORY**::
 123
 124 The specified directory is used as configuration directory for grml-live and its
 125 FAI. By default /etc/grml/fai is used as default configuration directory.  If
 126 you want to have different configuration scripts, package definitions, etc. with
 127 without messing with the global configuration under /etc/grml/fai provided by
 128 grml-live this option provides you the option to use your own configuration
 129 directory. This directory is what's being referred to as ${GRML_FAI_CONFIG}
 130 throughout this documentation.
 131
 132   -F::
 133
 134 Force execution and do not prompt for acknowledgment of configuration.
 135
 136   -g **GRML_NAME**::
 137
 138 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
 139 Please do NOT use blanks and any special characters like '/', ';' inside
 140 GRML_NAME, otherwise you might notice problems while booting.
 141
 142   -h::
 143
 144 Display short usage information and exit.
 145
 146   -i **ISO_NAME**::
 147
 148 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
 149 by default.
 150
 151   -I **CHROOT_INSTALL**::
 152
 153 Specify name of source directory which provides files that should become part of
 154 the chroot/ISO. Not enabled by default. Note: the files are installed under '/'
 155 in the chroot so you have to create the rootfs structure on your own.
 156
 157   -n::
 158
 159 Skip creation of the ISO file. This option is useful if you want to build/update
 160 the chroot and/or recreate the squashfs file without building an ISO file.
 161
 162   -N::
 163
 164 Bootstrap the chroot without building bootloader, squashfs, or finalizing the
 165 ISO. Use this option if installation of some packages fails, you want to run
 166 custom commands or similar.
 167 The main use of this option is to save time by skipping stages which aren't
 168 necessary for bootstrapping the chroot and which would get executed more than
 169 once when iterating through the initial bootstrapping.
 170 Alternatively, use this option as a test run of grml-live. Once you are
 171 satisfied with the state of your grml_chroot, use grml-live **-u** to build the
 172 remaining stages and finalize the ISO.
 173
 174   -o **OUTPUT_DIRECTORY**::
 175
 176 Main output directory of the build process of FAI.  Some directories are created
 177 inside this target directory, being: grml_cd (where the files for creating the
 178 ISO are located, including the compressed squashfs file), grml_chroot (the
 179 chroot system) and grml_isos (where the resulting ISO is stored).
 180
 181   -q::
 182
 183 Build the ISO without (re-)creating the squashfs compressed file using mksquashfs.
 184 This option is useful if you just want to update parts outside the chroot in the ISO.
 185 Consider combining this option with the build-only option '-b'.
 186
 187   -r **RELEASENAME**::
 188
 189 Specify name of the release.
 190
 191   -s **SUITE**::
 192
 193 Specify the Debian suite you want to use for your live-system.  Defaults to
 194 "squeeze" (being current Debian/stable). Supported values are: etch, lenny,
 195 squeeze, sid. Debian "squeeze" requires a recent base.tgz
 196 (${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of
 197 debootstrap.
 198
 199   -t **TEMPLATE_DIRECTORY**::
 200
 201 Specify place of the templates used for building the ISO. By default
 202 (and if not manually specified) this is /usr/share/grml-live/templates/.
 203
 204   -u::
 205
 206 Update existing chroot instead of rebuilding it from scratch. This option is
 207 based on the softupdate feature of FAI.
 208
 209   -v **VERSION_NUMBER**::
 210
 211 Specify version number of the release.
 212
 213   -V::
 214
 215 Increase verbosity in the build process.
 216
 217   -z::
 218
 219 Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process.
 220
 221 [[usage-examples]]
 222 Usage examples
 223 --------------
 224
 225 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
 226 as build and output directory just run:
 227
 228   # grml-live
 229
 230 To get a small Debian-unstable and grml-small based Live-CD using
 231 /home/mika/grml-live as build and output directory just use:
 232
 233   # grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
 234
 235 To get a medium sized, Debian-unstable and grml-based Live-CD for i386
 236 architecture using /grml/grml-live as build and output directory just run:
 237
 238   # grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
 239
 240 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
 241 output directory and use grml_0.0-3.iso as ISO name (placed inside
 242 /tmp/grml_isos) just invoke:
 243
 244   # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
 245
 246 [NOTE]
 247
 248 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
 249 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
 250 and use /dev/shm as build and output directory - resulting in very fast build
 251 process.  But please be aware of the fact that rebooting your system will result
 252 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
 253 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
 254
 255 [[main-features]]
 256 Main features of grml-live
 257 --------------------------
 258
 259 * create a grml-/Debian-based Linux Live-CD with one single command
 260
 261 * class based concept, providing a maximum of flexibility
 262
 263 * supports integration of own hooks, scripts and configuration
 264
 265 * supports use and integration of own Software and/or Kernels via simple use of
 266 Debian repositories
 267
 268 * native support of FAI features
 269
 270 * multi-arch support (work in progress)
 271
 272 [[class-concept]]
 273 The class concept
 274 -----------------
 275
 276 grml-live uses FAI and its class based concept for adjusting configuration and
 277 setup according to your needs. This gives you flexibility and strength without
 278 losing the simplicity in the build process.
 279
 280 The main and base class provided by grml-live is named GRMLBASE. It's strongly
 281 recommended to **always** use the class GRMLBASE when building an ISO using
 282 grml-live, as well as the architecture dependent class which provides the kernel
 283 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
 284 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
 285 relevant for class GRMLBASE by default:
 286
 287   ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/
 288   ${GRML_FAI_CONFIG}/config/debconf/GRMLBASE
 289   ${GRML_FAI_CONFIG}/config/class/GRMLBASE.var
 290   ${GRML_FAI_CONFIG}/config/hooks/instsoft.GRMLBASE
 291   ${GRML_FAI_CONFIG}/config/package_config/GRMLBASE
 292
 293 Take a look at the next section for information about the concept of those
 294 files/directories.
 295
 296 If you want to use your own configuration, extend an existing configuration
 297 and/or add additional packages to your ISO just invent a new class (or extend an
 298 existing one). For example if you want to use your own class named "FOOBAR" just
 299 set CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" inside /etc/grml/grml-live.local
 300 or invoke grml-live using the classes option: "grml-live -c
 301 GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
 302
 303 More details regarding the class concept can be found in the documentation of
 304 FAI itself (being available at /usr/share/doc/fai-doc/).
 305
 306 [[X7]]
 307 [[classes]]
 308 Available classes
 309 -----------------
 310
 311 The package selection part of the classes can be found in
 312 ${GRML_FAI_CONFIG}/config/package_config whereas some further classes are defined for
 313 example in ${GRML_FAI_CONFIG}/config/scripts/ so specific feature sets can be
 314 selected. The following classes are predefined:
 315
 316 * DEBORPHAN: get rid of all packages listed in output of Deborphan
 317
 318 * GRMLBASE: the main class responsible for getting a minimal subset of what's
 319 defining a grml system. Important parts of the buildprocess are specified in
 320 this class as well, so unless you have a really good reason you should always
 321 use this class.
 322
 323 * GRML_FULL: full featured grml, also known as the "normal", full grml.
 324
 325 * GRML_MEDIUM: medium sized grml version, known as grml-medium
 326
 327 * GRML_POWERPC: grml for PowerPC architecture, not supported yet (still work in
 328 progress)
 329
 330 * GRML_SMALL: minimum sized grml version, known as grml-small
 331
 332 * LATEX: LaTeX(-related) packages like auctex, texlive,...
 333 (which used to be shipped by grml before the LaTeX removal)
 334
 335 * LATEX_CLEANUP: get rid of several very large LaTeX directories
 336 (like some /usr/share/doc/texlive-*, /usr/share/doc/texmf,...)
 337
 338 * LOCALES: use full featured locales setup (see /etc/locale.gen.grml). This
 339 avoids to get rid of /usr/share/locale - which happens by default otherwise - as
 340 well.
 341
 342 * NO_ONLINE: do not run scripts during the chroot build process which require a
 343 network connection
 344
 345 * RELEASE: run some specific scripts and commands to provide the workflow for an
 346 official grml release
 347
 348 * REMOVE_DOCS: get rid of documentation directories (like /usr/share/doc,
 349 /usr/share/man/, /usr/share/info,...)
 350
 351 * XORG: providing important packages for use with a base grml-featured X.org
 352 setup
 353
 354 [[files]]
 355 Files
 356 -----
 357
 358 Notice that grml-live ships FAI configuration files that do not use the same
 359 namespace as the FAI packages itself. This ensures that grml-live does not clash
 360 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
 361 fai-client) grml uses ${GRML_FAI_CONFIG}/fai.conf instead. For more details see
 362 below. To get an idea how another configuration or example files could look like
 363 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 364 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
 365 provides documentation regarding configuration possibilities.
 366
 367   /usr/sbin/grml-live
 368
 369 Script for the main build process. Requires root permissions for execution.
 370
 371   /etc/grml/grml-live.conf
 372
 373 Main configuration file for grml-live which should be considered as a reference
 374 configuration file only. Please use /etc/grml/grml-live.local for local
 375 configuration instead.
 376
 377   /etc/grml/grml-live.local
 378
 379 All the local configuration should go to this file. This file overrides any
 380 defaults of grml-live. Configurations via /etc/grml/grml-live.local are preferred
 381 over the ones from /etc/grml/grml-live.conf. If you want to override settings
 382 from /etc/grml/grml-live.local as well you have to specify them on the grml-live
 383 commandline.
 384
 385   ${GRML_FAI_CONFIG}/fai.conf
 386
 387 Main configuration file for FAI which specifies where all the configuration
 388 files and scripts for FAI/grml-live can be found. By default the configuration
 389 variables are FAI_CONFIG_SRC=file:///etc/grml/fai/config and
 390 GRML_FAI_CONFIG=/etc/grml/fai/config - both pointing to a directory shipped by
 391 grml-live out-of-the-box so you shouldn't have to configure anything in this
 392 file.
 393
 394   ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf
 395
 396 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
 397 anything inside this file. If you want to modify NFSROOT though you can adjust
 398 it there.
 399
 400   ${GRML_FAI_CONFIG}/NFSROOT
 401
 402 This file specifies the package list for creating the NFSROOT.
 403
 404   ${GRML_FAI_CONFIG}/apt/sources.list
 405
 406 This file specifies which mirrors should be considered for retrieving the Debian
 407 packages when creating the main chroot (including all the software you would
 408 like to see included). Important: this file should *not* be adjusted manually!
 409 Instead use the GRML_LIVE_SOURCES variable inside /etc/grml/grml-live.conf or
 410 /etc/grml/grml-live.local which modifies ${GRML_FAI_CONFIG}/apt/sources.list
 411 on-the-fly via grml-live then. If you want to generally adjust apt configuration
 412 use FAI's fcopy command with ${GRML_FAI_CONFIG}/config/files instead.
 413
 414   ${GRML_FAI_CONFIG}/config/
 415
 416 The main directory for configuration of FAI/grml-live. More details below.
 417
 418   ${GRML_FAI_CONFIG}/config/class/
 419
 420 This directory contains files which specify main configuration variables for the
 421 FAI classes.
 422
 423   ${GRML_FAI_CONFIG}/config/debconf/
 424
 425 This directory provides the files for preseeding/configuration of debconf
 426 through files.
 427
 428   ${GRML_FAI_CONFIG}/config/hooks/
 429
 430 This directory provides files for customising the build process through hooks.
 431 Hooks are user defined programs or scripts, which are called during the
 432 installation process.
 433
 434   ${GRML_FAI_CONFIG}/config/package_config/
 435
 436 Directory with lists of software packages to be installed or removed.  The
 437 different classes describe what should find its way to your ISO.  When running
 438 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
 439 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
 440 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
 441 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
 442 adjust the package selection according to your needs.  Please notice that the
 443 directory GRMLBASE contains a package list defining a minimum but still
 444 reasonable package configuration.
 445
 446   ${GRML_FAI_CONFIG}/config/scripts/
 447
 448 Scripts for customising the ISO within the build process.
 449
 450   ${GRML_FAI_CONFIG}/live-initramfs/
 451
 452 This directory provides the files used for building the initramfs/initrd via
 453 live-initramfs(8).
 454
 455 [[log-files]]
 456 Available log files
 457 -------------------
 458
 459 grml-live itself logs to /var/log/grml-live.log. Unless you set PRESERVE_LOGFILE
 460 in your grml-live configuration the file is cleared on each new invocation of
 461 grml-live.
 462
 463 The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the
 464 default being /var/log/fai/grml/.
 465
 466 If you are using the grml-live buildd you will find the logs of the grml-live
 467 run at /var/log/grml-buildd.stdout.log and /var/log/grml-buildd.stderr.log.
 468
 469 If you want to store build information in a database just install the
 470 grml-live-db Debian package. Further details available in the grml-live-db
 471 manpage.
 472
 473 [[requirements]]
 474 Requirements for the build system
 475 ---------------------------------
 476
 477 * any Debian based system should be sufficient (if it doesn't work it's a bug,
 478 please send us a bug report then) [a usual
 479 link:http://grml.org/grml2hd/[grml2hd] harddisk installation (using grml or
 480 grml-medium) ships all you need]. Check out <<deploy-on-debian,How do I deploy
 481 grml-live on a plain Debian installation>> for details how to set up grml-live
 482 on a plain, original Debian system.
 483
 484 * enough free disk space; at least 800MB are required for a minimal grml-live
 485 run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
 486 [$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
 487 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
 488 total free disk space
 489
 490 * fast network access for retrieving the Debian packages used for creating the
 491 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 492 as possible)
 493
 494 For further information see next section.
 495
 496 [[X8]]
 497 [[current_state]]
 498 Current state of grml-live with squashfs-tools and kernel
 499 ---------------------------------------------------------
 500
 501 Use squashfs-tools >=4.2-1 (available from Grml repositories as well as from
 502 Debian/unstable) to build Grml (based) ISOs featuring kernel version
 503 2.6.38-grml[64].
 504
 505 ////////////////////////////////////////////////////////////////////////////////
 506 Difference between squashfs-lzma-tools, squashfs-lzma-tools4 and squashfs-tools
 507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 508
 509 Whereas the ZLIB compression is much faster in the build process, the LZMA
 510 compression provides a smaller resulting ISO. If you're wondering: the official
 511 Grml builds use the LZMA compression.
 512
 513 Squashfs-tools was introduced in Debian and once provided support for LZMA
 514 compression. Sadly LZMA compression within squashfs-tools became unsupported and
 515 therefore squashfs-lzma-tools[4] had to be introduced and maintained by the Grml
 516 team. Different kernel versions provide different squashfs file formats. Kernel
 517 versions until 2.6.28-grml[64] used the 3.x file format but those outdated
 518 kernels aren't supported by grml-live automatically anymore nowdays (manual
 519 handling through SQUASHFS_BINARY possible though). Kernel versions
 520 2.6.31-grml[64] and 2.6.33-grml[64] use openwrt's squashfs lzma file format
 521 version 4. Kernel versions starting with 2.6.35-grml[64] use the mainline ondisk
 522 file format version 4.
 523
 524 If you're wondering which package supports what, here's a short overview:
 525
 526 * squashfs-lzma-tools4 4.0-x: ZLIB as default, LZMA support via '-comp lzma'
 527 option (enabled by grml-live by default), file format version 4 (mainline
 528 version), package maintained and available from Grml, recommended for current
 529 grml-live builds featuring kernels >=2.6.35-grml[64]
 530
 531 * squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via '-lzma' option
 532 (enabled by grml-live by default), file format version 4 (openwrt style),
 533 package maintained and available from Grml, recommended for any grml-live builds
 534 with kernel versions 2.6.31-grml[64] and 2.6.33-grml[64]
 535
 536 * squashfs-tools 1:4.0-x: ZLIB as default, no LZMA support/options, file format
 537 version 4, package maintained and available from Debian, recommended only for
 538 ZLIB-only builds of any grml-live builds with kernel versions >=2.6.31-grml[64]
 539
 540 Outdated, JFTR:
 541
 542 * squashfs-tools 1:3.3-7: ZLIB as default, no LZMA support/options, file format
 543 version 3
 544
 545 * squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via '-nolzma'
 546 option, file format version 3
 547
 548 * squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via '-nolzma' option,
 549 file format version 3
 550
 551 Now, depending on the kernel version you want to use you need different versions
 552 of squashfs-tools/squashfs-lzma-tools[4]. Yes, that's a mess (don't ask how much
 553 this sucks for us developers) - though we're putting lots of effort into our
 554 toolchain to automatically handle this for you through the grml-live build
 555 system and provide proper documentation. The situation is supposed to calm down
 556 with the recent integration of the squashfs file format 4 in the mainline
 557 kernel. Support for LZMA is pending and as soon as it's available mainline this
 558 should dramatically simplify the situation for developers as well as users.
 559
 560 [TIP]
 561 If you want to force usage of a specific mksquashfs binary just set the
 562 SQUASHFS_BINARY configuration/environment variable. Set SQUASHFS_OPTIONS for
 563 customizing the options that should be used by the mksquashfs binary during
 564 build process.
 565
 566 Using squashfs-lzma-tools4 4.0-1 on the build system
 567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 568
 569 squashfs-lzma-tools4 4.0-1 is available via the Grml repositories. It provides
 570 the mksquashfs-lzma4 and unsquashfs-lzma4 binaries. The package does NOT
 571 conflict with neither Debian's squashfs-tools package nor Grml's
 572 squashfs-lzma-tools package, so you can install all of them at the same time and
 573 the build system will try to figure out the best matching binary automatically
 574 for you.
 575
 576 The packages can be downloaded from
 577 link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/]
 578
 579 It provides support for the new squashfs file format version 4 (as available in
 580 mainline, so *not* the one being used by squashfs-lzma-tools and kernel
 581 2.6.33-grml) and therefore requires kernel versions starting with
 582 2.6.35-grml[64]. It supports LZMA as well as ZLIB compression. Just use the
 583 defaults for enabling LZMA or use grml-live's '-z' option if you want to use
 584 ZLIB compression instead.
 585
 586 * Kernel 2.6.31-grml[64]: works with ZLIB compression, fails with LZMA
 587 * Kernel 2.6.33-grml[64]: works with ZLIB compression, fails with LZMA
 588 * Kernel 2.6.35-grml[64]: works with ZLIB *and* LZMA compression
 589 * Kernel 2.6.36-grml[64]: works with ZLIB *and* LZMA compression
 590
 591 [NOTE]
 592 squashfs-tools >=4.1-1 and/or squashfs-lzma-tools4 are the recommended package
 593 for building up2date ISOs with grml-live! Please use other squashfs-* packages
 594 only if you want to build live systems providing kernel versions older than
 595 2.6.35-grml*. Use squashfs-tools >=4.1-1 or squashfs-lzma-tools4 from Grml if
 596 you want to remaster any Grml releases MORE RECENT than 2010.04.
 597
 598 Using squashfs-lzma-tools 4.0-2 on the build system
 599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 600
 601 squashfs-lzma-tools 4.0-2 is available via the Grml repositories. It provides
 602 the mksquashfs-lzma and unsquashfs-lzma binaries. The package does NOT conflict
 603 with Debian's squashfs-tools package (you can install both of them at the same
 604 time).
 605
 606 The packages can be downloaded from
 607 link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools/]
 608
 609 It provides support for the new squashfs file format version 4 (based on openwrt
 610 patches, this is *not* the mainline file format that's being used by kernel
 611 2.6.35-grml and squashfs-lzma-tools4!) and therefore requires kernel versions
 612 newer than 2.6.28-grml[64]. It supports LZMA as well as ZLIB compression. Just
 613 use the defaults for enabling LZMA or use grml-live's '-z' option if you want to
 614 use ZLIB instead.
 615
 616 * Kernel \<=2.6.28-grml[64]: does not work
 617 * Kernel 2.6.31-grml[64]: works
 618 * Kernel 2.6.33-grml[64]: works
 619 * Kernel 2.6.35-grml[64]: works for ZLIB compression, fails for LZMA
 620
 621 [NOTE]
 622 Please use squashfs-lzma-tools >=4.0-2 from Grml only if you want to remaster
 623 Grml releases 2009.10 and 2010.04 or live systems with their according kernel
 624 versions.
 625
 626 Using squashfs-tools 1:4.0-X on the build system
 627 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 628
 629 squashfs-tools >=1:4.0-1 is available in Debian/unstable and Debian/testing. It
 630 provides the mksquashfs and unsquashfs binaries. The package does NOT conflict
 631 neither with the squashfs-lzma-tools 4.0-2 package nor with the
 632 squashfs-lzma-tools4 package (so you can install all of them at the same time).
 633
 634 The packages can be downloaded from
 635 link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/]
 636
 637 It provides support for the new squashfs file format version 4 and therefore
 638 requires kernel versions newer than 2.6.28-grml[64].
 639
 640 It does NOT support LZMA compression (dropped with
 641 link:http://packages.debian.org/changelogs/pool/main/s/squashfs-tools/current/changelog[version
 642 1:3.3-4] and not yet re-integrated yet, see
 643 link:http://bugs.debian.org/594595[#594595]). If you need LZMA support please
 644 use Grml's squashfs-lzma-tools[4] (see sections above) instead.
 645
 646 * Kernels \<=2.6.28-grml[64]: does not work
 647 * Kernel 2.6.31-grml[64]: works (ZLIB only)
 648 * Kernel 2.6.33-grml[64]: works (ZLIB only)
 649 * Kernel 2.6.35-grml[64]: works (ZLIB only)
 650 * Kernel 2.6.36-grml[64]: works (ZLIB only)
 651
 652 [NOTE]
 653 Please use squashfs-tools between 4.0-1 and 4.1-1 only if you want to remaster
 654 Grml releases starting with 2009.10 using the ZLIB compression, please use other
 655 squashfs packages otherwise instead.
 656
 657 Outdated, JFTR:
 658
 659 Using squashfs-lzma-tools 3.3-1 on the build system
 660 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 661
 662 squashfs-lzma-tools 3.3-1 from the Grml repository supports kernel
 663 2.6.26-grml[64] and 2.6.28-grml[64] using both LZMA and ZLIB (-nolzma)
 664 compression.
 665
 666 The packages can be downloaded from
 667 link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/].
 668
 669 [NOTE]
 670 Please use squashfs-lzma-tools 3.3-1 only if you want to remaster Grml releases
 671 2008.11 or 2009.05.
 672
 673 Using squashfs-tools 1:3.3-7 on the build system
 674 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 675
 676 squashfs-tools 1:3.3-7 is available through
 677 http://grml.org/squashfs/squashfs-tools_3.3-7_i386.deb (for x86) or
 678 http://grml.org/squashfs/squashfs-tools_3.3-7_amd64.deb (for amd64) [both build
 679 on and for Debian/etch but working with testing and unstable as well].
 680
 681 Please notice that squashfs-tools 1:3.3-7 does NOT support LZMA compression at
 682 all (so you won't be able to remaster release 2008.11 and 2009.05 using LZMA for
 683 example). The -nolzma option of mksquashfs is not available therefore (even
 684 though grml-live will deactivate it for you automatically anyway). Please use
 685 squashfs-lzma-tools instead.
 686
 687 * Kernel 2.6.23-grml: does NOT work, please use squashfs-tools 1:3.2r2-9exp1
 688                       instead if you still want to use kernel 2.6.23 (not
 689                       recommended)
 690 * Kernel 2.6.26-grml: works (without LZMA compression only of course!)
 691 * Kernel 2.6.28-grml: works (without LZMA compression only of course!)
 692
 693 Using squashfs-tools 1:3.2r2-9exp1 on the build system
 694 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 695
 696 squashfs-tools 1:3.2r2-9exp1 is available via the grml-testing repository,
 697 running:
 698
 699   # aptitude install squashfs-tools=1:3.2r2-9exp1
 700
 701 or directly via downloading the files
 702 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_i386.deb (for x86) or
 703 http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_amd64.deb (for amd64).
 704
 705 Using with ZLIB compression (SQUASHFS_OPTIONS='-nolzma' or -z
 706 option in grml-live cmdline):
 707
 708 * Kernel 2.6.23-grml: works
 709 * Kernel 2.6.26-grml: works
 710 * Kernel 2.6.28-grml: supposed to work (not verified though)
 711
 712 Using with LZMA compression:
 713
 714 * Kernel 2.6.23-grml: works
 715 * Kernel 2.6.26-grml: does NOT work, please use ZLIB mode instead or switch
 716   to Debian package squashfs-lzma-tools 3.3-1 (see section above).
 717 * Kernel 2.6.28-grml: does NOT work, please use ZLIB mode instead or switch
 718   to Debian package squashfs-lzma-tools 3.3-1 (see section above).
 719 //////////////////////////////////////////////////////////////////////////////////
 720
 721 [[faq]]
 722 FAQ
 723 ---
 724
 725 [[deploy-on-debian]]
 726 How do I deploy grml-live on a plain Debian installation?
 727 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 728
 729 The easiest way to get a running grml-live setup is to install Grml or
 730 grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you
 731 don't want to run it on a physical system). Of course using grml-live on a
 732 plain, original Debian installation is supported as well. So there we go.
 733
 734 What we have: plain, original Debian Lenny (5.0).
 735
 736 What we want: build a grml-medium ISO based on Debian/squeeze for the i386
 737 architecture using grml-live.
 738
 739 [IMPORTANT]
 740
 741 If you encounter any problems while booting the resulting ISO please be aware of
 742 <<current_state,the 'current state of grml-live with squashfs-tools and kernel'
 743 section>>.
 744
 745 Instructions
 746 ^^^^^^^^^^^^
 747
 748   # adjust sources.list:
 749   cat >> /etc/apt/sources.list << EOF
 750
 751   # grml stable repository:
 752     deb     http://deb.grml.org/ grml-stable  main
 753   # deb-src http://deb.grml.org/ grml-stable  main
 754
 755   # grml testing/development repository:
 756     deb     http://deb.grml.org/ grml-testing main
 757   # deb-src http://deb.grml.org/ grml-testing main
 758   EOF
 759
 760   # adjust apt-pinning (only prefer squashfs stuff from grml):
 761   cat >> /etc/apt/preferences << EOF
 762   Package: *
 763   Pin: origin deb.grml.org
 764   Pin-Priority: 1
 765
 766   Package: squashfs-tools
 767   Pin: origin deb.grml.org
 768   Pin-Priority: 996
 769   EOF
 770
 771   # get keyring for apt:
 772   apt-get update
 773   apt-get --allow-unauthenticated install grml-debian-keyring
 774
 775   # optionally(!) install basefile so we don't have to build basic
 776   # chroot from scratch, grab from http://daily.grml.org/
 777   # mkdir -p /etc/grml/fai/config/basefiles/
 778   # mv base.tgz /etc/grml/fai/config/basefiles/I386.tar.gz
 779   # mv base64.tgz /etc/grml/fai/config/basefiles/AMD64.tar.gz
 780
 781   # install relevant tools
 782   # please check out http://grml.org/grml-live/#current_state when encountering problems!
 783   apt-get -o APT::Install-Recommends=false install grml-live squashfs-tools
 784
 785   # adjust grml-live configuration for our needs:
 786   cat > /etc/grml/grml-live.local << EOF
 787   ## want a faster build process and don't need smaller ISOs?
 788   ## if so use zlib compression
 789   # SQUASHFS_OPTIONS="-comp gzip -b 256k"
 790   ## want to use a specific squashfs binary?
 791   # SQUASHFS_BINARY='/usr/bin/mksquashfs'
 792   # install local files into the chroot
 793   CHROOT_INSTALL="/etc/grml/fai/chroot_install"
 794   ## adjust if necessary (defaults to /grml/grml-live):
 795   ## OUTPUT="/srv/grml-live"
 796   FAI_DEBOOTSTRAP="squeeze http://cdn.debian.net/debian/"
 797   ARCH="i386"
 798   CLASSES="GRMLBASE,GRML_MEDIUM,I386"
 799   # PRESERVE_LOGFILE='1'
 800   # ZERO_FAI_LOGFILE='1'
 801   GRML_LIVE_SOURCES="
 802   deb http://deb.grml.org/            grml-stable  main
 803   deb http://deb.grml.org/            grml-testing main
 804   deb http://cdn.debian.net/debian squeeze main contrib non-free
 805   "
 806   EOF
 807
 808   # just optional(!) - upgrade FAI to latest available version:
 809   cat >> /etc/apt/sources.list << EOF
 810   # fai:
 811     deb http://fai-project.org/download lenny koeln
 812   EOF
 813
 814   # get gpg key of FAI repos and install current FAI version:
 815   gpg -a --recv-keys AB9B66FD; gpg -a --export AB9B66FD | apt-key add -
 816   apt-get update
 817   apt-get install fai-client fai-server fai-doc
 818
 819 That's it. Now invoking 'grml-live -V' should build the ISO.  If everything
 820 worked as expected the last line of the shell output should look like:
 821
 822   [*] Successfully finished execution of grml-live [running 687 seconds]
 823
 824 and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.
 825
 826 [[grml_fai_config_variable]]
 827 What is $GRML_FAI_CONFIG?
 828 ~~~~~~~~~~~~~~~~~~~~~~~~~
 829
 830 The variable '$GRML_FAI_CONFIG' is pointing to the directory /etc/grml/fai by
 831 default.  To provide you a maximum of flexibility you can set up your own
 832 configuration directory (e.g. based on /etc/grml/fai) and use this directory
 833 running grml-live with the '-D <config_dir>' option. Now '$GRML_FAI_CONFIG'
 834 points to the specified directory instead of using /etc/grml/fai and all the
 835 configuration files, scripts and hooks will be taken from your
 836 '$GRML_FAI_CONFIG' directory.
 837
 838 [[how-to-debug]]
 839 I've problems with the build process. How to start debugging?
 840 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 841
 842 Check out the logs inside /var/log/fai/... If you think it's a bug in grml-live
 843 send a copy of your config, logs and the commandline with a short problem
 844 description to <mika@grml.org>:
 845
 846   # history | grep grml-live > /etc/grml/grml_live.cmdline
 847   # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
 848             /etc/grml/grml_live.cmdline /etc/grml/grml-buildd.conf \
 849             /var/log/fai /etc/grml/fai
 850   -> finally mail grml_live_problem.tar.gz to <mika@grml.org>
 851
 852 If you need help with grml-live or would like to see new features as part of
 853 grml-live you can get commercial support via
 854 link:http://grml-solutions.com/[Grml Solutions].
 855
 856 [[lzma-vs-zlib]]
 857 How much is the difference between LZMA and ZLIB compression?
 858 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 859
 860 ISO size (bs = blocksize):
 861
 862 [width="45%",cols="3,^2,^2"]
 863 |============================================================
 864 |ISO                   |LZMA (256kB bs) |ZLIB
 865 |grml_sid              |666M | 771M
 866 |grml_squeeze          |659M | 761M
 867 |grml_lenny            |624M | 723M
 868 |grml64_sid            |677M | 791M
 869 |grml64_squeeze        |671M | 785M
 870 |grml64_lenny          |639M | 745M
 871 |grml-medium_sid       |208M | 236M
 872 |grml-medium_squeeze   |206M | 234M
 873 |grml-medium_lenny     |193M | 220M
 874 |grml64-medium_sid     |213M | 245M
 875 |grml64-medium_squeeze |213M | 244M
 876 |grml64-medium_lenny   |201M | 231M
 877 |grml-small_sid        |102M | 118M
 878 |grml-small_squeeze    |101M | 117M
 879 |grml-small_lenny      |97M  | 112M
 880 |grml64-small_sid      |103M | 120M
 881 |grml64-small_squeeze  |103M | 120M
 882 |grml64-small_lenny    |99M  | 116M
 883 |============================================================
 884
 885 Build time of grml-medium's squashfs file (depends on your system, though just
 886 to get the ratio between the different options):
 887
 888 * 10 minutes and 4 seconds with LZMA default blocksize (128k)
 889 * 7 minutes 27 seconds with LZMA and blocksize 256k
 890 * 6 minutes and 8 seconds with LZMA blocksize 512k
 891 * 1 minute and 40 seconds with ZLIB
 892
 893 [[install-local-files]]
 894 How do I install further files into the chroot/ISO?
 895 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 896
 897 Just point the configuration variable CHROOT_INSTALL to the directory which
 898 provides the files you would like to install. Note that the files are installed
 899 under '/' in the chroot - so you have to create the rootfs structure on your
 900 own. Usage example:
 901
 902   echo "CHROOT_INSTALL=\$GRML_FAI_CONFIG/chroot_install" >> /etc/grml/grml-live.local
 903   mkdir -p /etc/grml/fai/chroot_install/usr/src/
 904   wget example.org/foo.tar.gz
 905   mv foo.tar.gz /etc/grml/fai/chroot_install/usr/src/
 906   grml-live ...
 907
 908 [[local-debian-mirror]]
 909 Can I use my own (local) Debian mirror?
 910 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 911
 912 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
 913 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
 914 your needs. Please don't forget that you should use the grml servers as well
 915 (see default configuration) so all the grml packages can be downloaded as well.
 916
 917 If you want to use a local (for example NFS mount) mirror additionally, just
 918 adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as
 919 well.
 920
 921 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
 922 ${GRML_FAI_CONFIG}/apt/sources.list and ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf will be
 923 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
 924 files will be adjusted during runtime automatically.
 925
 926 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
 927 taken as first entry in the generated sources.list so it's preferred over
 928 non-local mirrors. Using a fallback mirror (via providing several mirrors in
 929 GRML_LIVE_SOURCES as used by default) is a recommended setting.
 930
 931 [[add-additional-debian-packages]]
 932 How do I add additional Debian package(s) to my CD/ISO?
 933 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 934
 935 Just create a new class (using the package_config directory):
 936
 937   # cat > /etc/grml/fai/config/package_config/MIKA << EOF
 938   PACKAGES aptitude
 939
 940   vim
 941   another_name_of_a_debian_package
 942   and_another_one
 943   EOF
 944
 945 and specify it when invoking grml-live then:
 946
 947   # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
 948
 949 [[reset-grml-live-configuration]]
 950 I fscked up my grml-live configuration. How do I reset it to the defaults?
 951 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 952
 953 Notice: this deletes all your grml-live configuration files. If that's really
 954 what you are searching for just run:
 955
 956   rm -rf /etc/grml/fai /etc/grml/grml-live.conf
 957   dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
 958
 959 [NOTE]
 960
 961 If you don't control your /etc using a version control system (VCS) yet it's a
 962 good chance to start using it now. Check out
 963 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/]
 964 for more details how to maintain /etc using the mercurial VCS.
 965
 966 [[create-a-base-tgz]]
 967 How do I create a base.tgz for use as NFSROOT?
 968 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 969
 970 First of all build the chroot system:
 971
 972   mkdir /tmp/nfsroot && cd /tmp/nfsroot
 973   debootstrap squeeze /tmp/nfsroot/ http://cdn.debian.net/debian
 974   tar zcf base.tgz ./
 975
 976 Then check out where your NFSROOT is located:
 977
 978   # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
 979   NFSROOT=/grml/fai/nfsroot
 980
 981 So as /grml/fai/nfsroot is your NFSROOT place the file under
 982 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
 983
 984   mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 985
 986 or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
 987 Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
 988
 989 Now running "grml-live ..." will use this file as main system instead of
 990 executing debootstrap. Check out the output for the following lines if using
 991 NFSROOT:
 992
 993   [...]
 994   Calling task_extrbase
 995   Unpacking Debian base archive
 996   Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 997   Calling task_mirror
 998   [...]
 999
1000 or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
1001
1002   [...]
1003   ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
1004   /grml-live/grml-live_20071029.22138/grml_chroot//
1005   [...]
1006
1007 [TIP]
1008 Existing base.tgz can be found at http://daily.grml.org/
1009
1010 [[apt-cacher]]
1011 Set up apt-cacher / apt-cacher-ng for use with grml-live
1012 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1013
1014 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
1015 FAI_DEBOOTSTRAP:
1016
1017   # cat /etc/grml/grml-live.conf
1018   [...]
1019   GRML_LIVE_SOURCES="
1020   deb http://localhost:3142/deb.grml.org grml-stable  main
1021   deb http://localhost:3142/deb.grml.org grml-testing main
1022   deb http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free
1023   "
1024   [...]
1025   FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free"
1026
1027 Make sure apt-cacher / apt-cacher-ng is running ('/etc/init.d/apt-cacher
1028 restart' or '/etc/init.d/apt-cacher-ng restart'). That's it.  All downloaded
1029 files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then.
1030
1031 [[approx]]
1032 Set up approx for use with grml-live
1033 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1034
1035 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
1036 FAI_DEBOOTSTRAP:
1037
1038   # cat /etc/grml/grml-live.conf
1039   [...]
1040   GRML_LIVE_SOURCES="
1041   deb http://localhost:9999/grml            grml-stable  main
1042   deb http://localhost:9999/grml            grml-testing main
1043   deb http://localhost:9999/debian squeeze  main contrib non-free
1044   "
1045   FAI_DEBOOTSTRAP="squeeze http://localhost:9999/debian"
1046
1047 Configure approx:
1048
1049   # cat /etc/approx/approx.conf
1050   [...]
1051   debian http://ftp.at.debian.org/debian
1052   grml   http://deb.grml.org/
1053
1054 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
1055 All downloaded files will be cached in /var/cache/approx now.
1056
1057 [[revert_manifold]]
1058 How do I revert the manifold feature from an ISO?
1059 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1060
1061 The so called manifold feature Grml ISOs use by default allows one to use the same
1062 ISO for CD boot and USB boot. If you notice any problems when booting just
1063 revert the manifold feature running:
1064
1065   % dd if=/dev/zero of=grml.iso bs=512 count=1 conv=notrunc
1066
1067 To switch from manifold to isohybrid mode (an alternative approach provided by
1068 syslinux) then just execute:
1069
1070   % isohybrid grml.iso
1071
1072 [[basetgz]]
1073 How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz)
1074 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1075
1076 Execute the following commands (requires root):
1077
1078   ARCH='amd64' # replace with i386 if necessary
1079   SUITE='squeeze' # using the current stable release should always work
1080   debootstrap --arch "$ARCH" --exclude=info,tasksel,tasksel-data "$SUITE" "$ARCH" http://debian.netcologne.de/debian
1081   cd "$ARCH"
1082   rm var/cache/apt/archives/*.deb
1083   tar zcf ../"${ARCH}".tar.gz *
1084
1085 And finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note
1086 that it needs to be uppercase letters matching the class names, so: AMD64.tar.gz
1087 for amd64 and I386.tar.gz for i386).
1088
1089 [[autobuild]]
1090 How do I set up an autobuild environment?
1091 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1092
1093 If you want to set up a system like link:http://daily.grml.org/[daily.grml.org]
1094 the Debian package grml-live-buildd provides all you need to start. Start with
1095 figuring out the cron job script /usr/share/grml-live/buildd/cronjob.sh.
1096
1097 If you want to automatically update the grml-live Debian package on your build
1098 system based on the git tree of grml-live (so you get bleeding edge of
1099 development which might is interesting for services like daily.grml.org) the
1100 provided release_helper.sh script provides everything you need. Execute as root:
1101
1102   echo "deb file:/home/grml-live-git/grml-live.build-area/ ./" >> /etc/apt/sources.list.d/grml-live.list
1103   adduser --disabled-login --disabled-password grml-live-git
1104
1105 Execute 'visudo' to update sudo configuration and add the following line:
1106
1107   grml-live-git ALL=NOPASSWD: /usr/bin/apt-get
1108
1109 Switch to user grml-live-git and configure the rest:
1110
1111   su - grml-live-git
1112   mkdir grml-live.build-area
1113   git clone git://git.grml.org/grml-live.git
1114   git config --global user.name "Grml-Live Git Autobuild"
1115   git config --global user.email "grml-live-git@$(hostname)"
1116
1117 Finally install a cron job (as user grml-live-git) like:
1118
1119   30 00 * * * cd /home/grml-live-git/grml-live.git/ && env AUTOBUILD=1 scripts/release_helper.sh >/home/grml-live-git/grml-live-build.log
1120
1121 Tip: To find out the build date of the installed grml-live package just execute:
1122
1123   % apt-cache policy grml-live | grep 'Installed.*autobuild'
1124    Installed: 0.13.1~autobuild1300450381
1125
1126 and run "date -ud @$STRING" where $STRING is the number behind the "autobuild",
1127 like:
1128
1129   % date -ud @1300450081
1130   Fri Mar 18 12:08:01 UTC 2011
1131
1132 [[question]]
1133 I've a question which isn't answered by this document
1134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1135
1136 Don't hesitate to contact the author: <mika@grml.org>
1137
1138 [[download]]
1139 Download / install grml-live as a Debian package
1140 ------------------------------------------------
1141
1142 Debian packages are available through the grml-repository at
1143 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org].  If you want to
1144 build a Debian package on your own (using for example a specific version or the
1145 current development tree), just execute:
1146
1147   git clone git://git.grml.org/grml-live
1148   cd grml-live
1149   debuild -us -uc
1150
1151 [[source]]
1152 Source
1153 ------
1154
1155 The source of grml-live is available at
1156 link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git]
1157
1158 [[todo-list]]
1159 TODO list
1160 ---------
1161
1162 Check out the link:http://git.grml.org/?p=grml-live.git;a=blob;f=TODO;hb=HEAD[TODO file].
1163
1164 [[bugs]]
1165 Bugs
1166 ----
1167
1168 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
1169 link:http://grml.org/contact/[to the grml-team]!
1170
1171 [[documentation]]
1172 Documentation
1173 -------------
1174
1175 The most recent grml-live documentation is available online at
1176 http://grml.org/grml-live/ and for offline reading also available
1177 in different formats:
1178
1179 * http://grml.org/grml-live/grml-live.epub
1180 * http://grml.org/grml-live/grml-live.pdf
1181
1182 [[authors]]
1183 Authors
1184 -------
1185 Michael Prokop <mika@grml.org>
1186
1187 /////////////////////////////////////
1188 // vim:ai tw=80 ft=asciidoc expandtab
1189 /////////////////////////////////////