config/grml-config.old.txt

   1 grml-config(1)
   2 ==============
   3
   4 NAME
   5 ----
   6 save-config - save configuration ; restore-config - restore
   7 configuration; mkpersistenthome - create persistent home directory;
   8 more options available via bootoptions (see following documentation)
   9
  10 SYNOPSIS
  11 --------
  12 save-config - please take a look at 'save-config -h' ; restore-config
  13 - please take a look at 'restore-config -h', mkpersistenthome (no
  14 options available)
  15
  16 Introduction
  17 ------------
  18
  19 By using the config-framework it is possible to save the configuration
  20 of a running grml system and restore it later. save-config is a script
  21 to store your running configuration inside a bzip2 compressed tar
  22 archive (from now on known as the 'configuration file').
  23 restore-config is a script to restore a configuration using the stored
  24 configuration file.  Several bootoptions provide additional features.
  25 If you do not know where to start just take a look at the available
  26 options and read the section <<X7,usage scenarios>>.
  27
  28 TIP: The generated configuration archives are plain bzip2 compressed tar
  29 archives. All the files are generated starting from the root-directory
  30 '/' so it is easy to handle. You can generate configuration archives
  31 manually as well, save-config is just a frontend which should make it
  32 easier to use.
  33
  34 Autoconfiguration
  35 -----------------
  36
  37 By default the booting process tries to mount a device labeled
  38 'GRMLCFG'. This provides the possibility to restore a configuration
  39 (named config.tbz) and execute a script (named grml.sh) without the
  40 need to specify any bootparams. If you want to disable this feature
  41 please take a look at the 'noautoconfig' bootparam.
  42
  43 Boot options
  44 ------------
  45
  46 As you probably know you can adjust boot parameters on the bootprompt.
  47 You want to set some boot options permanently? That's possible via
  48 adding a directory named 'bootparams' to the grml-ISO which has to be
  49 located at /live/image/bootparams/ afterwards. Place a textfile inside the
  50 directory containing the bootoptions which should be appended to
  51 default ones (this corresponds to booting without any special
  52 options). If you want to be able to boot from your grml-CD you have to
  53 create a multisession CD. See the <<X7,usage scenarios>> for more
  54 details how to use it.
  55
  56 Scripts
  57 -------
  58
  59 save-config - save configuration
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 This script generates a plain bzip2 compressed tar archive containing
  63 the specified files. The following options are supported for
  64 specifying which parts should be saved in the configuration file:
  65
  66   -home                         store hidden files from $HOME ($HOME/.*)
  67   -grmlhome                     store hidden files from \$HOME (\$HOME/.*) of user grml [use as user root]
  68   -etc                          store modified files from /etc
  69   -configdir                    store $HOME/config
  70   -all                          store all configuration files (:= -home, -configdir and -etc)
  71
  72 TIP: It is also possible to use environment variables for specifying which parts
  73 should be saved.  Just set the corresponding variable: $SAVE_HOME, $SAVE_ETC,
  74 $SAVE_CONFIGDIR and $SAVE_ALL
  75
  76 The default filename of the generated configuration file is
  77 config.tbz.  The following options are supported for specifying
  78 another destination of the configuration file:
  79
  80   -ssh user@host:/path/to/file  copy configuration via ssh/scp to remote host
  81   -mail <recipient>             send configuration via mail
  82   -file foo_bar_config.tbz      save configuration in specified file
  83
  84 Usage examples:
  85
  86   save-config -all                                  => store all configuration files in config.tbz in current dir
  87   save-config -home -mail  devnull@grml.org         => store $HOME/.* in config.tbz and send it via mail
  88   save-config -etc  -ssh   devnull@grml.org:/path/  => store /etc in config.tbz and scp it to specified host
  89   save-config -all  -file  foo.tbz                  => store all configuration files in foo.tbz
  90   SAVE_ALL=yes save-config -file /path/foo.tbz      => store all configuration files in /path/foo.tbz
  91
  92 restore-config - restore configuration
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94
  95 You can restore a configuration using the bootoptions or by a script
  96 file named 'restore-config'.  Specify the filename of the
  97 configuration archive which should be used as a parameter. The
  98 following options are available to specify which parts of the archive
  99 should be extracted.
 100
 101   -home                         extract hidden files from $HOME ($HOME/.*)
 102   -grmlhome                     store hidden files from \$HOME (\$HOME/.*) of user grml [use as user root]
 103   -etc                          extract modified files from /etc
 104   -configdir                    extract $HOME/config
 105
 106 The default is to extract (restore) all files found in the archive.
 107
 108 TIP: It is also possible to use environment variables for specifying
 109 which part should be restored. Just set the corresponding variable:
 110 $RESTORE_HOME, $RESTORE_ETC, $RESTORE_CONFIGDIR and $RESTORE_ALL
 111
 112 Usage examples:
 113
 114   restore-config -home foo_bar_config.tbz  => restore configuration from file foo_bar_config.tbz
 115   restore-config config.tbz                => restore configuration from file config.tbz
 116
 117 mkpersistenthome - use persistent home-directory
 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120 You have a local partition you would like to use as your
 121 home-directory?  Just use the interactive script called
 122 'mkpersistenthome'. It will either create a file named grml.img on the
 123 specified partition or create a partition using the ext2 filesystem
 124 (you can specify the option in a dialog inside the program). grml.img
 125 is a loopback device which size you can specify manually.  It is
 126 possible to scan through the partitions to identify the appropriate
 127 partition. To use a home-directory located on your hard-drive use the
 128 appropriate bootoption on bootprompt:
 129
 130   home=/dev/hda3    =>   use /dev/hda3 as the homepartition
 131   home=scan         =>   scan through the available partitions and search for file grml.img
 132
 133 Boot-Options
 134 ------------
 135
 136 The following bootoptions are supported. Use them at the (isolinux)
 137 bootprompt as documented here.
 138
 139 myconfig::
 140     This option is for restoring configuration using the file config.tbz
 141     on the specified device. Usage examples:
 142
 143   myconfig=/dev/sda1                        => use file config.tbz from usb-device
 144   myconfig=/dev/fd0                         => use file config.tbz from floppy-disk
 145   myconfig=/dev/sda1 file=config_foobar.tbz => use file config_foobar.tbz from usb-device
 146
 147 home::
 148     This option is for setting a specific partition as home directory.
 149     Usage examples:
 150
 151   home=/dev/hda3    =>  use /dev/hda3 as the homepartition
 152   home=scan         =>  scan through the available partitions and search
 153                         for file grml.img
 154
 155 partconf::
 156
 157     This option mounts the specified device in read-only mode and tries
 158     to copy all files specified in /etc/grml/partconf to the grml
 159     system. This provides the possibility to use the configuration of a
 160     harddisk installation. For example using the network configuration
 161     (which is specified in /etc/network) is possible using this
 162     bootoption. Usage example:
 163
 164     partconf=/dev/hda2 => try to mount /dev/hda2 and copy files specified
 165                           in /etc/grml/partconf to the booted grml system
 166
 167 netconfig::
 168     Use this option to restore configuration using wget to download
 169     a configuration file from specified destination. Usage example:
 170
 171   netconfig=server.tld/path/to/config.tbz  =>   restore configuration using wget to download file config.tbz
 172
 173 extract::
 174
 175     Extract specific directories from configuration archive. Notice:
 176     This bootparam is useful only with bootparams which are able to
 177     extract configuration archives.
 178
 179   extract=/home/grml         => extract only /home/grml from archive
 180   extract=/etc               => extract only /etc from archive
 181   extract=/home/grml/config  => extract only $HOME/config from archive
 182
 183 scripts::
 184     This option can start a script located in /live/image/scripts/.
 185     Usage examples:
 186
 187   scripts               =>   run script /live/image/scripts/grml.sh
 188   scripts=foobar.sh     =>   run script foobar.sh in /live/image/scripts/
 189
 190 config::
 191     Use this option to restore a configuration using directory
 192     /live/image/config (located in root-directory on a usb-device). Usage
 193     examples:
 194
 195   config                    =>   restore configuration using file config.tbz from directory /live/image/config/
 196   config=config_foobar.tbz  =>   restore configuration using file config_foobar.tbz from directory /live/image/config/
 197
 198 debs::
 199
 200     This options allows automatic installation of deb packages while
 201     booting. The debian packages have to be located in directory
 202     /live/image/debs/. Usage examples:
 203
 204   debs              =>   install all debian packages (suffix .deb) from directory /live/image/debs/
 205   debs=01           =>   install all debian packages (suffix .deb) starting with 01 in the filename from directory /live/image/debs/
 206
 207
 208 noautoconfig::
 209     Deactivate automounting. By default the command 'mount' tries to mount a
 210     device with label 'GRMLCFG'. If you specify the noautoconfig bootparam
 211     the automounting will be deactivated.
 212
 213   noautoconfig            => disables auto mounting of label 'GRMLCFG'
 214
 215
 216 [[X7]]
 217 Usage scenarios
 218 ---------------
 219
 220 Personal configuration files
 221 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 222
 223 You are a fan of the editor vim? Great. You probably have your own
 224 ~/.vimrc and want to use it on the grml system. You also don't like
 225 the default zsh configuration and want to use your own ~/.zshrc?
 226 How to procede? Copy your .vimrc and .zshrc to $HOME of user 'grml'.
 227 Place additional files in $HOME/config. Now create a configuration for
 228 your files running:
 229
 230   save-config -home -configdir
 231
 232 Now you should have a file named config.tbz containing your
 233 configuration files. You can copy the archive to a webserver
 234 and restore it via downloading during reboot using the following
 235 commandline on bootprompt:
 236
 237   grml netconfig=server.tld/path/to/config.tbz
 238
 239 You don't have network access but own a floppy drive? Copy the file
 240 to a floppy disk and boot with:
 241
 242   grml myconfig=/dev/fd0
 243
 244 Floppy is to small or to slow? Ok, let's use a usb device:
 245
 246   grml myconfig=/dev/sda1
 247
 248
 249 Network configuration
 250 ~~~~~~~~~~~~~~~~~~~~~
 251
 252 You need a specific network setup and want to use your own
 253 /etc/network/interfaces by default? Generate the configuration
 254 archive running the following command as user root:
 255
 256   save-config -etc
 257
 258 Now you should have a file named config.tbz containing your
 259 configuration files. If you want to use it with a floppy disk copy the
 260 file to a floppy and boot via using the following command on
 261 bootprompt:
 262
 263   grml myconfig=/dev/fd0
 264
 265 Floppy is to small or to slow? Ok, let's use a usb device:
 266
 267   grml myconfig=/dev/sda1
 268
 269 You do have an existing harddisk installation and want to use its
 270 configuration? Let's say the debian system is located in /dev/hda2. You
 271 want to use the directory /etc/network. This directory is activated by
 272 default in /etc/grml/partconf so we don't have to do any further work.
 273 We just need to activate it via using the following commandline on
 274 bootprompt:
 275
 276   grml partconf=/dev/hda2
 277
 278 Automatic installation of debian packages
 279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 280
 281 You have a specified debian package named 'foobar.deb' and want to use
 282 it with (therefore: install it on) grml by default? Notice: this feature
 283 is useful especially for grml-small (a ~80 MB ISO). If you want to use it
 284 with the large version of grml you might have to overburn the ISO.
 285
 286 Let's assume you have burned the grml iso to a CD-RW using a commandline like:
 287
 288   cdrecord dev=/dev/hdc -v -multi -tao grml_0.5.iso
 289
 290 Now create a directory named debs and place foobar.deb in it:
 291
 292   mkdir debs/ && cp foobar.deb debs/
 293
 294 Notice: This directory will be located in /live/image after burning the second session.
 295
 296 Now create the second session containing this directory:
 297
 298   mkisofs -M grml_0.5.iso -C `cdrecord -msinfo dev=/dev/hdc` -R -o 2nd_session.iso debs
 299
 300 Finally append the second session to the cd using:
 301
 302   cdrecord dev=/dev/hdc -v -multi -tao 2nd_session.iso
 303
 304 TIP: the application k3b (not available on the live-CD but available
 305 through the Debian repositories) provides an easy to use interface for
 306 doing the multisession task.
 307
 308 Now boot from your new personalized grml cd using the debs option:
 309
 310   grml debs
 311
 312 Run your own commands
 313 ~~~~~~~~~~~~~~~~~~~~~
 314
 315 You know that booting with 'grml service=foobar' executes
 316 /etc/init.d/foobar when booting grml. But you want to setup a more
 317 complex network configuration, adjust some other stuff and so on on your
 318 own? Just write a script named grml.sh which does the job and use own
 319 of the mentioned bootparams. Let's say you have placed grml.sh on your
 320 usb device (usb stick) then use the following commandline on bootprompt:
 321
 322   grml myconfig=/dev/sda1
 323
 324 Or even better: create a floppy disk with label GRMLCFG running:
 325
 326   fdformat /dev/fd0   # format the floppy disk if not done already
 327   mkfs.ext2 -L GRMLCFG /dev/fd0   # now create ext2 filesystem with label GRMLCFG on it:
 328
 329 TIP: several filesystems provide the possibility to provide a label.
 330 For example FAT provides this through: 'mkfs.vfat -n GRMLCFG
 331 /dev/sda1' (attention: this will destroy data on /dev/sda1 of
 332 course!). Take a look at the documentation/manpage of the filesystem
 333 you want to use.
 334
 335 Now place your configuration archive (see save-config and the other
 336 usage scenarios) and the script grml.sh on the floppy disk. Now you can
 337 boot your system without specifying any bootparameters on bootprompt
 338 because devices labeled with GRMLCFG are mounted readonly and used by
 339 default. If you did not label your device you can use the device anyway
 340 using 'grml myconfig=/dev/ice' on the bootprompt.
 341
 342 Debug remote systems
 343 ~~~~~~~~~~~~~~~~~~~~
 344
 345 You are responsible for a customer's system in her data center. The
 346 system has failed and you need to debug from remote, and the remote
 347 hands available in the data center do not have enough knowledge to get
 348 grml booted and configure the network without external help?
 349
 350 If the hard disk of the system is still available, you hopefully have
 351 saved a configuration file with IP address, netmask and default
 352 gateway somewhere on that hard disk. grml can use the information
 353 found on a partition. Take a look at the 'partconf' boot parameter.
 354 Usage example: 'grml partconf=/dev/hda2' copies files defined in
 355 /etc/grml/partconf from /dev/hda2 to the grml system. As /etc/network
 356 is predefined in /etc/grml/partconf the configuration from /dev/hda2
 357 will be taken.
 358
 359 Or you use a standard grml medium and have grml read IP address,
 360 netmask and default gateway from another medium like a floppy or an USB
 361 stick. Take a look at the script saveconfig and the boot parameter
 362 myconfig.
 363
 364 Adjust boot parameters
 365 ~~~~~~~~~~~~~~~~~~~~~~
 366
 367 You want to set some boot options permanently? Just add a directory
 368 named 'bootparams' to the CD-ROM so it is located at
 369 /live/image/bootparams/ and contains a textfile with the bootparams you
 370 would like to use.
 371
 372   mkdir bootparams
 373   echo lang=de > bootparams/my_bootparams
 374
 375 Now burn a multisession CD where directory bootparams is located in the
 376 root directory of the CD.
 377
 378 TIP: the application k3b (not available on the live-CD but available
 379 through the Debian repositories) provides an easy to use interface for
 380 doing the multisession task.
 381
 382 Use persistent home directory
 383 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 384
 385 You want to use a persistent home directory which includes all the files
 386 located in $HOME. Use the script mkpersistenthome to create such a
 387 persistent home directory. You have the options to either use a
 388 specific partition as your home directory or add a loopback file
 389 named grml.img on the specified partition (the default).
 390
 391 TIP: /dev/external in the partition selection of mkpersistenthome is
 392 an usb device without partitions. /dev/external1 corresponds to the
 393 first partition on an usb device (usually an usb stick).
 394
 395 After running the script mkpersistenthome you can use the boot
 396 parameter home to activate the home directory. If you are using the
 397 option with the loopback file (grml.img) you can boot via:
 398
 399   grml home=scan
 400
 401 which will scan through the partitions and if a file grml.img is found
 402 it will be mounted as your $HOME-directory. If you want to use a
 403 partition as your home directory specify the device as an option. If
 404 you want to use /dev/hda2 as your $HOME boot via:
 405
 406   grml home=/dev/hda2
 407
 408 Notice: the files located in /etc/skel will be copied to the partition
 409 (but will not overwrite any files).
 410
 411 Bugs
 412 ~~~~
 413 Please report feedback, bugreports and wishes link:http://grml.org/contact/[to us]!
 414
 415 Author
 416 ~~~~~~
 417 (c) 2005++, Michael Prokop <mika@grml.org>