X-Git-Url: http://git.grml.org/?p=grml-autoconfig.git;a=blobdiff_plain;f=doc%2Fgrml-autoconfig.txt;fp=doc%2Fgrml-autoconfig.txt;h=0000000000000000000000000000000000000000;hp=5bdae5ab625e3206c5421e66ed371a629a252757;hb=044d67ae243554c35bf3832f51bbac4570b04e77;hpb=dd31080f647066e88d42cd2a7981631e0cf632ba diff --git a/doc/grml-autoconfig.txt b/doc/grml-autoconfig.txt deleted file mode 100644 index 5bdae5a..0000000 --- a/doc/grml-autoconfig.txt +++ /dev/null @@ -1,577 +0,0 @@ -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 <> 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 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