X-Git-Url: https://git.grml.org/?a=blobdiff_plain;f=docs%2Fgrml-live.txt;h=91b40e80f9951a7a5770a1ba1efe6a306fc79406;hb=8ebdabd250a8c349d0832aba0e79f60f3a3ab95c;hp=45c5278fb2cf52cc2a823f69430d109b2b1eddbb;hpb=de6d7ed3e096db257ca1434c895ff69e3b0ef481;p=grml-live.git diff --git a/docs/grml-live.txt b/docs/grml-live.txt index 45c5278..91b40e8 100644 --- a/docs/grml-live.txt +++ b/docs/grml-live.txt @@ -3,44 +3,123 @@ grml-live(8) Name ---- -grml-live - generate a grml (based) live-cd +grml-live - build process script for generating a (grml based) Linux Live-ISO Synopsis -------- -grml-live [ todo...] +grml-live [-c ] [-t ] [-F] [-h|--help] ******************************************************************************* -Important! grml-live is under heavy construction and everything but ready yet. +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! ******************************************************************************* -Introduction ------------- +Description +----------- -grml-live provides the build system for creating a grml (based) live-cd. The +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). If you are familiar with FAI already it is very -easy to get a live-cd, if you don't know FAI yet don't despair: it's still very -easy. :) +(Fully Automatic Installation). FAI uses a class based system. This gives you the flexibility to choose the -packages you would like to include on your very own live-cd without having to -deal with all the details in the core of the system. +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! + +[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), debmirror(1), reprepro(1) (see +/usr/share/doc/grml-live/examples/reprepro/ for a sample configuration) and +approx. 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 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. + + -F:: + +Force execution and do not prompt for / display summary of configuration +details. + + -h:: + +Display short usage information and exit. + + -v:: + +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 /dev/shm/ +as build and output directory: + + # 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. :) + +The class concept +----------------- + +grml-live uses FAI and its class based concept for adjusting configuration +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 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: - # TARGET="/grml/chroot/grml_uncompressed" ; mkdir -p $TARGET - # fai -v -C /etc/grml/fai -cGRML dirinstall $TARGET - # mksquashfs $TARGET/* /grml/chroot/grml_cd/live/grml.squashfs -noappend - # cd /grml/chroot/grml_cd/ - # 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 . + /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 -(TODO: provide the contenct of /grml/chroot/grml_cd through the package -grml-live, in the meanwhil get the content from a current grml-ISO) +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="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/). Files ----- @@ -54,6 +133,11 @@ like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian packa fai-doc). /usr/share/doc/fai-doc/fai-guide.html/ch-config.html also provides documentation regarding configuration possibilities. + /usr/sbin/grml-live + +Script for the main build process (being a wrapper around FAI currently). +Requires root permissions for execution. + /etc/grml/fai/fai.conf Main configuration file which specifies where all the configuration files and @@ -61,6 +145,20 @@ scripts for FAI/grml-live can be found. By default it is FAI_CONFIGDIR=/etc/grml/fai/config, a directory shipped by grml-live out-of-the-box so you shouldn't have to configure anything in this file. + /etc/grml/fai/make-fai-nfsroot.conf + +TODO: documentation + + /etc/grml/fai/NFSROOT + +TODO: documentation + + /etc/grml/fai/apt/sources.list + +This file specifies which mirrors should be used for retreiving the Debian +packages used for creating the ISO. If you want to use a local mirror you have +to adjust this file. + /etc/grml/fai/config/ The main directory for configuration of FAI/grml-live. More details below. @@ -72,7 +170,7 @@ FAI classes. /etc/grml/fai/config/debconf/ -This directory provides the files for presseding/configuration of debconf +This directory provides the files for preseeding/configuration of debconf through files. /etc/grml/fai/config/hooks/ @@ -84,21 +182,101 @@ installation process. /etc/grml/fai/config/package_config/ 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 --cGRML dirinstall ...' only the files from the directory GRML/ will be taken, if -you use 'fai -v -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. +classes describe what should find its way to your ISO. When running 'fai -v -C +/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 +live-initramfs(8). + +Requirements for the build system +--------------------------------- + +* 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 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 +as possiblbe) + +Known TODOs +----------- + +* do not use /dev/shm/ als default target directory (which one do we want to use +instead?) + +* 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 (in progress) 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) + +* explain (and provide configuration for) use of NFSROOT + +* support setting stuff like ISO name, version,... (especially for stuff inside +boot/isolinux/*) + +* support "final builds" (including stuff like generating md5sums, gpg,...) + +* 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 + +* support hooks to allow further customisation of the build process + +Debian package +-------------- + +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: + + hg clone http://hg.grml.org/grml-live + cd grml-live + debuild -us -uc + +Source +------ + +The source of grml-live is available at +link:http://hg.grml.org/grml-live/[http://hg.grml.org/grml-live/] + Bugs ---- -Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes link:http://grml.org/contact/[to us]! + +Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes +link:http://grml.org/contact/[to the grml-team]! Authors ------- Michael Prokop . + +///////////////////////////////////// +// vim:ai tw=80 ft=asciidoc expandtab +/////////////////////////////////////