diff --git a/README.md b/README.md index aebce986..bc6ced8b 100644 --- a/README.md +++ b/README.md @@ -113,13 +113,13 @@ Check out how in the INSTALL section. 1) Install [Go 1.9 or newer](https://golang.org/doc/install) -2) Install acme-dns: `go get github.com/joohoi/acme-dns/...` +2) Install acme-dns: `go get github.com/joohoi/acme-dns/...`. This will install acme-dns to `~/go/bin/acme-dns`. 3) Edit config.cfg to suit your needs (see [configuration](#configuration)). `acme-dns` will read the configuration file from `/etc/acme-dns/config.cfg` or `./config.cfg` 4) Run acme-dns. Please note that acme-dns needs to open a privileged port (53, domain), so it needs to be run with elevated privileges. -## Using Docker +### Using Docker 1) Pull the latest acme-dns Docker image: `docker pull joohoi/acme-dns` @@ -139,7 +139,7 @@ docker run --rm --name acmedns \ -d joohoi/acme-dns ``` -## Docker Compose +### Docker Compose 1) Create directories: `config` for the configuration file, and `data` for the sqlite3 database. @@ -149,6 +149,49 @@ docker run --rm --name acmedns \ 4) Edit the `config/config.cfg` and `docker-compose.yml` to suit your needs, and run `docker-compose up -d` +## DNS Records + +Note: In this documentation: +- `example.com` is your domain name +- `auth.example.com` is the subdomain you want to use for acme-dns +- `198.51.100.1` is the **public** IP address of the system running acme-dns + +These values should be changed based on your environment. + +You will need to add some DNS records on your domain's regular DNS server: +- `NS` record for `auth.example.com` pointing to `ns.auth.example.com` +- `A` record for `ns.auth.example.com` pointing to `198.51.100.1` +- If using IPv6, an `AAAA` record pointing to the IPv6 address +- Each domain you will be authenticating will need a `CNAME` for a `_acme-challenge` subdomain added. The [client](README.md#clients) you use will explain how to do this. + +## Testing It Out + +You may want to test that acme-dns is working before using it for real queries. + +1) Confirm that DNS lookups for the acme-dns subdomain works as expected: `dig auth.example.com` + +2) Call the `/register` API endpoint to register a test domain: +``` +$ curl -X POST http://auth.example.com/register +{"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2","password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0","fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com","subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf","allowfrom":[]} +``` + +3) Call the `/update` API endpoint to set a test TXT record. Pass the `username`, `password` and `subdomain` received from the `register` call performed above: +``` +$ curl -X POST \ + -H "X-Api-User: eabcdb41-d89f-4580-826f-3e62e9755ef2" \ + -H "X-Api-Key: pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0" \ + -d '{"subdomain": "d420c923-bbd7-4056-ab64-c3ca54c9b3cf", "txt": "___validation_token_recieved_from_the_ca___"}' \ + http://auth.example.com/update +``` + +Note: The `txt` field must be exactly 43 characters long, otherwise acme-dns will reject it + +4) Perform a DNS lookup to the test subdomain to confirm that everything is working properly: +``` +$ dig @ns.auth.example.com d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com +``` + ## Configuration ```bash