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