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

Updated DNS API Dev Guide (markdown)

master
Farrel Franqois 2022-09-10 18:53:48 +07:00
parent 66511edae5
commit a002376897
1 changed files with 34 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
DNS-API-Dev-Guide.md

@ -1,27 +1,27 @@
# Guide for developing a dns api for acme.sh # Guide for developing a DNS API for acme.sh
This guide is to help any developer interested to build a brand new DNS API for acme.sh This guide is to help any developer interested to build a brand new DNS API for acme.sh
## 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/Neilpang/acme.sh/issues/1787) for details. Remember to remove `--staging` after testing. 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.
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:
```sh ```sh
export MYAPI_Username=myname export MYAPI_Username=myname
export MYAPI_Password=mypass export MYAPI_Password=mypass
acme.sh --issue -d example.com --dns dns_myapi acme.sh --issue -d example.com --dns dns_myapi
``` ```
Here we go: Here we go:
### 1. The Cloudflare dns api is a recommended reference: ### 1. The Cloudflare DNS API is a recommended reference:
Read it first: Read it first:
https://github.com/Neilpang/acme.sh/blob/master/dnsapi/dns_cf.sh https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_cf.sh
### 2. The script file name must be `dns_myapi.sh` ### 2. The script file name must be `dns_myapi.sh`
@ -47,7 +47,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 purpose, 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
@ -65,7 +65,7 @@ dns_myapi_add() {
``` ```
#### 2. You must save your username and password in the add function: #### 2. You must save your username and password in the add function:
The credentials such as username, password, api key or api token etc, must be saved so that acme.sh can renew the cert automatically in future. It will reuse the credentials automatically. The credentials such as username, password, API key or API token etc, must be saved so that acme.sh can renew the cert automatically in future. It will reuse the credentials automatically.
```sh ```sh
@ -100,18 +100,18 @@ 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)
*You can not just split the full domain, and get the first part as subdomain, and the rest as root zone. *You can not just split the full domain, and get the first part as a subdomain, and the rest as root zone.
Please make sure you can handle all the formats above.* 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/Neilpang/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() {
@ -128,17 +128,17 @@ dns_myapi_add() {
``` ```
#### 4. Call your dns api to add txt record. #### 4. Call your DNS API to add a TXT record.
Most of the dns providers provide a HTTP api or REST api. Most of the DNS providers provide an HTTP API or REST API.
So, you can just use HTTP GET/POST/PUT/DELETE method to call their api to add/remove txt record. So, you can just use the HTTP GET/POST/PUT/DELETE method to call their API to add/remove the TXT record.
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/Neilpang/acme.sh/blob/master/acme.sh#L1654 https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L2013
https://github.com/Neilpang/acme.sh/blob/master/acme.sh#L1582 https://github.com/acmesh-official/acme.sh/blob/8ded524236347d5a1f7a3169809cab9cf363a1c8/acme.sh#L1887
``` ```
_get() {} _get() {}
@ -147,11 +147,11 @@ _post() {}
You can use them directly. You can use them directly.
Please take care that the `_post()` function can send POST/PUT/DELETE request, not just `POST`. Please take care that the `_post()` function can send POST/PUT/DELETE requests, not just `POST`.
See: See:
https://github.com/Neilpang/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/Neilpang/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.
@ -192,13 +192,13 @@ Your HTTP method call may require additional headers for Authorization, ContentT
... ...
``` ```
Just number the _H*n* in the order that you need the headers. Please review [these](https://github.com/Neilpang/acme.sh/blob/master/dnsapi/dns_zone.sh#L110) [few](https://github.com/Neilpang/acme.sh/blob/master/dnsapi/dns_desec.sh#L151) [examples](https://github.com/Neilpang/acme.sh/blob/master/dnsapi/dns_jd.sh#L184) for inspiration. Just number the _H*n* in the order that you need the headers. Please review [these](https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_zone.sh#L110) [few](https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_desec.sh#L151) [examples](https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/dns_jd.sh#L184) for inspiration.
This is the only way to pass the equivalent wget's _--user_ and _--password_ and curl's _--user_ parameters. This is the only way to pass the equivalent wget's _--user_ and _--password_ and curl's _--user_ parameters.
#### 6. Process the api response. #### 6. Process the API Response.
The api response could be in text, json or xml format. Here are a lot of functions to process strings: The API response could be in text, JSON or XML format. Here are a lot of functions to process strings:
```sh ```sh
... ...
@ -222,32 +222,26 @@ 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/Neilpang/acme.sh/blob/ded7a5438ce94c4dd0435068de5c0c384b60e4dd/dnsapi/dns_cf.sh#L85 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 V2 wildcard cert: https://github.com/acmesh-official/acme.sh/issues/1261
https://github.com/Neilpang/acme.sh/issues/1261
### 9. Update the docs to include your dns api usage. ### 9. Update the docs to include your DNS API usage.
Please append your API at the end: https://github.com/acmesh-official/acme.sh/wiki/dnsapi2
please append your api at the end: https://github.com/Neilpang/acme.sh/wiki/dnsapi
### 10. Please create a new issue for future bugs ### 10. Please create a new issue for future bugs
Please report a new issue here: `" Report bugs to xxxx dns api"` https://github.com/Neilpang/acme.sh/issues Please report a new issue here: `" Report bugs to xxxx DNS API"` https://github.com/acmesh-official/acme.sh/issues
And please watch to that issue. Any future bug will be reported there. And please watch to that issue. Any future bug will be reported there.
Example: https://github.com/Neilpang/acme.sh/issues/2057 Example: https://github.com/acmesh-official/acme.sh/issues/2057
### 11. Please read and follow the instruction before creating a pull request ### 11. Please read and follow the instruction before creating a pull request
Please follow the guide: https://github.com/acmesh-official/acme.sh/wiki/DNS-API-Test Please follow the guide: https://github.com/acmesh-official/acme.sh/wiki/DNS-API-Test
See more code of conduct: https://github.com/acmesh-official/acme.sh/wiki/Code-of-conduct
See more code of conduct: https://github.com/acmesh-official/acme.sh/wiki/Code-of-conduct