87 lines
2.5 KiB
Markdown
87 lines
2.5 KiB
Markdown
|
||
A Dynamic-DNS (DDNS) service continuously keeps one or more DNS records in sync with the current public IP address of your machine.
|
||
In *clan* this service is backed by [qdm12/ddns-updater](https://github.com/qdm12/ddns-updater).
|
||
|
||
> Info
|
||
> ddns-updater itself is **heavily opinionated and version-specific**. Whenever you need the exhaustive list of flags or
|
||
> provider-specific fields refer to its *versioned* documentation – **not** the GitHub README
|
||
---
|
||
|
||
# 1. Configuration model
|
||
|
||
Internally ddns-updater consumes a single file named `config.json`.
|
||
A minimal configuration for the registrar *Namecheap* looks like:
|
||
|
||
```json
|
||
{
|
||
"settings": [
|
||
{
|
||
"provider": "namecheap",
|
||
"domain": "sub.example.com",
|
||
"password": "e5322165c1d74692bfa6d807100c0310"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Another example for *Porkbun*:
|
||
|
||
```json
|
||
{
|
||
"settings": [
|
||
{
|
||
"provider": "porkbun",
|
||
"domain": "domain.com",
|
||
"api_key": "sk1_…",
|
||
"secret_api_key": "pk1_…",
|
||
"ip_version": "ipv4",
|
||
"ipv6_suffix": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
When you write a `clan.nix` the **common** fields (`provider`, `domain`, `period`, …) are already exposed as typed
|
||
*Nix options*.
|
||
Registrar-specific or very new keys can be passed through an open attribute set called **extraSettings**.
|
||
|
||
---
|
||
|
||
# 2. Full Porkbun example
|
||
|
||
Manage three records – `@`, `home` and `test` – of the domain
|
||
`jon.blog` and refresh them every 15 minutes:
|
||
|
||
```nix title="clan.nix" hl_lines="10-11"
|
||
inventory.instances = {
|
||
dyndns = {
|
||
roles.default.machines."jon" = { };
|
||
roles.default.settings = {
|
||
period = 15; # minutes
|
||
settings = {
|
||
"all-jon-blog" = {
|
||
provider = "porkbun";
|
||
domain = "jon.blog";
|
||
|
||
# (1) tell the secret-manager which key we are going to store
|
||
secret_field_name = "secret_api_key";
|
||
|
||
# everything below is copied verbatim into config.json
|
||
extraSettings = {
|
||
host = "@,home,test"; # (2) comma-separated list of sub-domains
|
||
ip_version = "ipv4";
|
||
ipv6_suffix = "";
|
||
api_key = "pk1_4bb2b231275a02fdc23b7e6f3552s01S213S"; # (3) public – safe to commit
|
||
};
|
||
};
|
||
};
|
||
};
|
||
};
|
||
};
|
||
```
|
||
|
||
1. `secret_field_name` tells the *vars-generator* to store the entered secret under the specified JSON field name in the configuration.
|
||
2. ddns-updater allows multiple hosts by separating them with a comma.
|
||
3. The `api_key` above is *public*; the corresponding **private key** is retrieved through `secret_field_name`.
|
||
|