Skip to content

Commit

Permalink
Update documentation (FAQ, create TOC)
Browse files Browse the repository at this point in the history
  • Loading branch information
@mika
mika committed Aug 4, 2009
1 parent 533b646 commit be17ebf
Show file tree
Hide file tree
Showing 3 changed files with 129 additions and 38 deletions.
4 changes: 3 additions & 1 deletion debian/changelog
View file
Expand Up @@ -35,8 +35,10 @@ grml-live (0.9.20) UNRELEASED; urgency=low
it is possible to set it via conffile as well.
* Validate whether the specified architecture class matches the
architecture (option), otherwise installation of kernel will fail.
* Add 'How do I deploy grml-live on a plain Debian installation' to FAQ.
* Build grml-live documentation with table of content.

-- Michael Prokop <mika@grml.org> Tue, 04 Aug 2009 19:26:20 +0200
-- Michael Prokop <mika@grml.org> Wed, 05 Aug 2009 00:26:44 +0200

grml-live (0.9.19) unstable; urgency=low

Expand Down
2 changes: 1 addition & 1 deletion docs/Makefile
View file
Expand Up @@ -5,7 +5,7 @@ doc: doc_man doc_html
doc_html: html-stamp

html-stamp: grml-live.txt grml-live-remaster.txt
asciidoc -b xhtml11 -a icons grml-live.txt
asciidoc -b xhtml11 -a icons -a toc -a numbered grml-live.txt
asciidoc -b xhtml11 -a icons grml-live-remaster.txt
touch html-stamp

Expand Down
161 changes: 125 additions & 36 deletions docs/grml-live.txt
View file
Expand Up @@ -110,7 +110,7 @@ Force execution and do not prompt for acknowledgment of configuration.

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.
GRML_NAME, otherwise you might notice problems while booting.

-h::

Expand Down Expand Up @@ -412,9 +412,12 @@ run at /var/log/grml-buildd.stdout and /var/log/grml-buildd.stderr.
Requirements for the build system
---------------------------------
* any Debian based system should be sufficient (if not it's a bug, so please
send us a bug report then) [a usual link:http://grml.org/grml2hd/[grml2hd]
harddisk installation ships all you need]
* any Debian based system should be sufficient (if it doesn't work it's a bug,
please send us a bug report then) [a usual
link:http://grml.org/grml2hd/[grml2hd] harddisk installation (using grml or
grml-medium) ships all you need]. Check out <<deploy-on-debian,How do I deploy
grml-live on a plain Debian installation>> 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
Expand All @@ -436,45 +439,28 @@ 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
section is up2date by 04nd of august 2009, 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
squashfs-lzma-tools from the grml repository supports kernel 2.6.26-grml[64] and
2.6.28-grml[64] 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.
Please use squashfs-lzma-tools 3.3-1 if you want to remaster grml release
2008.11 or 2009.05.

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:
squashfs-tools 1:3.3-7 is available via the official Debian/unstable and
Debian/testing (Lenny) pool running:

# aptitude install squashfs-tools=1:3.3-7

Expand All @@ -483,15 +469,17 @@ 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
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 and 2009.05 using LZMA 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!)
instead if you still want to use kernel 2.6.23 (not
recommended)
* Kernel 2.6.26-grml: works (without LZMA compression only of course!)
* Kernel 2.6.28-grml: works (without LZMA compression only of course!)

Using squashfs-tools 1:3.2r2-9exp1 on the build system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -505,21 +493,122 @@ 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
Using 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
* Kernel 2.6.28-grml: supposed to work (not verified though)

Versions with LZMA compression:
Using 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).
* Kernel 2.6.28-grml: does NOT work, please use zlib mode instead or switch
to Debian package squashfs-lzma-tools (see section above).

FAQ
---

[[deploy-on-debian]]
How do I deploy grml-live on a plain Debian installation?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The easiest way to get a running grml-live setup is to install grml or
grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you
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
architecture using grml-live.

[IMPORTANT]

If you encounter any problems while booting the resulting ISO please be aware of
<<current_state,the 'current state of grml-live with squashfs-tools and kernel'
section>>.

Instructions
^^^^^^^^^^^^

# adjust sources.list:
cat >> /etc/apt/sources.list << EOF

# grml stable repository:
deb http://deb.grml.org/ grml-stable main
deb-src http://deb.grml.org/ grml-stable main

# grml testing/development repository:
deb http://deb.grml.org/ grml-testing main
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

Package: squashfs-lzma-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

# install basefile so we don't have to build basic chroot from scratch:
mkdir -p /etc/grml/fai/config/basefiles/
mv base.tgz /etc/grml/fai/config/basefiles/I386.tar.gz

# install relevant tools:
apt-get -o APT::Install-Recommends=false install grml-live squashfs-lzma-tools

# adjust grml-live configuration for our needs:
cat > /etc/grml/grml-live.local << EOF
# consider using lzma only for space reasons (resulting in longer
# build time but smaller ISO):
SQUASHFS_OPTIONS="-nolzma"
## adjust if necessary (defaults to /grml/grml-live):
## OUTPUT="/srv/grml-live"
FAI_DEBOOTSTRAP="squeeze http://ftp.de.debian.org/debian/"
ARCH="i386"
CLASSES="GRMLBASE,GRML_MEDIUM,I386"
ZERO_LOGFILE='1'
# ZERO_FAI_LOGFILE='1'
GRML_LIVE_SOURCES="
deb http://deb.grml.org/ grml-stable main
deb http://deb.grml.org/ grml-testing main
deb http://ftp.de.debian.org/debian squeeze main contrib non-free
"
EOF

# just optional(!) - upgrade FAI to latest available version:
cat >> /etc/apt/sources.list << EOF
# fai:
deb http://www.informatik.uni-koeln.de/fai/download lenny koeln
EOF

# get gpg key of FAI repos and install current FAI version:
gpg -a --recv-keys AB9B66FD; gpg -a --export AB9B66FD | apt-key add -
apt-get update
apt-get install fai-client fai-server fai-doc

That's it. Now invoking 'grml-live -V' should build the ISO. If everything
worked as expected the last line of the shell output should look like:

[*] Successfully finished execution of grml-live [running 687 seconds]

and the ISO can be found inside /grml-live/grml-live/grml_isos/ then.

Help, I'm using Debian etch and I don't have FAI version >3.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down

0 comments on commit be17ebf

Please sign in to comment.