From: Michael Prokop Date: Mon, 12 Dec 2011 14:33:28 +0000 (+0100) Subject: Update grml-live docs to current grml-live.git X-Git-Url: http://git.grml.org/?p=grml.org.git;a=commitdiff_plain;h=9e415c6c4a54d8a6e55aed2d2f5482a29933fe72 Update grml-live docs to current grml-live.git --- diff --git a/grml-live/grml-live.epub b/grml-live/grml-live.epub index 0fd1e3a..a88f8a2 100644 Binary files a/grml-live/grml-live.epub and b/grml-live/grml-live.epub differ diff --git a/grml-live/grml-live.pdf b/grml-live/grml-live.pdf index 495b0cb..54b95c1 100644 Binary files a/grml-live/grml-live.pdf and b/grml-live/grml-live.pdf differ diff --git a/grml-live/index.html b/grml-live/index.html index 4659291..93eb3bd 100644 --- a/grml-live/index.html +++ b/grml-live/index.html @@ -3,29 +3,26 @@ - + grml-live(8) @@ -550,7 +754,8 @@ Linux Live system (CD/ISO)

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]

+<suite>] [-t <template_directory>] [-v <version_number>] [-U <username>] [ +-AbBFnNquVz]

@@ -582,8 +787,8 @@ 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 +(unless overriden using the '-D' option). 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!
@@ -609,6 +814,15 @@ for details).
+-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. +

+
+
-a ARCHITECTURE
@@ -649,12 +863,13 @@ 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_MEDIUM and I386 are assumed, resulting in a small base -system (being about ~180MB 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 -the CLASSES section in this document for details about available classes). -So instead of GRML_MEDIUM you can also use GRML_SMALL and GRML_FULL. +the classes GRMLBASE, GRML_FULL and I386/AMD64 (depending on system +architecture) are assumed, resulting in a small base system (being about ~180MB +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 the CLASSES section in this document for +details about available classes). So instead of GRML_FULL you can also use +GRML_SMALL and GRML_FULL.

@@ -684,9 +899,7 @@ 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 (usually /etc/grml/grml-live.local). 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.local for configuration stuff used inside -/etc/grml/fai/config.

@@ -704,6 +917,19 @@ advance. Usage example: -d 2009-10-30

+-D CONFIGURATION_DIRECTORY +
+
+

+The specified directory is used as configuration directory for grml-live and its +FAI. By default /etc/grml/fai is used as default configuration directory. If +you want to have different configuration scripts, package definitions, etc. with +without messing with the global configuration under /etc/grml/fai provided by +grml-live this option provides you the option to use your own configuration +throughout this documentation. +

+
+
-F
@@ -758,6 +984,22 @@ the chroot and/or recreate the squashfs file without building an ISO file.

+-N +
+
+

+Bootstrap the chroot without building bootloader, squashfs, or finalizing the +ISO. Use this option if installation of some packages fails, you want to run +custom commands or similar. +The main use of this option is to save time by skipping stages which aren’t +necessary for bootstrapping the chroot and which would get executed more than +once when iterating through the initial bootstrapping. +Alternatively, use this option as a test run of grml-live. Once you are +satisfied with the state of your grml_chroot, use grml-live -u to build the +remaining stages and finalize the ISO. +

+
+
-o OUTPUT_DIRECTORY
@@ -779,6 +1021,14 @@ Consider combining this option with the build-only option -b.

+-Q +
+
+

+Build the ISO without generating a netboot package. +

+
+
-r RELEASENAME
@@ -794,7 +1044,6 @@ Specify name of the release. 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 -(/etc/grml/fai/config/basefiles/$CLASSNAME.tar.gz) or a recent version of debootstrap.

@@ -808,6 +1057,15 @@ Specify place of the templates used for building the ISO. By default

+-T CHROOT_ARCHIVE +
+
+

+Unpack chroot tar archive before starting. Most useful in combination with +-A and -b or -u. +

+
+
-u
@@ -817,6 +1075,14 @@ based on the softupdate feature of FAI.

+-U USERNAME +
+
+

+Sets ownership of all build output files to specified username before exiting. +

+
+
-v VERSION_NUMBER
@@ -856,20 +1122,20 @@ as build and output directory just run:

/home/mika/grml-live as build and output directory just use:

-
# grml-live -s sid -c GRMLBASE,GRML_SMALL,I386 -o /home/mika/grml-live
+
# grml-live -s sid -c GRMLBASE,GRML_SMALL,AMD64 -o /home/mika/grml-live
-

To get a medium sized, Debian-unstable and grml-based Live-CD for i386 +

