first README version

CryptOps-enabled Initrd

=======================

This repository contains files that need to be added or changed in a "vanilla"

initrd in order to be able to use the

[CryptOps](https://code.greenhost.net/open/cryptops) toolkit to set up an

encrypted VPS.

More information can be found on the [documentation

website](https://cryptops.com)

## VPS setup

Some variables need to be passed to the initrd with kernel options. They are

retrieved from `/proc/cmdline`.

- `root=/dev/mapper/xvda1_crypt`: The partition that needs to be mounted as root

- `cryptroot=/dev/xvda`: The device that needs to be partitioned and encrypted

- `ip=213.108.110.71::213.108.110.126:255.255.255.128:encrypted-system:eth0:off`

  IP information (

  `<ip>:<??>:<gateway>:<subnet mask>:<hostname>:<network interface>:<???>`)

### Startup Notification

Some extra variables are used in Greenhost's case to be able to use the API to

send a message to the owner of a VPS after it has been restarted. These

variables are used in /scripts/local-top/cryptroot-api to make

`$notification_command`.

If you don't run on Greenhost infrastructure, change

that variable to something else to notify you of a (re)boot. 

If you do not have a notification_command, CryptOps will work fine, but when

your VPS reboots, you run the risk of not knowing this and your VPS will stay in

the initrd, waiting for you to unlock the disk.

- `api_key=<key>`: The *Bearer* authentication key for using the API

- `instance_id=###`: The unique identifier of the VPS

- `cosmos_url=https://management.greenhost.nl`: The URL to the API

A VPS is assumed to have one drive that needs to be encrypted (additional drives

can be encrypted manually from the booted operating system). The drive will be

partitioned into an encrypted root partition (in this example `xvda1_crypt`) and

a not encrypted data partition. The latter is used to save SSH keys, so the user

can log into the SSH shell running in the initrd.

## File structure

The folder `crypt-initrd-extra-files` contains all the files that need to be

inserted in the root directory of an initrd to make CryptOps work. Some things

stand out:

- The folder contains some symlinks pointing to a nonexistent directory

  `conf/persistent/` (for example the `home_root` file). The persistent file

  system is mounted in this directory by

  `scripts/init-premount/mount_persistent_config`