Merge remote-tracking branch 'origin/github/pr/148'

[grml-live.git] / docs / grml-live.txt

diff --git a/docs/grml-live.txt b/docs/grml-live.txt
index 52541d1..46f4890 100644 (file)
--- a/docs/grml-live.txt
+++ b/docs/grml-live.txt
@@ -62,8 +62,8 @@ Use the specified architecture instead of the currently running one.  This
 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
 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. Currently supported values: i386
-and amd64.
+nature and the need of working in a chroot. Currently supported values: i386,
+amd64 and arm64.

 
   -b::
 
 
   -b::
 


@@ -82,7 +82,7 @@ really know that you do not want to update the chroot.
   -c **CLASSES**::
 
 Specify the CLASSES to be used for building the ISO via FAI.  By default only
   -c **CLASSES**::
 
 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
+the classes GRMLBASE, GRML_FULL and I386/AMD64/ARM64 (depending on system

 architecture) are assumed.  Additionally you can specify a class providing a
 (grml-)kernel (see <<classes,the 'CLASSES' section in this document>> for
 details about available classes). So instead of GRML_FULL you can also use e.g.
 architecture) are assumed.  Additionally you can specify a class providing a
 (grml-)kernel (see <<classes,the 'CLASSES' section in this document>> for
 details about available classes). So instead of GRML_FULL you can also use e.g.


@@ -202,7 +202,7 @@ Specify name of the release.
 
 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
 
 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 "stretch"). Please be aware that recent Debian
+corresponding release names like "bookworm"). 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.
 suites might require a recent base.tgz
 (${GRML_FAI_CONFIG}/config/basefiles/$CLASSNAME.tar.gz) or a recent version of
 debootstrap.


@@ -297,9 +297,9 @@ 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 dependent class which provides the kernel
 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 or GRML_FULL). The following files and directories are
-relevant for class GRMLBASE by default:
+(being 'I386' for x86_32, 'AMD64' for x86_64 and 'ARM64' for arm64) and a GRML_*
+class (like GRML_SMALL or GRML_FULL).
+The following files and directories are relevant for class GRMLBASE by default:

 
   ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/
   ${GRML_FAI_CONFIG}/config/debconf/GRMLBASE
 
   ${GRML_FAI_CONFIG}/config/scripts/GRMLBASE/
   ${GRML_FAI_CONFIG}/config/debconf/GRMLBASE


@@ -312,10 +312,10 @@ 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
 
 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,AMD64,FOOBAR" inside /etc/grml/grml-live.local
-or invoke grml-live using the classes option: "grml-live -c
-GRMLBASE,GRML_SMALL,AMD64,FOOBAR ...".
+existing one). For example if you want to use your own class named "FOOBAR" on
+your amd64 build, et 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,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/).
 
 More details regarding the class concept can be found in the documentation of
 FAI itself (being available at /usr/share/doc/fai-doc/).


@@ -330,15 +330,14 @@ ${GRML_FAI_CONFIG}/config/package_config whereas some further classes are define
 example in ${GRML_FAI_CONFIG}/config/scripts/ so specific feature sets can be
 selected. The following classes are predefined:
 
 example in ${GRML_FAI_CONFIG}/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
