X-Git-Url: https://git.grml.org/?p=grml-live.git;a=blobdiff_plain;f=docs%2Fgrml-live.txt;h=77f36973443eaa35b1f6597a5ebbb65d158261a6;hp=f3274bcb309ed2cf580743948d85680ddf64c8e4;hb=edf82cf35340ea8edb115857f378b20acc0cf12b;hpb=4b8ceac23b1c25a0e231a7beeedb43214a402935 diff --git a/docs/grml-live.txt b/docs/grml-live.txt index f3274bc..77f3697 100644 --- a/docs/grml-live.txt +++ b/docs/grml-live.txt @@ -10,15 +10,13 @@ Linux Live system (CD/ISO) Synopsis -------- -grml-live [-a ] [-c ] [-g ] [-i ] -[-o ] [-r ] [-s ] [-t -] [-v ] [-FVhu] +grml-live [-a ] [-c ] [-C ] [-g +] [-i ] [-o ] [-r ] [-s +] [-t ] [-v ] [-bBFhquVz] -******************************************************************************* -Important! This document is growing as requested. If you have questions which -aren't answered by this document yet please let me know: ! -This document currently applies to grml-live version 0.0.6. -******************************************************************************* +CAUTION: Please check out <> for details about current state of involved +tools before starting with grml-live or if you encounter any problems. Description ----------- @@ -58,9 +56,25 @@ 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 +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**:: @@ -69,8 +83,24 @@ 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. +<> 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:: @@ -79,6 +109,8 @@ 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. +Please do NOT use blanks and any special characters like '/', ';' inside +GRML_NAME, otherwise you might notice problems with booting. -h:: @@ -96,6 +128,12 @@ 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). + -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. @@ -107,7 +145,7 @@ Specify the Debian suite you want to use for your live-system. Defaults to -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:: @@ -123,6 +161,10 @@ Specify version number of the release. Increase verbosity in the build process. + -z:: + +Use ZLIB instead of LZMA compression in mksquashfs part of the build process. + Usage examples -------------- @@ -134,7 +176,12 @@ as build and output directory just run: 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 @@ -148,7 +195,7 @@ If you have about 700MB of free space inside /dev/shm (being a tmpfs, usually 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 @@ -200,10 +247,53 @@ 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/). +[[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 ----- @@ -304,14 +394,11 @@ 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 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. - -If you are using the update option of grml-live (option -u) the logs are -available at /var/log/fai/current. +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. @@ -331,7 +418,98 @@ total free disk space * 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 --- @@ -339,9 +517,10 @@ 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. @@ -349,14 +528,14 @@ 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 : +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 +: # 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -511,7 +690,7 @@ link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org]. If you want to 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 @@ -519,12 +698,12 @@ Source ------ 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 @@ -535,7 +714,7 @@ link:http://grml.org/contact/[to the grml-team]! Authors ------- -Michael Prokop . +Michael Prokop ///////////////////////////////////// // vim:ai tw=80 ft=asciidoc expandtab