grml2hd(8)
==========

Name
----
grml2hd - install grml on harddisk

Synopsis
--------
grml2hd [ partition ] [ options ]

*******************************************************************************
Important! The grml team does not take responsibility for loss of any data!
*******************************************************************************

Options and environment variables
---------------------------------

  -v

Return version and exit.

  GRML2HD_NONINTERACTIVE=1 grml2hd ....

Install grml2hd in non-interactive mode (using /etc/grml2hd/config).

  NOSWREMOVAL=1 grml2hd ...

Disable running script remove-packages-server for removing some
special software packages.

  SWRAID='mbr-only' grml2hd /dev/md0 -mbr /dev/md0

Install grml on raid array /dev/md0 and install mbr as well.

Introduction
------------

grml2hd installs grml on a partition on your harddisk and makes it
bootable. The partition is formatted with mkfs (using the selected
filesystem), then all necessary files are copied. Then you have to answer a
few questions like username, passwords and which features you want to use
on your harddisk installation.  To boot the new installation lilo is
installed in the boot-sector of the partition or in the MBR, depending
on your selection.

Automatic installation
----------------------

It is possible to run grml2hd in a non-interactive mode where no further
manual input is required. This mode is useful if you do not want to sit in
front of your computer during installation or if you want to set up a
cluster of computers (e.g. a computer lab). There are two possibilities to
run grml2hd in automatic mode.  But: Do *not* use the grml2hd
non-interactive mode if you do not know what you are doing!

Automatic installation trough running grml system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Configuration of the automatic installation is done via the configuration file
/etc/grml2hd/config. To activate automatic mode you have to set the environment
variable GRML2HD_NONINTERACTIVE or use the '-i' option on the commandline.
Use the automatic installation mode with care as you won't be prompted
for any more questions!

Automatic installation through booting grml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can install grml without even booting it before. If you do not know
your system very well we recommend booting grml before running grml2hd. If
everything works as intented and you want to install grml on many computers
at the same time you can do this via entering only some few words on the
bootprompt or use grml2hd via
link:http://grml.org/terminalserver/[grml-terminalserver].

Configuration is done via boot options:

   user=                                            => user name for user which should be used at hd-install (default: grml)
   filesystem={ext2|ext3|reiserfs|reiser4|jfs|xfs}  => filesystem to be used (default: ext3)
   mbr=/dev/...                                     => partition where MBR should be installed (default:=partition)
   partition=/dev/...                               => partition where grml should be installed (must be set - no default!)

Usage example for booting and installing grml on partition /dev/hda4:

   grml2hd partion=/dev/hda4 mbr=/dev/hda filesystem=ext3 user=mika

Passwords of user root and user are "grml" - please adjust after harddisk
installation!

*******************************************************************************
Important: not all filesystems are supported in grml-small. ext3 is the
default and recommended.  Do *not* use the grml2hd bootoption if you do not
know what you are doing!
*******************************************************************************

grml2hd with software RAID
--------------------------

  mdadm --create --verbose /dev/md0 --level=raid1 --raid-devices=2 /dev/hda1 /dev/hdc1

Prepare RAID setup with mdadm.

  SWRAID='mbr-only' grml2hd

