--- /dev/null
+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 Brml. 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.
+
+The grml-autoconfig code has been re-worked in August 2009. This document
+handles both the behavior of Grml releases up to 2009.05 (see
+<<up-to-200905,section 'Behavior up to grml 2009.05'>>) and the current behavior
+(see <<current-versions,section 'Behavior in current Grml versions'>>). Great
+care has been taken to provide maximum backwards compatibility during the
+rewrite.
+
+[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
+link:http://wiki.grml.org/doku.php?id=persistency for further information.
+
+[[up-to-200905]]
+Behavior up to grml 2009.05
+---------------------------
+
+This section applies to all Grml versions older than and including release 2009.05.
+
+Autoconfiguration
+~~~~~~~~~~~~~~~~~
+
+By default the booting process tries to mount a device labeled 'GRMLCFG'. This
+provides the possibility to restore a configuration (named config.tbz) and
+execute a script (named grml.sh) without the need to specify any bootparams. If
+you want to disable this feature please take a look at the 'noautoconfig'
+bootparam.
+
+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). If you want to be able to boot from
+your Grml-CD you have to create a multisession CD. See the <<X7,usage
+scenarios>> for more details how to use it or consider booting from a USB device
+(checkout grml2usb).
+
+The following boot parameters are supported. Use them at the (isolinux)
+bootprompt as documented here.
+
+myconfig::
+
+ This parameter is for restoring configuration using the file config.tbz
+ on the specified device. Usage examples:
+
+ myconfig=/dev/sda1 => use file config.tbz from usb-device
+ myconfig=/dev/fd0 => use file config.tbz from floppy-disk
+ myconfig=/dev/sda1 file=config_foobar.tbz => use file config_foobar.tbz from usb-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
+ configuration file from specified destination. Usage example:
+
+ netconfig=server.tld/path/to/config.tbz => restore configuration using wget to download file config.tbz
+
+extract::
+
+ Extract specific directories from configuration archive. Notice: This
+ bootparam is useful only with bootparams which are able to extract
+ configuration archives.
+
+ 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 a script located in the root-directory /scripts/ on
+ the Grml media/ISO (note: the directory is known as /live/image/scripts/ on
+ a _running_ Grml system then). Usage examples:
+
+ scripts => run script [/live/image]/scripts/grml.sh
+ scripts=foobar.sh => run script foobar.sh in [/live/image]/scripts/
+
+config::
+
+ This parameter restores a configuration using root-directory /config/ on the
+ Grml media/ISO (note: the directory is known as /live/image/config on a
+ _running_ Grml system then). Usage examples:
+
+ config => restore configuration using file config.tbz from directory [/live/image]/config/
+ config=config_foobar.tbz => restore configuration using file config_foobar.tbz from directory [/live/image]/config/
+
+debs::
+
+ This parameter allows automatic installation of deb packages while booting.
+ The debian packages have to be located in the root-directory /debs/ on the
+ Grml media/ISO (note: the directory is known as /live/image/debs/ on a
+ _running_ Grml system then). Usage examples:
+
+ debs => install all debian packages (suffix .deb) from directory [/live/image]/debs/
+ debs=01 => install all debian packages (suffix .deb) starting with 01 in the filename from directory [/live/image]/debs/
+
+
+noautoconfig::
+
+ Deactivate automounting. By default the command 'mount' tries to mount a
+ device with label 'GRMLCFG'. If you specify the noautoconfig bootparam the
+ automounting will be deactivated.
+
+ noautoconfig => disables auto mounting of label 'GRMLCFG'
+
+[[current-versions]]
+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).
+
+Without any additional boot parameters, the GCA at DCSDIR/config.tbz is
+automatically unpacked and DCSDIR/scrips/grml.sh is automaitcally 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
+
+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. Usage example:
+
+ netconfig=server.tld/path/to/config.tbz => restore configuration using wget to download file config.tbz
+
+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 it points to a directory, all scripts inside this
+ directory are executed. If the path points to a file, this single file is
+ executed. If no path is given, it defaults to scripts/grml.sh. 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
+
+
+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.
+
+[[X7]]
+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.
+
+Use persistent home directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You want to use a persistent home directory which includes all the files located
+in $HOME. Use the script mkpersistenthome to create such a persistent home
+directory. You have the options to either use a specific partition as your home
+directory or add a loopback file named grml.img on the specified partition (the
+default).
+
+TIP: /dev/external in the partition selection of mkpersistenthome is an usb
+device without partitions. /dev/external1 corresponds to the first partition on
+an usb device (usually an usb stick).
+
+After running the script mkpersistenthome you can use the boot parameter home to
+activate the home directory. If you are using the option with the loopback file
+(grml.img) you can boot via:
+
+ grml home=scan
+
+which will scan through the partitions and if a file grml.img is found it will
+be mounted as your $HOME-directory. If you want to use a partition as your home
+directory specify the device as an option. If you want to use /dev/sda2 as your
+$HOME boot via:
+
+ grml home=/dev/sda2
+
+Notice: the files located in /etc/skel will be copied to the partition (but will
+not overwrite any files).
+
+Bugs
+----
+If you find a bug please report it. See link:http://grml.org/bugs/ for details
+about how to report bugs.
+
+See also
+--------
+grml-autoconfig(8), mkpersistenthome(1), restore-config(1), save-config(1)
+
+Author
+------
+(c) 2005++, Michael Prokop <mika@grml.org>
projects / grml-autoconfig.git / blobdiff