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