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 features 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
=======================================

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
=======================================

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 options="noatime" quiet
    initrd /initrd-3.9.9-FB.02
}

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

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 triggers=zfs quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Normal RAID
=======================================

# 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/md0 triggers=raid quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Normal LVM
=======================================

# 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/lv-root triggers=lvm quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted LVM with just a passphrase and one encrypted drive
=======================================

# 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/lv-root enc_root=/dev/sda3 enc_type=pass triggers=luks,lvm quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted RAID with just a passphrase and two encrypted drives
=======================================

# 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/md0 enc_root=/dev/sda3,/dev/sdb3 enc_type=pass triggers=luks,raid quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted RAID + LVM with just a passphrase and two encrypted drives
=======================================

* Note: The initramfs only supports LVM on RAID, which means that your disks will first be decrypted, assembled,
        then the lvm will activate the logical volumes on that assembled raid array and then boot your system.
        Thus, the raid operations are actually transparent.

 Layout Example:
 ---------------
 /dev/sda3 - LUKS (vault0) -|\ _ /dev/md0 (vault0, vault1) -> volume group on md0 (let's say 'lv') -> /dev/mapper/lv-root
 /dev/sdb3 - LUKS (vault1) -|/

# 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/lv-root enc_root=/dev/sda3,/dev/sdb3 enc_type=pass triggers=luks,raid,lvm 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 BY DEFAULT: /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.
         
         OPTIONAL:  You may use enc_targets parameter to specify custom /dev/mapper/<mount_targets> names 
                    (see LUKS section below)

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 triggers=luks quiet
    initrd /initrd-3.9.9-FB.02
}

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

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 triggers=luks,zfs quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted ZFS with a gpg key and only one encrypted partition
(If an embedded keyfile is provided, it will automatically be used to try to decrypt the enc_drives)
=======================================

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 triggers=luks,zfs 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
=======================================

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 triggers=luks,zfs quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted ZFS with an key named "passphrase" in a folder called "lukskeys" on a USB stick drive labeled BOOTKEY, 4 encrypted whole disks and labeled /dev/mapper mountpoints
=======================================

insmod part_gpt
insmod fat
insmod efi_gop
insmod efi_uga

menuentry "Gentoo - 4.9.16" {
    linux /@/4.9.16-1/vmlinuz-4.9.16-gentoo root=rpool/ROOT/gentoo enc_drives=/dev/sda,/dev/sdb,/dev/sdc,/dev/sdd enc_targets=csda,csdb,csdc,csdd enc_type=key enc_key=/lukskeys/passphrase enc_key_drive=/dev/disk/by-label/BOOTKEY elevator=noop logo.nologo triggers=luks,zfs
    initrd /@/4.9.16-1/initrd
}


=======================================
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.
=======================================

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 triggers=luks,zfs
    enc_type=key enc_key_drive=PARTLABEL=Linux\x20filesystem quiet
    initrd /initrd-3.9.9-FB.02
}

=======================================
Encrypted btrfs w/ Mount Options and passphrase (one drive and the / is on a subvolume called tank/root)
=======================================

menuentry "Gentoo - 3.9.9-FB.02" {
    linux /kernels/3.9.9-FB.02/vmlinuz root=/dev/mapper/vault_0 enc_drives=/dev/sda4 enc_type=pass options="compress=lzo,defaults,noatime,autodefrag,subvol=tank/root" triggers=luks quiet
    initrd /kernels/3.9.9-FB.02/initrd
}

=======================================
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:
=======================================

=======
GENERAL
=======

root - Location to rootfs
    example for ZFS: linux <kernel> root=tank/gentoo/root
    example for rootfs on luks partition: linux <kernel> root=/dev/mapper/vault_0
    example for regular drive: linux <kernel> root=/dev/sda4

usr - Location of separate /usr
    example: linux <kernel> root=/dev/sda4 usr=/dev/sda3

    If you use this option, you need to make sure that /usr is on the same type of style as your /.
    Meaning that if you have / in a zfs dataset, than /usr should be on a zfs dataset as well.
    You cannot have / on a zfs dataset and /usr on a regular partition. I don't foresee a scenario or
    a reason for why someone would want to put their / on zfs and exclude their /usr from it. So this
    case should be a rare one.

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.