-
-* 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.
+* DEBORPHAN: get rid of "autoremove" and "removed-but-not-yet-purged" packages;
+also all packages listed in output of deborphan (only if deborphan is actually
+present, note that grml-live no longer installs deborphan by default as it's not
+present since Debian/trixie!). This class is called as such for historic
+reasons, and while deborphan itself is no longer relevant nowadays, the name of
+the class was kept as such for backwards compatibility reasons. This class is
+thought to be used *before* any further `GRML*` classes, like
+`DEBORPHAN,GRMLBASE,GRML_FULL,RELEASE,...` to get proper Grml releases.

 
 * FRESHCLAM: execute freshclam (if it's present) to update clamav definitions
 (increases resulting ISO size ~70MB). By default it's skipped to avoid bigger
 
 * FRESHCLAM: execute freshclam (if it's present) to update clamav definitions
 (increases resulting ISO size ~70MB). By default it's skipped to avoid bigger


@@ -348,17 +347,17 @@ ISO size.
 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. Please be aware that using *just* the GRMLBASE class won't be
 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. 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).
+enough, because the kernel packages (e.g. linux-image-pass:[*]) are chosen in
+further GRML_pass:[*] 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
 
 * GRML_FULL: full featured Grml, also known as the "normal", full grml as

-introduced in December 2011 (~600MB ISO size).
+introduced in December 2011 (~750 ISO size).

 
 

-* GRML_SMALL: minimum sized Grml version, known as grml-small (~300MB ISO
+* GRML_SMALL: minimum sized Grml version, known as grml-small (~360MB ISO

 size).
 
 * LATEX: LaTeX(-related) packages like auctex, texlive,...
 size).
 
 * LATEX: LaTeX(-related) packages like auctex, texlive,...


@@ -386,6 +385,8 @@ placed in the output directory under grml_sources.
 * XORG: providing important packages for use with a base grml-featured X.org
 setup
 
 * XORG: providing important packages for use with a base grml-featured X.org
 setup
 

+* ZFS: package selection to add support for OpenZFS/zfsonlinux
+

 [[files]]
 Files
 -----
 [[files]]
 Files
 -----


@@ -451,7 +452,7 @@ installation process.
 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,AMD64 ..." only the configuration of GRMLBASE,
 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,AMD64 ..." only the configuration of GRMLBASE,

-GRML_SMALL and and AMD64 will be taken. If you use 'grml-live -c
+GRML_SMALL 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
 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


@@ -486,15 +487,19 @@ please send us a bug report then). 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.
 
 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 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
