Name
----
-grml-live - build process script for generating a (grml based) Linux Live-ISO
+
+grml-live - build framework for generating a grml and Debian based Linux Live
+system (CD/ISO)
Synopsis
--------
+
grml-live [-c <classe[s]>] [-t <target_directory>] [-F] [-h|--help]
*******************************************************************************
-Important! grml-live is under heavy construction, your feedback is highly
+Important! grml-live is under heavy construction, though your feedback is highly
appreciated. This document is growing as requested. If you have questions which
-aren't answered by this document yet please let me (mika@grml.org) know!
+aren't answered by this document yet please let me know: <mika@grml.org>!
*******************************************************************************
Description
-----------
-grml-live provides the build system for creating (a grml based) live-cd. The
-build system is based on link:http://www.informatik.uni-koeln.de/fai/[FAI]
-(Fully Automatic Installation).
+grml-live provides the build system for creating a grml and Debian based Linux
+live-cd. The build system is based on
+link:http://www.informatik.uni-koeln.de/fai/[FAI] (Fully Automatic
+Installation). grml-live uses the "fai dirinstall" feature to generate a chroot
+system based on the class concept of FAI (see later section for further details)
+and provides all the details to be able to generate a full-featured ISO. It does
+not use all the FAI features by default though and you don't have to know FAI to
+be able to use it.
-FAI uses a class based system. This gives you the flexibility to choose the
+The use of FAI behind the curtains gives you the flexibility to choose the
packages you would like to include on your very own Linux live-cd without having
to deal with all the details of a build process.
-CAUTION: grml-live does not use /etc/fai for configuration but instead provides
-and uses /etc/grml/fai. This ensures that it does not clash with default FAI
-configuration and packages, so you can use grml-live and FAI completely
-independent!
+CAUTION: grml-live does **not** use /etc/fai for configuration but instead
+provides and uses /etc/grml/fai. This ensures that it does not clash with
+default FAI configuration and packages, so you can use grml-live and FAI
+completely independent at the same time!
[NOTE]
+
Please notice that you should have a fast network connection as all the Debian
packages will be installed via network. If you want to use a local mirror
-(strongly recommended!) checkout
-mkdebmirror (see /usr/share/doc/grml-live/examples/mkdebmirror)
-debmirro(1) and reprepro(1) (check out
-/usr/share/doc/grml-live/examples/reprepro/ for a sample configuration).
-To avoid downloading of the base system check out FAI's
-NFSROOT (check docs for ../fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz).
+(strongly recommended!) 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 of the base system check out FAI's NFSROOT (check
+docs for ../fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz).
Options
-------
-c **CLASSES**::
-Specify the CLASSES to be used for building the ISO via fai.
-By default only the class GRML is assumed, resulting in a small base system (being
-about ~170MB ISO size).
+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 ISO size).
+
+ -s **SUITE**::
+
+Specify the Debian suite you want to use for your live-system. Defaults to
+"etch"; support values are: etch, lenny, sid, stable, testing, unstable.
-t **TARGET_DIRECTORY**::
-Output directory of the build process of FAI - being the chroot
-used for building the ISO.
+Main output directory of the build process of FAI. Three directories are
+created inside the target directory, being: grml_cd/ - where the files for
+creating the ISO are located (including the compressed squashfs file),
+grml_chroot/ - the generated chroot system and grml_isos/ - where the resulting
+ISO is stored.
-F::
-Force execution and do not display summary of configuration details.
+Force execution and do not prompt for / display summary of configuration
+details.
- -h|--help::
+ -h::
Display short usage information and exit.
- additional_arguments_for_fai::
+ -v::
-Any additional argument(s) to grml-live will be given to the FAI commandline
-(being basically "fai dirinstall ...). This might become a temporary solution
-(due to security reasons), if you need an option please let us know so we can
-implement it.
+Increase verbosity in the build process.
How to get your own live-cd - the easy, fast and simple way
-----------------------------------------------------------
-To get a small, Debian-stable and grml based live-cd:
+To get a small, Debian-stable and grml based live-cd using /grml/grml-live
+as build and output directory:
+
+ # grml-live
+
+To get a small Debian-unstable and grml-small based live-cd using
+/home/mika/grml-live as build and output directory:
+
+ # grml-live -c GRMLBASE,GRML_SMALL,I386 -t /home/mika/grml-live
+
+[NOTE]
+
+If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually
+you 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. :)
+
+Features
+--------
+
+* create a grml-/Debian-based Linux Live-CD with one single command
+
+* class based concept, providing a maximum of flexibility
+
+* supports integration of own hooks, scripts and configuration
- # TARGET="/grml/grml_uncompressed"
- # CDDIR="/grml/grml_cd"
- # grml-live -c GRML -t $TARGET
- # mksquashfs $TARGET/* $CDDIR/live/grml.squashfs -noappend
- # cd $CDDIR
- # mkisofs -V "my personal grml" -l -r -J -no-emul-boot -boot-load-size 4 \
- -boot-info-table -c boot/isolinux/boot.cat \
- -b boot/isolinux/isolinux.bin -o /grml/grml.iso .
+* supports use and integration of own Software and/or Kernels via use of Debian
+repositories
-(TODO: provide the content of /grml/chroot/grml_cd through the package
-grml-live, in the meanwhile get the content from a current grml-ISO)
+* native support of FAI features
+
+* multi-arch support (work in progress)
The class concept
-----------------
according to your needs. This gives you flexibility and strength without losing
the simplicity in the build process.
-The main and base class provided by grml-live is named GRML. It's strongly
-recommended to **always** use the class GRML when building an ISO using
-grml-live. The following files and directories are relevant for class GRML by
-default:
+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 (being 'I386' for x86_32
+currently only). The following files and directories are relevant for class GRML
+by default:
- /etc/grml/fai/config/scripts/GRML/
- /etc/grml/fai/config/debconf/GRML
- /etc/grml/fai/config/class/GRML.var
- /etc/grml/fai/config/hooks/instsoft.GRML
- /etc/grml/fai/config/package_config/GRML
+ /etc/grml/fai/config/scripts/GRMLBASE/
+ /etc/grml/fai/config/debconf/GRMLBASE
+ /etc/grml/fai/config/class/GRMLBASE.var
+ /etc/grml/fai/config/hooks/instsoft.GRMLBASE
+ /etc/grml/fai/config/package_config/GRMLBASE
Take a look at the next section for information about the concept of those
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. For example
-if you want to use your own class named "FOOBAR" just extend CLASSES="GRML" inside
-/etc/grml/grml-live.conf to CLASSES="GRML,FOOBAR" or invoke grml-live using
-the classes option: "grml-live -c GRML,FOOBAR ...".
+if you want to use your own class named "FOOBAR" just extend CLASSES="GRMLBASE"
+inside /etc/grml/grml-live.conf to CLASSES="GRMLBASE,FOOBAR" or invoke grml-live
+using the classes option: "grml-live -c GRMLBASE,FOOBAR ...".
More details regarding the class concept can be found in the documentation of
FAI (available at /usr/share/doc/fai-doc/).
/etc/grml/fai/make-fai-nfsroot.conf
-TODO
+TODO: documentation
/etc/grml/fai/NFSROOT
-TODO
+TODO: documentation
/etc/grml/fai/apt/sources.list
File with lists of software packages to be installed or removed. The different
classes describe what should find its way to your ISO. When running 'fai -v -C
-/etc/grml/fai -cGRML dirinstall ...' only the files from the directory GRML/
-will be taken, if you use 'fai -v -C /etc/grml/fai -cGRML,FOOBAR dirinstall ...'
-then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So just
-create a new class to adjust it to your needs. Please notice that the directory
-GRML contains a package list defining a minimum but still reasonable package
-configuration.
+/etc/grml/fai -cGRMLBASE dirinstall ...' only the files from the directory GRML/
+will be taken, if you use 'fai -v -C /etc/grml/fai -cGRMLBASE,FOOBAR dirinstall
+...' then the files of GRML/ **plus** the files from FOOBAR/ will be taken. So
+just create a new class to adjust it to your needs. Please notice that the
+directory GRML contains a package list defining a minimum but still reasonable
+package configuration.
/etc/grml/fai/config/scripts/
Scripts for customising the ISO within build process.
+ /etc/grml/fai/files/
+
+This directory provides files used inside the scripts of
+/etc/grml/fai/config/scripts/*. For a full documentation what happens with the
+files please refer to the source of the scripts.
+
/etc/grml/fai/live-initramfs/
This directory provides the files used for building the initramfs/initrd via
* any Debian based system should be sufficient (if not please send a bug
report), for example a grml2hd harddisk installation ships all you need
-* enough free disk space, at least 1GB are required for a minimal grml-live run
+* 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
+temporary files)
* 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
Known TODOs
-----------
-* extend the grml-live wrapper script so it runs all the necessary command in a
-single run (boot/isolinux, mksquashfs and mkisofs stuff is missing currently)
+* document the available classes in more detail
+
+* make sure $TARGET is mounted rw,suid,dev
+
+* write a step-by-step guide **how** to adjust **what** at **which** place
+
+* 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)
+
+* support different grml-flavours through classes right out-of-the-box (being:
+grml, grml64, grml-small (done) for at least x86, amd64 and ppc)
+
+* support signed apt repositories (currently it's deactivated via FAI's
+FAI_ALLOW_UNSIGNED=1 for some packages in the toolchain)
+
+* explain (and provide configuration for) use of NFSROOT
+
+* support setting stuff like ISO name, version,... on-the-fly (especially for
+stuff inside boot/isolinux/*)
+
+* support "final builds" (including stuff like generating md5sums, gpg,... -
+create something like grml_release including all the details about the build
+like dpkg selection, logs,...)
+
+* the grml-live class(es) should send output as used inside FAI as well (so it's
+not as verbose unless you specify it, make it configurable)
+
+* provide possibility for cleanup of all created build directories and
+a smart summary of the buildprocess (including "took ... minutes/seconds to
+build...)
+
+* support hooks to allow further customisation of the build process
+
+Debian package
+--------------
-* really support signed apt repositories
+Debian packages will be available through the grml-repository at
+link:http://deb.grml.org/[http://deb.grml.org/] as soon as the grml-team
+considers grml-live as stable enough. In the meantime just build the package on
+your own:
-* explain (and provide configuration for) the use of NFSROOT
+ hg clone http://hg.grml.org/grml-live
+ cd grml-live
+ debuild -us -uc
-* support setting stuff like ISO name, version,...
+Source
+------
-* support different flavours and architectures of Debian (currently it defaults
-to Debian/stable x86_32)
+The source of grml-live is available at
+link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/]
Bugs
----
-------
Michael Prokop <mika@grml.org>.
+/////////////////////////////////////
+// vim:ai tw=80 ft=asciidoc expandtab
+/////////////////////////////////////
projects / grml-live.git / blobdiff