diff --git a/README.md b/README.md
new file mode 100644
index 0000000..863cc29
--- /dev/null
+++ b/README.md
@@ -0,0 +1,157 @@
+# Full DNS
+
+Wannabe full-stack dns ansible role
+
+
+## Wat?
+
+This role aims to configure (only on debian stable systems) a working dns stack
+that aims to offer for own zones:
+
+ - [x] authoritative DNS via `nsd`
+ - [x] primary/secondaries replication (with AXFR queries only on secure
+   wireguard ptp tunnel)
+ - [x] DNS caching via unbound
+ - [ ] DNSSEC
+ - [ ] DNS-over-TLS
+ - [ ] DNS-over-HTTPS (eventually via [doh-proxy][0])
+ - [ ] A bit of hardening here and there
+
+## Why?
+
+I need it for my servers
+
+## How?
+
+Configure appropriately your inventory to include one **main zone** and pointing
+out the primary (_star_) and the secondaries (_satellite_). An example [variable
+file][1] looks like this
+
+```yml
+---
+dns_server:
+  verbosity: 3
+  main_zone:
+    name: foundation.lan
+    soa: sagittarius.foundation.lan
+    email: postmaster.foundation.lan
+    records:
+      - {name: "", type: MX, value: "10 terminus"}
+      - {name: "", type: MX, value: "20 trantor"}
+  zones:
+    - name: seldon.org
+      soa: sagittarius.seldon.org
+      email: postmaster.seldon.org
+      records:
+        - {name: sagittarius, type: A, value: 192.168.123.20}
+        - {name: hari, type: A, value: 192.168.123.21}
+        - {name: "", type: MX, value: "10 sagittarius"}
+        - {name: "", type: MX, value: "40 the.mule.net."}
+    - name: mule.net
+      soa: the.mule.net
+      email: postmaster@foundation.net
+      records:
+        - {name: the, type: A, value: 10.13.12.20}
+        - {name: "", type: MX, value: "10 sagittarius.seldon.org."}
+        - {name: "", type: MX, value: "40 the"}
+        - {name: _special_key, type: TXT, value: "GOTCHA"}
+  servers:
+
+    - name: sagittariusAstar
+      hostname: sagittarius.foundation.lan
+      local_resolver: true
+      nsd_addr: 127.0.0.1
+      nsd_port: 5353
+      star: true
+      public_ip: 192.168.123.20
+      vpn:
+        address: 10.13.12.20
+        net_size: 24
+        private_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          62346638623333623232376462346232316233653633343634376235393662396462326566633632
+          3538386564616436343138343832383362653730396532350a353632323562666333383066353437
+          31326366356139383636643663303263623537303730643236333363653135386636653064656163
+          3166656534663766300a383232323561303436343562363433636432613636653866636364613464
+          38663164646533656363613137353963643735633433303036316634373033306138306137356338
+          6239666465306638313037343231373663633833626130623462
+        public_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          65343336343938626332646439393065626636353837326166303239373463636664656535336365
+          6138326166653438346466336533656136653665313832350a616431646232306436366166666537
+          37313139303532663165343731666234633532323633646561353261613138666238353534633361
+          3931393637333339630a343465363766626536663530656535323265373864376165343737633033
+          31313262313133356364653964356537303761313135613464373031326334323933323033303733
+          3861373164663366313766663835636561356565383363373433
+
+    - name: trantor
+      hostname: trantor.foundation.lan
+      local_resolver: true
+      nsd_addr: 127.0.0.1
+      nsd_port: 5353
+      satellite: true
+      public_ip: 192.168.123.21
+      vpn:
+        address: 10.13.12.21
+        net_size: 24
+        private_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          37646262626137633331326438306463353538636332353134306161333962356138663535666538
+          3064373263313763363630333733313966636665373130660a313163653136323634626431633161
+          35323831386164366534616265313532343961333734376362643637353332346434373461386362
+          3130656639303738620a313938376562373566646530383339376139623662633865306262393031
+          33623661313739653966643766613734653665353337663435336430633730643461346363613961
+          3531643132353633626333663539653839343963333037666536
+        public_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          64613433666138303634653661633536356362396431363134383736653539613237643839643565
+          6235326661333562646237623761356364376234383965300a666431663262346162633131363264
+          65623238663838643531343065353039306231323836326335323463303161333938613231303139
+          3132646335326339640a396162303436326231643364653637633036303137646666376138386637
+          66303465653361366565626139656665303162316663616634363361346534643161663932313434
+          6263316630323532346666373839613037303334316537366434
+
+    - name: terminus
+      hostname: terminus.foundation.lan
+      nsd_addr: 127.0.0.1
+      nsd_port: 5353
+      satellite: true
+      public_ip: 192.168.123.22
+      vpn:
+        address: 10.13.12.22
+        net_size: 24
+        private_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          66623362633739316266376234363561656639376637666165323465643738323664643261613065
+          6463663063633163313432373564363636663234303264350a303032373336333133353766376364
+          37663965663837663936383265346164343563656636623133346132626664383262356465313836
+          3932666563326363660a306463383364386662613563653136333061326434373731323231323763
+          64353130336661306266636565626561376465393737663832303633633436343633363861616364
+          6436623833326632353363333862616634366133323534666166
+        public_key: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          66333135396638326166396264386535646633663730333632306166633166323230376563316466
+          3230383366336466623738613134346439303933346661630a626637313036613135656435343334
+          30643530363638326264316664393833666134613234333435333831353966383162633862303063
+          6665653534313461660a633566656130616562636337373434333037313030356336643266313135
+          35663563626137653065633463613966363961343138656566333731373833366164333136313032
+          3434343664333661346339373233373739393332636433363433
+
+```
+
+the `public_key` and `private_key` blocks can be generated with the [provided
+python script][2]. The usage is:
+
+```
+Usage:
+    gen_keys.py <path/to/inventory> <path/to/vault_password_file>
+```
+
+The keys are output in the same path, at `result.yml` in an easy-to-copy form,
+yet per-host divided.
+
+
+
+ [0]: https://github.com/jedisct1/doh-server
+ [1]: ./test_vars.yml
+ [2]: ./keys/gen_keys.py