initial commit

Author: miguelangel-nubla

.github/workflows/release.yaml

@@ -0,0 +1,35 @@
+name: goreleaser
+
+on:
+  pull_request:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      -
+        name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: 'stable'
+          check-latest: true
+      -
+        name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v4
+        with:
+          distribution: goreleaser
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,2 @@
+./ipv6ddns
+dist/

.goreleaser.yaml

@@ -0,0 +1,71 @@
+before:
+  hooks:
+    - go mod tidy
+    - go generate ./...
+builds:
+  - env:
+      - CGO_ENABLED=0
+    goos:
+      # - aix
+      # - android
+      - darwin
+      # - dragonfly
+      - freebsd
+      # - illumos
+      # - ios
+      - js
+      - linux
+      - netbsd
+      - openbsd
+      # - plan9
+      - solaris
+      # - windows # weird behaviour NDP packages not received
+    goarch:
+      - ppc64
+      - 386
+      - amd64
+      - arm
+      - arm64
+      - wasm
+      - loong64
+      - mips
+      - mipsle
+      - mips64
+      - mips64le
+      - ppc64le
+      - riscv64
+      - s390x
+    goarm:
+      - 6
+      - 7
+
+archives:
+  - files:
+      - LICENSE*
+      - README*
+      - CHANGELOG*
+      - config.json
+    format: tar.gz
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    format_overrides:
+    - goos: windows
+      format: zip
+checksum:
+  name_template: 'checksums.txt'
+snapshot:
+  name_template: "{{ incpatch .Version }}-next"
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - '^docs:'
+      - '^test:'
+
+# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
+# vim: set ts=2 sw=2 tw=0 fo=cnqoj

README.md

