+++ /dev/null
-grml-autoconfig
-===============
-
-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.
-
-The grml-autoconfig code has been re-worked in August 2009. This
-document handles both the behavior of grml releases up to 2009.05 and
-the current behavior. Great care has been taken to provide maximum
-backwards compatibility during the rewrite.
-
-
-Behavior up to grml 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'
-
-
-Behavior in current development snapshots
------------------------------------------
-
-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.
-
-
-
-Scripts
--------
-
-NAME
-~~~~
-save-config - save configuration ; restore-config - restore
-configuration; mkpersistenthome - create persistent home directory;
-more options available via boot parameters (see above)
-
-SYNOPSIS
-~~~~~~~~
-save-config - please take a look at 'save-config -h' ; restore-config
-- please take a look at 'restore-config -h', mkpersistenthome (no
-options available)
-
-
-save-config - save configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This script generates a plain bzip2 compressed tar archive containing
-the specified files, suitable as a GCA. The following options are
-supported for specifying which parts should be saved in the
-configuration file:
-
- -home store hidden files from $HOME ($HOME/.*)
- -grmlhome store hidden files from \$HOME (\$HOME/.*) of user grml [use as user root]
- -etc store modified files from /etc
- -configdir store $HOME/config
- -all store all configuration files (:= -home, -configdir and -etc)
-
-TIP: It is also possible to use environment variables for specifying which parts
-should be saved. Just set the corresponding variable: $SAVE_HOME, $SAVE_ETC,
-$SAVE_CONFIGDIR and $SAVE_ALL
-
-The default filename of the generated configuration file is
-config.tbz. The following options are supported for specifying
-another destination of the configuration file:
-
- -ssh user@host:/path/to/file copy configuration via ssh/scp to remote host
- -mail <recipient> send configuration via mail
- -file foo_bar_config.tbz save configuration in specified file
-
-Usage examples:
-
- save-config -all => store all configuration files in config.tbz in current dir
- save-config -home -mail devnull@grml.org => store $HOME/.* in config.tbz and send it via mail
- save-config -etc -ssh devnull@grml.org:/path/ => store /etc in config.tbz and scp it to specified host
- save-config -all -file foo.tbz => store all configuration files in foo.tbz
- SAVE_ALL=yes save-config -file /path/foo.tbz => store all configuration files in /path/foo.tbz
-
-restore-config - restore configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can either restore a GCA using the boot parameters or by a script file
-named 'restore-config'. Specify the filename of the configuration
-archive which should be used as a parameter. The following options are
-available to specify which parts of the archive should be extracted.
-
- -home extract hidden files from $HOME ($HOME/.*)
- -grmlhome store hidden files from \$HOME (\$HOME/.*) of user grml [use as user root]
- -etc extract modified files from /etc
- -configdir extract $HOME/config
-
-The default is to extract (restore) all files found in the archive.
-
-TIP: It is also possible to use environment variables for specifying
-which part should be restored. Just set the corresponding variable:
-$RESTORE_HOME, $RESTORE_ETC, $RESTORE_CONFIGDIR and $RESTORE_ALL
-
-Usage examples:
-
- restore-config -home foo_bar_config.tbz => restore configuration from file foo_bar_config.tbz
- restore-config config.tbz => restore configuration from file config.tbz
-
-mkpersistenthome - use persistent home-directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You have a local partition you would like to use as your
-home-directory? Just use the interactive script called
-'mkpersistenthome'. It will either create a file named grml.img on the
-specified partition or create a partition using the ext2 filesystem
-(you can specify the option in a dialog inside the program). grml.img
-is a loopback device which size you can specify manually. It is
-possible to scan through the partitions to identify the appropriate
-partition. To use a home-directory located on your hard-drive use the
-appropriate boot parameter on bootprompt:
-
- home=/dev/sda3 => use /dev/sda3 as the homepartition
- home=scan => scan through the available partitions and search for file grml.img
-
-[[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 ~80 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
-~~~~
-Please report feedback, bugreports and wishes link:http://grml.org/contact/[to us]!
-
-Author
-~~~~~~
-(c) 2005++, Michael Prokop <mika@grml.org>
projects / grml-autoconfig.git / blobdiff