From 78d833e101193acb7adeb44bee34bd8b387bdd5f Mon Sep 17 00:00:00 2001 From: Ulrich Dangel Date: Sun, 13 Sep 2009 00:03:29 +0200 Subject: [PATCH] Splitted documentation for grml-autoconfig.1 in 2 different files moved documentation for different grml versions in separate files --- doc/grml-autoconfig.1.txt | 244 +--------------------------------------- doc/grml-autoconfig.200905.txt | 116 +++++++++++++++++++ doc/grml-autoconfig.current.txt | 159 ++++++++++++++++++++++++++ 3 files changed, 277 insertions(+), 242 deletions(-) create mode 100644 doc/grml-autoconfig.200905.txt create mode 100644 doc/grml-autoconfig.current.txt diff --git a/doc/grml-autoconfig.1.txt b/doc/grml-autoconfig.1.txt index 5f1b8af..e042f23 100644 --- a/doc/grml-autoconfig.1.txt +++ b/doc/grml-autoconfig.1.txt @@ -52,250 +52,10 @@ 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' +include::grml-autoconfig.200905.txt[] [[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. 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. Usage example: - - netcript=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 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' - +include::grml-autoconfig.current.txt[] Permanently adjust boot parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/grml-autoconfig.200905.txt b/doc/grml-autoconfig.200905.txt new file mode 100644 index 0000000..453a928 --- /dev/null +++ b/doc/grml-autoconfig.200905.txt @@ -0,0 +1,116 @@ +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' + + diff --git a/doc/grml-autoconfig.current.txt b/doc/grml-autoconfig.current.txt new file mode 100644 index 0000000..3266839 --- /dev/null +++ b/doc/grml-autoconfig.current.txt @@ -0,0 +1,159 @@ +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. 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. Usage example: + + netcript=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 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. + -- 2.1.4