7 By using the config framework, it is possible to customize grml's
8 startup in a multitude of ways. It allows to:
10 - execute one or more scripts on startup
11 - install Debian packages from deb files on startup
12 - unpack configuration on startup
14 The combination of Debs, Configuration and Scripts is called DCS in
15 grml. DCS can be read from the Live Image itself, from an arbitrary
16 file system on the local system which is marked with the volume label
17 GRMLCFG, or from the file system pointed to by the myconfig boot
20 The DCS handling is controlled by a number of boot parameters.
22 The scripts save-config and restore-config can be used to create and
23 handle files called 'grml configuration archive', abbreviated GCA.
24 save-config stores the running configuration inside a GCA;
25 restore-config is a script to restore a configuration from a GCA.
27 TIP: A GCA is a plain bzip2 compressed tar archive. All the files are
28 generated starting from the root-directory '/' so it is easy to
29 handle. You can generate configuration archives manually as well.
30 save-config is just a frontend which should make it easier to use.
32 The grml-autoconfig code has been re-worked in August 2009. This
33 document handles both the behavior of grml releases up to 2009.05 and
34 the current behavior. Great care has been taken to provide maximum
35 backwards compatibility during the rewrite.
38 Behavior up to grml 2009.05
39 ---------------------------
44 By default the booting process tries to mount a device labeled
45 'GRMLCFG'. This provides the possibility to restore a configuration
46 (named config.tbz) and execute a script (named grml.sh) without the
47 need to specify any bootparams. If you want to disable this feature
48 please take a look at the 'noautoconfig' bootparam.
53 As you probably know you can adjust boot parameters on the bootprompt. You want
54 to set some boot parameters permanently? That's possible via adding a directory
55 named 'bootparams' to the grml-ISO which has to be located at the root-directory
56 /bootparams/ (note: the directory is known as /live/image/bootparams/ on a
57 _running_ grml system then). Place a textfile inside the directory containing
58 the boot parameters which should be appended to default ones (this corresponds to
59 booting without any special parameters). If you want to be able to boot from your
60 grml-CD you have to create a multisession CD. See the <<X7,usage scenarios>> for
61 more details how to use it or consider booting from a USB device (checkout
64 The following boot parameters are supported. Use them at the (isolinux)
65 bootprompt as documented here.
69 This parameter is for restoring configuration using the file config.tbz
70 on the specified device. Usage examples:
72 myconfig=/dev/sda1 => use file config.tbz from usb-device
73 myconfig=/dev/fd0 => use file config.tbz from floppy-disk
74 myconfig=/dev/sda1 file=config_foobar.tbz => use file config_foobar.tbz from usb-device
78 This parameter is for setting a specific partition as home directory.
81 home=/dev/sda3 => use /dev/sda3 as the homepartition
82 home=scan => scan through the available partitions and search
87 This parameter mounts the specified device in read-only mode and tries
88 to copy all files specified in /etc/grml/partconf to the grml
89 system. This provides the possibility to use the configuration of a
90 harddisk installation. For example using the network configuration
91 (which is specified in /etc/network) is possible using this
92 boot parameter. Usage example:
94 partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
95 in /etc/grml/partconf to the booted grml system
98 Use this parameter to restore configuration using wget to download
99 a configuration file from specified destination. Usage example:
101 netconfig=server.tld/path/to/config.tbz => restore configuration using wget to download file config.tbz
105 Extract specific directories from configuration archive. Notice:
106 This bootparam is useful only with bootparams which are able to
107 extract configuration archives.
109 extract=/home/grml => extract only /home/grml from archive
110 extract=/etc => extract only /etc from archive
111 extract=/home/grml/config => extract only $HOME/config from archive
115 This parameter executes a script located in the root-directory /scripts/ on the
116 grml media/ISO (note: the directory is known as /live/image/scripts/ on a
117 _running_ grml system then). Usage examples:
119 scripts => run script [/live/image]/scripts/grml.sh
120 scripts=foobar.sh => run script foobar.sh in [/live/image]/scripts/
124 This parameter restores a configuration using root-directory /config/ on the
125 grml media/ISO (note: the directory is known as /live/image/config on a
126 _running_ grml system then). Usage examples:
128 config => restore configuration using file config.tbz from directory [/live/image]/config/
129 config=config_foobar.tbz => restore configuration using file config_foobar.tbz from directory [/live/image]/config/
133 This parameter allows automatic installation of deb packages while
134 booting. The debian packages have to be located in the root-directory /debs/
135 on the grml media/ISO (note: the directory is known as /live/image/debs/ on
136 a _running_ grml system then). Usage examples:
138 debs => install all debian packages (suffix .deb) from directory [/live/image]/debs/
139 debs=01 => install all debian packages (suffix .deb) starting with 01 in the filename from directory [/live/image]/debs/
144 Deactivate automounting. By default the command 'mount' tries to mount a
145 device with label 'GRMLCFG'. If you specify the noautoconfig bootparam
146 the automounting will be deactivated.
148 noautoconfig => disables auto mounting of label 'GRMLCFG'
151 Behavior in current development snapshots
152 -----------------------------------------
154 The central concept of grml-autoconfig is the DCS directory which
155 holds debs, configuration and scripts which are used during system
159 Determination of DCS directory
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162 The DCS directory defaults to the root directory of the GRML live
163 image. If a file system labeled GRMLCFG is found, the DCS directory is
164 the root directory of that file system. Alternatively, the myconfig
165 boot parameter can be used to directly specify a device which is then
166 taken as DCS directory (myconfig=/dev/sda1, for example).
168 Without any additional boot parameters, the GCA at DCSDIR/config.tbz
169 is automatically unpacked and DCSDIR/scrips/grml.sh is automaitcally
170 executed on system startup. The 'noautoconfig' boot parameter disables
171 this automatic behavior.
177 The following boot parameters are supported. Use them at the (isolinux)
178 bootprompt as documented here.
182 This parameter directly sets DCSDIR to the root directory of the
183 specified device. Usage examples:
185 myconfig=/dev/sda1 => read DCS from usb-device
186 myconfig=/dev/fd0 => read DCS from floppy-disk
190 This parameter is for setting a specific partition as home directory.
193 home=/dev/sda3 => use /dev/sda3 as the homepartition
194 home=scan => scan through the available partitions and search
199 This parameter mounts the specified device in read-only mode and tries
200 to copy all files specified in /etc/grml/partconf to the grml
201 system. This provides the possibility to use the configuration of a
202 harddisk installation. For example using the network configuration
203 (which is specified in /etc/network) is possible using this
204 boot parameter. Usage example:
206 partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
207 in /etc/grml/partconf to the booted grml system
210 Use this parameter to restore configuration using wget to download
211 a GCA from the specified destination. Usage example:
213 netconfig=server.tld/path/to/config.tbz => restore configuration using wget to download file config.tbz
217 Extract specific directories from the GCA which needs to be
218 specified by other means.
220 extract=/home/grml => extract only /home/grml from archive
221 extract=/etc => extract only /etc from archive
222 extract=/home/grml/config => extract only $HOME/config from archive
226 This parameter executes scripts. If an optional path is given, it
227 is relative to DCSDIR. If it points to a directory, all scripts
228 inside this directory are executed. If the path points to a file,
229 this single file is executed. If no path is given, it defaults to
230 scripts/grml.sh. Usage examples:
232 scripts => run script DCSDIR/scripts/grml.sh
233 scripts=foobar.sh => run script foobar.sh in DCSDIR
234 scripts=foobar => run all scripts inside DCSDIR/foobar directory
238 This parameter restores a configuration using a GCA. If an
239 optional path is given, it is relative to DCSDIR. If no path is
240 given, it defaults to DCSDIR/config.tbz. Usage examples:
242 config => restore configuration using file DCSDIR/config.tbz
243 config=config_foobar.tbz => restore configuration using file DCSDIR/config_foobar.tbz
247 This parameter allows automatic installation of deb packages while
248 booting. The path is relative to DCSDIR, not optional and is a
249 shell wildcard. All Files matching the wildcard are installed in a
250 single dpkg --install call. For backwards compatibility, if no
251 slash is contained in the path, it is taken relative to DCSDIR/debs.
255 debs=*.deb => install all debian packages (suffix .deb) from directory DCSDIR/debs/
256 debs=foo/01*.deb => install all debian packages (suffix .deb) starting with 01 in the filename from directory DCSDIR/foo
261 Deactivate automounting. By default the scripts try to mount a
262 device with label 'GRMLCFG'. If you specify the noautoconfig bootparam
263 this automounting will be deactivated.
265 noautoconfig => disables auto mounting of label 'GRMLCFG'
268 Permanently adjust boot parameters
269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
271 As you probably know you can adjust boot parameters on the bootprompt. You want
272 to set some boot parameters permanently? That's possible via adding a directory
273 named 'bootparams' to the grml-ISO which has to be located at the root-directory
274 /bootparams/ (note: the directory is known as /live/image/bootparams/ on a
275 _running_ grml system then). Place a textfile inside the directory containing
276 the boot parameters which should be appended to default ones (this corresponds to
277 booting without any special parameters).
280 echo lang=de > bootparams/my_bootparams
282 Then burn a multisession CD where directory bootparams is located in the root
286 Not all boot parameters can be used via /bootparams/. This is a limitation of the
287 way the kernel and userspace retrieve boot parameters. Boot parameter regarding the
288 kernel definitely do *NOT* work. Boot parameter related to grml-autoconfig (the
289 main part of the boot process in grml running in userspace, being all the stuff
290 after startup of udev) are expected to work. Boot parameter related to
291 initrd/initramfs (the part between 'Searching for GRML file' and startup of
292 udev) are *NOT* covered by /bootparams/ as well yet.
294 TIP: the application k3b (not available on the live-CD but available
295 through the Debian repositories) provides an easy to use interface for
296 doing the multisession task.
305 save-config - save configuration ; restore-config - restore
306 configuration; mkpersistenthome - create persistent home directory;
307 more options available via boot parameters (see above)
311 save-config - please take a look at 'save-config -h' ; restore-config
312 - please take a look at 'restore-config -h', mkpersistenthome (no
316 save-config - save configuration
317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
319 This script generates a plain bzip2 compressed tar archive containing
320 the specified files, suitable as a GCA. The following options are
321 supported for specifying which parts should be saved in the
324 -home store hidden files from $HOME ($HOME/.*)
325 -grmlhome store hidden files from \$HOME (\$HOME/.*) of user grml [use as user root]
326 -etc store modified files from /etc
327 -configdir store $HOME/config
328 -all store all configuration files (:= -home, -configdir and -etc)
330 TIP: It is also possible to use environment variables for specifying which parts
331 should be saved. Just set the corresponding variable: $SAVE_HOME, $SAVE_ETC,
332 $SAVE_CONFIGDIR and $SAVE_ALL
334 The default filename of the generated configuration file is
335 config.tbz. The following options are supported for specifying
336 another destination of the configuration file:
338 -ssh user@host:/path/to/file copy configuration via ssh/scp to remote host
339 -mail <recipient> send configuration via mail
340 -file foo_bar_config.tbz save configuration in specified file
344 save-config -all => store all configuration files in config.tbz in current dir
345 save-config -home -mail devnull@grml.org => store $HOME/.* in config.tbz and send it via mail
346 save-config -etc -ssh devnull@grml.org:/path/ => store /etc in config.tbz and scp it to specified host
347 save-config -all -file foo.tbz => store all configuration files in foo.tbz
348 SAVE_ALL=yes save-config -file /path/foo.tbz => store all configuration files in /path/foo.tbz
350 restore-config - restore configuration
351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
353 You can either restore a GCA using the boot parameters or by a script file
354 named 'restore-config'. Specify the filename of the configuration
355 archive which should be used as a parameter. The following options are
356 available to specify which parts of the archive should be extracted.
358 -home extract hidden files from $HOME ($HOME/.*)
359 -grmlhome store hidden files from \$HOME (\$HOME/.*) of user grml [use as user root]
360 -etc extract modified files from /etc
361 -configdir extract $HOME/config
363 The default is to extract (restore) all files found in the archive.
365 TIP: It is also possible to use environment variables for specifying
366 which part should be restored. Just set the corresponding variable:
367 $RESTORE_HOME, $RESTORE_ETC, $RESTORE_CONFIGDIR and $RESTORE_ALL
371 restore-config -home foo_bar_config.tbz => restore configuration from file foo_bar_config.tbz
372 restore-config config.tbz => restore configuration from file config.tbz
374 mkpersistenthome - use persistent home-directory
375 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
377 You have a local partition you would like to use as your
378 home-directory? Just use the interactive script called
379 'mkpersistenthome'. It will either create a file named grml.img on the
380 specified partition or create a partition using the ext2 filesystem
381 (you can specify the option in a dialog inside the program). grml.img
382 is a loopback device which size you can specify manually. It is
383 possible to scan through the partitions to identify the appropriate
384 partition. To use a home-directory located on your hard-drive use the
385 appropriate boot parameter on bootprompt:
387 home=/dev/sda3 => use /dev/sda3 as the homepartition
388 home=scan => scan through the available partitions and search for file grml.img
394 Personal configuration files
395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
397 You are a fan of the editor vim? Great. You probably have your own
398 ~/.vimrc and want to use it on the grml system. You also don't like
399 the default zsh configuration and want to use your own ~/.zshrc?
400 How to procede? Copy your .vimrc and .zshrc to $HOME of user 'grml'.
401 Place additional files in $HOME/config. Now create a configuration for
404 save-config -home -configdir
406 Now you should have a file named config.tbz containing your
407 configuration files. You can copy the archive to a webserver
408 and restore it via downloading during reboot using the following
409 commandline on bootprompt:
411 grml netconfig=server.tld/path/to/config.tbz
413 You don't have network access but own a floppy drive? Copy the file
414 to a floppy disk and boot with:
416 grml myconfig=/dev/fd0
418 Floppy is to small or to slow? Ok, let's use a usb device:
420 grml myconfig=/dev/sda1
423 Network configuration
424 ~~~~~~~~~~~~~~~~~~~~~
426 You need a specific network setup and want to use your own
427 /etc/network/interfaces by default? Generate the configuration
428 archive running the following command as user root:
432 Now you should have a file named config.tbz containing your
433 configuration files. If you want to use it with a floppy disk copy the
434 file to a floppy and boot via using the following command on
437 grml myconfig=/dev/fd0
439 Floppy is to small or to slow? Ok, let's use a usb device:
441 grml myconfig=/dev/sda1
443 You do have an existing harddisk installation and want to use its
444 configuration? Let's say the debian system is located in /dev/sda2. You
445 want to use the directory /etc/network. This directory is activated by
446 default in /etc/grml/partconf so we don't have to do any further work.
447 We just need to activate it via using the following commandline on
450 grml partconf=/dev/sda2
452 Automatic installation of debian packages
453 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
455 You have a specified debian package named 'foobar.deb' and want to use
456 it with (therefore: install it on) grml by default? Notice: this feature
457 is useful especially for grml-small (a ~80 MB ISO). If you want to use it
458 with the large version of grml you might have to overburn the ISO.
460 Let's assume you have burned the grml iso to a CD-RW using a commandline like:
462 cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
464 Now create a directory named debs and place foobar.deb in it:
466 mkdir debs/ && cp foobar.deb debs/
468 Notice: This directory will be located in /live/image after burning the second session.
470 Now create the second session containing this directory:
472 mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
474 Finally append the second session to the cd using:
476 cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
478 TIP: the application k3b (not available on the live-CD but available
479 through the Debian repositories) provides an easy to use interface for
480 doing the multisession task.
482 Now boot from your new personalized grml cd using the debs parameter:
486 Run your own commands on startup
487 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
489 You know that booting with 'grml service=foobar' executes
490 /etc/init.d/foobar when booting grml. But you want to setup a more
491 complex network configuration, adjust some other stuff and so on on your
492 own? Just write a script named grml.sh which does the job and use own
493 of the mentioned bootparams. Let's say you have placed grml.sh on your
494 usb device (usb stick) then use the following commandline on bootprompt:
496 grml myconfig=/dev/sda1
498 Or even better: create a floppy disk with label GRMLCFG running:
500 fdformat /dev/fd0 # format the floppy disk if not done already
501 mkfs.ext2 -L GRMLCFG /dev/fd0 # now create ext2 filesystem with label GRMLCFG on it:
503 TIP: several filesystems provide the possibility to provide a label.
504 For example FAT provides this through: 'mkfs.vfat -n GRMLCFG
505 /dev/sda1' (attention: this will destroy data on /dev/sda1 of
506 course!). Take a look at the documentation/manpage of the filesystem
509 Now place your configuration archive (see save-config and the other
510 usage scenarios) and the script grml.sh on the floppy disk. Now you can
511 boot your system without specifying any bootparameters on bootprompt
512 because devices labeled with GRMLCFG are mounted readonly and used by
513 default. If you did not label your device you can use the device anyway
514 using 'grml myconfig=/dev/ice' on the bootprompt.
519 You are responsible for a customer's system in her data center. The
520 system has failed and you need to debug from remote, and the remote
521 hands available in the data center do not have enough knowledge to get
522 grml booted and configure the network without external help?
524 If the hard disk of the system is still available, you hopefully have
525 saved a configuration file with IP address, netmask and default
526 gateway somewhere on that hard disk. grml can use the information
527 found on a partition. Take a look at the 'partconf' boot parameter.
528 Usage example: 'grml partconf=/dev/sda2' copies files defined in
529 /etc/grml/partconf from /dev/sda2 to the grml system. As /etc/network
530 is predefined in /etc/grml/partconf the configuration from /dev/sda2
533 Or you use a standard grml medium and have grml read IP address,
534 netmask and default gateway from another medium like a floppy or an USB
535 stick. Take a look at the script saveconfig and the boot parameter
538 Or you put a grml.iso file on your hard disk (maybe in /boot/grml) or
539 on an USB stick, use grub to boot from there and place debs,
540 configuration scripts or grml configuraton archives alongside the .iso.
542 Use persistent home directory
543 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
545 You want to use a persistent home directory which includes all the files
546 located in $HOME. Use the script mkpersistenthome to create such a
547 persistent home directory. You have the options to either use a
548 specific partition as your home directory or add a loopback file
549 named grml.img on the specified partition (the default).
551 TIP: /dev/external in the partition selection of mkpersistenthome is
552 an usb device without partitions. /dev/external1 corresponds to the
553 first partition on an usb device (usually an usb stick).
555 After running the script mkpersistenthome you can use the boot
556 parameter home to activate the home directory. If you are using the
557 option with the loopback file (grml.img) you can boot via:
561 which will scan through the partitions and if a file grml.img is found
562 it will be mounted as your $HOME-directory. If you want to use a
563 partition as your home directory specify the device as an option. If
564 you want to use /dev/sda2 as your $HOME boot via:
568 Notice: the files located in /etc/skel will be copied to the partition
569 (but will not overwrite any files).
573 Please report feedback, bugreports and wishes link:http://grml.org/contact/[to us]!
577 (c) 2005++, Michael Prokop <mika@grml.org>