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