triggers - Use this to let the initramfs load what feature hooks it needs to run.
       The order in which you write the list will determine how the hooks will be ran.

       For example, if you designed your partition structure to have encryption
       at the lowest level, and then you assembled those luks block devices into
       an array, and then after the array was assembled, you had your lvm volumes
       groups activate, you can say:

       triggers=luks,raid,lvm

       Which would run the encryption hook first, then raid assembly, then
       volume group activation.

       However, if you had raid at the lowest level, and then you had lvm, and then
       inside of the lvm, you would have luks devices, you could possibly say:

       triggers=raid,lvm,luks

       The supported triggers are:

       - luks
       - zfs
       - lvm
       - raid

       If you don't specify any triggers, than just the default initramfs
       commands will be executed (As if you had a simple system with just a
       regular filesystem on top of your drive block device directly -
       i.e ext4 on /dev/sda1).

       Given the permutations of how these triggers can be layed out, there
       might be problems in booting with specific configurations. If this happens,
       definitely let me know to see if we can work together to cleanly improve
       support for that specific trigger order.

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

by - Specifies what directory you want to use when looking for your zpool so that we can import it.

     Supported:
     by= dev, id, uuid, partuuid, label, partlabel, * (Wild card will just set the 'by' variable to whatever you specified.

    example: by=label -> /dev/disk/by-label
             by=uuid  -> /dev/disk/by-uuid
             by=dev   -> /dev
             by=/mystical/ninja -> /mystical/ninja

refresh - Ignores the zpool.cache in the rootfs, creates a new one
          inside the initramfs at import, and then copies it into the rootfs.

    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 you use 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_key_ignore - Ignores the embedded keyfile
    example: linux <kernel> enc_key_ignore

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
    
enc_targets - What /dev/mapper/TARGET_NAME to use? Comma separated list, same order as enc_drives!
    example: linux <kernel> enc_drives=/dev/sda1,/dev/sdb1 enc_targets=crypt_sda,crypt_sdb


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.

=======================================
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.py "_files" 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.

=======================================
Firmware Support
=======================================

If you want to include firmware inside your initramfs, open up the pkg/hooks/Firmware.py file,
enable the hook by changing the "_use" to "1" and then add the specific firmware name/path to
the files list. If you don't want to specify a specific firmware but would rather copy all the
firmware that's on your system, you can toggle the "_copy_all" flag by changing it to "1".
The firmware files will be copied from your system's /lib/firmware directory. The firmware that
you add to the "_files" list should be relative to this directory. More information can be found
inside the hook.

=======================================
Embedded Keyfile Support
=======================================

The initramfs has the ability to embed your encrypted drive(s)'s keyfile directly into itself.

Some of the benefits this may provide are:
> Not having to type multiple passphrases during boot.
> Rely on an external drive in order to decrypt the drive.
> If using an external drive, reduce the number of files on the /boot drive (just kernel and initramfs)

This was primarily implemented in order to reduce the number of passphrases needed to 1, when you have your
/boot directory inside of an encrypted / partition on LUKS. You will need to have GRUB decrypt your / partition
and once the initramfs loads, it will automatically use the embedded keyfile to decrypt the drives, and start up
your system.

In order to activate this, go into pkg/hooks/Luks.py and change the "_use_keyfile" value to 1, and then
set the "_keyfile_path" to the path on disk from where to copy your keyfile from. Once this is done,
during initramfs generation, you will see a message that the initramfs is embedding the keyfile into itself.

In your grub command line, you will need to have the "enc_type" set to "key".

When the initramfs starts up, if it detects that your initramfs has an embedded keyfile, it will
automatically try to decrypt the drives listed in "enc_drives" and not ask you any questions.
If you want to use some other form of decryption (passphrase, key_gpg), but you don't want to remake
the initramfs in order to remove the keyfile out of it, use the "enc_key_ignore" kernel line option.

=================================
LUKS Detached Header File Support
=================================

The initramfs has the ability to embed your detached luks header directly. This has a lot of security
benefits, the main ones being that:

1. Your LUKS device will look as if it was just a bunch of random data (Plausible Deniability)
2. Your LUKS device will pretty much be impossible to decrypt with modern technological standards due
   to the SALT no longer being on the same device as the LUKS device.

In order to activate this feature, change the "_use_detached_header" from 0 to 1 in order to enable this support.
After you do this, you can set the path of where you want the initramfs to automatically copy that file from by
modifying the "_detached_header_path" variable. By default, it will attempt to copy it from "/crypto_header.bin",
and it will automatically be placed inside the initramfs as "/etc/header".

Once this is done, use "enc_options=--header=/etc/header" in the initramfs to tell the initramfs at boot time where
to find the header file.