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