Update reference to TODO file in grml-live.txt

[grml-live.git] / docs / grml-live.txt

diff --git a/docs/grml-live.txt b/docs/grml-live.txt
index 85e8acf..54d15d2 100644 (file)
--- a/docs/grml-live.txt
+++ b/docs/grml-live.txt
@@ -89,18 +89,18 @@ So instead of GRML_MEDIUM you can also use GRML_SMALL and GRML_FULL.
   -C **CONFIGURATION_FILE**::
 
 The specified file is used as configuration file for grml-live. By default
   -C **CONFIGURATION_FILE**::
 
 The specified file is used as configuration file for grml-live. By default

-/etc/grml/grml-live.conf is used for main configuration. If a file named
+/etc/grml/grml-live.conf is used as default configuration. If a file named

 /etc/grml/grml-live.local exists it is used as well (sourced after reading
 /etc/grml/grml-live.local exists it is used as well (sourced after reading

-/etc/grml/grml-live.conf to allow overriding settings). As a last option the
-specified configuration file is sourced so it is possible to override settings
-of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local. Please
-notice that all configuration files have to be adjusted during execution of
-grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
-your own configuration file. Please also notice that the configuration file
-specified via this option is **not** (yet) supported inside the
-scripts/hooks/classes at /etc/grml/fai/config. Instead use
-/etc/grml/grml-live.conf and/or /etc/grml/grml-live.local for configuration
-stuff used inside /etc/grml/fai/config.
+/etc/grml/grml-live.conf meant as main file for local configuration). As a last
+option the specified configuration file is sourced so it is possible to override
+settings of /etc/grml/grml-live.conf as well as of /etc/grml/grml-live.local.
+Please notice that all configuration files have to be adjusted during execution
+of grml-live, so please make sure you use /etc/grml/grml-live.conf as a base for
+your own configuration file (usually /etc/grml/grml-live.local). Please also
+notice that the configuration file specified via this option is **not** (yet)
+supported inside the scripts/hooks/classes at /etc/grml/fai/config. Instead use
+/etc/grml/grml-live.local for configuration stuff used inside
+/etc/grml/fai/config.

 
   -F::
 
 
   -F::
 


@@ -121,6 +121,12 @@ Display short usage information and exit.
 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
 by default.
 
 Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
 by default.
 

+  -I **CHROOT_INSTALL**::
+
+Specify name of source directory which provides files that should become part of
+the chroot/ISO. Not enabled by default. Note: the files are installed under '/'
+in the chroot so you have to create the rootfs structure on your own.
+

   -o **OUTPUT_DIRECTORY**::
 
 Main output directory of the build process of FAI.  Some directories are created
   -o **OUTPUT_DIRECTORY**::
 
 Main output directory of the build process of FAI.  Some directories are created


@@ -143,7 +149,7 @@ Specify name of the release.
 Specify the Debian suite you want to use for your live-system.  Defaults to
 "lenny" (being current Debian/stable). Supported values are: etch, lenny, sid.
 Debian "squeeze" (current Debian/testing) requires base.tgz
 Specify the Debian suite you want to use for your live-system.  Defaults to
 "lenny" (being current Debian/stable). Supported values are: etch, lenny, sid.
 Debian "squeeze" (current Debian/testing) requires base.tgz

-(/etc/grml/fai/config/basefiles/....tar.gz) until it's supported by debootstrap.
+(/etc/grml/fai/config/basefiles/....tar.gz) or a recent version of debootstrap.

 
   -t **TEMPLATE_DIRECTORY**::
 
 
   -t **TEMPLATE_DIRECTORY**::
 


@@ -167,6 +173,7 @@ Increase verbosity in the build process.
 
 Use ZLIB instead of LZMA compression in mksquashfs part of the build process.
 
 
 Use ZLIB instead of LZMA compression in mksquashfs part of the build process.
 

+[[usage-examples]]

 Usage examples
 --------------
 
 Usage examples
 --------------
 


@@ -200,6 +207,7 @@ process.  But please be aware of the fact that rebooting your system will result
 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
 
 in an empty /dev/shm, so please use another directory for $CHROOT_OUTPUT,
 $BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
 

+[[main-features]]

 Main features of grml-live
 --------------------------
 
 Main features of grml-live
 --------------------------
 


@@ -216,6 +224,7 @@ Debian repositories
 
 * multi-arch support (work in progress)
 
 
 * multi-arch support (work in progress)
 

+[[class-concept]]

 The class concept
 -----------------
 
 The class concept
 -----------------
 


@@ -242,9 +251,9 @@ files/directories.
 If you want to use your own configuration, extend an existing configuration
 and/or add additional packages to your ISO just invent a new class (or extend an
 existing one). For example if you want to use your own class named "FOOBAR" just
 If you want to use your own configuration, extend an existing configuration
 and/or add additional packages to your ISO just invent a new class (or extend an
 existing one). For example if you want to use your own class named "FOOBAR" just

