USAGE

=======================================
Creating the initramfs
=======================================

Run the script by running: ./mkinitrd
* It must be run as root since root is the only user that can run `depmod`.

* If the script doesn't run and gives you a permission denied message,
  give it execution permission: `chmod +x mkinitrd` and then try again.

Select the option that you want, and tell it which kernel you want to use.

After that the required files will be gathered and packed into an initramfs and you
will find the initramfs in the directory that you are currently in. Copy that file
to your boot directory and name it whatever you want.

=======================================
Setting up the bootloader configuration (GRUB 2)
=======================================

If the following information is true:

* Kernel     = vmlinuz-3.9.9-FB.02
* Initramfs  = initrd-3.9.9-FB.02
* Partition Layout is GPT
* /boot = /dev/sda1 (formatted with the ext2 filesystem)

Add a new entry to /boot/grub/grub.cfg

=======================================
Normal Boot
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=/dev/sda3 quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Normal Boot w/ Mount Options
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    # Mounts your root partition with 'acl'
    linux /vmlinuz-3.9.9-FB.02 root=/dev/sda3 options="acl" quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Normal ZFS
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=tank/gentoo/root quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted Normal with one encrypted drive
=======================================

** Note: The program will auto mount all your encrypted drives as follows: /dev/mapper/vault_0, /dev/mapper/vault_1,
         /dev/mapper/vault_2 ... etc. Thus if you only have one encrypted drive, make sure you name it /dev/mapper/vault_0,
         or use its UUID.

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=/dev/mapper/vault_0 enc_drives=/dev/sda3 quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted ZFS with just a passphrase and four encrypted partitions
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=tank/gentoo/root enc_drives=/dev/sda3,/dev/sdb3,/dev/sdc3,/dev/sdd3 enc_type=pass quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted ZFS with a gpg key and only one encrypted partition
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=tank/gentoo/root enc_drives=/dev/sda3 enc_type=key quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted ZFS with an encrypted gpg key named "animal" in a folder called "farm" on a flash drive named /dev/sdc2 and two encrypted partitions
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=tank/gentoo/root enc_drives=/dev/sda3,/dev/sdb3 enc_type=key_gpg enc_key=/farm/animal enc_key_drive=/dev/sdc2 quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted ZFS with a gpg key, 3 encrypted drives for the tank pool, and mixing UUIDs, IDs, Labels, and regular drive naming,
and the key file on a usb which we also use a UUID for.
=======================================

