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 [-c <classe[s]>] [-g <grml_name>] [-i <iso_name> ] [-r <release_name>]
  14 [-s <suite>] [-t <target_directory>] [-v <version_number>] [-FVh]
  15
  16 *******************************************************************************
  17 Important! This document is growing as requested. If you have questions which
  18 aren't answered by this document yet please let me know: <mika@grml.org>!
  19 *******************************************************************************
  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) and approx(8). To avoid downloading the base system again
  50 and again check out FAI's NFSROOT (see FAQ of this document for details).
  51
  52 Options
  53 -------
  54
  55   -c **CLASSES**::
  56
  57 Specify the CLASSES to be used for building the ISO via FAI.  By default only
  58 the classes GRMLBASE, GRML_SMALL and I386 are assumed, resulting in a small base
  59 system (being about ~150MB total ISO size). If using a non-I386 system (like
  60 amd64) you should specify the appropriate architecture as well. Additionally you
  61 can specify a class providing a grml-kernel (see
  62 /etc/grml/fai/config/package_config/ for a full list).  So instead of GRML_SMALL
  63 you can also use GRML_MEDIUM and GRML_FULL instead.
  64
  65   -F::
  66
  67 Force execution and do not prompt for acknowledgment of configuration.
  68
  69   -g **GRML_NAME**::
  70
  71 Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
  72
  73   -h::
  74
  75 Display short usage information and exit.
  76
  77   -i **ISO_NAME**::
  78
  79 Specify name of ISO which will be available inside $TARGET_DIRECTORY/grml_isos
  80 by default.
  81
  82   -r **RELEASENAME**::
  83
  84 Specify name of the release.
  85
  86   -s **SUITE**::
  87
  88 Specify the Debian suite you want to use for your live-system.  Defaults to
  89 "etch" (being current Debian/stable). Supported values are: etch, lenny, sid.
  90
  91   -t **TARGET_DIRECTORY**::
  92
  93 Main output directory of the build process of FAI.  Some directories are created
  94 inside this target directory, being: grml_cd (where the files for creating the
  95 ISO are located, including the compressed squashfs file), grml_chroot (the
  96 chroot system) and grml_isos (where the resulting ISO is stored).
  97
  98   -v **VERSION_NUMBER**::
  99
 100 Specify version number of the release.
 101
 102   -V::
 103
 104 Increase verbosity in the build process.
 105
 106 Usage examples
 107 --------------
 108
 109 To get a small, Debian-stable and grml-based Live-CD using /grml/grml-live
 110 as build and output directory just run:
 111
 112   # grml-live
 113
 114 To get a small Debian-unstable and grml-small based Live-CD using
 115 /home/mika/grml-live as build and output directory just use:
 116
 117   # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
 118
 119 To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
 120 output directory and use grml_0.0-3.iso as ISO name (placed inside
 121 /tmp/grml_isos) just invoke:
 122
 123   # grml-live -t /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
 124
 125 [NOTE]
 126
 127 If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
 128 you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
 129 and use /dev/shm as build and output directory - resulting in very fast build
 130 process.  But please be aware of the fact that rebooting your system will result
 131 in an empty /dev/shm, so please another directory for $CHROOT_TARGET,
 132 $BUILD_TARGET and $ISO_TARGET if you plan to create more persistent output. :)
 133
 134 Main features of grml-live
 135 --------------------------
 136
 137 * create a grml-/Debian-based Linux Live-CD with one single command
 138
 139 * class based concept, providing a maximum of flexibility
 140
 141 * supports integration of own hooks, scripts and configuration
 142
 143 * supports use and integration of own Software and/or Kernels via simple use of
 144 Debian repositories
 145
 146 * native support of FAI features
 147
 148 * multi-arch support (work in progress)
 149
 150 The class concept
 151 -----------------
 152
 153 grml-live uses FAI and its class based concept for adjusting configuration and
 154 setup according to your needs. This gives you flexibility and strength without
 155 losing the simplicity in the build process.
 156
 157 The main and base class provided by grml-live is named GRMLBASE. It's strongly
 158 recommended to **always** use the class GRMLBASE when building an ISO using
 159 grml-live, as well as the architecture dependent class which provides the kernel
 160 (being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
 161 GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
 162 relevant for class GRMLBASE by default:
 163
 164   /etc/grml/fai/config/scripts/GRMLBASE/
 165   /etc/grml/fai/config/debconf/GRMLBASE
 166   /etc/grml/fai/config/class/GRMLBASE.var
 167   /etc/grml/fai/config/hooks/instsoft.GRMLBASE
 168   /etc/grml/fai/config/package_config/GRMLBASE
 169
 170 Take a look at the next section for information about the concept of those
 171 files/directories.
 172
 173 If you want to use your own configuration, extend an existing configuration
 174 and/or add additional packages to your ISO just invent a new class (or extend an
 175 existing one). For example if you want to use your own class named "FOOBAR" just
 176 extend CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.conf to
 177 CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" or invoke grml-live using the classes
 178 option: "grml-live -c GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
 179
 180 More details regarding the class concept can be found in the documentation of
 181 FAI itself (being available at /usr/share/doc/fai-doc/).
 182
 183 Files
 184 -----
 185
 186 Notice that grml-live ships FAI configuration files that do not use the same
 187 namespace as the FAI packages itself. This ensures that grml-live does not clash
 188 with your usual FAI configuration, so instead of /etc/fai/fai.conf (package
 189 fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see
 190 below. To get an idea how another configuration or example files could look like
 191 check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package
 192 fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html
 193 provides documentation regarding configuration possibilities.
 194
 195   /usr/sbin/grml-live
 196
 197 Script for the main build process. Requires root permissions for execution.
 198
 199   /etc/grml/grml-live.conf
 200
 201 Main configuration file for grml-live. All the important steps can be configured
 202 at this stage.
 203
 204   /etc/grml/fai/fai.conf
 205
 206 Main configuration file for FAI which specifies where all the configuration
 207 files and scripts for FAI/grml-live can be found. By default it is set to
 208 FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live
 209 out-of-the-box so you shouldn't have to configure anything in this file.
 210
 211   /etc/grml/fai/make-fai-nfsroot.conf
 212
 213 This file is used by make-fai-nfsroot(8) only. Usually you don't have to change
 214 anything inside this file. If you want to modify NFSROOT though you can adjust
 215 it there.
 216
 217   /etc/grml/fai/NFSROOT
 218
 219 This file specifies the package list for creating the NFSROOT.
 220
 221   /etc/grml/fai/apt/sources.list
 222
 223 This file specifies which mirrors should be used for retreiving the Debian
 224 packages used for creating the main chroot (including all the software you would
 225 like to see included). If you want to use a local mirror you either have to
 226 adjust this file or use the GRML_LIVE_SOURCES variable inside
 227 /etc/grml/grml-live.conf which modifies /etc/grml/fai/apt/sources.list
 228 on-the-fly then.
 229
 230   /etc/grml/fai/config/
 231
 232 The main directory for configuration of FAI/grml-live. More details below.
 233
 234   /etc/grml/fai/config/class/
 235
 236 This directory contains files which specify main configuration variables for the
 237 FAI classes.
 238
 239   /etc/grml/fai/config/debconf/
 240
 241 This directory provides the files for preseeding/configuration of debconf
 242 through files.
 243
 244   /etc/grml/fai/config/hooks/
 245
 246 This directory provides files for customising the build process through hooks.
 247 Hooks are user defined programs or scripts, which are called during the
 248 installation process.
 249
 250   /etc/grml/fai/config/package_config/
 251
 252 Directory with lists of software packages to be installed or removed.  The
 253 different classes describe what should find its way to your ISO.  When running
 254 "grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
 255 GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
 256 GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
 257 I386 **plus** the files from FOOBAR will be taken. So just create a new class to
 258 adjust the package selection according to your needs.  Please notice that the
 259 directory GRMLBASE contains a package list defining a minimum but still
 260 reasonable package configuration.
 261
 262   /etc/grml/fai/config/scripts/
 263
 264 Scripts for customising the ISO within the build process.
 265
 266   /etc/grml/fai/files/
 267
 268 This directory provides files used inside the scripts of
 269 /etc/grml/fai/config/scripts/*. For a full documentation what happens with the
 270 files please refer to the source of the scripts.
 271
 272   /etc/grml/fai/live-initramfs/
 273
 274 This directory provides the files used for building the initramfs/initrd via
 275 live-initramfs(8).
 276
 277 Requirements for the build system
 278 ---------------------------------
 279
 280 * any Debian based system should be sufficient (if not it's a bug, so please
 281 send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
 282 harddisk installation ships all you need]
 283
 284 * enough free disk space; at least 800MB are required for a minimal grml-live
 285 run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
 286 [$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
 287 temporary files), if you plan to use GRML_FULL you should have at least 4GB of
 288 total free disk space
 289
 290 * fast network access for retreiving the Debian packages used for creating the
 291 chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
 292 as possiblbe)
 293
 294 FAQ
 295 ---
 296
 297 Help, I'm using Debian etch and I don't have FAI version >3.2
 298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 299
 300   wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.1_all.deb \
 301        http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.1_all.deb
 302   dpkg -i fai-client_3.2.1_all.deb fai-server_3.2.1_all.deb
 303
 304 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
 305 further details.
 306
 307 I've problems with the build process. How to start debugging?
 308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 309
 310 Check out the logs inside /var/log/fai/dirinstall/... If you don't have the time
 311 to debug the problem in further detail or don't know how to proceed just send a
 312 copy of your config, logs and the commandline with a short problem description
 313 to <mika@grml.org>:
 314
 315   # history | grep grml-live > /etc/grml/grml_live.cmdline
 316   # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
 317             /var/log/fai/dirinstall /etc/grml/fai
 318
 319 Can I use my own (local) Debian mirror?
 320 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 321
 322 Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not
 323 already using NFSROOT's base.tgz) inside /etc/grml/grml-live.conf according to
 324 your needs. Please don't forget that you should use the grml servers as well
 325 (see default configuration) so all the grml packages can be downloaded as well.
 326
 327 If you want to use a local (for example NFS mount) mirror additionally, just
 328 adjust MIRROR_DIRECTORY and MIRROR_SOURCES insede /etc/grml/grml-live.conf as
 329 well.
 330
 331 Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
 332 /etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be
 333 taken. If you customise the variables in /etc/grml/grml-live.conf then the two
 334 files will be adjusted during runtime automatically.
 335
 336 If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be
 337 taken as first entry in the generated sources.list so it's prefered over
 338 non-local mirrors. Using a fallback mirror (via providing several mirrors in
 339 GRML_LIVE_SOURCES as used by default) is a recommended setting.
 340
 341 How do I add additional Debian package(s) to my CD/ISO?
 342 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 343
 344 Just create a new class (using the package_config directory):
 345
 346   # cat > /etc/grml/fai/config/package_config/MIKA << EOF
 347   PACKAGES aptitude
 348
 349   vim
 350   another_name_of_a_debian_package
 351   and_another_one
 352   EOF
 353
 354 and specify it when invoking grml-live then:
 355
 356   # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
 357
 358 I fscked up my grml-live configuration. How do I reset it to the defaults?
 359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 360
 361 Notice: this deletes all your grml-live configuration files. If that's really
 362 what you are searching for just run:
 363
 364   rm -rf /etc/grml/fai /etc/grml/grml-live.conf
 365   dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb
 366
 367 [NOTE]
 368
 369 If you don't control your /etc using a version control system (VCS) yet it's a
 370 good chance to start using it now. Check out
 371 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/]
 372 for more details how to maintain /etc using the mercurial VCS.
 373
 374 How do I create a base.tgz for use as NFSROOT?
 375 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 376
 377 First of all build the chroot system:
 378
 379   mkdir /tmp/nfsroot && cd /tmp/nfsroot
 380   debootstrap etch /tmp/nfsroot/ http://ftp.de.debian.org/debian
 381   tar zcf base.tgz ./
 382
 383 Then check out where your NFSROOT is located:
 384
 385   # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf
 386   NFSROOT=/grml/fai/nfsroot
 387
 388 So as /grml/fai/nfsroot is your NFSROOT place the file under
 389 /grml/fai/nfsroot/live/filesystem.dir/var/tmp/:
 390
 391   mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 392
 393 Now running "grml-live ..." will use this file as main system instead of
 394 executing debootstrap. Check out the output for the following lines:
 395
 396   [...]
 397   Calling task_extrbase
 398   Unpacking Debian base archive
 399   Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
 400   Calling task_mirror
 401   [...]
 402
 403 Set up approx for use with grml-live
 404 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 405
 406 Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
 407 FAI_DEBOOTSTRAP:
 408
 409   # cat /etc/grml/grml-live.conf
 410   [...]
 411   GRML_LIVE_SOURCES="
 412   deb http://localhost:9999/grml            grml-stable  main
 413   deb http://localhost:9999/grml            grml-testing main
 414   deb http://localhost:9999/debian etch     main contrib non-free
 415   "
 416   FAI_DEBOOTSTRAP="etch http://localhost:9999/debian"
 417
 418 Configure approx:
 419
 420   # cat /etc/approx/approx.conf
 421   [...]
 422   debian http://ftp.at.debian.org/debian
 423   grml   http://deb.grml.org/
 424
 425 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
 426 All downloaded files will be cached in /var/cache/approx now.
 427
 428 I've a question which isn't answered by this document
 429 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 430
 431 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
 432 a mail: <mika@grml.org>
 433
 434 Download / install grml-live as a Debian package
 435 ------------------------------------------------
 436
 437 Debian packages are available through the grml-repository at
 438 link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org].  If you want to
 439 build a Debian package on your own (using for example a specific version or the
 440 current development tree), just execute:
 441
 442   hg clone http://hg.grml.org/grml-live
 443   cd grml-live
 444   debuild -us -uc
 445
 446 Source
 447 ------
 448
 449 The source of grml-live is available at
 450 link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
 451
 452 TODO list
 453 ---------
 454
 455 Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
 456 for details.
 457
 458 Bugs
 459 ----
 460
 461 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 462 link:http://grml.org/contact/[to the grml-team]!
 463
 464 Authors
 465 -------
 466 Michael Prokop <mika@grml.org>.
 467
 468 /////////////////////////////////////
 469 // vim:ai tw=80 ft=asciidoc expandtab
 470 /////////////////////////////////////