-extend CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.conf to
-CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" or invoke grml-live using the classes
-option: "grml-live -c GRMLBASE,GRML_SMALL,I386,FOOBAR ...".
+set CLASSES="GRMLBASE,GRML_SMALL,I386" inside /etc/grml/grml-live.local or
+invoke grml-live using the classes option: "grml-live -c
+GRMLBASE,GRML_SMALL,I386,FOOBAR ...".

 
 More details regarding the class concept can be found in the documentation of
 FAI itself (being available at /usr/share/doc/fai-doc/).
 
 More details regarding the class concept can be found in the documentation of
 FAI itself (being available at /usr/share/doc/fai-doc/).


@@ -300,6 +309,7 @@ official grml release
 * XORG: providing important packages for use with a base grml-featured X.org
 setup
 
 * XORG: providing important packages for use with a base grml-featured X.org
 setup
 

+[[files]]

 Files
 -----
 
 Files
 -----
 


@@ -318,8 +328,17 @@ Script for the main build process. Requires root permissions for execution.
 
   /etc/grml/grml-live.conf
 
 
   /etc/grml/grml-live.conf
 

-Main configuration file for grml-live. All the important steps can be configured
-at this stage.
+Main configuration file for grml-live which should be considered as a reference
+configuration file only. Please use /etc/grml/grml-live.local for local
+configuration instead.
+
+  /etc/grml/grml-live.local
+
+All the local configuration should go to this file. This file overrides any
+defaults of grml-live. Configurations via /etc/grml/grml-live.local are prefered
+over the ones from /etc/grml/grml-live.conf. If you want to override settings
+from /etc/grml/grml-live.local as well you have to specify them on the grml-live
+commandline.

 
   /etc/grml/fai/fai.conf
 
 
   /etc/grml/fai/fai.conf
 


@@ -395,6 +414,7 @@ files please refer to the source of the scripts.
 This directory provides the files used for building the initramfs/initrd via
 live-initramfs(8).
 
 This directory provides the files used for building the initramfs/initrd via
 live-initramfs(8).
 

+[[log-files]]

 Available log files
 -------------------
 
 Available log files
 -------------------
 


@@ -409,6 +429,7 @@ default being /var/log/fai/grml/.
 If you are using the grml-live buildd you will find the logs of the grml-live
 run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
 
 If you are using the grml-live buildd you will find the logs of the grml-live
 run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
 

+[[requirements]]

 Requirements for the build system
 ---------------------------------
 
 Requirements for the build system
 ---------------------------------
 


@@ -508,6 +529,7 @@ Using with LZMA compression:
 * Kernel 2.6.28-grml: does NOT work, please use zlib mode instead or switch
   to Debian package squashfs-lzma-tools (see section above).
 
 * Kernel 2.6.28-grml: does NOT work, please use zlib mode instead or switch
   to Debian package squashfs-lzma-tools (see section above).
 

+[[faq]]

 FAQ
 ---
 
 FAQ
 ---
 


@@ -577,6 +599,8 @@ Instructions
   # consider using lzma only for space reasons (resulting in longer
   # build time but smaller ISO):
   SQUASHFS_OPTIONS="-nolzma"
   # consider using lzma only for space reasons (resulting in longer
   # build time but smaller ISO):
   SQUASHFS_OPTIONS="-nolzma"

+  # install local files into the chroot
+  CHROOT_INSTALL="/etc/grml/fai/chroot_install"

   ## adjust if necessary (defaults to /grml/grml-live):
   ## OUTPUT="/srv/grml-live"
   FAI_DEBOOTSTRAP="squeeze http://ftp.de.debian.org/debian/"
   ## adjust if necessary (defaults to /grml/grml-live):
   ## OUTPUT="/srv/grml-live"
   FAI_DEBOOTSTRAP="squeeze http://ftp.de.debian.org/debian/"


@@ -609,6 +633,7 @@ worked as expected the last line of the shell output should look like:
 
 and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.
 
 
 and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.
 

+[[fai-on-etch]]

 Help, I'm using Debian etch and I don't have FAI version >3.2
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Help, I'm using Debian etch and I don't have FAI version >3.2
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -620,18 +645,39 @@ Help, I'm using Debian etch and I don't have FAI version >3.2
 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
 further details.
 
 or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
 further details.
 

+[[how-to-debug]]

 I've problems with the build process. How to start debugging?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 I've problems with the build process. How to start debugging?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-Check out the logs inside /var/log/fai/... If you don't have the time to debug
-the problem in further detail or don't know how to proceed just send a copy of
-your config, logs and the commandline with a short problem description to
-<mika@grml.org>:
+Check out the logs inside /var/log/fai/... If you think it's a bug in grml-live
+send a copy of your config, logs and the commandline with a short problem
+description to <mika@grml.org>:

 
   # history | grep grml-live > /etc/grml/grml_live.cmdline
   # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
             /etc/grml/grml-buildd.conf /var/log/fai /etc/grml/fai
 
   # history | grep grml-live > /etc/grml/grml_live.cmdline
   # tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
             /etc/grml/grml-buildd.conf /var/log/fai /etc/grml/fai

