initial commit

2025-03-23 21:08:31 +01:00
commit 7517ee5534
17 changed files with 800 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,98 @@
+# Cloudns - A Cloudflare Dynamic DNS Solution
+
+A DNS record updater for [Cloudflare's DNS](https://developers.cloudflare.com/api/resources/dns/) API.
+
+## 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 Cloudflare 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.
+
+## Notes
+
+Every invocation of the script causes at least 1 request to a resolver specified and 1 API call to Cloudflare 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.
+
+## Usage
+
+First, get your User API Token from https://dash.cloudflare.com/profile/api-tokens.
+The token need the following permissions:
+
+* **Edit DNS**
+
+```json
+{
+  "api": {
+    "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" ]
+    }
+  },
+  "resolvers": [
+    "https://ifconfig.me/ip",
+    "https://me.gandi.net"
+  ],
+  "log-path": "./log.jsonl"
+}
+```
+
+## Nix
+
+Add this to the modules.
+
+```nix
+inputs = {
+  cloudns.url = "git+https://git.krsnik.at/Kristian/cloudns";
+};
+
+outputs = {
+  self,
+  nixpkgs,
+  cloudns
+}: {
+  ...
+  modules = [
+    cloudns.nixosModules.default
+    {
+      cloudns.enable = true;
+      cloudns.timer = 300;
+      cloudns.settings = {
+        api = {
+          "/path/to/a/file/containing/api_key" = {
+            "example.com" = ["@" "www"];
+          };
+        };
+        resolvers = [
+          "https://ifconfig.me/ip"
+          "https://me.gandi.net"
+        ];
+        log_path = "/path/to/log/file.jsonl";
+      };
+    }
+    ...
+  ];
+  ...
+}
+```
+
+Use `cloudns.nixosModules.default` for a NixOs module.
+
+`cloudns.timer` specifies a timer in seconds when the script should be repeated.
+
+## Features
+
+* Support for arbitrarily many domains and subdomains through a nested data structure.
+* Small codebase
+* Logging
+* NixOS and home-manager modules
+
+## Limitations
+
+* Only IPv4 addresses are supported