Synopsis
--------
-grml-live [-c <classe[s]>] [-i <iso_name> ] [-r <release_name>]
-[-s <suite>] [-t <target_directory>] [-v <version_number>] [-Fvh]
+grml-live [-a <architecture>] [-c <classe[s]>] [-g <grml_name>] [-i <iso_name> ]
+[-o <output_directory>] [-r <release_name>] [-s <suite>] [-t
+<template_directory>] [-v <version_number>] [-FVhu]
*******************************************************************************
Important! This document is growing as requested. If you have questions which
aren't answered by this document yet please let me know: <mika@grml.org>!
+This document currently applies to grml-live version 0.0.6.
*******************************************************************************
Description
local mirror (strongly recommended if you plan to use grml-live more than once)
checkout mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror),
debmirror(1), reprepro(1) (see /usr/share/doc/grml-live/examples/reprepro/ for a
-sample configuration) and approx(8). To avoid downloading the base system again
-and again check out FAI's NFSROOT (see FAQ of this document for details).
+sample configuration), apt-cacher(1) and approx(8). To avoid downloading the
+base system again and again check out FAI's NFSROOT (see FAQ of this document
+for details).
Options
-------
+ -a **ARCHITECTURE**::
+
+Use the specified architecture instead of the currently running one. This
+allows building a 32bit system on a 64bit host. Please notice that real
+crosscompiling (like building a ppc system on x86) isn't possible due to the
+nature and the need of working in a chroot.
+
-c **CLASSES**::
Specify the CLASSES to be used for building the ISO via FAI. By default only
-the classes GRMLBASE and I386 are assumed, resulting in a small base system
-(being about ~150MB total ISO size) for x86 (32bit).
+the classes GRMLBASE, GRML_SMALL and I386 are assumed, resulting in a small base
+system (being about ~150MB total ISO size). If using a non-I386 system (like
+amd64) you should specify the appropriate architecture as well. Additionally you
+can specify a class providing a grml-kernel (see
+/etc/grml/fai/config/package_config/ for a full list). So instead of GRML_SMALL
+you can also use GRML_MEDIUM and GRML_FULL instead.
-F::
Force execution and do not prompt for acknowledgment of configuration.
+ -g **GRML_NAME**::
+
+Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
+
-h::
Display short usage information and exit.
-i **ISO_NAME**::
-Specify name of ISO which will be available inside $TARGET_DIRECTORY/grml_isos
+Specify name of ISO which will be available inside $OUTPUT_DIRECTORY/grml_isos
by default.
+ -o **OUTPUT_DIRECTORY**::
+
+Main output directory of the build process of FAI. Some directories are created
+inside this target directory, being: grml_cd (where the files for creating the
+ISO are located, including the compressed squashfs file), grml_chroot (the
+chroot system) and grml_isos (where the resulting ISO is stored).
+
-r **RELEASENAME**::
-Specify name of the release. (Notice: the output of the release name is limited
-to 30 characters.)
+Specify name of the release.
-s **SUITE**::
Specify the Debian suite you want to use for your live-system. Defaults to
-"etch" (being current Debian/stable). Supported values are: etch, lenny, sid,
-stable, testing, unstable.
+"etch" (being current Debian/stable). Supported values are: etch, lenny, sid.
- -t **TARGET_DIRECTORY**::
+ -t **TEMPLATE_DIRECTORY**::
-Main output directory of the build process of FAI. Some directories are created
-inside this target directory, being: grml_cd (where the files for creating the
-ISO are located, including the compressed squashfs file), grml_chroot (the
-chroot system) and grml_isos (where the resulting ISO is stored).
+Specify place of the templates used for building the ISO. By default
+(and if not manually specified) this is /usr/share/grml-live/templates/.
+
+ -u::
+
+Update existing chroot instead of rebuilding it from scratch. This option is
+based on the softupdate feature of FAI.
-v **VERSION_NUMBER**::
-Specify version number of the release. (Notice: the output of the version number
-is limited to 5 characters. So "1.0-1" is fine, but "1.0.0.1" will be stripped
-to "1.0.0" then.)
+Specify version number of the release.
-V::
To get a small Debian-unstable and grml-small based Live-CD using
/home/mika/grml-live as build and output directory just use:
- # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
+ # grml-live -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
To get a small, Debian-unstable and grml-based Live-CD using /tmp as build and
output directory and use grml_0.0-3.iso as ISO name (placed inside
/tmp/grml_isos) just invoke:
- # grml-live -t /tmp -c GRMLBASE,I386 -s sid -i grml_0.0-3.iso
+ # grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
[NOTE]
you should have >=1GB of RAM) just run "mount -o remount,suid,dev,rw /dev/shm"
and use /dev/shm as build and output directory - resulting in very fast build
process. But please be aware of the fact that rebooting your system will result
-in an empty /dev/shm, so please another directory for $CHROOT_TARGET,
-$BUILD_TARGET and $ISO_TARGET if you plan to create more persistent output. :)
+in an empty /dev/shm, so please another directory for $CHROOT_OUTPUT,
+$BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :)
Main features of grml-live
--------------------------
The main and base class provided by grml-live is named GRMLBASE. It's strongly
recommended to **always** use the class GRMLBASE when building an ISO using
-grml-live, as well as the architecture dependend class which provides the kernel
-(being 'I386' for x86_32 currently only). The following files and directories
-are relevant for class GRMLBASE by default:
+grml-live, as well as the architecture dependent class which provides the kernel
+(being 'I386' for x86_32 and 'AMD64' for x86_64) and a GRML_* class (like
+GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are
+relevant for class GRMLBASE by default:
/etc/grml/fai/config/scripts/GRMLBASE/
/etc/grml/fai/config/debconf/GRMLBASE
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,I386" inside /etc/grml/grml-live.conf to
-CLASSES="GRMLBASE,I386,FOOBAR" or invoke grml-live using the classes option:
-"grml-live -c GRMLBASE,I386,FOOBAR ...".
+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 ...".
More details regarding the class concept can be found in the documentation of
FAI itself (being available at /usr/share/doc/fai-doc/).
+Available classes
+-----------------
+
+Documentation to be done...
+
Files
-----
Directory with lists of software packages to be installed or removed. The
different classes describe what should find its way to your ISO. When running
-"grml-live -c GRMLBASE,I386 ..." only the files from the directories GRMLBASE
-and I386 will be taken, if you use 'grml-live -c GRMLBASE,I386,FOOBAR ...' then
-the files of GRMLBASE, I386 **plus** the files from FOOBAR will be taken. So
-just create a new class to adjust the package selection according to your needs.
-Please notice that the directory GRMLBASE contains a package list defining a
-minimum but still reasonable package configuration.
+"grml-live -c GRMLBASE,GRML_SMALL,I386 ..." only the configuration of GRMLBASE,
+GRML_SMALL and and I386 will be taken. If you use 'grml-live -c
+GRMLBASE,GRML_SMALL,I386,FOOBAR ...' then the files of GRMLBASE, GRML_SMALL,
+I386 **plus** the files from FOOBAR will be taken. So just create a new class to
+adjust the package selection according to your needs. Please notice that the
+directory GRMLBASE contains a package list defining a minimum but still
+reasonable package configuration.
/etc/grml/fai/config/scripts/
This directory provides the files used for building the initramfs/initrd via
live-initramfs(8).
+Available log files
+-------------------
+
+grml-live itself logs to /var/log/grml-live.log. Unless you set ZERO_LOGFILE in
+/etc/grml/grml-live.conf the output is appended to the file. If you set the
+ZERO_LOGFILE configuration option the logfile will be truncated on each new
+invocation of grml-live.
+
+The FAI part of grml-live logs to /var/log/fai/$HOSTNAME/ - so the
+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.
+
Requirements for the build system
---------------------------------
harddisk installation ships all you need]
* enough free disk space; at least 800MB are required for a minimal grml-live
-run (\~400MB for the chroot [$CHROOT_TARGET], \~150MB for the build target
-[$BUILD_TARGET] and \~150MB for the resulting ISO [$ISO_TARGET] plus some
+run (\~400MB for the chroot [$CHROOT_OUTPUT], \~150MB for the build target
+[$BUILD_OUTPUT] and \~150MB for the resulting ISO [$ISO_OUTPUT] plus some
temporary files), if you plan to use GRML_FULL you should have at least 4GB of
total free disk space
Help, I'm using Debian etch and I don't have FAI version >3.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.1_all.deb \
- http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.1_all.deb
- dpkg -i fai-client_3.2.1_all.deb fai-server_3.2.1_all.deb
+ wget http://www.informatik.uni-koeln.de/fai/download/etch/fai-client_3.2.3_all.deb \
+ http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.3_all.deb \
+ http://www.informatik.uni-koeln.de/fai/download/etch/fai-doc_3.2.3_all.deb
+ dpkg -i fai-client_3.2.3_all.deb fai-server_3.2.3_all.deb fai-doc_3.2.3_all.deb
or check out the link:http://www.informatik.uni-koeln.de/fai/[FAI-homepage] for
further details.
I've problems with the build process. How to start debugging?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Check out the logs inside /var/log/fai/dirinstall/... 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 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>:
# history | grep grml-live > /etc/grml/grml_live.cmdline
# tar zcf grml_live_problem.tar.gz /etc/grml/grml-live.conf \
- /var/log/fai/dirinstall /etc/grml/fai
+ /etc/grml/grml-buildd.conf /var/log/fai /etc/grml/fai
Can I use my own (local) Debian mirror?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(see default configuration) so all the grml packages can be downloaded as well.
If you want to use a local (for example NFS mount) mirror additionally, just
-adjust MIRROR_DIRECTORY and MIRROR_SOURCES insede /etc/grml/grml-live.conf as
+adjust MIRROR_DIRECTORY and MIRROR_SOURCES inside /etc/grml/grml-live.conf as
well.
Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from
and specify it when invoking grml-live then:
- # grml-live -c GRMLBASE,I386,MIKA
+ # grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
I fscked up my grml-live configuration. How do I reset it to the defaults?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mv base.tgz /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz
+or even better use /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz instead.
+Use I386 as $CLASSNAME for i386 builds and AMD64 for amd64 builds.
+
Now running "grml-live ..." will use this file as main system instead of
-executing debootstrap. Check out the output for the following lines:
+executing debootstrap. Check out the output for the following lines if using
+NFSROOT:
[...]
Calling task_extrbase
Calling task_mirror
[...]
-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>
-
-Known TODOs
------------
-
-* the template system isn't flexible enough yet: provide support for different
-flavours, allow longer version number
-
-* support something like a directory /etc/grml/fai/packages to install
-additional Debian packages without the need for a Debian repository
+or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for:
-* provide hooks/options for updating an existing chroot/squashfs-file/ISO
-(work in progress, see patches directory inside source)
-
-* document the available classes in more detail (GRMLBASE, LATEX_CLEANUP,
-NO_ONLINE, REMOVE_DOCS, GRML_SMALL,...)
-
-* add a check to make sure $TARGET is mounted rw,suid,dev?
+ [...]
+ ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
+ /grml-live/grml-live_20071029.22138/grml_chroot//
+ [...]
-* add support for amd64 [gebi?] + ppc [formorer?] (and identify all packages
-that are arch specific so we have a clean package list in all classes)
+Set up apt-cacher for use with grml-live
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* support different grml-flavours through classes right out-of-the-box (being:
-grml and grml-small (done), each for x86, amd64 and ppc)
+Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
+FAI_DEBOOTSTRAP:
-* support signed apt repositories (currently it's deactivated via FAI's
-FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
+ # cat /etc/grml/grml-live.conf
+ [...]
+ GRML_LIVE_SOURCES="
+ deb http://localhost:3142/deb.grml.org grml-stable main
+ deb http://localhost:3142/deb.grml.org grml-testing main
+ deb http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free
+ "
+ [...]
+ FAI_DEBOOTSTRAP="etch http://localhost:3142/ftp.de.debian.org/debian etch main contrib non-free"
-* support "final builds" (including stuff like generating md5sums, gpg,... -
-create a grml_release-directory including all the details about the build
-process like dpkg selection, logs,...)
+Make sure apt-cacher is running (/etc/init.d/apt-cacher restart). That's it.
+All downloaded files will be cached in /var/cache/apt-cacher/ now.
-* the grml-live class(es) should send output to stdout and stderr as used inside
-FAI as well (so it's not as verbose unless you specify it, make it configurable
-though); check for errors inside the logs then as well
+Set up approx for use with grml-live
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* provide possibility for cleanup of all created build directories and
-a smart summary of the buildprocess (including "took ... minutes/seconds to
-build...")
+Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and
+FAI_DEBOOTSTRAP:
-* check out how FAI_DEBMIRROR of /etc/grml/fai/fai.conf could be merged with our
-MIRROR_DIRECTORY and MIRROR_SOURCES feature of /etc/grml/grml-live.conf
+ # cat /etc/grml/grml-live.conf
+ [...]
+ GRML_LIVE_SOURCES="
+ deb http://localhost:9999/grml grml-stable main
+ deb http://localhost:9999/grml grml-testing main
+ deb http://localhost:9999/debian etch main contrib non-free
+ "
+ FAI_DEBOOTSTRAP="etch http://localhost:9999/debian"
-* support hooks to allow further customisation of the build process
+Configure approx:
-Long term goals
----------------
+ # cat /etc/approx/approx.conf
+ [...]
+ debian http://ftp.at.debian.org/debian
+ grml http://deb.grml.org/
-* Provide all upcoming grml releases based on grml-live.
+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.
-* Provide a console interface (using dialog) for easy and common use of
-grml-live.
+I've a question which isn't answered by this document
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* Provide a graphical interface (for example using pygtk) for easy and common
-use of grml-live.
+Don't hesitate to ask on IRC (channel #grml on irc.freenode.org) or just drop me
+a mail: <mika@grml.org>
Download / install grml-live as a Debian package
------------------------------------------------
Debian packages are available through the grml-repository at
link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to
-build a Debian package of the most current version on your own, just execute:
+build a Debian package on your own (using for example a specific version or the
+current development tree), just execute:
hg clone http://hg.grml.org/grml-live
cd grml-live
The source of grml-live is available at
link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
+TODO list
+---------
+
+Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
+for details.
+
Bugs
----
projects / grml-live.git / blobdiff