terribleplan/acme-dns-httpreq
1
0
Fork 0
Code Issues Pull requests Projects Releases Activity

add README

Browse source
This commit is contained in:
Kegan Myers 2022-02-19 23:28:22 -06:00
parent 138f7ba4c9
commit aee714537e
1 changed files with 62 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
README.md Normal file
View file

@ -0,0 +1,62 @@
# acme-dns-httpreq
This is a simple DNS server intended for use with the [LEGO httpreq DNS provider](https://go-acme.github.io/lego/dns/httpreq/). It is almost, but not quite, entirely unlike [JooHoi's acme-dns](https://github.com/joohoi/acme-dns) project.
# Building
This project is quite simple, the only requirement is a module-aware go compiler.
```
go build .
```
# Running
`acme-dns-httpreq` takes two arguments:
1. The base domain, which is the zone that will be delegated in DNS to this server.
1. The server address, which is used in the SOA records served by this domain.
Both arguments are full DNS names, which should end with a period.
```
./acme-dns-httpreq "acme-dns.keganmyers.com." "dns.keganmyers.com."
```
# Usage
Let's assume you want to issue a certificate for `*.example.com`.
## Server
There should be an acme-dns-httpreq server runnign somewhere, let's say on a server with IP `1.2.3.4`. It will be available at `http://dns.example.net` for http requests and `1.2.3.4:53`/`dns.example.com:53` for DNS requests. The following DNS records are assumed to exist:
```
dns.example.net. 300 IN A 1.2.3.4
acme.example.net. 300 IN NS dns.example.net.
```
## Client
The client is a using the [LEGO's HTTP Request provider](https://go-acme.github.io/lego/dns/httpreq/), and will need the following environment variables:
```
HTTPREQ_ENDPOINT=http://dns.example.net
HTTPREQ_USERNAME=_acme-challenge.example.com.
HTTPREQ_PASSWORD=w5m8bxRRXSDxt59
```
There will also need to be a DNS record set for everything to work:
```
_acme-challenge.example.com. 300 IN CNAME _acme-challenge.example.com.acme.example.net.
```
# Caveats
No authentication is done by this server, it merely validates that the username provided by basic auth matches the domain name that should be set. Authentication should be handled by some external process, such as a proxy server. In the example given above anyone could issue a certificate for `example.com` unless something is in place to ensure the `HTTPREQ_PASSWORD` is validated before passing the request to acme-dns-httpreq.
This server is hard-coded to listen on ports 53 and 80, that is because this server is intended to be run inside as a container, and routing set up as needed, ideally with at least a reverse proxy in front of it.
This program is not, and does not intend to be a fully featured authoritative DNS server. If you need to run those on the same server as this you will need to figure out how to route requests to this server.