@@ -0,0 +1,122 @@
+# IPv6 DDNS Updater
+
+This utility discovers the IPv6 addresses of specific hosts in your network and updates DNS records dynamically. [Details](#what-does-this-do)
+
+## Installation
+
+Download the [latest release](https://github.com/miguelangel-nubla/ipv6ddns/releases/latest) for your architecture.
+
+### Or build from source
+
+Ensure you have Go installed on your system. If not, follow the instructions on the official [Go website](https://golang.org/doc/install) to install it. Then:
+```
+go install github.com/miguelangel-nubla/ipv6ddns
+```
+
+## Usage
+
+Adjust the configuration on config.json and run the binary with the desired flags:
+```
+./ipv6ddns [flags]
+```
+
+### Flags
+
+- `-config_file` (default "config.json"): Config file to use
+- `-log_level` (default "info"): Set the logging level (debug, info, warn, error, fatal, panic)
+- `-storm_delay` (default "60s"): Time to allow finishing storm of host discoveries before updating the DDNS record
+- `-ttl` (default "4h"): Time to keep a discovered host entry in the table after it has been last seen. This is not the TTL of the DDNS record
+- `-live` (default false): Show the current state live on the terminal
+
+This utility needs to be executed as a superuser to be able to listen on the required ports.
+
+Depending on your IPv6 network configuration, you will need to allow outside access to the hosts you want to expose.
+On Mikrotik devices it is particularly easy, you just need to add an address list with your domain, the IPv6 addresses to which it points to will be automatically resolved, and then you can simply create a new forwarding rule on the firewall that allows forwarding to hosts in that destination address list.
+The alternative on more limited systems is to either specify subnets or simply allow by destination MAC address.
+
+## Configuration
+
+This is the structure of the `config.json` file:
+
+```
+{ 
+  "tasks": {
+    "load_balancer_for_web_app": { // whichever name you like for this task
+      "subnets": ["2000::/3"], // only IPv6 addresses on these subnets will be updated. "2000::/3" is any GUA.
+      "mac_address": ["00:11:22:33:44:55", "00:11:22:33:44:56"], // MAC addresses of the hosts to look for
+      "endpoints": {
+        "example-project": [ // name of the endpoint to use for this task, as configured on the credentials section at the bottom
+          "test-webapp.example.com" // domain name whose AAAA records will be kept in sync
+        ]
+      }
+    }
+    // ...
+    // more task configurations if needed
+    // ...
+  },
+  "credentials": {
+    "example-project": { // name you will use to refer to this endpoint on the tasks
+      "provider": "cloudflare", // one of the supported providers
+      "settings": { // provider specific configuration
+        "email": "email@example.com",
+        "api_token": "CLOUDFLARETOKEN",
+        "zone_name": "example.com",
+        "ttl": "1h", // if proxied over cloudflare this will have no effect
+        "proxied": true
+      }
+    }
+    // ...
+    // more credentials if needed
+    // ...
+  }
+}
+```
+
+## DDNS providers
+
+The available DDNS providers are:
+
+- Cloudflare
+- Duckdns (provider only allows a single AAAA record)
+
+- :rocket: **Adding your preferred provider is easy**:
+  - Take a provider from `ddns/` such as cloudflare.go as a template.
+  - Replace every reference to cloudflare with the new provider. This is case-sensitive.
+  - Replace the API calls with the ones your provider need.
+  - Test.
+  - Create a PR!
+
+---
+
+# What does this do?
+
+## The problem
+Having a domain name `my-web.example.com` point to your application on an IPv6 network is both simpler and more challenging than doing it with regular IPv4.
+
+The classic method of directing traffic to your public IP address (i.e., your router) and then using NAT is no longer a good idea, nor necessary.
+
+IPv6 addresses are globally routable, which is nice, but you will need to know the exact IP, as different machines or even containers on the same host (and even different applications) will have different "public" IPs, or GUAs in IPv6 terminology.
+
+In this scenario DNS names become almost mandatory, good luck trying to remember and type a different `https://[2001:0db8:85a3:0000:8a2e:0370:7334:abcd]` to access each one of your hosts.
+
+Technically, IPv6 addresses could be static, but part of the beauty of IPv6 is the ability to use and rotate multiple different IP addresses on demand. Even if you don't want to, some ISPs change your IPv6 prefix on router reboot or periodically.
+
+## Rationale
+You might be thinking well, I will just run a DDNS updater on my server? It turns out that may not be really an option, remember each application has its own, *dynamic* IPv6? How do you indicate which IP should the DNS record point to? Does that mean the way to do that is to run the updater on the same container as your web server?
+
+Unfortunately yes. That is not a great idea. Aside from the inconvenience of forking and using your own container images, there will be systems that you will not be able to modify. Think about a device on your network that has no way of running a custom executable, like an appliance, or an IP camera.
+
+Wouldn't it be nice to have a utility anywhere on your network that detects the IPv6 of your desired hosts, identifies when they change, and updates the relevant DNS records accordingly?
+
+## The solution
+This utility scans the network for the IPv6s of the hosts you want to expose, identified by their MAC address, and updates the corresponding DNS records automatically. This works for _all your network_, having the configuration and your credentials in a single place.
+
+---
+
+# Other nice usages
+
+### Roaming over multiple IPv6 networks
+This utility allows you to move between IPv6 networks and to maintain inbound connectivity.
+You can have as many IPv6 addresses from different ISPs as you like and the AAAA records for your domain will be kept in sync.
+
+For example, you can have a fiber connection, a backup LTE connection, and Starlink on your roof. Your domain will have AAAA records for every WAN connection, inbound WAN failover will simply work.

cmd/ipv6ddns/ipv6ddns.go

@@ -0,0 +1,127 @@
+package ipv6ddns
+
+import (
+	"flag"
+	"log"
+	"net/netip"
+	"strings"
+	"time"
+
+	"github.com/miguelangel-nubla/ipv6ddns/config"
+	"github.com/miguelangel-nubla/ipv6ddns/pkg/tree"
+
+	"github.com/miguelangel-nubla/ipv6disc/pkg/terminal"
+	"github.com/miguelangel-nubla/ipv6disc/pkg/worker"
+
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+)
+
+var configFile string
+var logLevel string
+var stormDelay time.Duration
+var ttl time.Duration
+var live bool
+
+func init() {
+	flag.StringVar(&configFile, "config_file", "config.json", "Path to the configuration file, default: config.json")
+	flag.StringVar(&logLevel, "log_level", "info", "Logging level (debug, info, warn, error, fatal, panic) default: info")
+	flag.DurationVar(&stormDelay, "storm_delay", 60*time.Second, "Time to allow for host discovery before updating the DDNS record")
+	flag.DurationVar(&ttl, "ttl", 4*time.Hour, "Time to keep a discovered host entry in the table after it has been last seen. This is not the TTL of the DDNS record. Default: 4h")
+	flag.BoolVar(&live, "live", false, "Show the currrent state live on the terminal, default: false")
+}
+
+func Start() {
+	flag.Parse()
+
+	startUpdater()
+}
+
+func startUpdater() {
+	config := config.NewConfig(configFile)
+
+	sugar := initializeLogger()
+
+	liveOutput := make(chan string)
+
+	table := worker.NewTable()
+	worker.NewWorker(table, ttl, sugar).Start()
+
+	t := tree.NewTree()
+
+	onUpdate := func(endpoint *tree.Endpoint, domainName string) error {
+		sugar.Infof("endpoint %s starting update of: %s", endpoint.ID, domainName)
+
+		endpoint.DomainsMutex.RLock()
+		domain := endpoint.Domains[domainName]
+		domain.HostsMutex.RLock()
+		hostList := make([]string, 0, len(domain.Hosts))
+		for _, host := range domain.Hosts {
+			// Remove zone identifier from netip.Addr, zones strip prefixes
+			hostList = append(hostList, netip.AddrFrom16(host.Address.As16()).String())
+		}
+		domain.HostsMutex.RUnlock()
+		endpoint.DomainsMutex.RUnlock()
+
+		err := endpoint.Service.Update(domainName, hostList)
+
+		if err != nil {
+			sugar.Errorf("endpoint %s error updating %s: %s", endpoint.ID, domainName, err)
+		}
+
+		return err
+	}
+
+	go func() {
+		for {
+			t.Update(config, table, stormDelay, onUpdate)
+
+			if live {
+				var result strings.Builder
+				result.WriteString(t.PrettyPrint(4))
+				result.WriteString(table.PrettyPrint(4))
+				result.WriteString(config.PrettyPrint(4))
+				liveOutput <- result.String()
+			}
+
+			time.Sleep(1 * time.Second)
+		}
+	}()
+
+	if live {
+		terminal.LiveOutput(liveOutput)
+	} else {
+		select {}
+	}
+}
+
+func initializeLogger() *zap.SugaredLogger {
+	zapLevel, err := getLogLevel(logLevel)
+	if err != nil {
+		log.Fatalf("invalid log level: %s", logLevel)
+	}
+
+	if live {
+		zapLevel = zapcore.FatalLevel
+	}
+
+	cfg := zap.NewProductionConfig()
+	cfg.Level = zap.NewAtomicLevelAt(zapLevel)
+	cfg.OutputPaths = []string{"stdout"}
+	cfg.ErrorOutputPaths = []string{"stderr"}
+	cfg.EncoderConfig.EncodeTime = zapcore.RFC3339TimeEncoder
+
+	logger := zap.Must(cfg.Build())
+	defer logger.Sync()
+
+	return logger.Sugar()
+}
+
+func getLogLevel(level string) (zapcore.Level, error) {
+	var zapLevel zapcore.Level
+	err := zapLevel.UnmarshalText([]byte(level))
+	if err != nil {
+		return zap.InfoLevel, err
+	}
+	return zapLevel, nil
+}