README.md 2.75 KB
Newer Older
Maarten de Waard's avatar
Maarten de Waard committed
1
2
3
4
5
6
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
7
encrypted VPS. CryptOps is included as a subrepository, to be able to track the
Arie Peterson's avatar
Arie Peterson committed
8
changes to the API with the changes of this initrd. Use the `build.sh` script to
9
10
copy the CryptOps api and client binaries to the correct location in the initrd
before building it.
Maarten de Waard's avatar
Maarten de Waard committed
11
12
13
14
15
16
17

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
18
19
retrieved from `/proc/cmdline`. [Here's the official
documentation.](https://github.com/torvalds/linux/blob/master/Documentation/filesystems/nfs/nfsroot.txt)
Maarten de Waard's avatar
Maarten de Waard committed
20
21
22
23

- `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`
24
25
  IP information:
  `ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>`
Maarten de Waard's avatar
Maarten de Waard committed
26
27
28

### Startup Notification

Maarten de Waard's avatar
Maarten de Waard committed
29
30
31
Some extra variables are used in Greenhost's case to be able to use the Cosmos
Service Centre 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
Maarten de Waard's avatar
Maarten de Waard committed
32
33
34
35
36
37
38
39
40
`$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.

Maarten de Waard's avatar
Maarten de Waard committed
41
- `api_key=<key>`: The *Bearer* authentication key for using the Cosmos API
Maarten de Waard's avatar
Maarten de Waard committed
42
- `instance_id=###`: The unique identifier of the VPS
Maarten de Waard's avatar
Maarten de Waard committed
43
- `cosmos_url=https://management.greenhost.nl`: The URL to the Cosmos API
Maarten de Waard's avatar
Maarten de Waard committed
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

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`