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_bootparamsThen 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 -configdirNow 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.tbzYou 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/sda1Network 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 -etcNow 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/sda1You 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/sda2Automatic 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.isoNow 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 debsFinally 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 debsRun 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/sda1Or 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>