From 5270bfabfe805e69c5246c805c61fffc666ffc7d Mon Sep 17 00:00:00 2001 From: Chris Hofstaedtler Date: Fri, 24 Jul 2026 14:39:06 -0300 Subject: [PATCH 1/5] config: import grml-autoconfig.1 docs from grml-live at build time --- build-site | 1 + content/config/_index.md | 8 +- static/config/grml-autoconfig.1.html | 1251 -------------------------- 3 files changed, 2 insertions(+), 1258 deletions(-) delete mode 100644 static/config/grml-autoconfig.1.html diff --git a/build-site b/build-site index 1d339f36..97cadcef 100755 --- a/build-site +++ b/build-site @@ -34,6 +34,7 @@ copy_set_url source-repos/grml-etc-core/doc/grmlzshrc.adoc content/zsh/grmlzshrc git_clone grml-live cp source-repos/grml-live/docs/grml-live.8.adoc content/grml-live/index.adoc +copy_set_url source-repos/grml-live/docs/grml-autoconfig.1.adoc content/config/grml-autoconfig.1.adoc config/grml-autoconfig.1.html git_clone grml-x cp source-repos/grml-x/grml-x.txt content/grml-x/index.adoc diff --git a/content/config/_index.md b/content/config/_index.md index 6b4ae7e6..1dcd7ba4 100644 --- a/content/config/_index.md +++ b/content/config/_index.md @@ -6,13 +6,7 @@ icon = 'floppy' Starting with version 0.5 Grml provides a configuration system. Please see [grml-autoconfig.1.html](grml-autoconfig.1.html) for details. -In Grml releases up to and including 2009.05 the documentation is available on the -grml ISO via `man save-config` and as -[/usr/share/doc/grml-saveconfig/grml-config.html](file:///usr/share/doc/grml-saveconfig/grml-config.html). - -In Grml releases after 2009.05 the documentation is available on the -grml ISO via `man 1 grml-autoconfig` and as -[/usr/share/doc/grml-autoconfig/grml-autoconfig.1.html](file:///usr/share/doc/grml-autoconfig/grml-autoconfig.1.html). +In a running Grml Live ISO, you can also read it via `man 1 grml-autoconfig`. **Tip:** Make sure to also check out the new [persistency features](https://github.com/grml/grml/wiki/persistency) of Grml. diff --git a/static/config/grml-autoconfig.1.html b/static/config/grml-autoconfig.1.html deleted file mode 100644 index 9bdc9b2b..00000000 --- a/static/config/grml-autoconfig.1.html +++ /dev/null @@ -1,1251 +0,0 @@ - - - - - - -grml-autoconfig(1) - - - - - -
-
-

Name

-
-

grml-autoconfig - main bootup process of a grml system

-
-
-
-

Synopsis

-
-

None - it is a framework. See grml-autoconfig(8) for information regarding -the interface script.

-
-
-
-

Introduction

-
-

By using the config framework, it is possible to customize Grml’s startup in a -multitude of ways. It allows to:

-
    -
  • -

    -execute one or more scripts on startup -

    -
    • -
  • -

    -install Debian packages from deb files on startup -

    -
    • -
  • -

    -unpack configuration on startup -

    -
    • -
-

The combination of Debs, Configuration and Scripts is called DCS in Grml. DCS -can be read from the Live Image itself, from an arbitrary file system on the -local system which is marked with the volume label GRMLCFG, or from the file -system pointed to by the myconfig boot parameter.

-

The DCS handling is controlled by a number of boot parameters.

-

The scripts save-config and restore-config can be used to create and handle -files called grml configuration archive, abbreviated GCA. save-config stores -the running configuration inside a GCA; restore-config is a script to restore a -configuration from a GCA.

-
- - - -
-
Tip
-		A GCA is a plain bzip2 compressed tar archive. All the files are generated -starting from the root-directory / so it is easy to handle. You can generate -configuration archives manually as well. save-config is just a frontend which -should make it easier to use.
-
-
- - - -
-
Important
-		Starting with Grml release 2009.05 its possible to use root persistency on grml. -This means you can store your settings and reuse them on reboot, without having -to deal with this config framework. Visit -https://github.com/grml/grml/wiki/persistency for further information.
-
-
-
-
-

Behavior in current Grml versions

-
-

This section applies to all Grml versions newer than release 2013.02.

-

The central concept of grml-autoconfig is the DCS directory which holds debs, -configuration and scripts which are used during system startup.

-
-

Determination of DCS directory

-

The DCS directory defaults to the root directory of the GRML live image -(Note: the directory is known as /run/live/medium/ on a running -Grml system then!). If a file system labeled GRMLCFG is found, the DCS -directory is the root directory of that file system. Alternatively, the -myconfig boot parameter can be used to directly specify a device which -is then taken as DCS directory (myconfig=/dev/sda1, for example). If -your device is labeled different to GRMLCFG the proper label can be set -via the autoconfig boot parameter (autoconfig=SOMELABEL, for example).

-

Without any additional boot parameters, the GCA at DCSDIR/config.tbz is -automatically unpacked and DCSDIR/scripts/grml.sh is automatically executed on -system startup. The noautoconfig boot parameter disables this automatic -behavior.

-
-
-

Boot Parameters

-

The following boot parameters are supported. Use them at the (isolinux) -bootprompt as documented here.

-
-
-myconfig -
-
-

- This parameter directly sets DCSDIR to the root directory of the specified - device. Usage examples: -

-
-
-
myconfig=/dev/sda1                        => read DCS from usb-device
-
-
-
-autoconfig -
-
-

- This parameter specifies the label used to determine the DCS device. - If undefined the label GRMLCFG is used to find the DCS device. -

-
-
-
autoconfig=SOMELABEL      => search for device labeled SOMELABEL to use as
-                             DCS device.
-
-
-
-home -
-
-

- This parameter is for setting a specific partition as home directory. Usage - examples: -

-
-
-
home=/dev/sda3    =>  use /dev/sda3 as the homepartition
-home=scan         =>  scan through the available partitions and search
-                      for file grml.img
-
-
-
-partconf -
-
-

- This parameter mounts the specified device in read-only mode and tries to - copy all files specified in /etc/grml/partconf to the Grml system. This - provides the possibility to use the configuration of a harddisk - installation. For example using the network configuration (which is - specified in /etc/network) is possible using this boot parameter. Usage - example: -

-
-
-
partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
-                      in /etc/grml/partconf to the booted Grml system
-
-
-
-netconfig -
-
-

- Use this parameter to restore configuration using wget to download a GCA - from the specified destination. You can also add variables to change the - file name depending on the host configuration. Predefined and useful - variables are $ARCH, $HOSTNAME and $KERNEL. Usage example: -

-
-
-
netconfig=server.tld/path/to/config.tbz  =>   restore configuration using wget to download file config.tbz
-netconfig=server.tld/config-$ARCH.tbz    =>   download config for specified architecture
-
-
-
-netscript -
-
-

- Use this parameter to download and run a script from specified destination: - You can also add variables to change the file name depending on the host - configuration. Predefined and useful variables are $ARCH, $HOSTNAME and - $KERNEL. The environment variable NETSCRIPT is set to the specified URI. - This can be used to detect if the script is executed via the netscript bootoption. - Usage example: -

-
-
-
netscript=server.tld/path/to/script      =>   download and run script/executable from server
-netscript=server.tld/script-$HOSTNAME    =>   download and run script/executable for specific host
-
-
-
-extract -
-
-

- Extract specific directories from the GCA which needs to be specified by - other means. -

-
-
-
extract=/home/grml         => extract only /home/grml from archive
-extract=/etc               => extract only /etc from archive
-extract=/home/grml/config  => extract only $HOME/config from archive
-
-
-
-scripts -
-
-

- This parameter executes scripts. If an optional path is given, it is - relative to DCSDIR. If the path points to a file, this single file is - executed. If no path is given, it defaults to scripts/grml.sh. - If the given name points to a directory, all scripts inside it are - executed. Usage examples: -

-
-
-
scripts               =>   run script DCSDIR/scripts/grml.sh
-scripts=foobar.sh     =>   run script foobar.sh in DCSDIR
-scripts=foobar        =>   run all scripts inside DCSDIR/foobar directory
-
-
-
-config -
-
-

- This parameter restores a configuration using a GCA. If an optional path is - given, it is relative to DCSDIR. If no path is given, it defaults to - DCSDIR/config.tbz. Usage examples: -

-
-
-
config                    =>   restore configuration using file DCSDIR/config.tbz
-config=config_foobar.tbz  =>   restore configuration using file DCSDIR/config_foobar.tbz
-
-
-
-debs -
-
-

- This parameter allows automatic installation of deb packages while booting. - The path is relative to DCSDIR, not optional and is a shell wildcard. All - Files matching the wildcard are installed in a single dpkg --install call. - For backwards compatibility, if no slash is contained in the path, it is - taken relative to DCSDIR/debs. -

-
-
-
Usage examples:
-
-
-
-
debs=*.deb        =>   install all debian packages (suffix .deb) from directory DCSDIR/debs/
-debs=foo/01*.deb  =>   install all debian packages (suffix .deb) starting with 01 in the filename from directory DCSDIR/foo
-
-
-
-debnet -
-
-

- Search all local partitions and dm devices for file /etc/network/interfaces and - copy the directory /etc/network to the grml system and restart networking. -

-
-
-noautoconfig -
-
-

- Deactivate automounting. By default the scripts try to mount a device with - label GRMLCFG. If you specify the noautoconfig boot parameter this - automounting will be deactivated. -

-
-
-
noautoconfig            => disables auto mounting of label 'GRMLCFG'
-
-
-
-
-
-

Permanently adjust boot parameters

-

As you probably know you can adjust boot parameters on the bootprompt. -You want to set some boot parameters permanently? That’s possible via -adding a directory named bootparams to the Grml ISO which has to be -located at the root-directory /bootparams/ (Note: the directory is known -as /run/live/medium/bootparams/ on a_running_Grml system then!). -Place a textfile inside the directory containing the boot parameters -which should be appended to default ones (this corresponds to booting -without any special parameters).

-
-
-
mkdir bootparams
-echo lang=de > bootparams/my_bootparams
-
-

Then burn a multisession CD where directory bootparams is located in the root -directory of the CD.

-
- - - -
-
Note
-		Not all boot parameters can be used via /bootparams/. This is a limitation of -the way the kernel and userspace retrieve boot parameters. Boot parameter -regarding the kernel definitely do NOT work. Boot parameter related to -grml-autoconfig (the main part of the boot process in Grml running in userspace, -being all the stuff after startup of udev) are expected to work. Boot parameter -related to initrd/initramfs (the part between Searching for GRML file and -startup of udev) are NOT covered by /bootparams/ as well yet.
-
-
- - - -
-
Tip
-		the application k3b (not available on the live-CD but available through the -Debian repositories) provides an easy to use interface for doing the -multisession task.
-
-
-
-
-
-

Usage scenarios

-
-
-

Personal configuration files

-

You are a fan of the editor vim? Great. You probably have your own /.vimrc and -want to use it on the Grml system. You also don’t like the default zsh -configuration and want to use your own /.zshrc? How to proceed? Copy your -.vimrc and .zshrc to $HOME of user grml. Place additional files in -$HOME/config. Now create a configuration for your files running:

-
-
-
save-config -home -configdir
-
-

Now you should have a file named config.tbz containing your configuration files. -You can copy the archive to a webserver and restore it via downloading during -reboot using the following commandline on bootprompt:

-
-
-
grml netconfig=server.tld/path/to/config.tbz
-
-

You don’t have network access but own a USB device? Copy the file to a USB -device and boot with something like:

-
-
-
grml myconfig=/dev/sda1
-
-
-
-

Network configuration

-

You need a specific network setup and want to use your own -/etc/network/interfaces by default? Generate the configuration archive running -the following command as user root:

-
-
-
save-config -etc
-
-

Now you should have a file named config.tbz containing your configuration files. -If you want to use it with a USB device copy the file to it and boot via -using the following command on boot prompt:

-
-
-
grml myconfig=/dev/sda1
-
-

You do have an existing harddisk installation and want to use its configuration? -Let’s say the Debian system is located in /dev/sda2. You want to use the -directory /etc/network. This directory is activated by default in -/etc/grml/partconf so we don’t have to do any further work. We just need to -activate it via using the following commandline on bootprompt:

-
-
-
grml partconf=/dev/sda2
-
-
-
-

Automatic installation of debian packages

-

You have a specified debian package named foobar.deb and want to use it with -(therefore: install it on) Grml by default? Notice: this feature is useful -especially for grml-small (a ~100 MB ISO). If you want to use it with the large -version of Grml you might have to overburn the ISO.

-

Let’s assume you have burned the Grml iso to a CD-RW using a commandline like:

-
-
-
cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
-
-

Now create a directory named debs and place foobar.deb in it:

-
-
-
mkdir debs/ && cp foobar.deb debs/
-
-

Notice: This directory will be located in /run/live/medium after burning the second -session.

-

Now create the second session containing this directory:

-
-
-
mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
-
-

Finally append the second session to the cd using:

-
-
-
cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
-
-
- - - -
-
Tip
-		the application k3b (not available on the live CD but available through the -Debian repositories) provides an easy to use interface for doing the -multisession task.
-
-

Now boot from your new personalized Grml CD using the debs parameter:

-
-
-
grml debs
-
-
-
-

Run your own commands on startup

-

You know that booting with grml services=foobar executes -/etc/init.d/foobar when booting Grml. But you want to setup a more -complex network configuration, adjust some other stuff and so on, on -your own? Just write a script named grml.sh which does the job and use -one of the mentioned boot parameters. Let’s say you have placed grml.sh -on your usb device (usb stick) then use the following commandline on -bootprompt:

-
-
-
grml myconfig=/dev/sda1
-
-

Or even better: create a device with label GRMLCFG running (adjust /dev/sdX1 -according to your needs):

-
-
-
mkfs.ext3 -L GRMLCFG /dev/sdX1  # warning: this destroys all data on /dev/sdX1
-
-
- - - -
-
Tip
-		several filesystems provide the possibility to provide a label. For -example FAT provides this through: mkfs.vfat -n GRMLCFG /dev/sda1 (attention: -this will destroy data on /dev/sda1 of course!). Take a look at the -documentation/manpage of the filesystem you want to use.
-
-

Now place your configuration archive (see save-config and the other -usage scenarios) and the script grml.sh on the device. Now you can boot -your system without specifying any boot parameters on bootprompt because -devices labeled with GRMLCFG are mounted readonly and used by default. -If you did not label your device you can use the device anyway using -grml myconfig=/dev/sdX (adjust /dev/sdX) on the bootprompt.

-
-
-

Debug remote systems

-

You are responsible for a customer’s system in her data center. The system has -failed and you need to debug from remote, and the remote hands available in the -data center do not have enough knowledge to get Grml booted and configure the -network without external help?

-

If the hard disk of the system is still available, you hopefully have saved a -configuration file with IP address, netmask and default gateway somewhere on -that hard disk. Grml can use the information found on a partition. Take a look -at the partconf boot parameter. Usage example: grml partconf=/dev/sda2 -copies files defined in /etc/grml/partconf from /dev/sda2 to the Grml system. As -/etc/network is predefined in /etc/grml/partconf the configuration from -/dev/sda2 will be taken.

-

Or you use a standard Grml medium and have grml read IP address, netmask and -default gateway from another medium like a USB stick. Take a look at the script -saveconfig and the boot parameter myconfig.

-

Or you put a grml.iso file on your hard disk (maybe in /boot/grml) or on an USB -stick, use grub to boot from there and place debs, configuration scripts or Grml -configuration archives alongside the .iso.

-
-
-
-
-

Bugs

-
-

If you find a bug please report it. See http://grml.org/bugs/ for details -about how to report bugs.

-
-
-
-

See also

-
-

grml-autoconfig(8), restore-config(1), save-config(1)

-
-
-
-

Author

-
-

(c) 2005++, Michael Prokop <mika@grml.org>

-
-
-
-
- - - From c7b832fd08dbfc6122df95ae5a6f41861cbf6662 Mon Sep 17 00:00:00 2001 From: Chris Hofstaedtler Date: Fri, 24 Jul 2026 14:48:48 -0300 Subject: [PATCH 2/5] config: add grml-autoconfig.8 and link both from /docs/ --- build-site | 1 + content/config/_index.md | 4 ++-- content/docs/index.md | 8 ++++++++ 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/build-site b/build-site index 97cadcef..199f3ddd 100755 --- a/build-site +++ b/build-site @@ -35,6 +35,7 @@ copy_set_url source-repos/grml-etc-core/doc/grmlzshrc.adoc content/zsh/grmlzshrc git_clone grml-live cp source-repos/grml-live/docs/grml-live.8.adoc content/grml-live/index.adoc copy_set_url source-repos/grml-live/docs/grml-autoconfig.1.adoc content/config/grml-autoconfig.1.adoc config/grml-autoconfig.1.html +copy_set_url source-repos/grml-live/docs/grml-autoconfig.8.adoc content/config/grml-autoconfig.8.adoc config/grml-autoconfig.8.html git_clone grml-x cp source-repos/grml-x/grml-x.txt content/grml-x/index.adoc diff --git a/content/config/_index.md b/content/config/_index.md index 1dcd7ba4..5cdce3c0 100644 --- a/content/config/_index.md +++ b/content/config/_index.md @@ -4,9 +4,9 @@ icon = 'floppy' +++ Starting with version 0.5 Grml provides a configuration system. -Please see [grml-autoconfig.1.html](grml-autoconfig.1.html) for details. +Please see [grml-autoconfig(1)](grml-autoconfig.1.html) and [grml-autoconfig(8)](grml-autoconfig.8.html) for details. -In a running Grml Live ISO, you can also read it via `man 1 grml-autoconfig`. +In a running Grml Live ISO, you can also read it via `man 1 grml-autoconfig` and `man 8 grml-autoconfig`. **Tip:** Make sure to also check out the new [persistency features](https://github.com/grml/grml/wiki/persistency) of Grml. diff --git a/content/docs/index.md b/content/docs/index.md index 49a0d04f..0709b2c6 100644 --- a/content/docs/index.md +++ b/content/docs/index.md @@ -12,6 +12,14 @@ The available boot options are documented at the cheatcod Many tips and tricks can be found in the grml-wiki (wiki.grml.org) and in grml-tips. +## Live ISO Configuration + +The Live ISO can be configured at run time. See: + +* [grml-autoconfig(1)](/config/grml-autoconfig.1.html) and [grml-autoconfig(8)](/config/grml-autoconfig.8.html) +* [persistency](https://github.com/grml/grml/wiki/persistency) +* [boot cheatcodes](/cheatcodes/) - especially `netscript=` + ## Guides ### grml2usb From 6bb98a8a5216bc5e1cf8a196040587002c8d3136 Mon Sep 17 00:00:00 2001 From: Chris Hofstaedtler Date: Fri, 24 Jul 2026 14:49:15 -0300 Subject: [PATCH 3/5] docs: reorder alphabetically --- content/docs/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/index.md b/content/docs/index.md index 0709b2c6..6ab20594 100644 --- a/content/docs/index.md +++ b/content/docs/index.md @@ -34,10 +34,10 @@ The Live ISO can be configured at run time. See: grml-live: build framework based on FAI for generating a grml and Debian based Linux Live system (CD/ISO) -### grml-x - -grml-x: create xorg.conf file (providing hardware detection) and start X window system - ### grml-terminalserver grml-terminalserver: boot grml via network + +### grml-x + +grml-x: create xorg.conf file (providing hardware detection) and start X window system From 235da622c4166a4b6d7f365911cb73ef94f4fab5 Mon Sep 17 00:00:00 2001 From: Chris Hofstaedtler Date: Fri, 24 Jul 2026 14:53:17 -0300 Subject: [PATCH 4/5] docs: convert links to markdown syntax --- content/docs/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/docs/index.md b/content/docs/index.md index 6ab20594..14dccb2e 100644 --- a/content/docs/index.md +++ b/content/docs/index.md @@ -5,12 +5,12 @@ icon = 'doc' ## FAQ & zsh -Frequently asked questions and answers can be found in the section FAQ. -If you are looking for information on the Zsh take a look at the zsh-webpage. +Frequently asked questions and answers can be found in the section [FAQ](/faq/). +If you are looking for information on the Zsh take a look at the [zsh-webpage](/zsh/). -The available boot options are documented at the cheatcodes webpage. +The available boot options are documented at [the cheatcodes webpage](/cheatcodes/). -Many tips and tricks can be found in the grml-wiki (wiki.grml.org) and in grml-tips. +Many tips and tricks can be found in the [grml-wiki](https://wiki.grml.org/) and in [grml-tips](/tips/). ## Live ISO Configuration @@ -24,20 +24,20 @@ The Live ISO can be configured at run time. See: ### grml2usb -grml2usb: install grml ISO(s) on usb device for booting +[grml2usb](/grml2usb/): install grml ISO(s) on usb device for booting ### grml-debootstrap -grml-debootstrap: wrapper around debootstrap for installing plain Debian via grml +[grml-debootstrap](/grml-debootstrap/): wrapper around debootstrap for installing plain Debian via grml ### grml-live -grml-live: build framework based on FAI for generating a grml and Debian based Linux Live system (CD/ISO) +[grml-live](/grml-live/): build framework based on FAI for generating a grml and Debian based Linux Live system (CD/ISO) ### grml-terminalserver -grml-terminalserver: boot grml via network +[grml-terminalserver](/terminalserver/): boot grml via network ### grml-x -grml-x: create xorg.conf file (providing hardware detection) and start X window system +[grml-x](/grml-x/): create xorg.conf file (providing hardware detection) and start X window system From 6233de9cd01e542cb87636c22a5768738bc74d64 Mon Sep 17 00:00:00 2001 From: Chris Hofstaedtler Date: Fri, 24 Jul 2026 14:54:45 -0300 Subject: [PATCH 5/5] docs: update description of grml-live --- content/docs/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/index.md b/content/docs/index.md index 14dccb2e..d67de54e 100644 --- a/content/docs/index.md +++ b/content/docs/index.md @@ -32,7 +32,9 @@ The Live ISO can be configured at run time. See: ### grml-live -[grml-live](/grml-live/): build framework based on FAI for generating a grml and Debian based Linux Live system (CD/ISO) +[grml-live](/grml-live/): build framework for the Grml Live Linux system + +Read this if you want to build your own Grml-based system. ### grml-terminalserver