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 [[X7]]
  51 Usage scenarios
  52 ---------------
  53
  54 Personal configuration files
  55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56
  57 You are a fan of the editor vim? Great. You probably have your own ~/.vimrc and
  58 want to use it on the Grml system. You also don't like the default zsh
  59 configuration and want to use your own ~/.zshrc?  How to proceed? Copy your
  60 .vimrc and .zshrc to $HOME of user 'grml'.  Place additional files in
  61 $HOME/config. Now create a configuration for your files running:
  62
  63   save-config -home -configdir
  64
  65 Now you should have a file named config.tbz containing your configuration files.
  66 You can copy the archive to a webserver and restore it via downloading during
  67 reboot using the following commandline on bootprompt:
  68
  69   grml netconfig=server.tld/path/to/config.tbz
  70
  71 You don't have network access but own a USB device? Copy the file to a USB
  72 device and boot with something like:
  73
  74   grml myconfig=/dev/sda1
  75
  76 Network configuration
  77 ~~~~~~~~~~~~~~~~~~~~~
  78
  79 You need a specific network setup and want to use your own
  80 /etc/network/interfaces by default? Generate the configuration archive running
  81 the following command as user root:
  82
  83   save-config -etc
  84
  85 Now you should have a file named config.tbz containing your configuration files.
  86 If you want to use it with a USB device copy the file to it and boot via
  87 using the following command on boot prompt:
  88
  89   grml myconfig=/dev/sda1
  90
  91 You do have an existing harddisk installation and want to use its configuration?
  92 Let's say the Debian system is located in /dev/sda2. You want to use the
  93 directory /etc/network. This directory is activated by default in
  94 /etc/grml/partconf so we don't have to do any further work.  We just need to
  95 activate it via using the following commandline on bootprompt:
  96
  97   grml partconf=/dev/sda2
  98
  99 Automatic installation of debian packages
 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 101
 102 You have a specified debian package named 'foobar.deb' and want to use it with
 103 (therefore: install it on) Grml by default? Notice: this feature is useful
 104 especially for grml-small (a ~100 MB ISO). If you want to use it with the large
 105 version of Grml you might have to overburn the ISO.
 106
 107 Let's assume you have burned the Grml iso to a CD-RW using a commandline like:
 108
 109   cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
 110
 111 Now create a directory named debs and place foobar.deb in it:
 112
 113   mkdir debs/ && cp foobar.deb debs/
 114
 115 Notice: This directory will be located in /lib/live/mount/medium after burning the second
 116 session.
 117
 118 Now create the second session containing this directory:
 119
 120   mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
 121
 122 Finally append the second session to the cd using:
 123
 124   cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
 125
 126 TIP: the application k3b (not available on the live CD but available through the
 127 Debian repositories) provides an easy to use interface for doing the
 128 multisession task.
 129
 130 Now boot from your new personalized Grml CD using the debs parameter:
 131
 132   grml debs
 133
 134 Run your own commands on startup
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137 You know that booting with 'grml services=foobar' executes
 138 /etc/init.d/foobar when booting Grml. But you want to setup a more
 139 complex network configuration, adjust some other stuff and so on, on
 140 your own? Just write a script named grml.sh which does the job and use
 141 one of the mentioned boot parameters. Let's say you have placed grml.sh
 142 on your usb device (usb stick) then use the following commandline on
 143 bootprompt:
 144
 145   grml myconfig=/dev/sda1
 146
 147 Or even better: create a device with label GRMLCFG running (adjust /dev/sdX1
 148 according to your needs):
 149
 150   mkfs.ext3 -L GRMLCFG /dev/sdX1  # warning: this destroys all data on /dev/sdX1
 151
 152 TIP: several filesystems provide the possibility to provide a label.  For
 153 example FAT provides this through: 'mkfs.vfat -n GRMLCFG /dev/sda1' (attention:
 154 this will destroy data on /dev/sda1 of course!). Take a look at the
 155 documentation/manpage of the filesystem you want to use.
 156
 157 Now place your configuration archive (see save-config and the other
 158 usage scenarios) and the script grml.sh on the device. Now you can boot
 159 your system without specifying any boot parameters on bootprompt because
 160 devices labeled with GRMLCFG are mounted readonly and used by default.
 161 If you did not label your device you can use the device anyway using
 162 'grml myconfig=/dev/sdX' (adjust /dev/sdX) on the bootprompt.
 163
 164 Debug remote systems
 165 ~~~~~~~~~~~~~~~~~~~~
 166
 167 You are responsible for a customer's system in her data center. The system has
 168 failed and you need to debug from remote, and the remote hands available in the
 169 data center do not have enough knowledge to get Grml booted and configure the
 170 network without external help?
 171
 172 If the hard disk of the system is still available, you hopefully have saved a
 173 configuration file with IP address, netmask and default gateway somewhere on
 174 that hard disk. Grml can use the information found on a partition. Take a look
 175 at the 'partconf' boot parameter.  Usage example: 'grml partconf=/dev/sda2'
 176 copies files defined in /etc/grml/partconf from /dev/sda2 to the Grml system. As
 177 /etc/network is predefined in /etc/grml/partconf the configuration from
 178 /dev/sda2 will be taken.
 179
 180 Or you use a standard Grml medium and have grml read IP address, netmask and
 181 default gateway from another medium like a USB stick. Take a look at the script
 182 saveconfig and the boot parameter myconfig.
 183
 184 Or you put a grml.iso file on your hard disk (maybe in /boot/grml) or on an USB
 185 stick, use grub to boot from there and place debs, configuration scripts or Grml
 186 configuration archives alongside the .iso.
 187
 188 Bugs
 189 ----
 190 If you find a bug please report it. See link:http://grml.org/bugs/[] for details
 191 about how to report bugs.
 192
 193 See also
 194 --------
 195 grml-autoconfig(8), restore-config(1), save-config(1)
 196
 197 Author
 198 ------
 199 (c) 2005++, Michael Prokop <mika@grml.org>