X-Git-Url: https://git.grml.org/?p=grml-live.git;a=blobdiff_plain;f=docs%2Fgrml-live.txt;h=05e91776a4fe614206aecebe3fe71272adfaa14d;hp=c9c73716dcf44d755569339315972235666e2e53;hb=d039e207a6fea49a966168e7d31487b86840af11;hpb=5bfdcecb4c2ff08416a8c5262efa9bdc814008c2 diff --git a/docs/grml-live.txt b/docs/grml-live.txt index c9c7371..05e9177 100644 --- a/docs/grml-live.txt +++ b/docs/grml-live.txt @@ -10,10 +10,11 @@ Linux Live system (CD/ISO) Synopsis -------- -grml-live [-a ] [-c ] [-C ] [-g -] [-i ] [-o ] [-r ] [-s -] [-t ] [-v ] [-U ] [ --AbBFnNqQuVz] +grml-live [-a ] [-c ] [-C ] [ +-e ] [-g ] [-i ] [ +-o ] [-r ] [-s ] [ +-t ] [-v ] [-U ] [ +-w ] [-AbBFnNqQuVz] Description ----------- @@ -53,8 +54,8 @@ Options -A:: -Clean up output directories before attempting the build. Packs the chroot -into a tar archive, and removes chroot and ISO build directories before exiting. +Clean up all output directories before running the build process. After finishing, +clean up the Chroot target and Build target directories. -a **ARCHITECTURE**:: @@ -83,12 +84,10 @@ really know that you do not want to update the chroot. Specify the CLASSES to be used for building the ISO via FAI. By default only the classes GRMLBASE, GRML_FULL and I386/AMD64 (depending on system -architecture) are assumed, resulting in a base system of about 350MB -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 <> for -details about available classes). So instead of GRML_FULL you can also use -GRML_SMALL and GRML_FULL. +architecture) are assumed. Additionally you can specify a class providing a +(grml-)kernel (see <> for +details about available classes). So instead of GRML_FULL you can also use e.g. +GRML_SMALL. [IMPORTANT] All class names should be written in uppercase letters. Do not use a dash, use @@ -132,6 +131,11 @@ grml-live this option provides you the option to use your own configuration directory. This directory is what's being referred to as ${GRML_FAI_CONFIG} throughout this documentation. + -e **EXTRACT_ISO_NAME**:: + +The squashfs inside the specified ISO will be extracted and used as the chroot. +This option is useful for remastering, in combination with -A and -b or -u. + -F:: Force execution and do not prompt for acknowledgment of configuration. @@ -197,9 +201,10 @@ Specify name of the release. -s **SUITE**:: -Specify the Debian suite you want to use for your live-system. Defaults to -"squeeze" (being current Debian/stable). Supported values are: etch, lenny, -squeeze, sid. Debian "squeeze" requires a recent base.tgz +Specify the Debian suite you want to use for your live-system. If unset defaults +to "testing". Supported values are: stable, testing, unstable (or their +corresponding release names like "jessie"). Please be aware that recent Debian +suites might require a recent base.tgz (${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of debootstrap. @@ -208,11 +213,6 @@ debootstrap. Specify place of the templates used for building the ISO. By default (and if not manually specified) this is /usr/share/grml-live/templates/. - -T **CHROOT_ARCHIVE**:: - -Unpack chroot tar archive before starting. Most useful in combination with --A and -b or -u. - -u:: Update existing chroot instead of rebuilding it from scratch. This option is @@ -230,6 +230,22 @@ Specify version number of the release. Increase verbosity in the build process. + -w **DATE**:: + +The wayback machine. Build the system using Debian archives from the specified +date. Valid date formats are yyyymmddThhmmssZ or simply yyyymmdd. To learn +which snapshots exist, i.e. which date strings are valid, simply browse the +lists on http://snapshot.debian.org/. If there is no import at the exact time +you specified you will get the latest available timestamp which is before the +time you specified. +This option is useful especially for release and debugging builds - for example +if you know that the Debian archive was in a good state on a specific date but +you want to build it on another day in the future, where the archive might not +be as needed anymore. Please be aware that this is restricted to the plain +Debian repositories only, as referred to in /etc/apt/sources.list.d/debian.list +(so neither the Grml repositories nor any further custom ones are affected by +the wayback machine). + -z:: Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process. @@ -238,7 +254,7 @@ Use ZLIB instead of LZMA/XZ compression in mksquashfs part of the build process. Usage examples -------------- -To get a Debian-stable and Grml-based Live-CD using /grml/grml-live +To get a Debian-stable and Grml-based Live-CD using ./grml as build and output directory just run: # grml-live @@ -251,12 +267,10 @@ system: [NOTE] -If you have enough 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 use another directory for $CHROOT_OUTPUT, -$BUILD_OUTPUT and $ISO_OUTPUT if you plan to create more persistent output. :) +If you have enough RAM, just run "mount -t tmpfs none /media/ramdisk" to get a +tmpfs ("RAMDISK"), and use /media/ramdisk as build and output directory - this +results in a very fast build process. Note that these files will be gone when +rebooting. [[main-features]] Main features of grml-live @@ -285,7 +299,7 @@ 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 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 +GRML_SMALL or GRML_FULL). The following files and directories are relevant for class GRMLBASE by default: ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/ @@ -319,23 +333,35 @@ selected. The following classes are predefined: * DEBORPHAN: get rid of all packages listed in output of deborphan +* FILE_RC: instead of using systemd as init system use file-rc instead. file-rc +was the init system used by Grml until and including stable release 2014.11, +starting with beginning of 2016 Grml switched to systemd instead. If you want to +build a live system in the old style using file-rc instead of systemd then enable +this class. Please notice that support for file-rc is no longer being actively +maintained (the Grml team happily accepts patches though) and file-rc (upstream +wise) might disappear too. + +* FRESHCLAM: execute freshclam (if it's present) to update clamav definitions +(increases resulting ISO size ~70MB). By default it's skipped to avoid bigger +ISO size. + * 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. +use this class. Please be aware that using *just* the GRMLBASE class won't be +enough, because the kernel packages (e.g. linux-image-i386-grml + +linux-image-amd64-grml) are chosen in further GRML_* classes (to provide maximum +flexibility with kernel selection). If you don't want to use the existing +GRML_FULL or GRML_SMALL classes, define your own CLASS file choosing the kernel +package you want to use (and don't forget to include your CLASS in the arguments +of grml-live's -c... command line option). * GRML_FULL: full featured Grml, also known as the "normal", full grml as -introduced in December 2011 (~350MB ISO size). +introduced in December 2011 (~600MB ISO size). -* GRML_MEDIUM: medium sized Grml version, used to be known as grml-medium -until December 2011 (~220MB ISO size). - -* GRML_SMALL: minimum sized Grml version, known as grml-small (~110MB ISO +* GRML_SMALL: minimum sized Grml version, known as grml-small (~300MB ISO size). -* GRML_XL: large size Grml version, used to be known as "full grml" until -December 2011 (~700MB ISO size). - * LATEX: LaTeX(-related) packages like auctex, texlive,... (which used to be shipped by grml before the LaTeX removal) @@ -401,16 +427,6 @@ GRML_FAI_CONFIG=/etc/grml/fai/config - both pointing to a directory shipped by grml-live out-of-the-box so you shouldn't have to configure anything in this file. - ${GRML_FAI_CONFIG}/make-fai-nfsroot.conf - -This file is used by make-fai-nfsroot(8) only. Usually you don't have to change -anything inside this file. If you want to modify NFSROOT though you can adjust -it there. - - ${GRML_FAI_CONFIG}/NFSROOT - -This file specifies the package list for creating the NFSROOT. - ${GRML_FAI_CONFIG}/config/ The main directory for configuration of FAI/grml-live. More details below. @@ -471,15 +487,14 @@ please send us a bug report then). Check out <> for details how to set up grml-live on a plain, original Debian system. -* enough free disk space; at least 800MB are required for a minimal grml-live -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 +* enough free disk space; at least 1.5GB are required for a minimal grml-live +run (\~850MB for the chroot [$CHROOT_OUTPUT], \~300MB for the build target +[$BUILD_OUTPUT], \~30MB for the netboot files and \~300MB 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 * fast network access for retrieving the Debian packages used for creating the -chroot (check out "local mirror" and "NFSROOT" to workaround this problem as far -as possible) +chroot (check out "local mirror" to workaround this problem as far as possible) For further information see next section. @@ -488,9 +503,8 @@ For further information see next section. Current state of grml-live with squashfs-tools and kernel --------------------------------------------------------- -Use squashfs-tools >=4.2-1 (available from Grml repositories as well as from -Debian/testing and Debian/unstable) to build Grml (based) ISOs featuring kernel -version 2.6.38-grml[64] or newer. +Use squashfs-tools >=4.2-1 to build Grml (based) ISOs featuring kernel version +2.6.38-grml[64] or newer. [[faq]] FAQ @@ -504,9 +518,9 @@ The easiest way to get a running grml-live setup is to just use Grml. Of course using grml-live on a plain, original Debian installation is supported as well. So there we go. -What we have: plain, original Debian squeeze (6.0). +What we have: plain, original Debian jessie (8.x). -What we want: build a Grml ISO based on Debian/wheezy for the amd64 architecture +What we want: build a Grml ISO based on Debian/jessie for the amd64 architecture using grml-live. Instructions @@ -524,17 +538,6 @@ Instructions # deb-src http://deb.grml.org/ grml-testing main EOF - # adjust apt-pinning (only prefer squashfs stuff from grml): - cat >> /etc/apt/preferences << EOF - Package: * - Pin: origin deb.grml.org - Pin-Priority: 1 - - Package: squashfs-tools - Pin: origin deb.grml.org - Pin-Priority: 996 - EOF - # get keyring for apt: apt-get update apt-get --allow-unauthenticated install grml-debian-keyring @@ -542,12 +545,11 @@ Instructions # optionally(!) install basefile so we don't have to build basic # chroot from scratch, grab from http://daily.grml.org/ # mkdir -p /etc/grml/fai/config/basefiles/ - # mv base.tgz /etc/grml/fai/config/basefiles/I386.tar.gz - # mv base64.tgz /etc/grml/fai/config/basefiles/AMD64.tar.gz + # mv I386.tar.gz /etc/grml/fai/config/basefiles/ + # mv AMD64.tar.gz /etc/grml/fai/config/basefiles/ # install relevant tools - # please check out http://grml.org/grml-live/#current_state when encountering problems! - apt-get -o APT::Install-Recommends=false install grml-live squashfs-tools + apt-get --no-install-recommends install grml-live # adjust grml-live configuration for our needs: cat > /etc/grml/grml-live.local << EOF @@ -558,21 +560,21 @@ Instructions # SQUASHFS_BINARY='/usr/bin/mksquashfs' ## install local files into the chroot # CHROOT_INSTALL="/etc/grml/fai/chroot_install" - ## adjust if necessary (defaults to /grml/grml-live): + ## adjust if necessary (defaults to ./grml/): ## OUTPUT="/srv/grml-live" - FAI_DEBOOTSTRAP="wheezy http://cdn.debian.net/debian/" + FAI_DEBOOTSTRAP="jessie http://ftp.debian.org/debian/" # ARCH="amd64" CLASSES="GRMLBASE,GRML_FULL,AMD64" EOF # just optional(!) - upgrade FAI to latest available version: - cat >> /etc/apt/sources.list << EOF - # fai: - deb http://fai-project.org/download squeeze koeln + cat >> /etc/apt/sources.list.d/fai.list << EOF + deb http://jenkins.grml.org/debian fai main + deb-src http://jenkins.grml.org/debian fai main EOF # get gpg key of FAI repos and install current FAI version: - gpg -a --recv-keys AB9B66FD; gpg -a --export AB9B66FD | apt-key add - + wget -O - http://jenkins.grml.org/debian/C525F56752D4A654.asc | sudo apt-key add - apt-get update apt-get install fai-client fai-server fai-doc @@ -627,7 +629,7 @@ Can I use my own (local) Debian mirror? Yes. Set up an according sources.list configuration as class file in ${GRML_FAI_CONFIG}/config/files/etc/apt/sources.list.d/ and adjust the variable -FAI_DEBOOTSTRAP (if not already using NFSROOT's base.tgz) inside +FAI_DEBOOTSTRAP (if not already using a base.tgz) inside /etc/grml/grml-live.conf[.local]. If you're setting up your own class file don't forget to include the class name in the class list (grml-live -c ...). @@ -645,7 +647,7 @@ How do I add additional Debian package(s) to my CD/ISO? Just create a new class (using the package_config directory): # cat > /etc/grml/fai/config/package_config/MIKA << EOF - PACKAGES aptitude + PACKAGES install vim another_name_of_a_debian_package @@ -666,50 +668,6 @@ what you are searching for just run: rm -rf /etc/grml/fai /etc/grml/grml-live.conf dpkg -i --force-confnew --force-confmiss /path/to/grml-live_..._all.deb -[[create-a-base-tgz]] -How do I create a base.tgz for use as NFSROOT? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First of all build the chroot system: - - mkdir /tmp/nfsroot && cd /tmp/nfsroot - debootstrap squeeze /tmp/nfsroot/ http://cdn.debian.net/debian - tar zcf base.tgz ./ - -Then check out where your NFSROOT is located: - - # grep '^NFSROOT' /etc/grml/fai/make-fai-nfsroot.conf - NFSROOT=/grml/fai/nfsroot - -So as /grml/fai/nfsroot is your NFSROOT place the file under -/grml/fai/nfsroot/live/filesystem.dir/var/tmp/: - - 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 if using -NFSROOT: - - [...] - Calling task_extrbase - Unpacking Debian base archive - Extracting /grml/fai/nfsroot/live/filesystem.dir/var/tmp/base.tgz - Calling task_mirror - [...] - -or if using /etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz for: - - [...] - ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to - /grml-live/grml-live_20071029.22138/grml_chroot// - [...] - -[TIP] -Existing base.tgz can be found at http://daily.grml.org/ - [[apt-cacher]] Set up apt-cacher-ng for use with grml-live ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -721,7 +679,7 @@ FAI_DEBOOTSTRAP: [...] APT_PROXY="http://localhost:3142/" [...] - FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free" + FAI_DEBOOTSTRAP="jessie http://localhost:3142/ftp.debian.org/debian jessie main contrib non-free" Make sure apt-cacher-ng is running ('/etc/init.d/apt-cacher-ng restart'). That's it. All downloaded files will be cached in /var/cache/apt-cacher-ng then. @@ -741,79 +699,122 @@ syslinux) then just execute: % isohybrid grml.iso -[[basetgz]] +[[create-a-base-tgz]] How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +[[basetgz]] -Execute the following commands (requires root): +First of all create the chroot using debootstrap (requires root): - ARCH='amd64' # replace with i386 if necessary - SUITE='squeeze' # using the current stable release should always work - debootstrap --arch "$ARCH" --exclude=info,tasksel,tasksel-data "$SUITE" "$ARCH" http://debian.netcologne.de/debian - cd "$ARCH" - rm var/cache/apt/archives/*.deb - tar zcf ../"${ARCH}".tar.gz * + BASECHROOT='/tmp/basefile' # path where the chroot gets generated + SUITE='jessie' # using the current stable release should always work + debootstrap --exclude=info,tasksel,tasksel-data "$SUITE" "$BASECHROOT" http://ftp.debian.org/debian + tar -C "$BASECHROOT" --exclude='var/cache/apt/archives/*.deb' -zcf "${SUITE}".tar.gz ./ -And finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note -that it needs to be uppercase letters matching the class names, so: AMD64.tar.gz -for amd64 and I386.tar.gz for i386). +[TIP] +By default debootstrap builds a chroot matching the architecture of the running +host system. If you're using an amd64 system and want to build an i386 base.tgz +then invoke debootstrap using the '--arch i386' option. Disclaimer: building an +AMD64 base.tgz won't work if you are using a 32bit kernel system of course. -[[autobuild]] -How do I set up an autobuild environment? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Finally place the generated tarball in /etc/grml/fai/config/basefiles/ (note +that it needs to be uppercase letters matching the class names, so: e.g. +AMD64.tar.gz for amd64 and I386.tar.gz for i386). -If you want to set up a system like link:http://daily.grml.org/[daily.grml.org] -the Debian package grml-live-buildd provides all you need to start. Start with -figuring out the cron job script /usr/share/grml-live/buildd/cronjob.sh. +Then executing grml-live should use this file as base system instead of executing +debootstrap. Check out the output for something like: -If you want to automatically update the grml-live Debian package on your build -system based on the git tree of grml-live (so you get bleeding edge of -development which might is interesting for services like daily.grml.org) the -provided release_helper.sh script provides everything you need. Execute as root: + [...] + ftar: extracting //etc/grml/fai/config/basefiles///AMD64.tar.gz to /srv/grml64_testing/grml_chroot// + [...] + +[[localrepos]] +How to use your own local repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - echo "deb file:/home/grml-live-git/grml-live.build-area/ ./" >> /etc/apt/sources.list.d/grml-live.list - adduser --disabled-login --disabled-password grml-live-git +Let's assume you have Debian package(s) in your filesystem inside +`/home/foobar/local-packages` and want to provide them to your grml-live build. +This can be achieved either 1) through a bind mount (using the MIRROR_DIRECTORY +configuration) or 2) by serving a repository via HTTP. -Execute 'visudo' to update sudo configuration and add the following line: +Serving via bind mount / MIRROR_DIRECTORY +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - grml-live-git ALL=NOPASSWD: /usr/bin/apt-get +Make sure to create an according sources.list configuration file, e.g. using +your own class name `CUSTOM`: + + # cat > /etc/grml/fai/config/files/etc/apt/sources.list.d/local-packages.list/CUSTOM << EOF + deb file:///home/foobar/local-packages ./ + EOF -Switch to user grml-live-git and configure the rest: +Add the according MIRROR_DIRECTORY configuration to your grml-live configuration: - su - grml-live-git - mkdir grml-live.build-area - git clone git://git.grml.org/grml-live.git - git config --global user.name "Grml-Live Git Autobuild" - git config --global user.email "grml-live-git@$(hostname)" + # echo "MIRROR_DIRECTORY='/home/foobar/packages'" >> /etc/grml/grml-live.local -Finally install a cron job (as user grml-live-git) like: +Make sure the local directory looks like a mirror: - 30 00 * * * cd /home/grml-live-git/grml-live.git/ && env AUTOBUILD=1 scripts/release_helper.sh >/home/grml-live-git/grml-live-build.log + % cd /home/foobar/packages + % dpkg-scanpackages . /dev/null | gzip > Packages.gz -Tip: To find out the build date of the installed grml-live package just execute: +Finally invoke grml-live with your class name (`CUSTOM` in this example) added +to the list of classes on the command line (see grml-live option `-c`). - % apt-cache policy grml-live | grep 'Installed.*autobuild' - Installed: 0.13.1~autobuild1300450381 +Serving a repository via HTTP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Make sure to create an according sources.list configuration file, e.g. using +your own class name `CUSTOM`: + + # cat > /etc/grml/fai/config/files/etc/apt/sources.list.d/local-packages.list/CUSTOM << EOF + deb http://127.0.0.1:8000/ ./ + EOF -and run "date -ud @$STRING" where $STRING is the number behind the "autobuild", -like: +Make sure the local directory is served via HTTP on the according IP address and +port. For the `http://127.0.0.1:8000/` example from above it should be enough to +just invoke: - % date -ud @1300450081 - Fri Mar 18 12:08:01 UTC 2011 + % cd /home/foobar/packages + % dpkg-scanpackages . /dev/null | gzip > Packages.gz + % python -m SimpleHTTPServer 8000 + +[TIP] +Of course you can also use a real Debian repository setup using tools like +reprepro(1) and/or using a real web server, though for quick debugging sessions +python's SimpleHTTPServer in combination with dpkg-scanpackages from package +dpkg-dev is a simple and easy approach. + +Finally invoke grml-live with your class name (`CUSTOM` in this example) added +to the list of classes on the command line (see grml-live option `-c`). [[download]] 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 on your own (using for example a specific version or the -current development tree), just execute: +Stable Debian packages are available through the grml-repository at +link:http://deb.grml.org/pool/main/g/grml-live/[deb.grml.org] and the latest +Git commits are available as Debian packages from +link:http://jenkins.grml.org/job/grml-live-binaries/[jenkins.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: git clone git://git.grml.org/grml-live cd grml-live debuild -us -uc +[[run-from-git]] +Run grml-live directly from git +------------------------------- + +In case you want to run grml-live directly from the git repository checkout +(after making sure all dependencies are installed), you should set +`GRML_FAI_CONFIG` so that a) it finds the according FAI configuration files and +b) does not use the config files of an possibly installed `grml-live` package. +Usage example: + + # export GRML_FAI_CONFIG=$(pwd)/etc/grml/fai + # export SCRIPTS_DIRECTORY=$(pwd)/scripts + # ./grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64 + [[source]] Source ------