dyn-gandi/README.md

101 lines
3.0 KiB
Markdown
Raw Normal View History

2023-07-25 22:49:47 +00:00
# Dyn-Gandi
A DNS record updater for [Gandi's LiveDNS](https://api.gandi.net/docs/livedns/) API.
This script is heavily inspired by [dyn-gandi](https://github.com/Danamir/dyn-gandi).
## How it works
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.
2023-07-25 22:49:47 +00:00
## 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.
2023-07-25 22:49:47 +00:00
## How to use
First, get your API key from https://account.gandi.net/en/users/USER/security where `USER` is your Gandi username.
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.
2023-07-25 22:49:47 +00:00
```json
{
"api": {
"<Your-API-Key>": {
"example.com": [ "@", "www", "sub1" ],
"example.org": [ "@", "www", "sub1", "sub2" ]
},
"/path/to/a/file/containing/api_key": {
"example.at": [ "sub1" ],
2023-08-15 19:45:59 +00:00
"example.au": [ "sub1", "sub2" ]
2023-07-25 22:49:47 +00:00
}
},
"resolvers": [
2023-08-01 19:12:03 +00:00
"https://ifconfig.me/ip",
2023-07-25 22:49:47 +00:00
"https://me.gandi.net"
],
"ttl": 3600,
2023-07-25 22:49:47 +00:00
"log_path": "./log.txt"
}
```
## Nix
Add this to the modules.
```nix
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
2023-08-13 14:05:59 +00:00
dyn-gandi.url = "git+https://git.krsnik.at/Kristian/dyn-gandi";
};
outputs = {
self,
nixpkgs,
dyn-gandi
}: {
...
modules = [
dyn-gandi.nixosModules.default
{
dyn-gandi.enable = true;
2023-08-13 14:41:43 +00:00
dyn-gandi.timer = 300;
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";
};
}
...
];
...
}
```
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.
2023-07-25 22:49:47 +00:00
## Features
* Support for arbitrarily many domains and subdomains through a nested data structure.
* Small codebase
2023-07-25 22:49:47 +00:00
* Logging
* NixOS and home-manager modules
2023-07-25 22:49:47 +00:00
## Limitations
* Only IPv4 addresses are supported
2023-07-25 22:49:47 +00:00
## TODO
* Testing
* Command line options controlling: dry-run, config, log, verbosity, force
* Support IPv6
2023-07-25 22:49:47 +00:00
* Per subdomain TTL
* Better documentation
* Better logging