updated README to reflect current state of the project

This commit is contained in:
Kristian Krsnik 2023-08-13 15:06:57 +02:00
parent f7d5a7d59f
commit be54a045f3

View File

@ -3,58 +3,99 @@ A DNS record updater for [Gandi's LiveDNS](https://api.gandi.net/docs/livedns/)
This script is heavily inspired by [dyn-gandi](https://github.com/Danamir/dyn-gandi).
## How it works
This script determines the your server's current IP by querying the resolvers defined in the config file.
After that it reads the current state of the domains and subdomains you specified of Gandi.
Should the IP address of a subdomain not match your current IP it will be updated.
The subdomain will be created should it not already exist.
This script determines the the current IP address by querying the resolvers defined in the config file.
It then queries the subdomains' A records off of Gandi and compares their IP addresses to the current IP address.
Should the IP address of a subdomain's A record not match your current IP address it will be updated. The subdomain's A record will be created should it not already exist.
## Note
The current implementation only allows for one entry per subdomain.
Meaning that should you have a TXT and a CNAME record for a subdomain that is in the config file, then both these entries will be deleted and replaced by a single A name record.
## Notes
Every invocation of the script causes at least 1 request to a resolver specified and 1 API call to Gandi per domain.
Updating a subdomain's A record is 1 API request per subdomain, even if they share the same domain.
Resolvers are queried in the order specified until one returns a valid IP address.
It is also possible to define a path to a file with the API key written in it. This is good for environments where the config file has to be shared like in a nix project.
## How to use
First, get your API key from https://account.gandi.net/en/users/USER/security where `USER` is your Gandi username.
On first run the program will create a minimal, yet complete `config.json` in the same directory it is being run in.
Next, enter the API key into the configuration file and assign domains to it.
The domains are keys to a list of subdomain for a given domain you wish to monitor.
The below example is complete and should explain itself.
Resolvers are queried one after another until one returns a valid IP.
`config.json`
The script looks for a config file at `$HOME/.config/dyn-gandi/config.log` or `/etc/dyn-gandi.conf` in that order. So create a file at one of these locations according to the schema below.
```json
{
"api": {
"<Your-API-Key>": {
"example.com": [ "@", "www", "sub1" ],
"example.org": [ "@", "www", "sub1", "sub2" ]
},
"/path/to/a/file/containing/api_key": {
"example.at": [ "sub1" ],
"example.au": [ "sub1" "sub2" ]
}
},
"ttl": 3600,
"resolvers": [
"https://ifconfig.me/ip",
"https://me.gandi.net"
],
"ttl": 3600,
"log_path": "./log.txt"
}
```
## Nix
Add this to the modules.
```nix
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
dyn-gandi.url = "/home/kristian/dyn-gandi";
};
outputs = {
self,
nixpkgs,
dyn-gandi
}: {
...
modules = [
dyn-gandi.nixosModules.default
{
dyn-gandi.enable = true;
dyn-gandi.settings = {
api = {
"/path/to/a/file/containing/api_key" = {
"example.com" = ["@" "www"];
};
};
resolvers = [
"https://ifconfig.me/ip"
"https://me.gandi.net"
];
ttl = 3600;
log_path = "/path/to/log/file";
};
dyn-gandi.timer = 300;
}
...
];
...
}
```
Use `dyn-gandi.nixosModules.default` for a NixOs module and `dyn-gandi.homeManagerModules.default` for home-manager
`dyn-gandi.timer` specifies a timer in seconds when the script should be repeated.
## Features
* Support for arbitrarily many domains and records through a nested data structure.
* Small codebase.
* Support for arbitrarily many domains and subdomains through a nested data structure.
* Small codebase
* Logging
* NixOS and home-manager modules
## Limitations
* Right now only IPv4 addresses are supported
* Every record is only allowed one A record.
* Extra records (TXT, CNAME and such) will get deleted on update.
* Only IPv4 addresses are supported
## TODO
* Testing
* Command line options controlling: dry-run, config, log, verbosity, force
* Per subdomain TTL
* Nix Flake support with exported config and service options
* Better documentation
* Better logging
* Support IPv6
* Remember other record types (TXT, etc.)
* Detect TTL change and update even when the IP is the same
* Per subdomain TTL
* Better documentation
* Better logging