+  -> finally mail grml_live_problem.tar.gz to <mika@grml.org>
+
+If you need help with grml-live or would like to see new features as part of
+grml-live you can get commercial support via
+link:http://grml-solutions.com/[Grml Solutions].
+
+[[install-local-files]]
+How to I install further files into the chroot/ISO?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just point the configuration variable CHROOT_INSTALL to the directory which
+provides the files you would like to install. Note that the files are installed
+under '/' in the chroot - so you have to create the rootfs structure on your
+own. Usage example:
+
+  echo "CHROOT_INSTALL=\$GRML_FAI_CONFIG/chroot_install" >> /etc/grml/grml-live.local
+  mkdir -p /etc/grml/fai/chroot_install/usr/src/
+  wget example.org/foo.tar.gz
+  mv foo.tar.gz /etc/grml/fai/chroot_install/usr/src/
+  grml-live ...

 
 

+[[local-debian-mirror]]

 Can I use my own (local) Debian mirror?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Can I use my own (local) Debian mirror?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -654,6 +700,7 @@ taken as first entry in the generated sources.list so it's prefered over
 non-local mirrors. Using a fallback mirror (via providing several mirrors in
 GRML_LIVE_SOURCES as used by default) is a recommended setting.
 
 non-local mirrors. Using a fallback mirror (via providing several mirrors in
 GRML_LIVE_SOURCES as used by default) is a recommended setting.
 

+[[add-additional-debian-packages]]

 How do I add additional Debian package(s) to my CD/ISO?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 How do I add additional Debian package(s) to my CD/ISO?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -671,6 +718,7 @@ and specify it when invoking grml-live then:
 
   # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
 
 
   # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
 

+[[reset-grml-live-configuration]]

 I fscked up my grml-live configuration. How do I reset it to the defaults?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 I fscked up my grml-live configuration. How do I reset it to the defaults?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -687,6 +735,7 @@ good chance to start using it now. Check out
 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/]
 for more details how to maintain /etc using the mercurial VCS.
 
 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/]
 for more details how to maintain /etc using the mercurial VCS.
 

+[[create-a-base-tgz]]

 How do I create a base.tgz for use as NFSROOT?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 How do I create a base.tgz for use as NFSROOT?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -727,6 +776,7 @@ or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
   /grml-live/grml-live_20071029.22138/grml_chroot//
   [...]
 
   /grml-live/grml-live_20071029.22138/grml_chroot//
   [...]
 

+[[apt-cacher]]

 Set up apt-cacher / apt-cacher-ng for use with grml-live
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Set up apt-cacher / apt-cacher-ng for use with grml-live
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -747,6 +797,7 @@ Make sure apt-cacher / apt-cacher-ng is running ('/etc/init.d/apt-cacher
 restart' or '/etc/init.d/apt-cacher-ng restart'). That's it.  All downloaded
 files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then.
 
 restart' or '/etc/init.d/apt-cacher-ng restart'). That's it.  All downloaded
 files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then.
 

+[[approx]]

 Set up approx for use with grml-live
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Set up approx for use with grml-live
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 


@@ -772,12 +823,14 @@ Configure approx:
 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
 All downloaded files will be cached in /var/cache/approx now.
 
 Don't forget to restart approx (/etc/init.d/approx restart). That's it.
 All downloaded files will be cached in /var/cache/approx now.
 

+[[question]]

 I've a question which isn't answered by this document
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
 a mail: <mika@grml.org>
 
 I've a question which isn't answered by this document
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
 a mail: <mika@grml.org>
 

+[[download]]

 Download / install grml-live as a Debian package
 ------------------------------------------------
 
 Download / install grml-live as a Debian package
 ------------------------------------------------
 


@@ -790,24 +843,27 @@ current development tree), just execute:
   cd grml-live
   debuild -us -uc
 
   cd grml-live
   debuild -us -uc
 

+[[source]]

 Source
 ------
 
 The source of grml-live is available at
 link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git]
 
 Source
 ------
 
 The source of grml-live is available at
 link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git]
 

+[[todo-list]]

 TODO list
 ---------
 
 TODO list
 ---------
 

-Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live in the grml-wiki]
-for details.
+Check out the link:http://git.grml.org/?p=grml-live.git;a=blob;f=TODO;hb=HEAD[TODO file].

 
 

+[[bugs]]

 Bugs
 ----
 
 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 link:http://grml.org/contact/[to the grml-team]!
 
 Bugs
 ----
 
 Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes
 link:http://grml.org/contact/[to the grml-team]!
 

+[[authors]]

 Authors
 -------
 Michael Prokop <mika@grml.org>
 Authors
 -------
 Michael Prokop <mika@grml.org>