# Gentoo
menuentry "Gentoo - 3.9.9-FB.02" {
    insmod part_gpt
    insmod ext2

    set root=(hd0,gpt1)

    linux /vmlinuz-3.9.9-FB.02 root=tank/gentoo/root enc_drives=UUID=4443433f-5f03-475f-974e-5345fd524c34,ID=ata-ST500LT012-9WS142_W0V788BP-part2,/dev/sda4
    enc_type=key enc_key_drive=PARTLABEL=Linux\x20filesystem quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Summary:
=======================================

This would load the 'vmlinuz-3.9.9-FB.02' kernel and try to mount the 'tank/gentoo/root' dataset
as the / of the filesystem. It will then chroot into it and load your system.

If you are using Encrypted ZFS, then the 'enc_drives' parameter will luksOpen each of your listed
devices, and then it will continue as usual.

* In order for you to unlock multiple devices, the passphrase/keyfile must be identical for all of them.
  or if you are just using a passphrase (and no keyfile), you can have multiple passphrases and just enter
  them all at boot (interactively).

=======================================
Kernel Options:
=======================================

=======
ZFS
=======

root - ZFS root name
    example: linux <kernel> root=tank/gentoo/root

refresh - ignores the zpool.cache in the initramfs, creates a new one
          at import and then copies it into the rootfs. You should recreate
          your initramfs afterwards so that your initramfs has the new cache.
    example: linux <kernel> root=tank/gentoo/root refresh

=======
LUKS
=======

Follow the same instructions as above, but also add "enc_drives=" and "enc_type" to your kernel line.
If you don't enter them, the initramfs will just ask you for it.

enc_drives - Encrypted drives (You need the enc_type variable below as well)

If you have your zpool on spread over multiple drives, you can pass them all
to this variable as well:
    example: linux <kernel> enc_drives=/dev/sda2,/dev/sdb3,/dev/sdc4,/dev/sdd5,/dev/sde6

enc_type - What type of method will are you using to decrypt?
    Types: pass - passphrase
           key - plain keyfile
           key_gpg - keyfile encrypted with gpg

enc_key_drive - What drive the keyfile in?
    example: linux <kernel> enc_drives=/dev/sda3 enc_type=key enc_key_drive=/dev/sdb1
             linux <kernel> enc_drives=/dev/sda3 enc_type=key enc_key_drive=UUID=4443433f-5f03-475f-974e-5345fd524c34

enc_key - What is the path to the keyfile?
    You basically pass to grub where in the drive the file is located
    (After the initramfs mounts the drive that you have the key in).

    example: linux <kernel> enc_drives=/dev/sda3 enc_type=key enc_key_drive=/dev/sdb1 enc_key=/keys/root.gpg

    In this example, once the initramfs mounts /dev/sdb1, it will look for the /keys/root.gpg at /dev/sdb1.
    So if the initramfs mounts /dev/sdb1 at /mnt/key, it will look for the key at /mnt/key/keys/root.gpg.

enc_options - Allows you to pass options to the 'cryptsetup' command
    example: linux <kernel> enc_drives=/dev/sda3,/dev/sda4 enc_options="--allow-discards"

enc_tries - Allows you to set how many times you can retype your passphrase before the initramfs fails to unlock your drives (default is 5)
    example: linux <kernel> enc_tries=10

LUKS passphrase/key:
The easiest way to pass the passphrase is just to wait till the initramfs
asks you for it. When this happens, it will use the _same_ passphrase
(or same key) for all your pools. This is to make it convenient for you.
It would be annoying to have a zpool on 6 drives (Encrypted RAIDZ2 let's say),
and then you had to put the password for each one. If you still want to do this,
then just leave the passphrase blank when the initramfs asks you for it.

=======
OTHER
=======

recover - Use this if you want the initrd to throw you into a rescue shell.
      Useful for recovery purposes.

      example: linux <kernel> recover

su - Single User Mode. This is a really crappy implementation of a single user,
     mode. But at least it will help you if you forgot to change your password,
     after installation.

     example: linux <kernel> root=tank/gentoo/root su

init - Specifies the init system to use. If the init system isn't located in /sbin/init,
       you can specific it explictly:

     example: linux <kernel> root=tank/gentoo/root init=/path/to/init

redetect - Use this if you want to have the option to re-scan your /dev/ directory for new devices.
       You really only need this if you don't know where your enc_key_drive is.

       Sometimes during the output of available drives, you won't see your drives listed, don't worry,
       if it normally works on your machine, your drive will silently appear. You could just wait a few
       seconds yourself until you feel it is ready, and then just press enter to attempt to mount
       and decrypt the drive.

=======================================
Modules Support:
=======================================

If you have compiled some critical stuff as modules rather than them being built
into the kernel, you can now write which modules you need in the
pkg/hooks/addon.sh "mods" variable. The initramfs will gather the module and
it's dependencies and put them in the initramfs for you. Then the initramfs will
automatically load all those modules for you at boot.

Example:
    mods = [ "i915", "zfs", "ahci", "ext2", "ext3", "ext4", "dm-crypt",
          "ohci-hcd", "ehci-hcd", "xhci-hcd", "usb-storage" ]

That example basically loads the intel i915 gfx driver, zfs, ahci, ext2-4
filesystem hdd drivers, dm-crypt for luks support driver, ohci/ehci/xhci
usb 1.1,2.0,3.0 drivers and the usb-storage driver. All the dependencies
are automatically gathered and compressed by the initramfs, and automatically
loaded at boot in that order.