doc/grml-autoconfig.txt

   1 grml-autoconfig
   2 ===============
   3
   4 Introduction
   5 ------------
   6
   7 By using the config framework, it is possible to customize grml's
   8 startup in a multitude of ways. It allows to:
   9
  10 - execute one or more scripts on startup
  11 - install Debian packages from deb files on startup
  12 - unpack configuration on startup
  13
  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
  18 parameter.
  19
  20 The DCS handling is controlled by a number of boot parameters.
  21
  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.
  26
  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.
  31
  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.
  36
  37
  38 Behavior up to grml 2009.05
  39 ---------------------------
  40
  41 Autoconfiguration
  42 ~~~~~~~~~~~~~~~~~
  43
  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.
  49
  50 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 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
  62 grml2usb).
  63
  64 The following boot parameters are supported. Use them at the (isolinux)
  65 bootprompt as documented here.
  66
  67 myconfig::
  68
  69    This parameter is for restoring configuration using the file config.tbz
  70     on the specified device. Usage examples:
  71
  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
  75
  76 home::
  77
  78     This parameter is for setting a specific partition as home directory.
  79     Usage examples:
  80
  81   home=/dev/sda3    =>  use /dev/sda3 as the homepartition
  82   home=scan         =>  scan through the available partitions and search
  83                         for file grml.img
  84
  85 partconf::
  86
  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:
  93
  94     partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
  95                           in /etc/grml/partconf to the booted grml system
  96
  97 netconfig::
  98     Use this parameter to restore configuration using wget to download
  99     a configuration file from specified destination. Usage example:
 100
 101   netconfig=server.tld/path/to/config.tbz  =>   restore configuration using wget to download file config.tbz
 102
 103 extract::
 104
 105     Extract specific directories from configuration archive. Notice:
 106     This bootparam is useful only with bootparams which are able to
 107     extract configuration archives.
 108
 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
 112
 113 scripts::
 114
 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:
 118
 119   scripts               =>   run script [/live/image]/scripts/grml.sh
 120   scripts=foobar.sh     =>   run script foobar.sh in [/live/image]/scripts/
 121
 122 config::
 123
 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:
 127
 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/
 130
 131 debs::
 132
 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:
 137
 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/
 140
 141
 142 noautoconfig::
 143
 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.
 147
 148   noautoconfig            => disables auto mounting of label 'GRMLCFG'
 149
 150
 151 Behavior in current development snapshots
 152 -----------------------------------------
 153
 154 The central concept of grml-autoconfig is the DCS directory which
 155 holds debs, configuration and scripts which are used during system
 156 startup.
 157
 158
 159 Determination of DCS directory
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 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).
 167
 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.
 172
 173
 174 Boot Parameters
 175 ~~~~~~~~~~~~~~~
 176
 177 The following boot parameters are supported. Use them at the (isolinux)
 178 bootprompt as documented here.
 179
 180 myconfig::
 181
 182    This parameter directly sets DCSDIR to the root directory of the
 183    specified device. Usage examples:
 184
 185   myconfig=/dev/sda1                        => read DCS from usb-device
 186   myconfig=/dev/fd0                         => read DCS from floppy-disk
 187
 188 home::
 189
 190     This parameter is for setting a specific partition as home directory.
 191     Usage examples:
 192
 193   home=/dev/sda3    =>  use /dev/sda3 as the homepartition
 194   home=scan         =>  scan through the available partitions and search
 195                         for file grml.img
 196
 197 partconf::
 198
 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:
 205
 206     partconf=/dev/sda2 => try to mount /dev/sda2 and copy files specified
 207                           in /etc/grml/partconf to the booted grml system
 208
 209 netconfig::
 210     Use this parameter to restore configuration using wget to download
 211     a GCA from the specified destination. Usage example:
 212
 213   netconfig=server.tld/path/to/config.tbz  =>   restore configuration using wget to download file config.tbz
 214
 215 extract::
 216
 217     Extract specific directories from the GCA which needs to be
 218     specified by other means.
 219
 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
 223
 224 scripts::
 225
 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:
 231
 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
 235
 236 config::
 237
 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:
 241
 242   config                    =>   restore configuration using file DCSDIR/config.tbz
 243   config=config_foobar.tbz  =>   restore configuration using file DCSDIR/config_foobar.tbz
 244
 245 debs::
 246
 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.
 252
 253     Usage examples:
 254
 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
 257
 258
 259 noautoconfig::
 260
 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.
 264
 265   noautoconfig            => disables auto mounting of label 'GRMLCFG'
 266
 267
 268 Permanently adjust boot parameters
 269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 270
 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).
 278
 279   mkdir bootparams
 280   echo lang=de > bootparams/my_bootparams
 281
 282 Then burn a multisession CD where directory bootparams is located in the root
 283 directory of the CD.
 284
 285 [NOTE]
 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.
 293
 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.
 297
 298
 299
 300 Scripts
 301 -------
 302
 303 NAME
 304 ~~~~
 305 save-config - save configuration ; restore-config - restore
 306 configuration; mkpersistenthome - create persistent home directory;
 307 more options available via boot parameters (see above)
 308
 309 SYNOPSIS
 310 ~~~~~~~~
 311 save-config - please take a look at 'save-config -h' ; restore-config
 312 - please take a look at 'restore-config -h', mkpersistenthome (no
 313 options available)
 314
 315
 316 save-config - save configuration
 317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 318
 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
 322 configuration file:
 323
 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)
 329
 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
 333
 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:
 337
 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
 341
 342 Usage examples:
 343
 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
 349
 350 restore-config - restore configuration
 351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 352
 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.
 357
 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
 362
 363 The default is to extract (restore) all files found in the archive.
 364
 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
 368
 369 Usage examples:
 370
 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
 373
 374 mkpersistenthome - use persistent home-directory
 375 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 376
 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:
 386
 387   home=/dev/sda3    =>   use /dev/sda3 as the homepartition
 388   home=scan         =>   scan through the available partitions and search for file grml.img
 389
 390 [[X7]]
 391 Usage scenarios
 392 ---------------
 393
 394 Personal configuration files
 395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 396
 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
 402 your files running:
 403
 404   save-config -home -configdir
 405
 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:
 410
 411   grml netconfig=server.tld/path/to/config.tbz
 412
 413 You don't have network access but own a floppy drive? Copy the file
 414 to a floppy disk and boot with:
 415
 416   grml myconfig=/dev/fd0
 417
 418 Floppy is to small or to slow? Ok, let's use a usb device:
 419
 420   grml myconfig=/dev/sda1
 421
 422
 423 Network configuration
 424 ~~~~~~~~~~~~~~~~~~~~~
 425
 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:
 429
 430   save-config -etc
 431
 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
 435 bootprompt:
 436
 437   grml myconfig=/dev/fd0
 438
 439 Floppy is to small or to slow? Ok, let's use a usb device:
 440
 441   grml myconfig=/dev/sda1
 442
 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
 448 bootprompt:
 449
 450   grml partconf=/dev/sda2
 451
 452 Automatic installation of debian packages
 453 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 454
 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.
 459
 460 Let's assume you have burned the grml iso to a CD-RW using a commandline like:
 461
 462   cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
 463
 464 Now create a directory named debs and place foobar.deb in it:
 465
 466   mkdir debs/ && cp foobar.deb debs/
 467
 468 Notice: This directory will be located in /live/image after burning the second session.
 469
 470 Now create the second session containing this directory:
 471
 472   mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
 473
 474 Finally append the second session to the cd using:
 475
 476   cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
 477
 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.
 481
 482 Now boot from your new personalized grml cd using the debs parameter:
 483
 484   grml debs
 485
 486 Run your own commands on startup
 487 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 488
 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:
 495
 496   grml myconfig=/dev/sda1
 497
 498 Or even better: create a floppy disk with label GRMLCFG running:
 499
 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:
 502
 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
 507 you want to use.
 508
 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.
 515
 516 Debug remote systems
 517 ~~~~~~~~~~~~~~~~~~~~
 518
 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?
 523
 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
 531 will be taken.
 532
 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
 536 myconfig.
 537
 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.
 541
 542 Use persistent home directory
 543 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 544
 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).
 550
 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).
 554
 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:
 558
 559   grml home=scan
 560
 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:
 565
 566   grml home=/dev/sda2
 567
 568 Notice: the files located in /etc/skel will be copied to the partition
 569 (but will not overwrite any files).
 570
 571 Bugs
 572 ~~~~
 573 Please report feedback, bugreports and wishes link:http://grml.org/contact/[to us]!
 574
 575 Author
 576 ~~~~~~
 577 (c) 2005++, Michael Prokop <mika@grml.org>