From 4b470222c465fb2274d8297940bd68e319ce76db Mon Sep 17 00:00:00 2001
From: Frank Denis <github@pureftpd.org>
Date: Fri, 20 Sep 2019 12:03:49 +0200
Subject: [PATCH] Update the documentation

---
 .github/workflows/rust.yml | 21 ++++++++++++
 README.md                  | 69 +++++++++++++++++++++++++++++++-------
 encrypted-dns.toml         |  5 +--
 3 files changed, 80 insertions(+), 15 deletions(-)
 create mode 100644 .github/workflows/rust.yml

diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
new file mode 100644
index 0000000..9044013
--- /dev/null
+++ b/.github/workflows/rust.yml
@@ -0,0 +1,21 @@
+name: Rust
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@master
+      - uses: hecrj/setup-rust-action@master
+        with:
+          rust-version: nightly
+      - name: Check Cargo availability
+        run: cargo --version
+      - name: Check Rustup default toolchain
+        run: rustup default | grep nightly
+      - name: Build
+        run: cargo build
+      - name: Run tests
+        run: cargo test
diff --git a/README.md b/README.md
index 579ae3f..2849ade 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,64 @@
 # Encrypted DNS Server
 
-A new server-side proxy for encrypted DNS, written in Rust, supporting:
+An easy to install, zero maintenance proxy to run an encrypted DNS server.
+
+Written in Rust.
+
+## Protocols
+
+The proxy aims at supporting the following protocols:
 
 - [DNSCrypt v2](https://github.com/DNSCrypt/dnscrypt-protocol/blob/master/DNSCRYPT-V2-PROTOCOL.txt)
-- [Anonymized DNSCrypt](https://github.com/DNSCrypt/dnscrypt-protocol/blob/master/ANONYMIZED-DNSCRYPT.txt)
+- [Anonymized DNSCrypt](https://github.com/DNSCrypt/dnscrypt-protocol/blob/master/ANONYMIZED-DNSCRYPT.txt) (WIP)
 - DNS-over-HTTP (DoH)
 
-Distinctive features:
+All of these can be served simultaneously, on the same port (usually port 443). The proxy automatically detects what protocol is being used by each client.
+
+## Installation
+
+The proxy uses recent features of the Rust compiler, and currently requires rust-nightly.
+
+Rust can installed with:
+
+```sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+Once rust is installed, the proxy can be compiled and installed with the following command, to be run in the source directory:
+
+```sh
+cargo install --path .
+```
+
+## Setup
+
+The proxy requires a recursive DNS resolver, such as Knot, PowerDNS or Unbound.
+
+That resolver can run locally and only respond to `127.0.0.1`. External resolvers such as Quad9 or Cloudflare DNS can also be used, but this may be less reliable due to rate limits.
+
+In order to support DoH in addition to DNSCrypt, a DoH proxy must be running as well. [rust-doh](https://github.com/jedisct1/rust-doh) is the recommended DoH proxy server. DoH support is optional, as it is currently way more complicated to setup than DNSCrypt due to certificate management.
+
+Review the `encrypted-dns.toml` configuration file. This is where all the parameters can be configured, including the IP addresses to listen to. You should probably at least change the `provider_name` setting.
+
+Start the proxy. It will automatically create a new provider key pair if there isn't any.
+
+The DNS stamps are printed. They can be used directly with `dnscrypt-proxy`.
+
+There is nothing else to do. Certificates are automatically generated and rotated.
+
+## Migrating from dnscrypt-wrapper
+
+If you are currently running an encrypted DNS server using `dnscrypt-wrapper`, moving to the new proxy is simple:
+
+- Double check that the provider name in `encrypted-dns.toml` matches the one you previously configured. If you forgot it, it can be recovered [from its DNS stamp](https://dnscrypt.info/stamps/).
+- Run `dnscrypt-dns --import-from-dnscrypt-wrapper secret.key`, with `secret.key` being the file with the `dnscrypt-wrapper` provider secret key.
+
+Done. Your server is now running the new proxy.
+
+## State file
+
+The proxy creates and updates a file named `encrypted-dns.state` by default. That file contains the provider secret key, as well as certificates and encryption keys.
 
-- Trivial to set up. Keys, certificates and stamps are automatically created and renewed without requiring any external scripts.
-- Keys can be imported from `dnscrypt-wrapper`.
-- Serve all protocols on the same IP and port. Yes, you can serve both DNSCrypt and DoH on port 443.
-- Caching.
-- Anonymized DNSCrypt.
-- Rate limiting.
-- Prometheus metrics.
-- Local filtering.
-- Windows support.
+Do not delete the file, unless you want to change parameters (such as the provider name), and keep it secret, or the keys will be lost.
 
-## *** This is a work in progress - Nothing to see yet ***
+Putting it in a directory that is only readable by the super-user is not a bad idea.
diff --git a/encrypted-dns.toml b/encrypted-dns.toml
index e2071dc..b37ec81 100644
--- a/encrypted-dns.toml
+++ b/encrypted-dns.toml
@@ -12,7 +12,7 @@
 
 ## IP addresses and ports to listen to
 
-listen_addrs = ["127.0.0.1:4443", "[::1]:4443"]
+listen_addrs = ["0.0.0.0:443", "[::1]:4443"]
 
 
 ## IP address to connect to upstream servers from
@@ -61,8 +61,9 @@ tcp_max_active_connections = 100
 
 
 ## Path to chroot() to, when started as root.
+## The path to the state file is relative to the chroot base.
 
-# chroot = "/tmp"
+# chroot = "/var/empty"