6 grml-autoconfig - main bootup process of a grml system
10 None - it is a framework. See grml-autoconfig(8) for information regarding
16 By using the config framework, it is possible to customize Grml's startup in a
17 multitude of ways. It allows to:
19 - execute one or more scripts on startup
20 - install Debian packages from deb files on startup
21 - unpack configuration on startup
23 The combination of Debs, Configuration and Scripts is called DCS in Grml. DCS
24 can be read from the Live Image itself, from an arbitrary file system on the
25 local system which is marked with the volume label GRMLCFG, or from the file
26 system pointed to by the myconfig boot parameter.
28 The DCS handling is controlled by a number of boot parameters.
30 The scripts save-config and restore-config can be used to create and handle
31 files called 'grml configuration archive', abbreviated GCA. save-config stores
32 the running configuration inside a GCA; restore-config is a script to restore a
33 configuration from a GCA.
36 A GCA is a plain bzip2 compressed tar archive. All the files are generated
37 starting from the root-directory '/' so it is easy to handle. You can generate
38 configuration archives manually as well. save-config is just a frontend which
39 should make it easier to use.
41 The grml-autoconfig code has been re-worked in August 2009. This document
42 handles both the behavior of Grml releases up to 2009.05 (see
43 <<up-to-200905,section 'Behavior up to grml 2009.05'>>) and the current behavior
44 (see <<current-versions,section 'Behavior in current Grml versions'>>). Great
45 care has been taken to provide maximum backwards compatibility during the
49 Starting with grml release 2009.05 its possible to use root persistency on grml.
50 This means you can store your settings and reuse them on reboot, without having
51 to deal with this config framework. Visit
52 link:http://wiki.grml.org/doku.php?id=persistency for further information.
55 Behavior up to grml 2009.05
56 ---------------------------
58 This section applies to all Grml versions older than and including release 2009.05.
63 By default the booting process tries to mount a device labeled 'GRMLCFG'. This
64 provides the possibility to restore a configuration (named config.tbz) and
65 execute a script (named grml.sh) without the need to specify any bootparams. If
66 you want to disable this feature please take a look at the 'noautoconfig'
72 As you probably know you can adjust boot parameters on the bootprompt. You want
73 to set some boot parameters permanently? That's possible via adding a directory
74 named 'bootparams' to the Grml-ISO which has to be located at the root-directory
75 /bootparams/ (note: the directory is known as /live/image/bootparams/ on a
76 _running_ grml system then). Place a textfile inside the directory containing
77 the boot parameters which should be appended to default ones (this corresponds
78 to booting without any special parameters). If you want to be able to boot from
79 your Grml-CD you have to create a multisession CD. See the <<X7,usage
80 scenarios>> for more details how to use it or consider booting from a USB device
83 The following boot parameters are supported. Use them at the (isolinux)
84 bootprompt as documented here.
88 This parameter is for restoring configuration using the file config.tbz
89 on the specified device. Usage examples:
91 myconfig=/dev/sda1 => use file config.tbz from usb-device
92 myconfig=/dev/fd0 => use file config.tbz from floppy-disk
93 myconfig=/dev/sda1 file=config_foobar.tbz => use file config_foobar.tbz from usb-device
97 This parameter is for setting a specific partition as home directory.
100 home=/dev/sda3 => use /dev/sda3 as the homepartition
101 home=scan => scan through the available partitions and search
106 This parameter mounts the specified device in read-only mode and tries to
107 copy all files specified in /etc/grml/partconf to the Grml system. This
108 provides the possibility to use the configuration of a harddisk
109 installation. For example using the network configuration (which is
110 specified in /etc/network) is possible using this boot parameter. Usage
113 partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
114 in /etc/grml/partconf to the booted Grml system
118 Use this parameter to restore configuration using wget to download a
119 configuration file from specified destination. Usage example:
121 netconfig=server.tld/path/to/config.tbz => restore configuration using wget to download file config.tbz
125 Extract specific directories from configuration archive. Notice: This
126 bootparam is useful only with bootparams which are able to extract
127 configuration archives.
129 extract=/home/grml => extract only /home/grml from archive
130 extract=/etc => extract only /etc from archive
131 extract=/home/grml/config => extract only $HOME/config from archive
135 This parameter executes a script located in the root-directory /scripts/ on
136 the Grml media/ISO (note: the directory is known as /live/image/scripts/ on
137 a _running_ Grml system then). Usage examples:
139 scripts => run script [/live/image]/scripts/grml.sh
140 scripts=foobar.sh => run script foobar.sh in [/live/image]/scripts/
144 This parameter restores a configuration using root-directory /config/ on the
145 Grml media/ISO (note: the directory is known as /live/image/config on a
146 _running_ Grml system then). Usage examples:
148 config => restore configuration using file config.tbz from directory [/live/image]/config/
149 config=config_foobar.tbz => restore configuration using file config_foobar.tbz from directory [/live/image]/config/
153 This parameter allows automatic installation of deb packages while booting.
154 The debian packages have to be located in the root-directory /debs/ on the
155 Grml media/ISO (note: the directory is known as /live/image/debs/ on a
156 _running_ Grml system then). Usage examples:
158 debs => install all debian packages (suffix .deb) from directory [/live/image]/debs/
159 debs=01 => install all debian packages (suffix .deb) starting with 01 in the filename from directory [/live/image]/debs/
164 Deactivate automounting. By default the command 'mount' tries to mount a
165 device with label 'GRMLCFG'. If you specify the noautoconfig bootparam the
166 automounting will be deactivated.
168 noautoconfig => disables auto mounting of label 'GRMLCFG'
171 Behavior in current Grml versions
172 ---------------------------------
174 This section applies to all Grml versions newer than release 2009.05.
176 The central concept of grml-autoconfig is the DCS directory which holds debs,
177 configuration and scripts which are used during system startup.
179 Determination of DCS directory
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182 The DCS directory defaults to the root directory of the GRML live image. If a
183 file system labeled GRMLCFG is found, the DCS directory is the root directory of
184 that file system. Alternatively, the myconfig boot parameter can be used to
185 directly specify a device which is then taken as DCS directory
186 (myconfig=/dev/sda1, for example).
188 Without any additional boot parameters, the GCA at DCSDIR/config.tbz is
189 automatically unpacked and DCSDIR/scrips/grml.sh is automaitcally executed on
190 system startup. The 'noautoconfig' boot parameter disables this automatic
196 The following boot parameters are supported. Use them at the (isolinux)
197 bootprompt as documented here.
201 This parameter directly sets DCSDIR to the root directory of the specified
202 device. Usage examples:
204 myconfig=/dev/sda1 => read DCS from usb-device
205 myconfig=/dev/fd0 => read DCS from floppy-disk
209 This parameter is for setting a specific partition as home directory. Usage
212 home=/dev/sda3 => use /dev/sda3 as the homepartition
213 home=scan => scan through the available partitions and search
218 This parameter mounts the specified device in read-only mode and tries to
219 copy all files specified in /etc/grml/partconf to the Grml system. This
220 provides the possibility to use the configuration of a harddisk
221 installation. For example using the network configuration (which is
222 specified in /etc/network) is possible using this boot parameter. Usage
225 partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
226 in /etc/grml/partconf to the booted Grml system
230 Use this parameter to restore configuration using wget to download a GCA
231 from the specified destination. You can also add variables to change the
232 file name depending on the host configuration. Predefined and useful
233 variables are $ARCH, $HOSTNAME and $KERNEL. Usage example:
235 netconfig=server.tld/path/to/config.tbz => restore configuration using wget to download file config.tbz
236 netconfig=server.tld/config-$ARCH.tbz => download config for specified architecture
239 Use this parameter to download and run a script from specified destination:
240 You can also add variables to change the file name depending on the host
241 configuration. Predefined and useful variables are $ARCH, $HOSTNAME and
242 $KERNEL. Usage example:
244 netcript=server.tld/path/to/script => download and run script/executable from server
245 netscript=server.tld/script-$HOSTNAME => download and run script/executable for specific host
249 Extract specific directories from the GCA which needs to be specified by
252 extract=/home/grml => extract only /home/grml from archive
253 extract=/etc => extract only /etc from archive
254 extract=/home/grml/config => extract only $HOME/config from archive
258 This parameter executes scripts. If an optional path is given, it is
259 relative to DCSDIR. If it points to a directory, all scripts inside this
260 directory are executed. If the path points to a file, this single file is
261 executed. If no path is given, it defaults to scripts/grml.sh. Usage
264 scripts => run script DCSDIR/scripts/grml.sh
265 scripts=foobar.sh => run script foobar.sh in DCSDIR
266 scripts=foobar => run all scripts inside DCSDIR/foobar directory
270 This parameter restores a configuration using a GCA. If an optional path is
271 given, it is relative to DCSDIR. If no path is given, it defaults to
272 DCSDIR/config.tbz. Usage examples:
274 config => restore configuration using file DCSDIR/config.tbz
275 config=config_foobar.tbz => restore configuration using file DCSDIR/config_foobar.tbz
279 This parameter allows automatic installation of deb packages while booting.
280 The path is relative to DCSDIR, not optional and is a shell wildcard. All
281 Files matching the wildcard are installed in a single dpkg --install call.
282 For backwards compatibility, if no slash is contained in the path, it is
283 taken relative to DCSDIR/debs.
287 debs=*.deb => install all debian packages (suffix .deb) from directory DCSDIR/debs/
288 debs=foo/01*.deb => install all debian packages (suffix .deb) starting with 01 in the filename from directory DCSDIR/foo
293 Deactivate automounting. By default the scripts try to mount a device with
294 label 'GRMLCFG'. If you specify the noautoconfig bootparam this automounting
297 noautoconfig => disables auto mounting of label 'GRMLCFG'
300 Permanently adjust boot parameters
301 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
303 As you probably know you can adjust boot parameters on the bootprompt. You want
304 to set some boot parameters permanently? That's possible via adding a directory
305 named 'bootparams' to the Grml ISO which has to be located at the root-directory
306 /bootparams/ (note: the directory is known as /live/image/bootparams/ on a
307 _running_ Grml system then). Place a textfile inside the directory containing
308 the boot parameters which should be appended to default ones (this corresponds
309 to booting without any special parameters).
312 echo lang=de > bootparams/my_bootparams
314 Then burn a multisession CD where directory bootparams is located in the root
318 Not all boot parameters can be used via /bootparams/. This is a limitation of
319 the way the kernel and userspace retrieve boot parameters. Boot parameter
320 regarding the kernel definitely do *NOT* work. Boot parameter related to
321 grml-autoconfig (the main part of the boot process in Grml running in userspace,
322 being all the stuff after startup of udev) are expected to work. Boot parameter
323 related to initrd/initramfs (the part between 'Searching for GRML file' and
324 startup of udev) are *NOT* covered by /bootparams/ as well yet.
326 TIP: the application k3b (not available on the live-CD but available through the
327 Debian repositories) provides an easy to use interface for doing the
334 Personal configuration files
335 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
337 You are a fan of the editor vim? Great. You probably have your own ~/.vimrc and
338 want to use it on the Grml system. You also don't like the default zsh
339 configuration and want to use your own ~/.zshrc? How to procede? Copy your
340 .vimrc and .zshrc to $HOME of user 'grml'. Place additional files in
341 $HOME/config. Now create a configuration for your files running:
343 save-config -home -configdir
345 Now you should have a file named config.tbz containing your configuration files.
346 You can copy the archive to a webserver and restore it via downloading during
347 reboot using the following commandline on bootprompt:
349 grml netconfig=server.tld/path/to/config.tbz
351 You don't have network access but own a floppy drive? Copy the file to a floppy
354 grml myconfig=/dev/fd0
356 Floppy is to small or to slow? Ok, let's use a usb device:
358 grml myconfig=/dev/sda1
360 Network configuration
361 ~~~~~~~~~~~~~~~~~~~~~
363 You need a specific network setup and want to use your own
364 /etc/network/interfaces by default? Generate the configuration archive running
365 the following command as user root:
369 Now you should have a file named config.tbz containing your configuration files.
370 If you want to use it with a floppy disk copy the file to a floppy and boot via
371 using the following command on bootprompt:
373 grml myconfig=/dev/fd0
375 Floppy is to small or to slow? Ok, let's use a usb device:
377 grml myconfig=/dev/sda1
379 You do have an existing harddisk installation and want to use its configuration?
380 Let's say the debian system is located in /dev/sda2. You want to use the
381 directory /etc/network. This directory is activated by default in
382 /etc/grml/partconf so we don't have to do any further work. We just need to
383 activate it via using the following commandline on bootprompt:
385 grml partconf=/dev/sda2
387 Automatic installation of debian packages
388 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
390 You have a specified debian package named 'foobar.deb' and want to use it with
391 (therefore: install it on) Grml by default? Notice: this feature is useful
392 especially for grml-small (a ~100 MB ISO). If you want to use it with the large
393 version of Grml you might have to overburn the ISO.
395 Let's assume you have burned the Grml iso to a CD-RW using a commandline like:
397 cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
399 Now create a directory named debs and place foobar.deb in it:
401 mkdir debs/ && cp foobar.deb debs/
403 Notice: This directory will be located in /live/image after burning the second
406 Now create the second session containing this directory:
408 mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
410 Finally append the second session to the cd using:
412 cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
414 TIP: the application k3b (not available on the live CD but available through the
415 Debian repositories) provides an easy to use interface for doing the
418 Now boot from your new personalized Grml CD using the debs parameter:
422 Run your own commands on startup
423 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
425 You know that booting with 'grml service=foobar' executes /etc/init.d/foobar
426 when booting Grml. But you want to setup a more complex network configuration,
427 adjust some other stuff and so on on your own? Just write a script named grml.sh
428 which does the job and use own of the mentioned bootparams. Let's say you have
429 placed grml.sh on your usb device (usb stick) then use the following commandline
432 grml myconfig=/dev/sda1
434 Or even better: create a floppy disk with label GRMLCFG running:
436 fdformat /dev/fd0 # format the floppy disk if not done already
437 mkfs.ext2 -L GRMLCFG /dev/fd0 # now create ext2 filesystem with label GRMLCFG on it:
439 TIP: several filesystems provide the possibility to provide a label. For
440 example FAT provides this through: 'mkfs.vfat -n GRMLCFG /dev/sda1' (attention:
441 this will destroy data on /dev/sda1 of course!). Take a look at the
442 documentation/manpage of the filesystem you want to use.
444 Now place your configuration archive (see save-config and the other usage
445 scenarios) and the script grml.sh on the floppy disk. Now you can boot your
446 system without specifying any bootparameters on bootprompt because devices
447 labeled with GRMLCFG are mounted readonly and used by default. If you did not
448 label your device you can use the device anyway using 'grml myconfig=/dev/ice'
454 You are responsible for a customer's system in her data center. The system has
455 failed and you need to debug from remote, and the remote hands available in the
456 data center do not have enough knowledge to get Grml booted and configure the
457 network without external help?
459 If the hard disk of the system is still available, you hopefully have saved a
460 configuration file with IP address, netmask and default gateway somewhere on
461 that hard disk. Grml can use the information found on a partition. Take a look
462 at the 'partconf' boot parameter. Usage example: 'grml partconf=/dev/sda2'
463 copies files defined in /etc/grml/partconf from /dev/sda2 to the Grml system. As
464 /etc/network is predefined in /etc/grml/partconf the configuration from
465 /dev/sda2 will be taken.
467 Or you use a standard Grml medium and have grml read IP address, netmask and
468 default gateway from another medium like a floppy or an USB stick. Take a look
469 at the script saveconfig and the boot parameter myconfig.
471 Or you put a grml.iso file on your hard disk (maybe in /boot/grml) or on an USB
472 stick, use grub to boot from there and place debs, configuration scripts or Grml
473 configuraton archives alongside the .iso.
475 Use persistent home directory
476 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
478 You want to use a persistent home directory which includes all the files located
479 in $HOME. Use the script mkpersistenthome to create such a persistent home
480 directory. You have the options to either use a specific partition as your home
481 directory or add a loopback file named grml.img on the specified partition (the
484 TIP: /dev/external in the partition selection of mkpersistenthome is an usb
485 device without partitions. /dev/external1 corresponds to the first partition on
486 an usb device (usually an usb stick).
488 After running the script mkpersistenthome you can use the boot parameter home to
489 activate the home directory. If you are using the option with the loopback file
490 (grml.img) you can boot via:
494 which will scan through the partitions and if a file grml.img is found it will
495 be mounted as your $HOME-directory. If you want to use a partition as your home
496 directory specify the device as an option. If you want to use /dev/sda2 as your
501 Notice: the files located in /etc/skel will be copied to the partition (but will
502 not overwrite any files).
506 If you find a bug please report it. See link:http://grml.org/bugs/ for details
507 about how to report bugs.
511 grml-autoconfig(8), mkpersistenthome(1), restore-config(1), save-config(1)
515 (c) 2005++, Michael Prokop <mika@grml.org>