Synopsis
--------
-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]
+grml-live [-a <architecture>] [-c <classe[s]>] [-C <configfile>] [-g
+<grml_name>] [-i <iso_name> ] [-o <output_directory>] [-r <release_name>] [-s
+<suite>] [-t <template_directory>] [-v <version_number>] [-bBFhquVz]
-*******************************************************************************
-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.
-*******************************************************************************
+CAUTION: Please check out <<current_state,the 'Current state of grml-live with
+squashfs-tools and kernel' section>> for details about current state of involved
+tools before starting with grml-live or if you encounter any problems.
Description
-----------
-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
+allows building a 32bit system on a 64bit host (though you can't build a 64bit
+system on a 32bit system/kernel of course). 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.
+nature and the need of working in a chroot. Currently supported values: i386
+and amd64.
+
+ -b::
+
+Build the ISO without updating the chroot via FAI. This option is useful for
+example when working on stable releases: if you have a working base
+system/chroot and do not want to execute any further updates (via "-u" option)
+but intend to only build the ISO.
+
+ -B::
+
+Build the ISO without touching the chroot at all. This option is useful if
+you modified anything that FAI or grml-live might adjust via grml's FAI
+scripts. It's like the '-b' option but even more advanced. Use only if you
+really know that you do not want to update the chroot.
-c **CLASSES**::
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.
+<<classes,the 'CLASSES' section in this document>> for details about available classes).
+So instead of GRML_SMALL you can also use GRML_MEDIUM and GRML_FULL.
+
+ -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.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.
-F::
-g **GRML_NAME**::
Set the grml flavour name. Common usage examples: grml, grml-small, grml64.
+Please do NOT use blanks and any special characters like '/', ';' inside
+GRML_NAME, otherwise you might notice problems with booting.
-h::
ISO are located, including the compressed squashfs file), grml_chroot (the
chroot system) and grml_isos (where the resulting ISO is stored).
+ -q::
+
+Build the ISO without (re-)creating the squashfs compressed file using mksquashfs.
+This option is useful if you just want to update parts outside the chroot in the ISO.
+Consider combining this option with the build-only option '-b'.
+
-r **RELEASENAME**::
Specify name of the release.
-t **TEMPLATE_DIRECTORY**::
-Specify place of the templates used for building the ISO. By default
+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::
Increase verbosity in the build process.
+ -z::
+
+Use ZLIB instead of LZMA compression in mksquashfs part of the build process.
+
Usage examples
--------------
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 -o /home/mika/grml-live
+ # grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
+
+To get a medium sized, Debian-unstable and grml-based Live-CD for i386
+architecture using /grml/grml-live as build and output directory just run:
+
+ # grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
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
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_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 of grml-live
More details regarding the class concept can be found in the documentation of
FAI itself (being available at /usr/share/doc/fai-doc/).
+[[X7]]
+[[classes]]
Available classes
-----------------
-Documentation to be done...
+The package selection part of the classes can be found in
+/etc/grml/fai/config/package_config whereas some further classes are defined for
+example in /etc/grml/fai/config/scripts/ so specific feature sets can be
+selected. The following classes are predefined:
+
+* DEBORPHAN: get rid of all packages listed in output of Deborphan
+
+* GRMLBASE: the main class responsible for getting a minimal subset of what's
+defining a grml system. Important parts of the buildprocess are specified in
+this class as well, so unless you have a really good reason you should always
+use this class.
+
+* GRML_FORENSIC: tools for forensic investigations which has been created
+by people from link:http://www.forensic-geeks.org/[forensic-geeks.org].
+
+* GRML_FULL: full featured grml, also known as the "normal", full grml.
+
+* GRML_MEDIUM: medium sized grml version, known as grml-medium
+
+* GRML_POWERPC: grml for PowerPC architecture, not supported yet (still work in
+progress)
+
+* GRML_SMALL: minimum sized grml version, known as grml-small
+
+* LATEX_CLEANUP: get rid of several very large LaTeX directories
+(like some /usr/share/doc/texlive-*, /usr/share/doc/texmf,...)
+
+* LOCALES: use full featured locales setup (see /etc/locale.gen.grml). This
+avoids to get rid of /usr/share/locale - which happens by default otherwise - as
+well.
+
+* NO_ONLINE: do not run scripts during the chroot build process which require a
+network connection
+
+* RELEASE: run some specific scripts and commands to provide the workflow for an
+official grml release
+
+* REMOVE_DOCS: get rid of documentation directories (like /usr/share/doc,
+/usr/share/man/, /usr/share/info,...)
+
+* XORG: providing important packages for use with a base grml-featured X.org
+setup
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 a new
+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/dirinstall/$HOSTNAME - so the
-default being /var/log/fai/dirinstall/grml.
+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 update option of grml-live (option -u) the logs are
-available at /var/log/fai/current.
+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
---------------------------------
* fast network access for retreiving the Debian packages used for creating the
chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far
-as possiblbe)
+as possible)
+
+For further information see next section.
+
+[[X8]]
+[[current_state]]
+Current state of grml-live with squashfs-tools and kernel
+---------------------------------------------------------
+
+To make it easier to track problems this section documents current state of
+grml-live playing together with squashfs-tools / squashfs-lzma-tools (for
+building the compressed file) and the kernel version. Documentation of this
+section is up2date by 02nd of december 2008, please report any bugs you
+encounter.
+
+System
+~~~~~~
+
+* grml-live, version 0.9.6
+
+* building grml-medium (Debian/unstable)
+
+* software versions used in the ISO (being installed automatically, recorded
+just as a reference):
+
+ ii busybox 1:1.10.2-2 Tiny utilities for small and embedded systems
+ ii initramfs-tools 0.92f.grml01 tools for generating an initramfs
+ ii klibc-utils 1.5.12-2 small utilities built with klibc for early boot
+ ii live-initramfs 1.139.1-4grml.03 Debian Live initramfs hook
+ ii lvm2 2.02.39-2 The Linux Logical Volume Manager
+ ii mdadm 2.6.7.1-1 tool to administer Linux MD arrays (software RAID)
+ ii udev 0.125-6grml0 /dev/ and hotplug management daemon
+
+Using squashfs-lzma-tools 3.3-1 on the build system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+squashfs-lzma-tools from the grml repository supports kernel 2.6.26-grml[64]
+(version >=grml.05) using both lzma and zlib (-nolzma) compression. It's the
+recommended package for building ISOs with grml-live currently!
+
+The packages can be downloaded from
+link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/].
+
+[NOTE]
+Please use squashfs-lzma-tools 3.3-1 if you want to remaster release 2008.11 of grml.
+
+Using squashfs-tools 1:3.3-7 on the build system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+squashfs-tools 1:3.3-7 is available via Debian/unstable and Debian/testing
+(lenny) pool running:
+
+ # aptitude install squashfs-tools=1:3.3-7
+
+or directly via downloading the files
+http://grml.org/squashfs/squashfs-tools_3.3-7_i386.deb (for x86) or
+http://grml.org/squashfs/squashfs-tools_3.3-7_amd64.deb (for amd64) [both build
+on and for Debian/etch but working with testing and unstable as well].
+
+Please notice that squashfs-tools 1:3.3-7 does NOT support LZMA compression
+at all (so you won't be able to remaster release 2008.11 for example). The
+-nolzma option of mksquashfs is not available therefore (even though
+grml-live will deactivate it for you automatically anyway). Please use
+squashfs-lzma-tools instead.
+
+* Kernel 2.6.23-grml: does NOT work, please use squashfs-tools 1:3.2r2-9exp1
+ instead if you still want to use kernel 2.6.23
+* Kernel 2.6.26-grml: works (without LZMA compression of course!)
+
+Using squashfs-tools 1:3.2r2-9exp1 on the build system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+squashfs-tools 1:3.2r2-9exp1 is available via the grml-testing repository,
+running:
+
+ # aptitude install squashfs-tools=1:3.2r2-9exp1
+
+or directly via downloading the files
+http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_i386.deb (for x86) or
+http://grml.org/squashfs/squashfs-tools_3.2r2-9exp1_amd64.deb (for amd64).
+
+Versions with ZLIB compression (SQUASHFS_OPTIONS='-nolzma' or -z
+option in grml-live cmdline):
+
+* Kernel 2.6.23-grml: works
+* Kernel 2.6.26-grml: works
+
+Versions with LZMA compression:
+
+* Kernel 2.6.23-grml: works
+* Kernel 2.6.26-grml: does NOT work, please use zlib mode instead or switch
+ to Debian package squashfs-lzma-tools (see section above).
FAQ
---
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.8_all.deb \
+ http://www.informatik.uni-koeln.de/fai/download/etch/fai-server_3.2.8_all.deb \
+ http://www.informatik.uni-koeln.de/fai/download/etch/fai-doc_3.2.8_all.deb
+ dpkg -i fai-client_3.2.8_all.deb fai-server_3.2.8_all.deb fai-doc_3.2.8_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
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
+ git clone git://git.grml.org/grml-live
cd grml-live
debuild -us -uc
------
The source of grml-live is available at
-link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
+link:http://git.grml.org/?p=grml-live.git[http://git.grml.org/?p=grml-live.git]
TODO list
---------
-Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live@grml-wiki]
+Check out link:http://wiki.grml.org/doku.php?id=grml-live[grml-live in the grml-wiki]
for details.
Bugs
Authors
-------
-Michael Prokop <mika@grml.org>.
+Michael Prokop <mika@grml.org>
/////////////////////////////////////
// vim:ai tw=80 ft=asciidoc expandtab
projects / grml-live.git / blobdiff