diff --git a/README.md b/README.md
new file mode 100644
index 0000000..68af8f0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,19 @@
+# PowerDNS - Letsencrypt
+
+This role extends the PowerDNS role with another backend to handle Letsencrypt challanges.
+
+## operation
+
+We register a [PowerDNS pipe backend](https://doc.powerdns.com/authoritative/backends/pipe.html) and deploy a python script to serve it.
+The script is stored at `/usr/local/bin/pdns.py`. This script processes queries matching the regex `^_acme-challenge\\.`.
+It can also be called directly with `pdns.py <dns entry> <value>` to add challanges, for example `pdns.py "_acme-challenge.example.com" "R8aa0mt6cnCVLF6RHsSNxmDBzJffNCK6"`
+Challanges older than two days are removed when a new entry is added.
+
+## parameters
+
+All config is to be placed inside the `powerdns` dict in another dict called `letsencrypthandler`
+```
+# path to save the internaly used sqlite database to
+dbpath: '/var/lib/powerdns/letsencrypt/challenges.sqlite'
+
+```