simon/acme-dns
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Oh I suck at markdown

Browse Source
This commit is contained in:
Joona Hoikkala 2016-11-29 00:43:24 +02:00
parent 0b9bc7d740
commit b661ffcf22
No known key found for this signature in database
GPG Key ID: C14AAE0F5ADCB854
1 changed files with 56 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
README.md
View File

@ -5,75 +5,78 @@ A simplified DNS server with a RESTful HTTP API to provide a simple way to autom
## Usage ## Usage
Using acme-dns is a three-step process (provided you already have the server set up, or are using a service): Using acme-dns is a three-step process (provided you already have the server set up, or are using a service):
- Get credentials and unique subdomain (simple GET request to https://auth.exmaple.org/register) - Get credentials and unique subdomain (simple GET request to https://auth.exmaple.org/register)
- Create a (ACME magic) CNAME record to your existing zone, pointing to the subdomain you got from the registration. (eg. \_acme-challenge.domainiwantcertfor.tld. CNAME a097455b-52cc-4569-90c8-7a4b97c6eba8.auth.example.org )
- Create a (ACME magic) CNAME record to your existing zone, pointing to the subdomain you got from the registration. (eg. `_acme-challenge.domainiwantcertfor.tld. CNAME a097455b-52cc-4569-90c8-7a4b97c6eba8.auth.example.org` )
- Use your credentials to POST a new DNS challenge values to an acme-dns server for the CA to validate them off of. - Use your credentials to POST a new DNS challenge values to an acme-dns server for the CA to validate them off of.
After that, crontab and forget. After that, crontab and forget.
## Why? ## Why?
Many DNS servers do not provide an API to enable automation for the ACME DNS challenges. And those which do, give the keys way too much power to leave them laying around your random boxes, which sadly would be required to have a meaningful way to automate the process. Many DNS servers do not provide an API to enable automation for the ACME DNS challenges. And those which do, give the keys way too much power to leave them laying around your random boxes, which sadly would be required to have a meaningful way to automate the process.
So basically it boils down to **accessibility** and **security** So basically it boils down to **accessibility** and **security**
## Features ## Features
- Simplified DNS server, serving your ACME DNS challenges (TXT) - Simplified DNS server, serving your ACME DNS challenges (TXT)
- Custom records (have your required A, AAAA, NS, etc. records served) - Custom records (have your required A, AAAA, NS, etc. records served)
- HTTP API automatically acquires and uses Let's Encrypt TLS certificate - HTTP API automatically acquires and uses Let's Encrypt TLS certificate
- Simple deployment (it's Go after all) - Simple deployment (it's Go after all)
- Supports SQLite & PostgreSQL as DB backends - Supports SQLite & PostgreSQL as DB backends
## API ## API
### Register endpoint ### Register endpoint
The method returns a new unique subdomain to point the CNAME record to, along with credentials needed to update its TXT response. The method returns a new unique subdomain to point the CNAME record to, along with credentials needed to update its TXT response.
```GET /register``` ```GET /register```
#### Parameters #### Parameters
None None
```Status: 201 Created``` ```Status: 201 Created```
``` ```
{ {
"fulldomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.acme-dns.io", "fulldomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.acme-dns.io",
"password": "htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z", "password": "htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z",
"subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a", "subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
"username": "c36f50e8-4632-44f0-83fe-e070fef28a10" "username": "c36f50e8-4632-44f0-83fe-e070fef28a10"
} }
``` ```
### Update endpoint ### Update endpoint
The method allows you to update the TXT answer contents of your unique subdomain. Usually carried automatically by automated ACME client. The method allows you to update the TXT answer contents of your unique subdomain. Usually carried automatically by automated ACME client.
```POST /update``` ```POST /update```
#### Required headers #### Required headers
| Header name | Description | Example | | Header name | Description | Example |
| ------------- |--------------------------------------------|-------------------------------------------------------| | ------------- |--------------------------------------------|-------------------------------------------------------|
| X-Api-User | UUIDv4 username recieved from registration | `X-Api-User: c36f50e8-4632-44f0-83fe-e070fef28a10` | | X-Api-User | UUIDv4 username recieved from registration | `X-Api-User: c36f50e8-4632-44f0-83fe-e070fef28a10` |
| X-Api-Key | Password recieved from registration | `X-Api-Key: htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z` | | X-Api-Key | Password recieved from registration | `X-Api-Key: htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z` |
#### Example input #### Example input
``` ```
{ {
"subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a", "subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
"txt": "______my_43_char_dns_validation_token______" "txt": "______my_43_char_dns_validation_token______"
} }
``` ```
#### Response #### Response
```200 OK``` ```200 OK```
``` ```
{ {
"txt": "______my_43_char_dns_validation_token______" "txt": "______my_43_char_dns_validation_token______"
} }
``` ```
## Self-hosted ## Self-hosted
@ -89,19 +92,19 @@ I am runnin an acme-dns instance as a service for everyone wanting to get on in
## Installation ## Installation
1) Install [Go](https://golang.org/doc/install) 1) Install [Go](https://golang.org/doc/install)
2) Clone this repo: `git clone https://github.com/joohoi/acme-dns $GOPATH/src/acme-dns` 2) Clone this repo: `git clone https://github.com/joohoi/acme-dns $GOPATH/src/acme-dns`
3) Install govendor. ‘go get -u github.com/kardianos/govendor’ . This is used for dependency handling. 3) Install govendor. ‘go get -u github.com/kardianos/govendor’ . This is used for dependency handling.
4) Get dependencies: `cd $GOPATH/src/acme-dns` and `govendor sync` 4) Get dependencies: `cd $GOPATH/src/acme-dns` and `govendor sync`
5) Build ACME-DNS: `go build` 5) Build ACME-DNS: `go build`
6) Edit config.cfg to suit your needs (see [configuration](#configuration)) 6) Edit config.cfg to suit your needs (see [configuration](#configuration))
7) Run acme-dns. Please note that acme-dns needs to open a privileged port (53, domain), so it needs to be run with according privileges. 7) Run acme-dns. Please note that acme-dns needs to open a privileged port (53, domain), so it needs to be run with according privileges.
## Configuration ## Configuration
@ -167,13 +170,13 @@ logformat = "text"
## TODO ## TODO
- Ability to POST to /register endpoint, giving users the possibility to define CIDR masks to restrict the /update requests for the created user / key to. - Ability to POST to /register endpoint, giving users the possibility to define CIDR masks to restrict the /update requests for the created user / key to.
- Want to see something implemented, make a feature request! - Want to see something implemented, make a feature request!
## Contributing ## Contributing
acme-dns is open for contributions. So if you have an improvement, please open a Pull Request. acme-dns is open for contributions. So if you have an improvement, please open a Pull Request.
## License ## License
acme-dns is released under the [MIT License](http://www.opensource.org/licenses/MIT). acme-dns is released under the [MIT License](http://www.opensource.org/licenses/MIT).