diff --git a/README.md b/README.md
index 1a382ef8b9031e6dbdb1b01328169d527813a814..0f3e7238b918a809d68ea3dc7d7d6fd5d37c778f 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,7 @@
-# Usage
+CryptOps implements full disk encryption for virtual private servers.
-```sh
-cryptops-api --root-device=DEV --crypt-name=LABEL [--notify-command=COMMAND]
-```
+All documentation can be found on
+[the website](https://cryptops.com).
-* The `--root-device=DEV` option is mandatory. `DEV` should be the root device
- of the machine, like `/dev/sda` or `/dev/xvda`.
-
- When the root device is still unencrypted (for example when starting
- cryptops-api for the first time), this should be an unpartitioned device,
- with the file system spanning the whole device.
-
- As part of the encryption process, this device will be partitioned and the
- encrypted contents will be stored on the second partition, but DEV should
- still point to the whole device, as before.
-
-* The `--crypt-name=LABEL` option is mandatory. `LABEL` will be used by
- cryptsetup to name the encrypted volume. This will be visible to the operating
- system, as the decrypted root disk is available at `/dev/mapper/LABEL`.
-
-* The `--notify-command=COMMAND` option is optional. The given `COMMAND` will be
- run whenever cryptops-api detects that the root device needs the user to enter
- their password to continue the booting process. You can use this to notify the
- user of this situation.
+In particular, please read the
+[security considerations](https://cryptops.com/considerations.html).
diff --git a/docs/considerations.rst b/docs/considerations.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7245a86e6476a9fb45a19735441d69348afed01e
--- /dev/null
+++ b/docs/considerations.rst
@@ -0,0 +1,54 @@
+Considerations
+==============
+
+CryptOps is a tool that can be used to raise the level of security in some
+particular aspects. It does not provide all-round security of your VPS.
+
+CryptOps can be used as a part of an overall security strategy and should never
+be used as definitive security solution.
+
+Possible reasons to use CryptOps
+--------------------------------
+
+* You want to make it harder for the hoster's employees to casually view your
+ data on disk.
+* You trust your hoster now, but you want to have an easy way to cut off their
+ access to your data – maybe when they change owners, or when you anticipate
+ that they are forced by some authority to grant access to your data.
+* You want your data to be safe in case the hosters disks get confiscated,
+ stolen, or discarded without shredding.
+* You want your data to be encrypted at rest.
+
+Invalid reasons to use CryptOps
+-------------------------------
+
+* You don't trust your hoster, or you fear that they may be forced to grant
+ access to your data without a timely warning. If your hoster or a powerful
+ third party really wants to view your data, they could
+
+ * install a modified version of CryptOps that doesn't really encrypt;
+ * man-in-the-middle your first ssh connection to the server running in the
+ initrd, capturing your encryption password when you first enter it;
+ * access your decrypted data in memory while your vps is active;
+ * various other methods.
+
+It is very hard to prevent someone who has access (physical or via network) to
+the host running your vps from reading your data, and CryptOps does not pretend
+to do so.
+
+Possible reasons to not use CryptOps
+------------------------------------
+
+* It increases the chance of data loss: if you forget or lose your encryption
+ password, a single reboot of your vps (for whatever reason) renders your data
+ irrecoverably lost.
+* It can increase downtime of your vps: whenever your vps reboots, you need to
+ become aware of this (though we have a customisable hook to notify you of this
+ situation), connect to the vps, and enter your encryption password; only then
+ can the boot process of the vps continue. All this time the service provided
+ by your vps is not running.
+* You may not need full disk encryption of your vps: depending on the software
+ running on your vps, it could be easier to encrypt only some data directories.
+ On the other hand, it is easy to overlook some sensitive data stored in
+ configuration, cache files, temporary files, etc.
+
diff --git a/docs/index.rst b/docs/index.rst
index 48f725884724f76ac92890c0a393ba283552f018..27cdd7fdffeb9f429fb296e5a859fa4706699728 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,4 +1,4 @@
-.. Cryptops documentation master file, created by
+.. CryptOps documentation master file, created by
sphinx-quickstart on Tue Oct 17 10:00:20 2017.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
@@ -24,7 +24,7 @@ provider? Existing solutions often rely on encryption keys being managed by the
service providers themselves or the data being encrypted at the application
level.
-CryptOps is a new, provider agnostic approach which makes full-disk encryption
+CryptOps is a new, provider agnostic approach which makes full disk encryption
at the Virtual Machine layer more accessible and secure for the average user.
Users can encrypt their VPSs by logging into a `Dropbear SSH`_ shell
that runs in the initrd. In this environment, the user is allowed to type
@@ -35,8 +35,11 @@ to manage their SSH and LUKS encryption keys. The CryptOps framework has been
designed to be open & extensible, allowing it to support external client
applications in the future.
-Find the code at `<https://code.greenhost.net/open/cryptops>`_ and an example initrd at
-`<https://code.greenhost.net/open/cryptops-initrd>`_
+Please read the :doc:`security considerations <considerations>` to learn
+exactly what CryptOps does and doesn't protect against.
+
+Find the code at `<https://code.greenhost.net/open/cryptops>`_ and an example
+initrd at `<https://code.greenhost.net/open/cryptops-initrd>`_
.. _`Dropbear SSH`: https://matt.ucc.asn.au/dropbear/dropbear.html
.. _Greenhost: https://greenhost.net
@@ -45,8 +48,9 @@ Find the code at `<https://code.greenhost.net/open/cryptops>`_ and an example in
:maxdepth: 2
:caption: Contents:
- readme.md
- api_documentation.rst
+ considerations
+ usage
+ api_documentation
diff --git a/docs/readme.md b/docs/readme.md
deleted file mode 120000
index 32d46ee883b58d6a383eed06eb98f33aa6530ded..0000000000000000000000000000000000000000
--- a/docs/readme.md
+++ /dev/null
@@ -1 +0,0 @@
-../README.md
\ No newline at end of file
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8e794a26bbd65a3933c2da0af502e4ca35dd4a95
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,26 @@
+Usage
+=====
+
+::
+
+ cryptops-api --root-device=DEV --crypt-name=LABEL [--notify-command=COMMAND]
+
+* The ``--root-device=DEV`` option is mandatory. ``DEV`` should be the root device
+ of the machine, like ``/dev/sda`` or ``/dev/xvda``.
+
+ When the root device is still unencrypted (for example when starting
+ cryptops-api for the first time), this should be an unpartitioned device,
+ with the file system spanning the whole device.
+
+ As part of the encryption process, this device will be partitioned and the
+ encrypted contents will be stored on the second partition, but DEV should
+ still point to the whole device, as before.
+
+* The ``--crypt-name=LABEL`` option is mandatory. ``LABEL`` will be used by
+ cryptsetup to name the encrypted volume. This will be visible to the operating
+ system, as the decrypted root disk is available at ``/dev/mapper/LABEL``.
+
+* The ``--notify-command=COMMAND`` option is optional. The given ``COMMAND`` will be
+ run whenever cryptops-api detects that the root device needs the user to enter
+ their password to continue the booting process. You can use this to notify the
+ user of this situation.