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 http://wiki.grml.org/doku.php?id=persistency for further information.

Behavior in current Grml versions

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

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. 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/scrips/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
myconfig=/dev/fd0                         => read DCS from floppy-disk
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: 

netcript=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, but the run-parts name restrictions apply: script names must consist entirely of upper and lower case letters, digits, underscores, and hyphens. 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 bootparam 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 /live/image/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.

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 /live/image/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 procede? 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 floppy drive? Copy the file to a floppy disk and boot with:

grml myconfig=/dev/fd0

Floppy is to small or to slow? Ok, let’s use a usb device:

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 floppy disk copy the file to a floppy and boot via using the following command on bootprompt:

grml myconfig=/dev/fd0

Floppy is to small or to slow? Ok, let’s use a usb device:

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 /live/image 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 service=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 own of the mentioned bootparams. 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 floppy disk with label GRMLCFG running:

fdformat /dev/fd0   # format the floppy disk if not done already
mkfs.ext2 -L GRMLCFG /dev/fd0   # now create ext2 filesystem with label GRMLCFG on it:
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 floppy disk. Now you can boot your system without specifying any bootparameters 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/ice 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 floppy or an 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 configuraton 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>