X-Git-Url: http://git.grml.org/?p=grml-autoconfig.git;a=blobdiff_plain;f=doc%2Fgrml-autoconfig.1.txt;fp=doc%2Fgrml-autoconfig.1.txt;h=0cbac2fe62280a534f7eae4bf0f9e45a77d6aa6d;hp=0000000000000000000000000000000000000000;hb=044d67ae243554c35bf3832f51bbac4570b04e77;hpb=dd31080f647066e88d42cd2a7981631e0cf632ba diff --git a/doc/grml-autoconfig.1.txt b/doc/grml-autoconfig.1.txt new file mode 100644 index 0000000..0cbac2f --- /dev/null +++ b/doc/grml-autoconfig.1.txt @@ -0,0 +1,503 @@ +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 +<>) and the current behavior +(see <>). 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 <> 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