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>] [
  14 -e <extract_iso_name>] [-g <grml_name>] [-i <iso_name>] [
  15 -o <output_directory>] [-r <release_name>] [-s <suite>] [
  16 -t <template_directory>] [-v <version_number>] [-U <username>] [
  17 -w <date>] [-AbBFnNqQuVz]
  18
  19 Description
  20 -----------
  21
  22 grml-live provides the build system for creating a Grml and Debian based Linux
  23 Live-CD. The build system is based on
  24 link:http://fai-project.org/[FAI] (Fully Automatic
  25 Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
  26 system based on the class concept of FAI (see later sections for further
  27 details) and provides the framework to be able to generate a full-featured ISO.
  28 It does not use all the FAI features by default though and you don't have to
  29 know FAI to be able to use it.
  30
  31 The use of FAI gives you the flexibility to choose the packages you would like
  32 to include on your very own Linux Live-CD without having to deal with all the
  33 details of a build process.
  34
  35 CAUTION: grml-live does **not** use /etc/fai for configuration but instead
  36 provides and uses ${GRML_FAI_CONFIG} which is pointing to /etc/grml/fai by default
  37 (unless overridden using the ''-D'' option). This ensures that it does not clash
  38 with default FAI configuration and packages, so you can use grml-live and FAI
  39 completely independent at the same time!
  40
  41 [NOTE]
  42
  43 Please notice that you should have a fast network connection as all the Debian
  44 packages will be downloaded and installed via network. If you want to use a
  45 local mirror (strongly recommended if you plan to use grml-live more than once)
  46 checkout debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
  47 sample configuration), apt-cacher(1) and approx(8). To avoid downloading the
  48 base system again and again check out <<create-a-base-tgz,the base tar.gz
  49 feature>>.
  50
  51 Options
  52 -------
  53
  54   -A::
  55
  56 Clean up all output directories before running the build process. After finishing,
  57 clean up the Chroot target and Build target directories.
  58
  59   -a **ARCHITECTURE**::
  60
  61 Use the specified architecture instead of the currently running one.  This
  62 allows building a 32bit system on a 64bit host (though you can't build a 64bit
  63 system on a 32bit system/kernel of course). Please notice that real
  64 crosscompiling (like building a ppc system on x86) isn't possible due to the
  65 nature and the need of working in a chroot. Currently supported values: i386,
  66 amd64 and arm64.
  67
  68   -b::
  69
  70 Build the ISO without updating the chroot via FAI. This option is useful for
  71 example when working on stable releases: if you have a working base
  72 system/chroot and do not want to execute any further updates (via "-u" option)
  73 but intend to only build the ISO.
  74
  75   -B::
  76
  77 Build the ISO without touching the chroot at all. This option is useful if
  78 you modified anything that FAI or grml-live might adjust via Grml's FAI
  79 scripts.  It's like the '-b' option but even more advanced. Use only if you
  80 really know that you do not want to update the chroot.
  81
  82   -c **CLASSES**::
  83
  84 Specify the CLASSES to be used for building the ISO via FAI.  By default only
  85 the classes GRMLBASE, GRML_FULL and I386/AMD64/ARM64 (depending on system
  86 architecture) are assumed.  Additionally you can specify a class providing a
  87 (grml-)kernel (see <<classes,the 'CLASSES' section in this document>> for
  88 details about available classes). So instead of GRML_FULL you can also use e.g.
  89 GRML_SMALL.
  90
  91 [IMPORTANT]
  92 All class names should be written in uppercase letters. Do not use a dash, use
  93 an underscore. So do not use "amd64" but "AMD64", do not use "FOO BAR" but
  94 "FOO_BAR".
  95
  96
  97   -C **CONFIGURATION_FILE**::
  98
  99 The specified file is used as configuration file for grml-live. By default
 100 /etc/grml/grml-live.conf is used as default configuration. If a file named
 101 /etc/grml/grml-live.local exists it is used as well (sourced after reading
 102 /etc/grml/grml-live.conf meant as main file for local configuration). As a last
 103 option the specified configuration file is sourced so it is possible to override
 104 settings of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local.
 105 Please notice that all configuration files have to be adjusted during execution
 106 of grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
 107 your own configuration file (usually /etc/grml/grml-live.local). Please also
 108 notice that the configuration file specified via this option is **not** (yet)
 109 supported inside the scripts/hooks/classes at ${GRML_FAI_CONFIG}/config. Instead use
 110 /etc/grml/grml-live.local for configuration stuff used inside
 111 ${GRML_FAI_CONFIG}/config.
 112
 113   -d **DATE**::
 114
 115 Use specified date as build date information on the ISO instead of the default.
 116 The default is the date when grml-live is being executed (retrieved via
 117 executing 'date +%Y-%m-%d'). The information is stored inside the file
 118 /GRML/grml-version on the ISO, /etc/grml_version in the squashfs file and in all
 119 the bootsplash related files. This option is useful if you want to provide an
 120 ISO with release information for a specific date but have to build it in
 121 advance. Usage example: '-d 2009-10-30'
 122
 123   -D **CONFIGURATION_DIRECTORY**::
 124
 125 The specified directory is used as configuration directory for grml-live and its
 126 FAI. By default /etc/grml/fai is used as default configuration directory.  If
 127 you want to have different configuration scripts, package definitions, etc. with
 128 without messing with the global configuration under /etc/grml/fai provided by
 129 grml-live this option provides you the option to use your own configuration
 130 directory. This directory is what's being referred to as ${GRML_FAI_CONFIG}
 131 throughout this documentation.
 132
 133   -e **EXTRACT_ISO_NAME**::
 134
 135 The squashfs inside the specified ISO will be extracted and used as the chroot.
 136 This option is useful for remastering, in combination with -A and -b or -u.
 137
 138   -F::
 139
 140 Force execution and do not prompt for acknowledgment of configuration.
 141
 142   -g **GRML_NAME**::
 143
 144 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
 145 Please do NOT use blanks and any special characters like '/', ';' inside
 146 GRML_NAME, otherwise you might notice problems while booting.
 147
 148   -h::
 149
 150 Display short usage information and exit.
 151
 152   -i **ISO_NAME**::
 153
 154 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
 155 by default.
 156
 157   -I **CHROOT_INSTALL**::
 158
 159 Specify name of source directory which provides files that should become part of
 160 the chroot/ISO. Not enabled by default. Note: the files are installed under '/'
 161 in the chroot so you have to create the rootfs structure on your own.
 162
 163   -n::
 164
 165 Skip creation of the ISO file. This option is useful if you want to build/update
 166 the chroot and/or recreate the squashfs file without building an ISO file.
 167
 168   -N::
 169
 170 Bootstrap the chroot without building bootloader, squashfs, or finalizing the
 171 ISO. Use this option if installation of some packages fails, you want to run
 172 custom commands or similar.
 173 The main use of this option is to save time by skipping stages which aren't
 174 necessary for bootstrapping the chroot and which would get executed more than
 175 once when iterating through the initial bootstrapping.
 176 Alternatively, use this option as a test run of grml-live. Once you are
 177 satisfied with the state of your grml_chroot, use grml-live **-u** to build the
 178 remaining stages and finalize the ISO.
 179
 180   -o **OUTPUT_DIRECTORY**::
 181
 182 Main output directory of the build process of FAI.  Some directories are created
 183 inside this target directory, being: grml_cd (where the files for creating the
 184 ISO are located, including the compressed squashfs file), grml_chroot (the
 185 chroot system) and grml_isos (where the resulting ISO is stored).
 186
 187   -q::
 188
 189 Build the ISO without (re-)creating the squashfs compressed file using mksquashfs.
 190 This option is useful if you just want to update parts outside the chroot in the ISO.
 191 Consider combining this option with the build-only option '-b'.
 192
 193   -Q::
 194
 195 Build the ISO without generating a netboot package.
 196
 197   -r **RELEASENAME**::
 198
 199 Specify name of the release.
 200
 201   -s **SUITE**::
 202
 203 Specify the Debian suite you want to use for your live-system. If unset defaults
 204 to "testing". Supported values are: stable, testing, unstable (or their
 205 corresponding release names like "bookworm"). Please be aware that recent Debian
 206 suites might require a recent base.tgz
 207 (${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of
 208 debootstrap.
 209
 210   -t **TEMPLATE_DIRECTORY**::
 211
 212 Specify place of the templates used for building the ISO. By default
 213 (and if not manually specified) this is /usr/share/grml-live/templates/.
 214
 215   -u::
 216
 217 Update existing chroot instead of rebuilding it from scratch. This option is
 218 based on the softupdate feature of FAI.
 219
 220   -U **USERNAME**::
 221
 222 Sets ownership of all build output files to specified username before exiting.
 223
 224   -v **VERSION_NUMBER**::
 225
 226 Specify version number of the release.
 227
 228   -V::
 229
 230 Increase verbosity in the build process.
 231
 232   -w **DATE**::
 233
 234 The wayback machine. Build the system using Debian archives from the specified
 235 date.  Valid date formats are yyyymmddThhmmssZ or simply yyyymmdd.  To learn
 236 which snapshots exist, i.e. which date strings are valid, simply browse the
 237 lists on http://snapshot.debian.org/.  If there is no import at the exact time
 238 you specified you will get the latest available timestamp which is before the
 239 time you specified.
 240 This option is useful especially for release and debugging builds - for example
 241 if you know that the Debian archive was in a good state on a specific date but
 242 you want to build it on another day in the future, where the archive might not
 243 be as needed anymore. Please be aware that this is restricted to the plain
 244 Debian repositories only, as referred to in /etc/apt/sources.list.d/debian.list
 245 (so neither the Grml repositories nor any further custom ones are affected by
 246 the wayback machine).
 247
 248   -z::
 249
 250 Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process.
 251
 252 [[usage-examples]]
 253 Usage examples
 254 --------------
 255
 256 To get a Debian-stable and Grml-based Live-CD using ./grml
 257 as build and output directory just run:
 258
 259   # grml-live
 260
 261 To get a 64bit Debian-testing and grml-small based Live-CD using /srv/grml-live
 262 as build and output directory use the following command line on your amd64
 263 system:
 264
 265   # grml-live -s testing -c GRMLBASE,GRML_SMALL,AMD64 -o /srv/grml-live
 266
 267 [NOTE]
 268
 269 If you have enough RAM, just run "mount -t tmpfs none /media/ramdisk" to get a
 270 tmpfs ("RAMDISK"), and use /media/ramdisk as build and output directory - this
 271 results in a very fast build process. Note that these files will be gone when
 272 rebooting.
 273
 274 [[main-features]]
 275 Main features of grml-live
 276 --------------------------
 277
 278 * create a Grml-/Debian-based Linux Live-CD with one single command
 279
 280 * class based concept, providing a maximum of flexibility
 281
 282 * supports integration of own hooks, scripts and configuration
 283
 284 * supports use and integration of own Software and/or Kernels via simple use of
 285 Debian repositories
 286
 287 * native support of FAI features
 288
 289 [[class-concept]]
 290 The class concept
 291 -----------------
 292
 293 grml-live uses FAI and its class based concept for adjusting configuration and
 294 setup according to your needs. This gives you flexibility and strength without
 295 losing the simplicity in the build process.
 296
 297 The main and base class provided by grml-live is named GRMLBASE. It's strongly
 298 recommended to **always** use the class GRMLBASE when building an ISO using
 299 grml-live, as well as the architecture dependent class which provides the kernel
 300 (being 'I386' for x86_32, 'AMD64' for x86_64 and 'ARM64' for arm64) and a GRML_*
 301 class (like GRML_SMALL or GRML_FULL).
 302 The following files and directories are relevant for class GRMLBASE by default:
 303
 304   ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/
 305   ${GRML_FAI_CONFIG}/config/debconf/GRMLBASE
 306   ${GRML_FAI_CONFIG}/config/class/GRMLBASE.var
 307   ${GRML_FAI_CONFIG}/config/hooks/instsoft.GRMLBASE
 308   ${GRML_FAI_CONFIG}/config/package_config/GRMLBASE
 309
 310 Take a look at the next section for information about the concept of those
 311 files/directories.
 312
 313 If you want to use your own configuration, extend an existing configuration
 314 and/or add additional packages to your ISO just invent a new class (or extend an
 315 existing one). For example if you want to use your own class named "FOOBAR" on
 316 your amd64 build, et CLASSES="GRMLBASE,GRML_SMALL,AMD64,FOOBAR" inside
 317 /etc/grml/grml-live.local or invoke grml-live using the classes option:
 318 "grml-live -c GRMLBASE,GRML_SMALL,AMD64,FOOBAR ...".
 319
 320 More details regarding the class concept can be found in the documentation of
 321 FAI itself (being available at /usr/share/doc/fai-doc/).
 322
 323 [[X7]]
 324 [[classes]]
 325 Available classes
 326 -----------------
 327
 328 The package selection part of the classes can be found in
 329 ${GRML_FAI_CONFIG}/config/package_config whereas some further classes are defined for
 330 example in ${GRML_FAI_CONFIG}/config/scripts/ so specific feature sets can be
 331 selected. The following classes are predefined:
 332
 333 * DEBORPHAN: get rid of all packages listed in output of deborphan
 334
 335 * FRESHCLAM: execute freshclam (if it's present) to update clamav definitions
 336 (increases resulting ISO size ~70MB). By default it's skipped to avoid bigger
 337 ISO size.
 338
 339 * GRMLBASE: the main class responsible for getting a minimal subset of what's
 340 defining a Grml system. Important parts of the buildprocess are specified in
 341 this class as well, so unless you have a really good reason you should always
 342 use this class. Please be aware that using *just* the GRMLBASE class won't be
 343 enough, because the kernel packages (e.g. linux-image-pass:[*]) are chosen in
 344 further GRML_pass:[*] classes (to provide maximum flexibility with kernel
 345 selection). If you don't want to use the existing GRML_FULL or GRML_SMALL
 346 classes, define your own CLASS file choosing the kernel package you want to use
 347 (and don't forget to include your CLASS in the arguments of grml-live's `-c...`
 348 command line option).
 349
 350 * GRML_FULL: full featured Grml, also known as the "normal", full grml as
 351 introduced in December 2011 (~750 ISO size).
 352
 353 * GRML_SMALL: minimum sized Grml version, known as grml-small (~360MB ISO
 354 size).
 355
 356 * LATEX: LaTeX(-related) packages like auctex, texlive,...
 357 (which used to be shipped by grml before the LaTeX removal)
 358
 359 * LATEX_CLEANUP: get rid of several very large LaTeX directories
 360 (like some /usr/share/doc/texlive-*, /usr/share/doc/texmf,...)
 361
 362 * LOCALES: use full featured locales setup (see /etc/locale.gen.grml). This
 363 avoids to get rid of /usr/share/locale - which happens by default otherwise - as
 364 well.
 365
 366 * NO_ONLINE: do not run scripts during the chroot build process which require a
 367 network connection
 368
 369 * RELEASE: run some specific scripts and commands to provide the workflow for an
 370 official grml release
 371
 372 * REMOVE_DOCS: get rid of documentation directories (like /usr/share/doc,
 373 /usr/share/man/, /usr/share/info,...)
 374
 375 * SOURCES: retrieve Debian source packages after installation. Files will be
 376 placed in the output directory under grml_sources.
 377
 378 * XORG: providing important packages for use with a base grml-featured X.org
 379 setup
 380
 381 * ZFS: package selection to add support for OpenZFS/zfsonlinux
 382
 383 [[files]]
 384 Files
 385 -----
 386
 387 Notice that grml-live ships FAI configuration files that do not use the same
 388 namespace as the FAI packages itself. This ensures that grml-live does not clash
 389 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
 390 fai-client) grml uses ${GRML_FAI_CONFIG}/fai.conf instead. For more details see
 391 below. To get an idea how another configuration or example files could look like
 392 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 393 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
 394 provides documentation regarding configuration possibilities.
 395
 396   /usr/sbin/grml-live
 397
 398 Script for the main build process. Requires root permissions for execution.
 399
 400   /etc/grml/grml-live.conf
 401
 402 Main configuration file for grml-live which should be considered as a reference
 403 configuration file only. Please use /etc/grml/grml-live.local for local
 404 configuration instead.
 405
 406   /etc/grml/grml-live.local
 407
 408 All the local configuration should go to this file. This file overrides any
 409 defaults of grml-live. Configurations via /etc/grml/grml-live.local are preferred
 410 over the ones from /etc/grml/grml-live.conf. If you want to override settings
 411 from /etc/grml/grml-live.local as well you have to specify them on the grml-live
 412 commandline.
 413
 414   ${GRML_FAI_CONFIG}/fai.conf
 415
 416 Main configuration file for FAI which specifies where all the configuration
 417 files and scripts for FAI/grml-live can be found. By default the configuration
 418 variables are FAI_CONFIG_SRC=file:///etc/grml/fai/config and
 419 GRML_FAI_CONFIG=/etc/grml/fai/config - both pointing to a directory shipped by
 420 grml-live out-of-the-box so you shouldn't have to configure anything in this
 421 file.
 422
 423   ${GRML_FAI_CONFIG}/config/
 424
 425 The main directory for configuration of FAI/grml-live. More details below.
 426
 427   ${GRML_FAI_CONFIG}/config/class/
 428
 429 This directory contains files which specify main configuration variables for the
 430 FAI classes.
 431
 432   ${GRML_FAI_CONFIG}/config/debconf/
 433
 434 This directory provides the files for preseeding/configuration of debconf
 435 through files.
 436
 437   ${GRML_FAI_CONFIG}/config/hooks/
 438
 439 This directory provides files for customising the build process through hooks.
 440 Hooks are user defined programs or scripts, which are called during the
 441 installation process.
 442
 443   ${GRML_FAI_CONFIG}/config/package_config/
 444
 445 Directory with lists of software packages to be installed or removed.  The
 446 different classes describe what should find its way to your ISO.  When running
 447 "grml-live -c GRMLBASE,GRML_SMALL,AMD64 ..." only the configuration of GRMLBASE,
 448 GRML_SMALL and AMD64 will be taken. If you use 'grml-live -c
 449 GRMLBASE,GRML_SMALL,AMD64,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
 450 AMD64 **plus** the files from FOOBAR will be taken. So just create a new class to
 451 adjust the package selection according to your needs.  Please notice that the
 452 directory GRMLBASE contains a package list defining a minimum but still
 453 reasonable package configuration.
 454
 455   ${GRML_FAI_CONFIG}/config/scripts/
 456
 457 Scripts for customising the ISO within the build process.
 458
 459   ${GRML_FAI_CONFIG}/live-initramfs/
 460
 461 This directory provides the files used for building the initramfs/initrd via
 462 live-initramfs(8).
 463
 464 [[log-files]]
 465 Available log files
 466 -------------------
 467
 468 Starting with grml-live version 0.17.0 you should find log files in a directory
 469 named 'grml_logs' in the output directory (next to grml_isos, grml_chroot,...).
 470
 471 grml-live versions before 0.17.0 used to log into /var/log/grml-live.log
 472 and /var/log/fai/grml.
 473
 474 [[requirements]]
 475 Requirements for the build system
 476 ---------------------------------
 477
 478 * any Debian based system should be sufficient (if it doesn't work it's a bug,
 479 please send us a bug report then). Check out <<deploy-on-debian,How do I deploy
 480 grml-live on a plain Debian installation>> for details how to set up grml-live
 481 on a plain, original Debian system.
 482
 483 * enough free disk space; at least ~2GB are required for a minimal grml-live
 484 run (\~1GB for the chroot [$CHROOT_OUTPUT], \~400MB for the build target
 485 [$BUILD_OUTPUT], \~35MB for the netboot files and \~350MB for the resulting ISO
 486 [$ISO_OUTPUT] plus some temporary files), if you plan to use GRML_FULL you
 487 should have at least 4GB of total free disk space
 488
 489 * fast network access for retrieving the Debian packages used for creating the
 490 chroot (check out "local mirror" to workaround this problem as far as possible)
 491
 492 * your output directory should not be mounted with any of the "nodev", "noexec"
 493 or "nosuid" mount options. (/tmp typically is at least "nodev" and "nosuid" on
 494 most systems.)
 495
 496 For further information see next section.
 497
 498 [[X8]]
 499 [[current_state]]
 500 Current state of grml-live with squashfs-tools and kernel
 501 ---------------------------------------------------------
 502
 503 Use squashfs-tools >=4.2-1 to build Grml (based) ISOs featuring kernel version
 504 2.6.38-grml[64] or newer.
 505
 506 [[faq]]
 507 FAQ
 508 ---
 509
 510 [[deploy-on-debian]]
 511 How do I deploy grml-live on a plain Debian installation?
 512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 513
 514 The easiest way to get a running grml-live setup is to just use Grml.
 515 Of course using grml-live on a plain, original Debian installation is supported
 516 as well. So there we go.
 517
 518 What we have: plain, original Debian bookworm (v12).
 519
 520 What we want: build a Grml ISO based on Debian/bookworm for the amd64 architecture
 521 using grml-live.
 522
 523 Instructions
 524 ^^^^^^^^^^^^
 525
 526   # adjust sources.list:
 527   cat >> /etc/apt/sources.list << EOF
 528
 529   # grml stable repository:
 530     deb     http://deb.grml.org/ grml-stable  main
 531   # deb-src http://deb.grml.org/ grml-stable  main
 532
 533   # grml testing/development repository:
 534     deb     http://deb.grml.org/ grml-testing main
 535   # deb-src http://deb.grml.org/ grml-testing main
 536   EOF
 537
 538   # get keyring for apt:
 539   apt-get update
 540   apt-get --allow-unauthenticated install grml-debian-keyring
 541
 542   # optionally(!) install basefile so we don't have to build basic
 543   # chroot from scratch, grab from http://daily.grml.org/
 544   # mkdir -p /etc/grml/fai/config/basefiles/
 545   # mv I386.tar.gz /etc/grml/fai/config/basefiles/
 546   # mv AMD64.tar.gz /etc/grml/fai/config/basefiles/
 547   # mv ARM64.tar.gz /etc/grml/fai/config/basefiles/
 548
 549   # install relevant tools
 550   apt-get --no-install-recommends install grml-live
 551
 552   # adjust grml-live configuration for our needs:
 553   cat > /etc/grml/grml-live.local << EOF
 554   ## want a faster build process and don't need smaller ISOs?
 555   ## if so use zlib compression
 556   # SQUASHFS_OPTIONS="-comp gzip -b 256k"
 557   ## want to use a specific squashfs binary?
 558   # SQUASHFS_BINARY='/usr/bin/mksquashfs'
 559   ## install local files into the chroot
 560   # CHROOT_INSTALL="/etc/grml/fai/chroot_install"
 561   ## adjust if necessary (defaults to ./grml/):
 562   ## OUTPUT="/srv/grml-live"
 563   FAI_DEBOOTSTRAP="bookworm http://deb.debian.org/debian/"
 564   # ARCH="amd64"
 565   CLASSES="GRMLBASE,GRML_FULL,AMD64"
 566   EOF
 567
 568   # just optional(!) - upgrade FAI to latest available version:
 569   cat >> /etc/apt/sources.list.d/fai.list << EOF
 570   deb     http://jenkins.grml.org/debian fai main
 571   deb-src http://jenkins.grml.org/debian fai main
 572   EOF
 573
 574   # get gpg key of FAI repos and install current FAI version:
 575   wget -O - http://jenkins.grml.org/debian/C525F56752D4A654.asc | sudo apt-key add -
 576   apt-get update
 577   apt-get install fai-client fai-server fai-doc
 578
 579 That's it. Now invoking 'grml-live -V' should build the ISO.  If everything
 580 worked as expected the last line of the shell output should look like:
 581
 582   [*] Successfully finished execution of grml-live [running 687 seconds]
 583
 584 and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.
 585
 586 [[grml_fai_config_variable]]
 587 What is $GRML_FAI_CONFIG?
 588 ~~~~~~~~~~~~~~~~~~~~~~~~~
 589
 590 The variable '$GRML_FAI_CONFIG' is pointing to the directory /etc/grml/fai by
 591 default.  To provide you a maximum of flexibility you can set up your own
 592 configuration directory (e.g. based on /etc/grml/fai) and use this directory
 593 running grml-live with the '-D <config_dir>' option. Now '$GRML_FAI_CONFIG'
 594 points to the specified directory instead of using /etc/grml/fai and all the
 595 configuration files, scripts and hooks will be taken from your
 596 '$GRML_FAI_CONFIG' directory.
 597
 598 [[how-to-debug]]
 599 I've problems with the build process. How to start debugging?
 600 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 601
 602 Check out the logs inside the directory 'grml_logs' next to your grml_chroot,
 603 grml_isos,... directories.
 604
 605 If you need help with grml-live or would like to see new features as part of
 606 grml-live you can get commercial support via
 607 link:http://grml-solutions.com/[Grml Solutions].
 608
 609 Note that FAI doesn't abort immediately on errors that will ultimately cause
 610 the build to fail. Be sure to look through the logs and find the actual error;
 611 look for lines that start with "E: " or contain "FAILED" or "exit code 1".
 612 Some messages that may look like errors are actually benign; e.g.
 613 "/tmp/grml64/grml_chroot/var/lib/dpkg is not a mounted ramdisk" is not an error.
 614
 615 [[install-local-files]]
 616 How do I install further files into the chroot/ISO?
 617 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 618
 619 Just point the configuration variable CHROOT_INSTALL to the directory which
 620 provides the files you would like to install. Note that the files are installed
 621 under '/' in the chroot - so you have to create the rootfs structure on your
 622 own. Usage example:
 623
 624   echo "CHROOT_INSTALL=\$GRML_FAI_CONFIG/chroot_install" >> /etc/grml/grml-live.local
 625   mkdir -p /etc/grml/fai/chroot_install/usr/src/
 626   wget example.org/foo.tar.gz
 627   mv foo.tar.gz /etc/grml/fai/chroot_install/usr/src/
 628   grml-live ...
 629
 630 [[local-debian-mirror]]
 631 Can I use my own (local) Debian mirror?
 632 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 633
 634 Yes. Set up an according sources.list configuration as class file in
 635 ${GRML_FAI_CONFIG}/config/files/etc/apt/sources.list.d/ and adjust the variable
 636 FAI_DEBOOTSTRAP (if not already using a base.tgz) inside
 637 /etc/grml/grml-live.conf[.local]. If you're setting up your own class file don't
 638 forget to include the class name in the class list (grml-live -c ...).
 639
 640 If you want to use a local (for example NFS mount) mirror additionally then
 641 adjust MIRROR_DIRECTORY in /etc/grml/grml-live.conf[.local] as well.
 642
 643 If you want to use a HTTP Proxy (like apt-cacher-ng), set APT_PROXY. Example:
 644
 645   APT_PROXY="http://localhost:3142/"
 646
 647 [[add-additional-debian-packages]]
 648 How do I add additional Debian package(s) to my CD/ISO?
 649 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 650
 651 Just create a new class (using the package_config directory):
 652
 653   # cat > /etc/grml/fai/config/package_config/MIKA << EOF
 654   PACKAGES install
 655
 656   vim
 657   another_name_of_a_debian_package
 658   and_another_one
 659   EOF
 660
 661 and specify it when invoking grml-live then:
 662
 663   # grml-live -c GRMLBASE,GRML_SMALL,AMD64,MIKA
 664
 665 [[reset-grml-live-configuration]]
 666 I fscked up my grml-live configuration. How do I reset it to the defaults?
 667 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 668
 669 Notice: this deletes all your grml-live configuration files. If that's really
 670 what you are searching for just run:
 671
 672   rm -rf /etc/grml/fai /etc/grml/grml-live.conf
 673   dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
 674
 675 [[apt-cacher]]
 676 Set up apt-cacher-ng for use with grml-live
 677 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 678
 679 Make sure /etc/grml/grml-live.local provides according APT_PROXY and
 680 FAI_DEBOOTSTRAP:
 681
 682   # cat /etc/grml/grml-live.local
 683   [...]
 684   APT_PROXY="http://localhost:3142/"
 685   [...]
 686   FAI_DEBOOTSTRAP="bookworm http://localhost:3142/ftp.debian.org/debian bookworm main contrib non-free"
 687
 688 Make sure apt-cacher-ng is running ('/etc/init.d/apt-cacher-ng restart').
 689 That's it.  All downloaded files will be cached in /var/cache/apt-cacher-ng then.
 690
 691 [[revert_manifold]]
 692 How do I revert the manifold feature from an ISO?
 693 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 694
 695 By default, Grml ISOs use isohybrid to allow them to be booted from CDs as
 696 well as USB sticks. Manifold is an alternative to isohybrid.
 697
 698 If you notice any problems
 699 when booting manifold-crafted media, just revert the manifold feature running:
 700
 701   % dd if=/dev/zero of=grml.iso bs=512 count=1 conv=notrunc
 702
 703 To switch from manifold to isohybrid mode (an alternative approach provided by
 704 syslinux, used by default for official Grml images) then just execute:
 705
 706   % isohybrid grml.iso
 707
 708 [[create-a-base-tgz]]
 709 How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz or ARM64.tar.gz)
 710 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 711 [[basetgz]]
 712
 713 First of all create the chroot using debootstrap (requires root):
 714
 715   BASECHROOT='/tmp/basefile'  # path where the chroot gets generated
 716   SUITE='bookworm'            # using the current stable release should always work
 717   debootstrap --exclude=info,tasksel,tasksel-data,isc-dhcp-client,isc-dhcp-common "${SUITE}" "${BASECHROOT}" http://deb.debian.org/debian
 718   tar -C "$BASECHROOT" --exclude='var/cache/apt/archives/*.deb' --exclude 'var/lib/apt/lists/*_*' --xattrs --xattrs-include='*.*' --acls -zcf "${SUITE}".tar.gz ./
 719
 720 [TIP]
 721 By default debootstrap builds a chroot matching the architecture of the running
 722 host system. If you're using an amd64 system and want to build an i386 base.tgz
 723 then invoke debootstrap using the '--arch i386' option. Disclaimer: building an
 724 AMD64 base.tgz won't work if you are using a 32bit kernel system of course.
 725 Also building an ARM64 base.tgz requires an arm64 system.
 726
 727 Finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note
 728 that it needs to be uppercase letters matching the class names, so: e.g.
 729 AMD64.tar.gz for amd64, I386.tar.gz for i386 or ARM64.tar.gz for arm64).
 730
 731 Then executing grml-live should use this file as base system instead of executing
 732 debootstrap. Check out the output for something like:
 733
 734   [...]
 735   ftar: extracting //etc/grml/fai/config/basefiles///AMD64.tar.gz to /srv/grml64_testing/grml_chroot//
 736   [...]
 737
 738 [[localrepos]]
 739 How to use your own local repository
 740 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 741
 742 Let's assume you have Debian package(s) in your filesystem inside
 743 `/home/foobar/local-packages` and want to provide them to your grml-live build.
 744 This can be achieved either 1) through a bind mount (using the MIRROR_DIRECTORY
 745 configuration) or 2) by serving a repository via HTTP.
 746
 747 Serving via bind mount / MIRROR_DIRECTORY
 748 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 749
 750 Make sure to create an according sources.list configuration file, e.g. using
 751 your own class name `CUSTOM`:
 752
 753   # cat > /etc/grml/fai/config/files/etc/apt/sources.list.d/local-packages.list/CUSTOM << EOF
 754   deb file:///home/foobar/local-packages ./
 755   EOF
 756
 757 Add the according MIRROR_DIRECTORY configuration to your grml-live configuration:
 758
 759   # echo "MIRROR_DIRECTORY='/home/foobar/packages'" >> /etc/grml/grml-live.local
 760
 761 Make sure the local directory looks like a mirror:
 762
 763   % cd /home/foobar/packages
 764   % dpkg-scanpackages . /dev/null | gzip > Packages.gz
 765
 766 Finally invoke grml-live with your class name (`CUSTOM` in this example) added
 767 to the list of classes on the command line (see grml-live option `-c`).
 768
 769 Serving a repository via HTTP
 770 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 771
 772 Make sure to create an according sources.list configuration file, e.g. using
 773 your own class name `CUSTOM`:
 774
 775   # cat > /etc/grml/fai/config/files/etc/apt/sources.list.d/local-packages.list/CUSTOM << EOF
 776   deb http://127.0.0.1:8000/ ./
 777   EOF
 778
 779 Make sure the local directory is served via HTTP on the according IP address and
 780 port. For the `http://127.0.0.1:8000/` example from above it should be enough to
 781 just invoke:
 782
 783   % cd /home/foobar/packages
 784   % dpkg-scanpackages . /dev/null | gzip > Packages.gz
 785   % python -m SimpleHTTPServer 8000
 786
 787 [TIP]
 788 Of course you can also use a real Debian repository setup using tools like
 789 reprepro(1) and/or using a real web server, though for quick debugging sessions
 790 python's SimpleHTTPServer in combination with dpkg-scanpackages from package
 791 dpkg-dev is a simple and easy approach.
 792
 793 Finally invoke grml-live with your class name (`CUSTOM` in this example) added
 794 to the list of classes on the command line (see grml-live option `-c`).
 795
 796 [[download]]
 797 Download / install grml-live as a Debian package
 798 ------------------------------------------------
 799
 800 Stable Debian packages are available through the grml-repository at
 801 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org] and the latest
 802 Git commits are available as Debian packages from
 803 link:http://jenkins.grml.org/job/grml-live-binaries/[jenkins.grml.org].
 804 If you want to build a Debian package on your own (using for example a specific
 805 version or the current development tree), just execute:
 806
 807   git clone git://git.grml.org/grml-live
 808   cd grml-live
 809   debuild -us -uc
 810
 811 [[run-from-git]]
 812 Run grml-live directly from git
 813 -------------------------------
 814
 815 In case you want to run grml-live directly from the git repository checkout
 816 (after making sure all dependencies are installed), you should set
 817 `GRML_FAI_CONFIG` so that a) it finds the according FAI configuration files and
 818 b) does not use the config files of an possibly installed `grml-live` package.
 819 Usage example:
 820
 821     # export GRML_FAI_CONFIG=$(pwd)/etc/grml/fai
 822     # export SCRIPTS_DIRECTORY=$(pwd)/scripts
 823     # export TEMPLATE_DIRECTORY=$(pwd)/templates
 824     # ./grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64
 825
 826 [[source]]
 827 Source
 828 ------
 829
 830 The source of grml-live is available at
 831 link:https://github.com/grml/grml-live/[https://github.com/grml/grml-live/]
 832
 833 [[bugs]]
 834 Bugs
 835 ----
 836
 837 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 838 link:http://grml.org/contact/[to the Grml team]!
 839
 840 [[documentation]]
 841 Documentation
 842 -------------
 843
 844 The most recent grml-live documentation is available online at
 845 http://grml.org/grml-live/ and for offline reading also available
 846 in different formats:
 847
 848 * http://grml.org/grml-live/grml-live.epub
 849 * http://grml.org/grml-live/grml-live.pdf
 850
 851 [[authors]]
 852 Authors
 853 -------
 854 Michael Prokop <mika@grml.org>
 855
 856 /////////////////////////////////////
 857 // vim:ai tw=80 ft=asciidoc expandtab
 858 /////////////////////////////////////