README.md
1# goacmedns
2
3A Go library to handle [acme-dns](https://github.com/joohoi/acme-dns) client
4communication and persistent account storage.
5
6[](https://github.com/cpu/goacmedns/actions?query=workflow%3AGo)
7[](https://github.com/cpu/goacmedns/actions?query=workflow%3Agolangci-lint)
8[](https://coveralls.io/github/cpu/goacmedns?branch=master)
9[](https://goreportcard.com/report/github.com/cpu/goacmedns)
10
11You may also be interested in a Python equivalent,
12[pyacmedns](https://github.com/joohoi/pyacmedns/).
13
14# Installation
15
16Once you have [installed Go](https://golang.org/doc/install) 1.15+ you can
17install `goacmedns` with `go get`:
18
19 go get github.com/cpu/goacmedns/...
20
21# Usage
22
23The following is a short example of using the library to update a TXT record
24served by an `acme-dns` instance.
25
26```go
27package main
28
29import (
30 "log"
31
32 "github.com/cpu/goacmedns"
33)
34
35const (
36 domain = "your.example.org"
37)
38
39var (
40 whitelistedNetworks = []string{"192.168.11.0/24", "[::1]/128"}
41)
42
43func main() {
44 // Initialize the client. Point it towards your acme-dns instance.
45 client := goacmedns.NewClient("https://auth.acme-dns.io")
46 // Initialize the storage. If the file does not exist, it will be
47 // automatically created.
48 storage := goacmedns.NewFileStorage("/tmp/storage.json", 0600)
49
50 // Check if credentials were previously saved for your domain
51 account, err := storage.Fetch(domain)
52 if err != nil && err != goacmedns.ErrDomainNotFound {
53 log.Fatal(err)
54 } else if err == goacmedns.ErrDomainNotFound {
55 // The account did not exist. Let's create a new one
56 // The whitelisted networks parameter is optional and can be nil
57 newAcct, err := client.RegisterAccount(whitelistedNetworks)
58 if err != nil {
59 log.Fatal(err)
60 }
61 // Save it
62 err = storage.Put(domain, newAcct)
63 if err != nil {
64 log.Fatalf("Failed to put account in storage: %v", err)
65 }
66 err = storage.Save()
67 if err != nil {
68 log.Fatalf("Failed to save storage: %v", err)
69 }
70 account = newAcct
71 }
72
73 // Update the acme-dns TXT record
74 err = client.UpdateTXTRecord(account, "___validation_token_recieved_from_the_ca___")
75 if err != nil {
76 log.Fatal(err)
77 }
78}
79```
80
81# Pre-Registration
82
83When using `goacmedns` with an ACME client hook it may be desirable to do the
84initial ACME-DNS account creation and CNAME delegation ahead of time The
85`goacmedns-register` command line utility provides an easy way to do this:
86
87 go install github.com/cpu/goacmedns/...
88 goacmedns-register -api http://10.0.0.1:4443 -domain example.com -allowFrom 192.168.100.1/24,1.2.3.4/32,2002:c0a8:2a00::0/40 -storage /tmp/example.storage.json
89
90This will register an account for `example.com` that is only usable from the
91specified CIDR `-allowFrom` networks with the ACME-DNS server at
92`http://10.0.0.1:4443`, saving the account details in
93`/tmp/example.storage.json` and printing the required CNAME record for the
94`example.com` DNS zone to stdout.
95
){kind=link}
){kind=link}
){kind=link}