To get a medium sized, Debian-unstable and grml-based Live-CD for amd64 architecture using /grml/grml-live as build and output directory just run:

-
# grml-live -s sid -a i386 -c GRMLBASE,GRML_MEDIUM,I386
+
# grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64

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 /tmp/grml_isos) just invoke:

-
# grml-live -o /tmp -c GRMLBASE,GRML_SMALL,I386 -s sid -i grml_0.0-3.iso
+
# grml-live -o /tmp -c GRMLBASE,GRML_SMALL,AMD64 -s sid -i grml_0.0-3.iso
@@ -938,20 +1204,20 @@ GRML_SMALL, GRML_MEDIUM or GRML_FULL). The following files and directories are relevant for class GRMLBASE by default:

-
/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
+
${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/
+${GRML_FAI_CONFIG}/config/debconf/GRMLBASE
+${GRML_FAI_CONFIG}/config/class/GRMLBASE.var
+${GRML_FAI_CONFIG}/config/hooks/instsoft.GRMLBASE
+${GRML_FAI_CONFIG}/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 (or extend an existing one). For example if you want to use your own class named "FOOBAR" just -set CLASSES="GRMLBASE,GRML_SMALL,I386,FOOBAR" inside /etc/grml/grml-live.local +set CLASSES="GRMLBASE,GRML_SMALL,AMD64,FOOBAR" inside /etc/grml/grml-live.local or invoke grml-live using the classes option: "grml-live -c -GRMLBASE,GRML_SMALL,I386,FOOBAR …".

+GRMLBASE,GRML_SMALL,AMD64,FOOBAR …".

More details regarding the class concept can be found in the documentation of FAI itself (being available at /usr/share/doc/fai-doc/).

@@ -960,8 +1226,6 @@ FAI itself (being available at /usr/share/doc/fai-doc/).

8. Available classes

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:

  • @@ -972,30 +1236,33 @@ 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 +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_FULL: full featured grml, also known as the "normal", full grml. +GRML_FULL: full featured grml, also known as the "normal", full grml as +introduced in november 2011 (~350MB ISO size).

  • -GRML_MEDIUM: medium sized grml version, known as grml-medium +GRML_MEDIUM: medium sized grml version, used to be known as grml-medium +until november 2011 (~220MB ISO size).

  • -GRML_POWERPC: grml for PowerPC architecture, not supported yet (still work in -progress) +GRML_SMALL: minimum sized grml version, known as grml-small (~110MB ISO +size).

  • -GRML_SMALL: minimum sized grml version, known as grml-small +GRML_XL: large size Grml version, used to be known as "full grml" until +november 2011 (~700MB ISO size).

  • @@ -1037,6 +1304,12 @@ REMOVE_DOCS: get rid of documentation directories (like /usr/share/doc,

  • +SOURCES: retrieve Debian source packages after installation. Files will be +placed in the output directory under grml_sources. +

    +
    • +
  • +

    XORG: providing important packages for use with a base grml-featured X.org setup

    @@ -1050,7 +1323,6 @@ setup

    Notice that grml-live ships FAI configuration files that do not use the same namespace as the FAI packages itself. This ensures that grml-live does not clash with your usual FAI configuration, so instead of /etc/fai/fai.conf (package -fai-client) grml uses /etc/grml/fai/fai.conf instead. For more details see below. To get an idea how another configuration or example files could look like check out /usr/share/doc/fai-doc/examples/simple/ (provided by Debian package fai-doc). Furthermore /usr/share/doc/fai-doc/fai-guide.html/ch-config.html @@ -1078,82 +1350,80 @@ from /etc/grml/grml-live.local as well you have to specify them on the grml-live commandline.

    -
    /etc/grml/fai/fai.conf
    +
    ${GRML_FAI_CONFIG}/fai.conf

    Main configuration file for FAI which specifies where all the configuration files and scripts for FAI/grml-live can be found. By default the configuration variables are FAI_CONFIG_SRC=file:///etc/grml/fai/config and -FAI_CONFIGDIR=/etc/grml/fai/config - both pointing to a directory shipped by +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.

    -
    /etc/grml/fai/make-fai-nfsroot.conf
    +
    ${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.

    -
    /etc/grml/fai/NFSROOT
    +
    ${GRML_FAI_CONFIG}/NFSROOT

    This file specifies the package list for creating the NFSROOT.

    -
    /etc/grml/fai/apt/sources.list
    +
    ${GRML_FAI_CONFIG}/apt/sources.list

    This file specifies which mirrors should be considered for retrieving the Debian packages when creating the main chroot (including all the software you would like to see included). Important: this file should not be adjusted manually! Instead use the GRML_LIVE_SOURCES variable inside /etc/grml/grml-live.conf or -/etc/grml/grml-live.local which modifies /etc/grml/fai/apt/sources.list -on-the-fly via grml-live then. If you want to generally adjust apt configuration -use FAI’s fcopy command with /etc/grml/fai/config/files instead.

    +on-the-fly via grml-live then. If you want to generally adjust apt configuration

-
/etc/grml/fai/config/
+
${GRML_FAI_CONFIG}/config/

The main directory for configuration of FAI/grml-live. More details below.

-
/etc/grml/fai/config/class/
+
${GRML_FAI_CONFIG}/config/class/

This directory contains files which specify main configuration variables for the FAI classes.

-
/etc/grml/fai/config/debconf/
+
${GRML_FAI_CONFIG}/config/debconf/

This directory provides the files for preseeding/configuration of debconf through files.

-
/etc/grml/fai/config/hooks/
+
${GRML_FAI_CONFIG}/config/hooks/

This directory provides files for customising the build process through hooks. Hooks are user defined programs or scripts, which are called during the installation process.

-
/etc/grml/fai/config/package_config/
+
${GRML_FAI_CONFIG}/config/package_config/

Directory with lists of software packages to be installed or removed. The different classes describe what should find its way to your ISO. When running -"grml-live -c GRMLBASE,GRML_SMALL,I386 …" only the configuration of GRMLBASE, -GRML_SMALL and and I386 will be taken. If you use grml-live -c -GRMLBASE,GRML_SMALL,I386,FOOBAR … then the files of GRMLBASE, GRML_SMALL, -I386 plus the files from FOOBAR will be taken. So just create a new class to +"grml-live -c GRMLBASE,GRML_SMALL,AMD64 …" only the configuration of GRMLBASE, +GRML_SMALL and and AMD64 will be taken. If you use grml-live -c +GRMLBASE,GRML_SMALL,AMD64,FOOBAR … then the files of GRMLBASE, GRML_SMALL, +AMD64 plus the files from FOOBAR will be taken. So just create a new class to adjust the package selection according to your needs. Please notice that the directory GRMLBASE contains a package list defining a minimum but still reasonable package configuration.

-
/etc/grml/fai/config/scripts/
+
${GRML_FAI_CONFIG}/config/scripts/

Scripts for customising the ISO within the build process.

-
/etc/grml/fai/live-initramfs/
+
${GRML_FAI_CONFIG}/live-initramfs/

This directory provides the files used for building the initramfs/initrd via live-initramfs(8).

@@ -1168,7 +1438,7 @@ grml-live.

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.

+run at /var/log/grml-buildd.log.

If you want to store build information in a database just install the grml-live-db Debian package. Further details available in the grml-live-db manpage.

@@ -1225,7 +1495,7 @@ grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,… if don’t want to run it on a physical system). 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 Lenny (5.0).

-

What we want: build a grml-medium ISO based on Debian/squeeze for the i386 +

What we want: build a grml-medium ISO based on Debian/squeeze for the amd64 architecture using grml-live.

@@ -1306,7 +1576,7 @@ CHROOT_INSTALL="/etc/grml/fai/chroot_install" ## OUTPUT="/srv/grml-live" FAI_DEBOOTSTRAP="squeeze http://cdn.debian.net/debian/" ARCH="i386" -CLASSES="GRMLBASE,GRML_MEDIUM,I386" +CLASSES="GRMLBASE,GRML_FULL,AMD64" # PRESERVE_LOGFILE='1' # ZERO_FAI_LOGFILE='1' GRML_LIVE_SOURCES=" @@ -1341,16 +1611,14 @@ worked as expected the last line of the shell output should look like:

-

13.2. Help, I’m using Debian etch and I don’t have FAI version >3.2

-
-
-
wget http://fai-project.org/download/etch/fai-client_3.2.8_all.deb \
-     http://fai-project.org/download/etch/fai-server_3.2.8_all.deb \
-     http://fai-project.org/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 FAI-homepage for -further details.

+

13.2. What is $GRML_FAI_CONFIG?

+

The variable $GRML_FAI_CONFIG is pointing to the directory /etc/grml/fai by +default. To provide you a maximum of flexibility you can set up your own +configuration directory (e.g. based on /etc/grml/fai) and use this directory +running grml-live with the -D <config_dir> option. Now $GRML_FAI_CONFIG +points to the specified directory instead of using /etc/grml/fai and all the +configuration files, scripts and hooks will be taken from your +$GRML_FAI_CONFIG directory.

13.3. I’ve problems with the build process. How to start debugging?

@@ -1521,21 +1789,17 @@ grml-live ...

13.6. Can I use my own (local) Debian mirror?

-

Sure. Just adjust the variables GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP (if not -already using NFSROOT’s base.tgz) inside /etc/grml/grml-live.conf according to -your needs. Please don’t forget that you should use the grml servers as well -(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 inside /etc/grml/grml-live.conf as -well.

-

Unless you specify GRML_LIVE_SOURCES and/or FAI_DEBOOTSTRAP the default from -/etc/grml/fai/apt/sources.list and /etc/grml/fai/make-fai-nfsroot.conf will be -taken. If you customise the variables in /etc/grml/grml-live.conf then the two -files will be adjusted during runtime automatically.

-

If MIRROR_DIRECTORY and MIRROR_SOURCES are specified the local mirror will be -taken as first entry in the generated sources.list so it’s preferred over -non-local mirrors. Using a fallback mirror (via providing several mirrors in -GRML_LIVE_SOURCES as used by default) is a recommended setting.

+

Yes. Set up an according sources.list configuration as class file in +FAI_DEBOOTSTRAP (if not already using NFSROOT’s 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 …).

+

If you want to use a local (for example NFS mount) mirror additionally then +adjust MIRROR_DIRECTORY in /etc/grml/grml-live.conf[.local] as well.

+

If you want to use a HTTP Proxy (like apt-cacher-ng), set APT_PROXY. Example:

+
+
+
APT_PROXY="http://localhost:3142/"
+

13.7. How do I add additional Debian package(s) to my CD/ISO?

@@ -1555,7 +1819,7 @@ EOF

and specify it when invoking grml-live then:

-
# grml-live -c GRMLBASE,GRML_SMALL,I386,MIKA
+
# grml-live -c GRMLBASE,GRML_SMALL,AMD64,MIKA
@@ -1630,29 +1894,24 @@ ftar: extracting /etc/grml/fai/config/basefiles///AMD64.tar.gz to
Existing base.tgz can be found at http://daily.grml.org/
-
-
-

13.10. Set up apt-cacher / apt-cacher-ng for use with grml-live

-

Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and -FAI_DEBOOTSTRAP:

-
+

Set up apt-cacher-ng for use with grml-live

+
-
# cat /etc/grml/grml-live.conf
-[...]
-GRML_LIVE_SOURCES="
-deb http://localhost:3142/deb.grml.org grml-stable  main
-deb http://localhost:3142/deb.grml.org grml-testing main
-deb http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free
-"
-[...]
-FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze main contrib non-free"
+
Make sure /etc/grml/grml-live.local provides according APT_PROXY and
+FAI_DEBOOTSTRAP:
+
+  # cat /etc/grml/grml-live.local
+  [...]
+  APT_PROXY="http://localhost:3142/"
+  [...]
+  FAI_DEBOOTSTRAP="squeeze http://localhost:3142/cdn.debian.net/debian squeeze 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.
+
+[[approx]]
+Set up approx for use with grml-live
-

Make sure apt-cacher / apt-cacher-ng is running (/etc/init.d/apt-cacher -restart or /etc/init.d/apt-cacher-ng restart). That’s it. All downloaded -files will be cached in /var/cache/apt-cacher/ or /var/cache/apt-cacher-ng then.

-
-
-

13.11. Set up approx for use with grml-live

Make sure /etc/grml/grml-live.conf provides according GRML_LIVE_SOURCES and FAI_DEBOOTSTRAP:

@@ -1678,8 +1937,8 @@ grml http://deb.grml.org/ All downloaded files will be cached in /var/cache/approx now.

-

13.12. How do I revert the manifold feature from an ISO?

-

The so called manifold feature Grml ISOs use by default allows to use the same +

13.10. How do I revert the manifold feature from an ISO?

+

The so called manifold feature Grml ISOs use by default allows one to use the same ISO for CD boot and USB boot. If you notice any problems when booting just revert the manifold feature running:

@@ -1694,7 +1953,7 @@ syslinux) then just execute:

-

13.13. How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz)

+

13.11. How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz)

Execute the following commands (requires root):

@@ -1710,7 +1969,7 @@ that it needs to be uppercase letters matching the class names, so: AMD64.tar.gz for amd64 and I386.tar.gz for i386).

-

13.14. How do I set up an autobuild environment?

+

13.12. How do I set up an autobuild environment?

If you want to set up a system like 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.

@@ -1757,7 +2016,7 @@ Fri Mar 18 12:08:01 UTC 2011
-

13.15. I’ve a question which isn’t answered by this document

+

13.13. I’ve a question which isn’t answered by this document

Don’t hesitate to contact the author: <mika@grml.org>

@@ -1827,7 +2086,7 @@ in different formats: