1 files changed, 82 insertions, 0 deletions
diff --git a/tutorial.mdwn b/tutorial.mdwn
new file mode 100644
index 0000000..1d7d003
--- /dev/null
+++ b/tutorial.mdwn
@@ -0,0 +1,82 @@
+[[!meta title="Bootless: barebones tutorial"]]
+
+This tutorial helps you to build a Grub USB stick to boot your operating systems.
+
+Create basic folder structure
+-----------------------------
+
+    mkdir -p /tmp/bootless/{grub,custom}
+    wget https://git.fluxo.info/bootless/plain/templates/grub.cfg   -O /tmp/bootless/grub/grub.cfg
+    wget https://git.fluxo.info/bootless/plain/templates/custom.cfg -O /tmp/bootless/grub/custom.cfg
+
+Edit the config files
+---------------------
+
+Please check and customized the downloaded configuration above. The defaults allows you to load into Grub
+and boot your OS using the grub shell.
+
+Example: Full Disk Encryption
+-----------------------------
+
+Here is an example of a Full Disk Encryption with an entry loaded into `custom.cfg`:
+
+    menuentry 'darkstar full disk encryption' {
+      # Loads luks and lvm modules so you can access kernel
+      # and initrd from inside your encrypted OS!
+      insmod luks
+      insmod lvm
+
+      # This opens the encrypted volume /dev/mapper/darkstar-root
+      # and sets it as the root in the grub shell.
+      cryptomount lvm/darkstar-root
+      set         root=(crypto0)
+
+      # This loads the kernel and initramfs
+      echo        "Loading ${volume}..."
+      linux       /boot/vmlinuz-3.16.0-4-amd64 root=/dev/mapper/root cryptopts=target=root,source=/dev/mapper/darkstar-root ro quiet
+      echo        'Loading initial ramdisk ...'
+      initrd      /boot/initrd.img-3.16.0-4-amd64
+    }
+
+Example: boot with images loaded into the USB stick
+---------------------------------------------------
+
+You may also place custom images into the USB stick -- with the drawback to have to keep them up-to-date:
+
+    cp -r /boot /tmp/bootless/custom/debian
+
+    menuentry 'darkstar: preloaded images' {
+      # This loads the kernel and initramfs using images preloaded into the USB stick.
+      echo        "Loading ${volume}..."
+      linux       /boot/custom/debian/vmlinuz-3.16.0-4-amd64 root=/dev/mapper/root cryptopts=target=root,source=/dev/mapper/darkstar-root ro quiet
+      echo        'Loading initial ramdisk ...'
+      initrd      /boot/custom/debian/initrd.img-3.16.0-4-amd64
+    }
+
+Example: builtin bootless functions
+-----------------------------------
+
+The supplied configuration provides two functions, `bootfde` and `bootimg` that simplify the two previous examples into:
+
+    menuentry 'darkstar: full disk encryption' {
+      bootfde darkstar-root
+    }
+
+    menuentry 'darkstar: preloaded images' {
+      bootimg darkstar-root
+    }
+
+Create a bootable image
+-----------------------
+
+    grub-mkrescue -o output.img /tmp/bootless
+
+Record the image into the USB stick
+-----------------------------------
+
+*WARNING!* This will irrevocably replace the contents of your USB stick.
+
+Pay attention to get the right device. If your USB stick is attached to
+your computer and reachable through `/dev/sdb`, you just have to run
+
+    sudo dd if=output.img of=/dev/sdb