updated README to reflect current state of the project
This commit is contained in:
parent
f7d5a7d59f
commit
be54a045f3
91
README.md
91
README.md
|
|
@ -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
|
||||
Loading…
Reference in New Issue