mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
## Configuration
|
|
|
|
To use this provider, add an entry to `creds.json` with `TYPE` set to `HETZNER`
|
|
along with a [Hetzner API Key](https://dns.hetzner.com/settings/api-token).
|
|
|
|
Example:
|
|
|
|
{% code title="creds.json" %}
|
|
```json
|
|
{
|
|
"hetzner": {
|
|
"TYPE": "HETZNER",
|
|
"api_key": "your-api-key"
|
|
}
|
|
}
|
|
```
|
|
{% endcode %}
|
|
|
|
## Metadata
|
|
|
|
This provider does not recognize any special metadata fields unique to Hetzner
|
|
DNS Console.
|
|
|
|
## Usage
|
|
|
|
An example `dnsconfig.js` configuration:
|
|
|
|
```javascript
|
|
var REG_NONE = NewRegistrar("none");
|
|
var DSP_HETZNER = NewDnsProvider("hetzner");
|
|
|
|
D("example.tld", REG_NONE, DnsProvider(DSP_HETZNER),
|
|
A("test", "1.2.3.4")
|
|
);
|
|
```
|
|
|
|
## Activation
|
|
|
|
Create a new API Key in the
|
|
[Hetzner DNS Console](https://dns.hetzner.com/settings/api-token).
|
|
|
|
## Caveats
|
|
|
|
### CAA
|
|
|
|
As of June 2022, the Hetzner DNS Console API does not accept spaces in CAA
|
|
records.
|
|
```text
|
|
0 issue "letsencrypt.org; validationmethods=dns-01; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234"
|
|
```
|
|
|
|
Removing the spaces might still work for any consumer of the record.
|
|
```text
|
|
0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234"
|
|
```
|
|
|
|
### SOA
|
|
|
|
Hetzner DNS Console does not allow changing the SOA record via their API.
|
|
There is an alternative method using an import of a full BIND file, but this
|
|
approach does not play nice with incremental changes or ignored records.
|
|
At this time you cannot update SOA records via DNSControl.
|
|
|
|
### Rate Limiting
|
|
|
|
Hetzner is rate limiting requests in multiple tiers: per Hour, per Minute and
|
|
per Second.
|
|
|
|
Depending on how many requests you are planning to perform, you can adjust the
|
|
delay between requests in order to stay within your quota.
|
|
|
|
The setting `optimize_for_rate_limit_quota` controls this behavior and accepts
|
|
a case-insensitive value of
|
|
- `Hour`
|
|
- `Minute`
|
|
- `Second`
|
|
|
|
The default for `optimize_for_rate_limit_quota` is `Second`.
|
|
|
|
Example: Your per minute quota is 60 requests and in your settings you
|
|
specified `Minute`. DNSControl will perform at most one request per second.
|
|
DNSControl will emit a warning in case it breaches the next quota.
|
|
|
|
In your `creds.json` for all `HETZNER` provider entries:
|
|
|
|
{% code title="creds.json" %}
|
|
```json
|
|
{
|
|
"hetzner": {
|
|
"TYPE": "HETZNER",
|
|
"api_key": "your-api-key",
|
|
"optimize_for_rate_limit_quota": "Minute"
|
|
}
|
|
}
|
|
```
|
|
{% endcode %}
|
|
|
|
Every response from the Hetzner DNS Console API includes your limits:
|
|
|
|
```shell
|
|
curl --silent --include \
|
|
--header 'Auth-API-Token: ...' \
|
|
https://dns.hetzner.com/api/v1/zones \
|
|
| grep x-ratelimit-limit
|
|
x-ratelimit-limit-second: 3
|
|
x-ratelimit-limit-minute: 42
|
|
x-ratelimit-limit-hour: 1337
|
|
```
|
|
|
|
Every DNSControl invocation starts from scratch in regard to rate-limiting.
|
|
In case you are frequently invoking DNSControl, you will likely hit a limit for
|
|
any first request.
|
|
You can either use an out-of-bound delay (e.g. `$ sleep 1`), or specify
|
|
`start_with_default_rate_limit` in the settings of the provider.
|
|
With `start_with_default_rate_limit` DNSControl uses a quota equivalent to
|
|
`x-ratelimit-limit-second: 1` until it could parse the actual quota from an
|
|
API response.
|
|
|
|
In your `creds.json` for all `HETZNER` provider entries:
|
|
|
|
{% code title="creds.json" %}
|
|
```json
|
|
{
|
|
"hetzner": {
|
|
"TYPE": "HETZNER",
|
|
"api_key": "your-api-key",
|
|
"start_with_default_rate_limit": "true"
|
|
}
|
|
}
|
|
```
|
|
{% endcode %}
|