+* enough free disk space; at least ~2GB are required for a minimal grml-live
+run (\~1GB for the chroot [$CHROOT_OUTPUT], \~400MB for the build target
+[$BUILD_OUTPUT], \~35MB for the netboot files and \~350MB 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" to workaround this problem as far as possible)
 
 [$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" to workaround this problem as far as possible)
 

+* your output directory should not be mounted with any of the "nodev", "noexec"
+or "nosuid" mount options. (/tmp typically is at least "nodev" and "nosuid" on
+most systems.)
+

 For further information see next section.
 
 [[X8]]
 For further information see next section.
 
 [[X8]]


@@ -517,9 +522,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.
 
 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 stretch (9.x).
+What we have: plain, original Debian bookworm (v12).

 
 

-What we want: build a Grml ISO based on Debian/stretch for the amd64 architecture
+What we want: build a Grml ISO based on Debian/bookworm for the amd64 architecture

 using grml-live.
 
 Instructions
 using grml-live.
 
 Instructions


@@ -538,7 +543,7 @@ Instructions
   EOF
 
   # get keyring for apt:
   EOF
 
   # get keyring for apt:

-  apt-get update
+  apt-get -o Acquire::AllowInsecureRepositories=true update

   apt-get --allow-unauthenticated install grml-debian-keyring
 
   # optionally(!) install basefile so we don't have to build basic
   apt-get --allow-unauthenticated install grml-debian-keyring
 
   # optionally(!) install basefile so we don't have to build basic


@@ -546,6 +551,7 @@ Instructions
   # mkdir -p /etc/grml/fai/config/basefiles/
   # mv I386.tar.gz /etc/grml/fai/config/basefiles/
   # mv AMD64.tar.gz /etc/grml/fai/config/basefiles/
   # mkdir -p /etc/grml/fai/config/basefiles/
   # mv I386.tar.gz /etc/grml/fai/config/basefiles/
   # mv AMD64.tar.gz /etc/grml/fai/config/basefiles/

+  # mv ARM64.tar.gz /etc/grml/fai/config/basefiles/

 
   # install relevant tools
   apt-get --no-install-recommends install grml-live
 
   # install relevant tools
   apt-get --no-install-recommends install grml-live


@@ -561,7 +567,7 @@ Instructions
   # CHROOT_INSTALL="/etc/grml/fai/chroot_install"
   ## adjust if necessary (defaults to ./grml/):
   ## OUTPUT="/srv/grml-live"
   # CHROOT_INSTALL="/etc/grml/fai/chroot_install"
   ## adjust if necessary (defaults to ./grml/):
   ## OUTPUT="/srv/grml-live"

-  FAI_DEBOOTSTRAP="stretch http://ftp.debian.org/debian/"
+  FAI_DEBOOTSTRAP="bookworm http://deb.debian.org/debian/"

   # ARCH="amd64"
   CLASSES="GRMLBASE,GRML_FULL,AMD64"
   EOF
   # ARCH="amd64"
   CLASSES="GRMLBASE,GRML_FULL,AMD64"
   EOF


@@ -607,6 +613,12 @@ If you need help with grml-live or would like to see new features as part of
 grml-live you can get commercial support via
 link:http://grml-solutions.com/[Grml Solutions].
 
 grml-live you can get commercial support via
 link:http://grml-solutions.com/[Grml Solutions].
 

+Note that FAI doesn't abort immediately on errors that will ultimately cause
+the build to fail. Be sure to look through the logs and find the actual error;
+look for lines that start with "E: " or contain "FAILED" or "exit code 1".
+Some messages that may look like errors are actually benign; e.g.
+"/tmp/grml64/grml_chroot/var/lib/dpkg is not a mounted ramdisk" is not an error.
+

 [[install-local-files]]
 How do I install further files into the chroot/ISO?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 [[install-local-files]]
 How do I install further files into the chroot/ISO?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


@@ -678,7 +690,7 @@ FAI_DEBOOTSTRAP:
   [...]
   APT_PROXY="http://localhost:3142/"
   [...]
   [...]
   APT_PROXY="http://localhost:3142/"
   [...]

-  FAI_DEBOOTSTRAP="stretch http://localhost:3142/ftp.debian.org/debian stretch main contrib non-free"
+  FAI_DEBOOTSTRAP="bookworm http://localhost:3142/ftp.debian.org/debian bookworm 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.
 
 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.


@@ -687,38 +699,41 @@ That's it.  All downloaded files will be cached in /var/cache/apt-cacher-ng then
 How do I revert the manifold feature from an ISO?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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:
+By default, Grml ISOs use isohybrid to allow them to be booted from CDs as
+well as USB sticks. Manifold is an alternative to isohybrid.
+
+If you notice any problems
+when booting manifold-crafted media, just revert the manifold feature running:

 
   % dd if=/dev/zero of=grml.iso bs=512 count=1 conv=notrunc
 
 To switch from manifold to isohybrid mode (an alternative approach provided by
 
   % dd if=/dev/zero of=grml.iso bs=512 count=1 conv=notrunc
 
 To switch from manifold to isohybrid mode (an alternative approach provided by

-syslinux) then just execute:
+syslinux, used by default for official Grml images) then just execute:

 
   % isohybrid grml.iso
 
 [[create-a-base-tgz]]
 
   % isohybrid grml.iso
 
 [[create-a-base-tgz]]

-How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How do I create a base tar.gz (I386.tar.gz or AMD64.tar.gz or ARM64.tar.gz)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 [[basetgz]]
 
 First of all create the chroot using debootstrap (requires root):
 
   BASECHROOT='/tmp/basefile'  # path where the chroot gets generated
 [[basetgz]]
 
 First of all create the chroot using debootstrap (requires root):
 
   BASECHROOT='/tmp/basefile'  # path where the chroot gets generated

-  SUITE='stretch'              # 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 ./
+  SUITE='bookworm'            # using the current stable release should always work
+  debootstrap --exclude=info,tasksel,tasksel-data,isc-dhcp-client,isc-dhcp-common "${SUITE}" "${BASECHROOT}" http://deb.debian.org/debian
+  tar -C "$BASECHROOT" --exclude='var/cache/apt/archives/*.deb' --exclude 'var/lib/apt/lists/*_*' --xattrs --xattrs-include='*.*' --acls -zcf "${SUITE}".tar.gz ./

 
 [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.
 
 [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.

+Also building an ARM64 base.tgz requires an arm64 system.

 
 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.
 
 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).
+AMD64.tar.gz for amd64, I386.tar.gz for i386 or ARM64.tar.gz for arm64).

 
 Then executing grml-live should use this file as base system instead of executing
 debootstrap. Check out the output for something like:
 
 Then executing grml-live should use this file as base system instead of executing
 debootstrap. Check out the output for something like:


@@ -812,6 +827,7 @@ Usage example:
 
     # export GRML_FAI_CONFIG=$(pwd)/etc/grml/fai
     # export SCRIPTS_DIRECTORY=$(pwd)/scripts
 
     # export GRML_FAI_CONFIG=$(pwd)/etc/grml/fai
     # export SCRIPTS_DIRECTORY=$(pwd)/scripts

+    # export TEMPLATE_DIRECTORY=$(pwd)/templates

     # ./grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64
 
 [[source]]
     # ./grml-live -s sid -a amd64 -c GRMLBASE,GRML_FULL,AMD64
 
 [[source]]