github
/
acme.sh
mirror of https://github.com/acmesh-official/acme.sh
1
0
Fork 0
Code Issues Releases Wiki Activity

Tidy up links

master
Farrel Franqois 2022-09-10 19:03:34 +07:00
parent a002376897
commit 43f869667e
1 changed files with 12 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
DNS-API-Dev-Guide.md

@ -5,7 +5,7 @@ This guide is to help any developer interested to build a brand new DNS API for
## Some useful tips ## Some useful tips
1. It's normal to run into errors, so do use `--debug 2` when testing. For e.g., `acme.sh --issue --debug 2 -d example.com --dns dns_myapi` 1. It's normal to run into errors, so do use `--debug 2` when testing. For e.g., `acme.sh --issue --debug 2 -d example.com --dns dns_myapi`
2. It's normal to burst rate limits for letsencrypt, so do use `--staging` when testing. For e.g., `acme.sh --issue --staging --debug 2 -d example.com --dns dns_myapi` Read [issue 1787](https://github.com/acmesh-official/acme.sh/issues/1787) for details. Remember to remove `--staging` after testing. 2. It's normal to burst rate limits for Let's Encrypt, so do use `--staging` when testing. For e.g., `acme.sh --issue --staging --debug 2 -d example.com --dns dns_myapi` Read [issue 1787](https://github.com/acmesh-official/acme.sh/issues/1787) for details. Remember to remove `--staging` after testing.
Let's assume your API name is `myapi`, and you will use your API like: Let's assume your API name is `myapi`, and you will use your API like:
@ -34,7 +34,6 @@ Here we go:
acme.sh searches the script files in either the acme.sh home dir(`.acme.sh/`) or in the `dnsapi` subfolder(`.acme.sh/dnsapi`). acme.sh searches the script files in either the acme.sh home dir(`.acme.sh/`) or in the `dnsapi` subfolder(`.acme.sh/dnsapi`).
### 4. There must be 2 functions in your script: ### 4. There must be 2 functions in your script:
```sh ```sh
@ -47,7 +46,7 @@ Here we go:
dns_myapi_rm() { } dns_myapi_rm() { }
``` ```
Actually, the `dns_myapi_add()` is required, but `dns_myapi_rm()` is optional. You can just write the add function at the beginning for testing purposes, it's `highly recommended` to implement the rm function too. Otherwise, your txt records will increase 1 every 2 months. Actually, the `dns_myapi_add()` is required, but `dns_myapi_rm()` is optional. You can just write the add function at the beginning for testing purposes, it's `highly recommended` to implement the rm function too. Otherwise, your TXT records will increase 1 every 2 months.
### 5. Guide for the add function ### 5. Guide for the add function
@ -100,8 +99,8 @@ The full domain could be in either one of the following formats:
4. `_acme-challenge.www.example.co.uk` 4. `_acme-challenge.www.example.co.uk`
5. `_acme-challenge.sub1.sub2.www.example.co.uk` 5. `_acme-challenge.sub1.sub2.www.example.co.uk`
6. `sub1.sub2.example.co.uk` 6. `sub1.sub2.example.co.uk`
7. `example.com` ( For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)) 7. `example.com` (For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode))
8. `example.co.uk` ( For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)) 8. `example.co.uk` (For [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode))
For most of the DNS providers, you must determine which part is the domain root zone(example.com or example.co.uk), and which part is the subdomain(_acme-challenge or _acme-challenge.www) For most of the DNS providers, you must determine which part is the domain root zone(example.com or example.co.uk), and which part is the subdomain(_acme-challenge or _acme-challenge.www)
@ -110,8 +109,7 @@ Please make sure you can handle all the formats above.*
A good practice is to list all your root zones through your DNS API, then compare and detect which part is the root zone. Then the rest is the subdomain. A good practice is to list all your root zones through your DNS API, then compare and detect which part is the root zone. Then the rest is the subdomain.
See: See: https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_cf.sh#L142
https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_cf.sh#L142
```sh ```sh
dns_myapi_add() { dns_myapi_add() {
@ -136,9 +134,9 @@ So, you can just use the HTTP GET/POST/PUT/DELETE method to call their API to ad
acme.sh defined two functions to make http GET/POST/PUT/DELETE connections. acme.sh defined two functions to make http GET/POST/PUT/DELETE connections.
see: See:
https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L2013 - https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L2013
https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L1887 - https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L1887
``` ```
_get() {} _get() {}
@ -150,8 +148,8 @@ You can use them directly.
Please take care that the `_post()` function can send POST/PUT/DELETE requests, not just `POST`. Please take care that the `_post()` function can send POST/PUT/DELETE requests, not just `POST`.
See: See:
https://github.com/acmesh-official/acme.sh/blob/975a7359a23cd5f8335aca58ceab552d8d967ea7/dnsapi/dns_infoblox.sh#L85 - https://github.com/acmesh-official/acme.sh/blob/975a7359a23cd5f8335aca58ceab552d8d967ea7/dnsapi/dns_infoblox.sh#L85
https://github.com/acmesh-official/acme.sh/blob/ded7a5438ce94c4dd0435068de5c0c384b60e4dd/dnsapi/dns_cf.sh#L73 - https://github.com/acmesh-official/acme.sh/blob/ded7a5438ce94c4dd0435068de5c0c384b60e4dd/dnsapi/dns_cf.sh#L73
Do not use `curl` or `wget` directly in your script. Do not use `curl` or `wget` directly in your script.
@ -177,7 +175,7 @@ _acme-challenge.example.com. 3600 IN TXT "XhVGx_0VVeR5yiaGLHHXrRl2sAbZhI7IugMSdb
#### 5. Additional HTTP headers. #### 5. Additional HTTP headers.
Your HTTP method call may require additional headers for Authorization, ContentType, Accept, Cookies, etc. for the DNS providers api to add/remove the txt record. You can export _H*n* (_H1, _H2, _H3, etc.) environment variables with the [HTTP header](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) needed: Your HTTP method call may require additional headers for Authorization, ContentType, Accept, Cookies, etc. for the DNS providers API to add/remove the txt record. You can export _H*n* (_H1, _H2, _H3, etc.) environment variables with the [HTTP header](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) needed:
```sh ```sh
... ...
@ -221,8 +219,7 @@ Please take care that the rm function and add function are called in 2 different
You must re-do all the preparations of the add function here too. You must re-do all the preparations of the add function here too.
See: See: https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/dnsapi/dns_cf.sh#L106
https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/dnsapi/dns_cf.sh#L106
### 8. Please also check this bug to support the V2 wildcard cert: ### 8. Please also check this bug to support the V2 wildcard cert: