From 114072e86b69a3fe2fee9d73c729e9dfd4d2a0a7 Mon Sep 17 00:00:00 2001 From: artin Date: Thu, 4 Dec 2025 01:09:11 +0800 Subject: [PATCH] ALIDNS: Add documentation --- README.md | 1 + documentation/SUMMARY.md | 1 + documentation/provider/alidns.md | 126 +++++++++++++++++++++++++++++++ documentation/provider/index.md | 2 +- 4 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 documentation/provider/alidns.md diff --git a/README.md b/README.md index 6a8985375..09985d8b9 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ Currently supported DNS providers: - AdGuard Home - Akamai Edge DNS +- Alibaba Cloud DNS (ALIDNS) - AutoDNS - AWS Route 53 - AXFR+DDNS diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index dad8a6a95..2237f6472 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -114,6 +114,7 @@ * [Supported providers](provider/index.md) * [AdGuard Home](provider/adguardhome.md) * [Akamai Edge DNS](provider/akamaiedgedns.md) +* [Alibaba Cloud DNS (ALIDNS)](provider/alidns.md) * [Amazon Route 53](provider/route53.md) * [AutoDNS](provider/autodns.md) * [AXFR+DDNS](provider/axfrddns.md) diff --git a/documentation/provider/alidns.md b/documentation/provider/alidns.md new file mode 100644 index 000000000..c35a66f19 --- /dev/null +++ b/documentation/provider/alidns.md @@ -0,0 +1,126 @@ +## Configuration + +This provider is for [Alibaba Cloud DNS](https://www.alibabacloud.com/product/dns) (also known as ALIDNS). To use this provider, add an entry to `creds.json` with `TYPE` set to `ALIDNS` along with your API credentials. + +Example: + +{% code title="creds.json" %} +```json +{ + "alidns": { + "TYPE": "ALIDNS", + "access_key_id": "YOUR_ACCESS_KEY_ID", + "access_key_secret": "YOUR_ACCESS_KEY_SECRET" + } +} +``` +{% endcode %} + +Optionally, you can specify a `region_id`: + +{% code title="creds.json" %} +```json +{ + "alidns": { + "TYPE": "ALIDNS", + "access_key_id": "YOUR_ACCESS_KEY_ID", + "access_key_secret": "YOUR_ACCESS_KEY_SECRET", + "region_id": "cn-hangzhou" + } +} +``` +{% endcode %} + +Note: The `region_id` defaults to `"cn-hangzhou"`. The region value does not affect DNS management (DNS is global), but Alibaba's SDK requires a region to be provided. + +## Usage + +An example configuration: + +{% code title="dnsconfig.js" %} +```javascript +var REG_NONE = NewRegistrar("none"); +var DSP_ALIDNS = NewDnsProvider("alidns"); + +D("example.com", REG_NONE, DnsProvider(DSP_ALIDNS), + A("test", "1.2.3.4"), + CNAME("www", "example.com."), + MX("@", 10, "mail.example.com."), +); +``` +{% endcode %} + +## Activation + +DNSControl depends on an Alibaba Cloud [RAM user](https://www.alibabacloud.com/help/en/ram/user-guide/overview-of-ram-users) with permissions to manage DNS records. + +### Creating RAM User and Access Keys + +1. Log in to the [RAM console](https://ram.console.aliyun.com/) +2. Create a new RAM user or use an existing one +3. Generate an AccessKey ID and AccessKey Secret for the user +4. Attach the `AliyunDNSFullAccess` policy to the user + +The minimum required permissions are: + +```json +{ + "Version": "1", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "alidns:DescribeDomains", + "alidns:DescribeDomainRecords", + "alidns:DescribeDomainInfo", + "alidns:AddDomainRecord", + "alidns:UpdateDomainRecord", + "alidns:DeleteDomainRecord" + ], + "Resource": "*" + } + ] +} +``` + +## Important Notes + +### TTL Constraints + +Alibaba Cloud DNS has different TTL constraints depending on your DNS edition: + +- **Enterprise Ultimate Edition**: TTL can be as low as 1 second (1-86400) +- **Personal Edition / Free Edition**: Minimum TTL is 600 seconds (600-86400) + +DNSControl will automatically validate TTL values based on your domain's edition. If you attempt to use a TTL below the minimum for your edition, you will receive an error. + +### Chinese Domain Name Support + +ALIDNS supports Chinese domain names (IDN with Chinese characters). However: + +- **Supported**: ASCII characters and Chinese characters (CJK Unified Ideographs) +- **Not supported**: Other Unicode characters (e.g., German umlauts, Arabic script) + +DNSControl will automatically convert between punycode and unicode as needed. + +### Record Type Support + +The following record types are supported: +- A, AAAA, CNAME, MX, TXT, NS +- CAA (requires quoted values: `0 issue "letsencrypt.org"`) +- SRV + +### TXT Record Constraints + +Alibaba Cloud DNS has specific constraints for TXT records: +- Cannot be empty +- Maximum length: 512 bytes +- Cannot contain unescaped double quotes +- Cannot have trailing spaces +- Cannot have unpaired backslashes (odd number of consecutive backslashes) + +DNSControl will audit and reject records that violate these constraints. + +## New Domains + +If a domain does not exist in your Alibaba Cloud account, you must create it manually through the Alibaba Cloud console. DNSControl does not automatically create new domains for this provider. diff --git a/documentation/provider/index.md b/documentation/provider/index.md index 50c15679f..dc262d8ac 100644 --- a/documentation/provider/index.md +++ b/documentation/provider/index.md @@ -391,6 +391,7 @@ Providers in this category and their maintainers are: |Name|Maintainer| |---|---| |[`ADGUARDHOME`](adguardhome.md)|@ishanjain28| +|[`ALIDNS`](alidns.md)|@bytemain| |[`AZURE_PRIVATE_DNS`](azure_private_dns.md)|@matthewmgamble| |[`AKAMAIEDGEDNS`](akamaiedgedns.md)|@edglynes| |[`AXFRDDNS`](axfrddns.md)|@hnrgrgr| @@ -445,7 +446,6 @@ code to support this provider, we'd be glad to help in any way. *(The list below is sorted alphabetically.)* * [1984 Hosting](https://github.com/StackExchange/dnscontrol/issues/1251) (#1251) -* [Alibaba Cloud DNS](https://github.com/StackExchange/dnscontrol/issues/420)(#420) * [BookMyName](https://github.com/StackExchange/dnscontrol/issues/3451) (#3451) * [Constellix (DNSMadeEasy)](https://github.com/StackExchange/dnscontrol/issues/842) (#842) * [CoreDNS](https://github.com/StackExchange/dnscontrol/issues/1284) (#1284)