doc/grml-autoconfig.1.txt

   1 grml-autoconfig(1)
   2 ==================
   3
   4 Name
   5 ----
   6 grml-autoconfig - main bootup process of a grml system
   7
   8 Synopsis
   9 --------
  10 None - it is a framework. See grml-autoconfig(8) for information regarding
  11 the interface script.
  12
  13 Introduction
  14 ------------
  15
  16 By using the config framework, it is possible to customize Grml's startup in a
  17 multitude of ways. It allows to:
  18
  19 - execute one or more scripts on startup
  20 - install Debian packages from deb files on startup
  21 - unpack configuration on startup
  22
  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.
  27
  28 The DCS handling is controlled by a number of boot parameters.
  29
  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.
  34
  35 [TIP]
  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.
  40
  41 [IMPORTANT]
  42 Starting with Grml release 2009.05 its possible to use root persistency on grml.
  43 This means you can store your settings and reuse them on reboot, without having
  44 to deal with this config framework. Visit
  45 link:http://wiki.grml.org/doku.php?id=persistency[] for further information.
  46
  47 [[current-versions]]
  48 include::grml-autoconfig.current.txt[]
  49
  50 Permanently adjust boot parameters
  51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52
  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
  59 to booting without any special parameters).
  60
  61   mkdir bootparams
  62   echo lang=de > bootparams/my_bootparams
  63
  64 Then burn a multisession CD where directory bootparams is located in the root
  65 directory of the CD.
  66
  67 [NOTE]
  68 Not all boot parameters can be used via /bootparams/. This is a limitation of
  69 the way the kernel and userspace retrieve boot parameters. Boot parameter
  70 regarding the kernel definitely do *NOT* work. Boot parameter related to
  71 grml-autoconfig (the main part of the boot process in Grml running in userspace,
  72 being all the stuff after startup of udev) are expected to work. Boot parameter
  73 related to initrd/initramfs (the part between 'Searching for GRML file' and
  74 startup of udev) are *NOT* covered by /bootparams/ as well yet.
  75
  76 TIP: the application k3b (not available on the live-CD but available through the
  77 Debian repositories) provides an easy to use interface for doing the
  78 multisession task.
  79
  80 [[X7]]
  81 Usage scenarios
  82 ---------------
  83
  84 Personal configuration files
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 You are a fan of the editor vim? Great. You probably have your own ~/.vimrc and
  88 want to use it on the Grml system. You also don't like the default zsh
  89 configuration and want to use your own ~/.zshrc?  How to procede? Copy your
  90 .vimrc and .zshrc to $HOME of user 'grml'.  Place additional files in
  91 $HOME/config. Now create a configuration for your files running:
  92
  93   save-config -home -configdir
  94
  95 Now you should have a file named config.tbz containing your configuration files.
  96 You can copy the archive to a webserver and restore it via downloading during
  97 reboot using the following commandline on bootprompt:
  98
  99   grml netconfig=server.tld/path/to/config.tbz
 100
 101 You don't have network access but own a floppy drive? Copy the file to a floppy
 102 disk and boot with:
 103
 104   grml myconfig=/dev/fd0
 105
 106 Floppy is to small or to slow? Ok, let's use a usb device:
 107
 108   grml myconfig=/dev/sda1
 109
 110 Network configuration
 111 ~~~~~~~~~~~~~~~~~~~~~
 112
 113 You need a specific network setup and want to use your own
 114 /etc/network/interfaces by default? Generate the configuration archive running
 115 the following command as user root:
 116
 117   save-config -etc
 118
 119 Now you should have a file named config.tbz containing your configuration files.
 120 If you want to use it with a floppy disk copy the file to a floppy and boot via
 121 using the following command on bootprompt:
 122
 123   grml myconfig=/dev/fd0
 124
 125 Floppy is to small or to slow? Ok, let's use a usb device:
 126
 127   grml myconfig=/dev/sda1
 128
 129 You do have an existing harddisk installation and want to use its configuration?
 130 Let's say the debian system is located in /dev/sda2. You want to use the
 131 directory /etc/network. This directory is activated by default in
 132 /etc/grml/partconf so we don't have to do any further work.  We just need to
 133 activate it via using the following commandline on bootprompt:
 134
 135   grml partconf=/dev/sda2
 136
 137 Automatic installation of debian packages
 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 139
 140 You have a specified debian package named 'foobar.deb' and want to use it with
 141 (therefore: install it on) Grml by default? Notice: this feature is useful
 142 especially for grml-small (a ~100 MB ISO). If you want to use it with the large
 143 version of Grml you might have to overburn the ISO.
 144
 145 Let's assume you have burned the Grml iso to a CD-RW using a commandline like:
 146
 147   cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
 148
 149 Now create a directory named debs and place foobar.deb in it:
 150
 151   mkdir debs/ && cp foobar.deb debs/
 152
 153 Notice: This directory will be located in /live/image after burning the second
 154 session.
 155
 156 Now create the second session containing this directory:
 157
 158   mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
 159
 160 Finally append the second session to the cd using:
 161
 162   cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
 163
 164 TIP: the application k3b (not available on the live CD but available through the
 165 Debian repositories) provides an easy to use interface for doing the
 166 multisession task.
 167
 168 Now boot from your new personalized Grml CD using the debs parameter:
 169
 170   grml debs
 171
 172 Run your own commands on startup
 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 174
 175 You know that booting with 'grml service=foobar' executes /etc/init.d/foobar
 176 when booting Grml. But you want to setup a more complex network configuration,
 177 adjust some other stuff and so on on your own? Just write a script named grml.sh
 178 which does the job and use own of the mentioned bootparams. Let's say you have
 179 placed grml.sh on your usb device (usb stick) then use the following commandline
 180 on bootprompt:
 181
 182   grml myconfig=/dev/sda1
 183
 184 Or even better: create a floppy disk with label GRMLCFG running:
 185
 186   fdformat /dev/fd0   # format the floppy disk if not done already
 187   mkfs.ext2 -L GRMLCFG /dev/fd0   # now create ext2 filesystem with label GRMLCFG on it:
 188
 189 TIP: several filesystems provide the possibility to provide a label.  For
 190 example FAT provides this through: 'mkfs.vfat -n GRMLCFG /dev/sda1' (attention:
 191 this will destroy data on /dev/sda1 of course!). Take a look at the
 192 documentation/manpage of the filesystem you want to use.
 193
 194 Now place your configuration archive (see save-config and the other usage
 195 scenarios) and the script grml.sh on the floppy disk. Now you can boot your
 196 system without specifying any bootparameters on bootprompt because devices
 197 labeled with GRMLCFG are mounted readonly and used by default. If you did not
 198 label your device you can use the device anyway using 'grml myconfig=/dev/ice'
 199 on the bootprompt.
 200
 201 Debug remote systems
 202 ~~~~~~~~~~~~~~~~~~~~
 203
 204 You are responsible for a customer's system in her data center. The system has
 205 failed and you need to debug from remote, and the remote hands available in the
 206 data center do not have enough knowledge to get Grml booted and configure the
 207 network without external help?
 208
 209 If the hard disk of the system is still available, you hopefully have saved a
 210 configuration file with IP address, netmask and default gateway somewhere on
 211 that hard disk. Grml can use the information found on a partition. Take a look
 212 at the 'partconf' boot parameter.  Usage example: 'grml partconf=/dev/sda2'
 213 copies files defined in /etc/grml/partconf from /dev/sda2 to the Grml system. As
 214 /etc/network is predefined in /etc/grml/partconf the configuration from
 215 /dev/sda2 will be taken.
 216
 217 Or you use a standard Grml medium and have grml read IP address, netmask and
 218 default gateway from another medium like a floppy or an USB stick. Take a look
 219 at the script saveconfig and the boot parameter myconfig.
 220
 221 Or you put a grml.iso file on your hard disk (maybe in /boot/grml) or on an USB
 222 stick, use grub to boot from there and place debs, configuration scripts or Grml
 223 configuraton archives alongside the .iso.
 224
 225 Bugs
 226 ----
 227 If you find a bug please report it. See link:http://grml.org/bugs/[] for details
 228 about how to report bugs.
 229
 230 See also
 231 --------
 232 grml-autoconfig(8), restore-config(1), save-config(1)
 233
 234 Author
 235 ------
 236 (c) 2005++, Michael Prokop <mika@grml.org>