Install grml on raid array /dev/md0 and install mbr as well.  The SWRAID
environment variable provides the option for the raid-extra-boot option in
/etc/lilo.conf. Please notice that the driver(s) for the devices used in a
raid array have to be statically compiled into the kernel, otherwise
automatic assembling won't work and assembling has to be done in userland
(won't work for SW-RAID on root partitions then of course).

grml2hd with encrypted partitions.
----------------------------------

Installing grml on an encrypted root-partition (\'/\') is *not* supported.
But you can use encrypted partitions like /home or swap. Install grml2hd as
usual, (re)boot into your grml system and then activate encrypted
partitions manually.

encrypted swap partition
~~~~~~~~~~~~~~~~~~~~~~~~

Deactivate swap partition:

  # swapoff -a

Now adjust /etc/crypttab

  # echo "cswap   /dev/hda5       /dev/urandom    swap" >> /etc/crypttab

Now delete the old swap-entry in /etc/fstab and add the following line:

  /dev/mapper/cswap   none    swap  sw,pri=1        0  0

Make sure this entry is above(!) the \'Warning! Please do \*not\* change
any...\' line!  Then enable the encrypted swap partition running:

  # /etc/init.d/cryptdisks start && swapon -a

encrypted /home partition
~~~~~~~~~~~~~~~~~~~~~~~~~

Make sure the device you want to use for your /home-partition is not
mounted. Then initialize the partition you want to use as encrypted /home
using grml-crypt. Important: this will destroy all data on /home!
grml-crypt is a wrapper around cryptsetup-luks, you will be able to use the
partition with every linux distribution which supports cryptsetup-luks.

The following example demonstrates how to use /dev/hda5 as an encrypted
/home partition:

  # grml-crypt -t ext3 -o format /dev/hda5

Now adjust /etc/crypttab

  # echo "chda5  /dev/hda5  none luks" >>/etc/crypttab

Then add the /home-partition to /etc/fstab (make sure there is not other
entry for the partition):

  /dev/mapper/chda5  /home  ext3  defaults  0 0

Make sure this entry is above(!) the \'Warning! Please do \*not\* change
any...\' line! If you want to keep content of your old /home make sure you
can access it later again:

  # mv /home /home.old
  # mkdir -m 755 /home

To make sure that /home is not accessible before mounted as crypto
partition you can use chattr:

  # chattr +i /home

Now start cryptdisks and mount your new /home-partition:

  # /etc/init.d/cryptdisks start && mount /home

Please make sure cryptdisks is started in runlevel 2 via
/etc/runlevel.conf!

If you moved your old /home to /home.old copy files to your new
/home-partition:

  # cp -a /home.old/* /home/

If everything works as expected you will be prompted for the given LUKS
passphrase when booting your grml system.

Files
-----

  /etc/grml2hd/config

Configuration file for automatic installation via grml2hd. You do not
need to adjust this file if you do not want to run the automatic installation.

  /usr/sbin/grml2hd-chrooted

A small helper script, that executes a few commands in the harddisk
installation. You'll never need this script, it's only useful for the
grml2hd script.

  /usr/bin/grml2hd-bootparams

A small helper script that reads kernel's command line and displays a menu
of boot parameters which should be used for lilo's append line.  The script
provides the selected entries on stdout so it's possible to use the script
inside grml2hd itself.

  /boot/grub/grml-template_menu.lst

Template file for use with grml installation (grml2hd) and Grub.
Adjust it for your needs before using it.

FAQ
---

Why is $FEATURE not available in grml2hd?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Because one major goal of grml2hd is keep it small, simple and stable.  If
you think that you can not live without $FEATURE please let us know, see
<<X7,the 'Bugs' section in this document>> how to report feedback/bugs.

Why is SW-RAID and/or encrypted partition not available through an interface?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are using such a feature you should know how to handle it. It won\'t
help you if you get an interface within the installer but do not know
how to handle it afterwards.

Is it possible to customize grml2hd?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Yes, you can customize execution of grml2hd via the configuration file
/etc/grml2hd/customization. It is used automatically when running grml2hd,
so you just have to adjust the configuration file itself.

Known issues
------------

grub and SW-RAID
~~~~~~~~~~~~~~~~

Installation of grub as bootmanager does not yet support installation on
Software RAID devices.

I can't boot my grml system because Lilo says LI L99 99 99...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You probably did not install lilo to master boot record (MBR) within grml2hd and
don't have a bootmanager in your MBR.  Solution: Install lilo to MBR. Example:

  sudo mount /mnt/hda1  # mount harddisk
  sudo chroot /mnt/hda1 # chroot into the grml-system
  vim -X /etc/lilo.conf # adjust the line containing the bootoption to 'boot=/dev/hda'
  lilo  # now run lilo again, leave chroot environment (exit) and reboot your system afterwards

I installed grml on a XFS, JFS or reiser4 filesystem and grml does not boot anymore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some filesystems and lilo don't work together when lilo is installed in the
boot sector of the harddisk because the filesystem superblock goes where
lilo would be installed. You have to install lilo in the master boot record
of your harddisk to solve this problem.
If you read this after installing grml to your harddisk you should use the
grml live-cd and fix /etc/lilo.conf manually and rerun lilo (see above).

I installed grml to an SCSI device and now I can not boot it anymore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To access an SCSI device you probably need a specific kernel module.  This
is provided by an initial ramdisk. Please use the initrd support within
grml2hd. To fix this issue please install a kernel with SCSI-device support
in the chroot after running grml2hd:

  sudo mount -o /mnt/hda1   # mount harddisk where grml is installed
  sudo chroot /mnt/hda1     # chroot into the grml-system
  update-initramfs -u -t -k $(uname -r) # create initramfs
  vim -X /etc/lilo.conf               # adjust lilo for use with initrd
  lilo  # now run lilo again, leave chroot environment (exit) and reboot your system afterwards

Further issues
~~~~~~~~~~~~~~

TODOs are documented at /usr/share/doc/grml2hd/TODO.

Usage examples
--------------

Install grml on /dev/sda4 and install lilo in the mbr of /dev/sda.

  GRML2HD_NONINTERACTIVE=1 grml2hd

Runs grml2hd in automatic (non-interactive) mode. Needs adjustment of
/etc/grml2hd/config. Use with care!

[[X7]]
Bugs
----
Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes link:http://grml.org/contact/[to us]!

Authors
-------
Michael Prokop <mika@grml.org> and Andreas "Jimmy" Gredler <jimmy@grml.org>
