{"id":15968838,"url":"https://github.com/taskmedia/ddns-allowlist","last_synced_at":"2025-06-27T10:35:07.826Z","repository":{"id":257806364,"uuid":"863091983","full_name":"taskmedia/ddns-allowlist","owner":"taskmedia","description":"A Traefik plugin / middleware to allowlist dynamic DNS addresses","archived":false,"fork":false,"pushed_at":"2025-03-23T13:46:08.000Z","size":255,"stargazers_count":5,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-02T11:07:53.334Z","etag":null,"topics":["docker","go","golang","hacktoberfest","kubernetes","middleware","traefik","traefik-plugin"],"latest_commit_sha":null,"homepage":"https://plugins.traefik.io/plugins/66fef7d4573cd7803d65cb12/ddns-allowlist","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taskmedia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-25T17:42:43.000Z","updated_at":"2025-05-23T20:48:48.000Z","dependencies_parsed_at":"2024-11-28T15:33:23.415Z","dependency_job_id":"65215e9a-aedf-455d-a598-396fdfa6e19f","html_url":"https://github.com/taskmedia/ddns-allowlist","commit_stats":null,"previous_names":["taskmedia/ddns-whitelist","taskmedia/ddns-allowlist","taskmedia/ddnswhitelist"],"tags_count":15,"template":false,"template_full_name":"traefik/plugindemo","purl":"pkg:github/taskmedia/ddns-allowlist","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taskmedia%2Fddns-allowlist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taskmedia%2Fddns-allowlist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taskmedia%2Fddns-allowlist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taskmedia%2Fddns-allowlist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taskmedia","download_url":"https://codeload.github.com/taskmedia/ddns-allowlist/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taskmedia%2Fddns-allowlist/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262240072,"owners_count":23280450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","go","golang","hacktoberfest","kubernetes","middleware","traefik","traefik-plugin"],"created_at":"2024-10-07T19:04:15.888Z","updated_at":"2025-06-27T10:35:07.795Z","avatar_url":"https://github.com/taskmedia.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DDNS allowlist - Traefik plugin\n\nDynamic DNS allowlist plugin for [Traefik](https://doc.traefik.io/traefik): Add your dynamic hostname (your homenetwork router) to the allow list.\n\nHave a look at the official [Traefik Plugin Catalog](https://plugins.traefik.io/plugins/66fef7d4573cd7803d65cb12/ddns-allowlist).\nWe would love if you leave a star on this repository.\n\n## About\n\nThe `ddns-allowlist` plugin for Traefik allows you to add dynamic DNS (DDNS) hosts to the allowed requesters.\nRequests from IP addresses that do not resolve to the specified DDNS hosts will be denied.\nYou might also know this as [whitelist](https://inclusivenaming.org/word-lists/tier-1/whitelist/) instead of allowlist.\n\nThe initial idea is that you can add your home router with a floating (non-static) IP address to an allowed list of addresses.\nYou are not limited to your DDNS supporting router - you can add any host you like.\nIf you want so it is more likely a hostname allowlist.\n\nThe basic concept is to periodically resolve the hostname to an IP address and add it to the allowlist.\nBecause server typically have a static IP, you should add its static IPs to the allowlist (`sourceRangeIps`).\n\n:warning: IPv6 is supported but e.g. with FritzBox router you maybe have some issues because the IPv6 address your router provides is not the same as the network prefix of your network.\n\n## Installation\n\nThe installation of a [Traefik plugin](https://doc.traefik.io/traefik/plugins/) is pretty simple.\nTo install the `ddns-allowlist` plugin follow one of the following methods.\n\n### Traefik CLI\n\nFirst way to add the plugin is to add the following CLI options to your Traefik setup:\n\n```bash\n--experimental.plugins.ddns-allowlist.modulename=github.com/taskmedia/ddns-allowlist\n--experimental.plugins.ddns-allowlist.version=v1.6.1\n```\n\n### yaml / Traefik Helm chart\n\nAnother way to add the plugin is to add the following configuration to your Traefik static configuration / Helm chart:\n\n```yaml\nexperimental:\n  plugins:\n    ddns-allowlist:\n      moduleName: \"github.com/taskmedia/ddns-allowlist\"\n      version: v1.6.1\n```\n\n## Configuration\n\nYou also need to create a middleware and add it to one of your routes.\nThere are multiple ways to do this - this document will show you how to configure the plugin with [dynamic configuration](#dynamic-configuration) and [Kubernetes CRD](#kubernetes-crd).\n\nBut first we will have a look about the configuration options available for the plugin.\n\n### Available options\n\nOnly mandatory option is `sourceRangeHosts` - all other options are optional.\n\n- **`sourceRangeHosts`** (required)\u003cbr /\u003e\n  Hosts to dynamically add to allowlist via DNS lookup\n- **`sourceRangeIps`**\u003cbr /\u003e\n  Additional IP addresses to add to allowlist\n- **`ipStrategy.*`**\u003cbr /\u003e\n  Strategy to determine the client IP address - see configurations below.\n  If no strategy is specified (or value is zero), the plugin will use the `RemoteAddr` as default.\n- **`ipStrategy.cloudflareDepth`**\u003cbr /\u003e\n  Use Cloudflare headers (`Cf-Connecting-Ip`) to determine the client IP address.\n  The cloudflareDepth option expects an integer to determ which IP address should be used (starting from the right).\n- **`ipStrategy.depth`**\u003cbr /\u003e\n  Use headers (`X-Forwarded-For`) to determine the client IP address.\n  The depth option expects an integer to determ which IP address should be used (starting from the right).\n- **`ipStrategy.excludedIPs`**\u003cbr /\u003e\n  Will return the first IP address that is not in the excluded list (also uses `X-Forwarded-For` header).\n- **`rejectStatusCode`**\u003cbr /\u003e\n  Status code to return if the request is rejected (default: 403)\n- **`logLevel`**\u003cbr /\u003e\n  Log level for the plugin (allowed: ERROR, INFO, DEBUG, TRACE - default: ERROR)\n- **`lookupInterval`**\u003cbr /\u003e\n  Lookup interval for DNS hosts in seconds (default: 5 min)\n- **`allowedIPv6NetworkPrefix`**\u003cbr /\u003e\n  Allow any interface identifier based on given prefix from the looked up sourceRangeHosts IPv6 addresses (default: disabled)\n\n_Hint: You can only choose one of the ip strategy options. It is not possible to combine multiple.\nThe strategies are similar to the one provided with middleware [IPWhiteList](https://doc.traefik.io/traefik/middlewares/http/ipwhitelist/#ipstrategydepth)._\n\n### Configuration examples\n\n#### Dynamic configuration\n\nAdd the `ddns-allowlist` middleware to your Traefik dynamic configuration:\n\n\u003cdetails open\u003e\n\u003csummary\u003edynamic configuration\u003c/summary\u003e\n\n```yaml\n# Dynamic configuration\nhttp:\n  routers:\n    my-router:\n      rule: host(`demo.localhost`)\n      service: service-foo\n      entryPoints:\n        - web\n      middlewares:\n        - ddns-allowlist-router\n\n  services:\n    service-foo:\n      loadBalancer:\n        servers:\n          - url: http://127.0.0.1:5000\n\n  middlewares:\n    ddns-allowlist-router:\n      plugin:\n        my-ddnswl:\n          # optional: log level for the plugin (allowed: ERROR, INFO, DEBUG, TRACE - default: ERROR)\n          logLevel: ERROR\n          # hosts to dynamically add to allowlist via DNS lookup\n          sourceRangeHosts:\n            - my.router.ddns.tld\n          # optional: IP addresses to allowlist\n          sourceRangeIps:\n            - 1.2.3.4\n          # optional: IP strategy to determine the client IP address (default: RemoteAddr)\n          # also see: https://doc.traefik.io/traefik/middlewares/http/ipwhitelist/#ipstrategy\n          ipStrategy:\n            depth: 1\n            cloudflareDepth: 1\n            excludedIPs:\n              - 4.3.2.1\n          # optional: allow IPv6 interface identifier based on given prefix\n          # this will skip the interface identifier validation (default: disabled)\n          allowedIPv6NetworkPrefix: 64\n          # optional: lookup interval for DNS hosts in seconds (default: 5 min)\n          lookupInterval: 60\n```\n\n\u003c/details\u003e\n\n#### Kubernetes CRD\n\n\u003cdetails open\u003e\n\u003csummary\u003eKubernetes CRD configuration\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: my-ddnswl\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      # see other options in dynamic configuration or in section 'Available options'\n```\n\nAlso see more detailed in the [examples section](#examples).\n\n\u003c/details\u003e\n\n## Examples\n\nThis section contains example configurations for the `ddns-allowlist` plugin.\nThe examples are provided as in Kubernetes CRD but also can be defined in other formats.\nYou need to expand the configuration example in each section on the triangle.\n\nIt shows different common configuration options.\nKeep note that the IP strategies can not be combined with each other.\n\nThe following examples are alphabetically sorted and not according to the frequency of use.\n\n### Allowed IPv6 network prefix\n\nWhen using IPv6 your home router will report its full address to the DDNS provider.\nThis address contains the network prefix and the interface identifier.\nWhen an device inside your network tries to access your service it will be rejected because the interface identifier is not the same as the one from your router.\nWith this option you can allow any interface identifier based on the given prefix from the looked up sourceRangeHosts IPv6 addresses.\n\nThe common value used for that is `64`.\nThis is the common value which splits the address into network prefix and interface identifier.\nIf your routers DNS lookup resolves in IP address `aaaa:bbbb:cccc:dddd:1111:2222:3333:4444`, the addresses in network `aaaa:bbbb:cccc:dddd::/64` will be allowed.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Allowed IPv6 network prefix\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      allowedIPv6NetworkPrefix: 64\n```\n\n\u003c/details\u003e\n\n### Cloudflare - DNS only\n\nIf you are using [Cloudflare](https://cloudflare.com) as DNS nameserver ([without proxy](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/)), you need to use the default configuration using `RemoteAddr` (no IP strategy required in plugin config).\n\nAlso see [RemoteAddr](#remoteaddr) example.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Cloudflare - DNS only\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-cloudflare-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n```\n\n\u003c/details\u003e\n\n### Cloudflare - proxy\n\nIf you are using [Cloudflare](https://cloudflare.com) as DNS nameserver ([with proxy](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/)), you need to get the IP address of the client from the `Cf-Connecting-Ip` header.\nTherefore use the `cloudflareDepth` configuration option.\n\nUsually the header only contains one IP address - so you can use `1` as value.\nTo ensure the same implementation as in `ipStrategy.depth` you are allowed to specify a higher value.\nBut this configuration should not be necessary.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Cloudflare - proxy\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-cloudflare-proxy\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      ipStrategy:\n        cloudflareDepth: 1\n```\n\n\u003c/details\u003e\n\n### Excluded IPs\n\nIf you want to get the client IP address from the `X-Forwarded-For` header but exclude some IPs from the list (eg. your reverse proxies), you can use the `excludedIPs` option.\nThis will allow you to exclude some IPs from the list and return the first IP address that is not in the excluded list.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Excluded IPs\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-excludeips\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      ipStrategy:\n        excludedIPs:\n          - 1.2.3.4\n```\n\n\u003c/details\u003e\n\n### Log level\n\nIf you want to see more logs from the plugin, you can set the log level to a more detailed level.\nThe allowed values are `ERROR` (default), `INFO`, `DEBUG`, `TRACE`.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Log level\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      logLevel: DEBUG\n```\n\n\u003c/details\u003e\n\n### Lookup interval\n\nIf you want to change the lookup interval for DNS hosts, you can set the `lookupInterval` option.\nThe default value is `300` seconds (5 minutes).\n\nThe lookup will only happen if the middleware is triggered from a new client request.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Lookup interval\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      lookupInterval: 30 # seconds\n```\n\n\u003c/details\u003e\n\n### Rejection code\n\nIf you feel more like a [tea pot](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/418) feel free to change the rejection code:\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Rejection code\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      rejectStatusCode: 418\n```\n\n\u003c/details\u003e\n\n### RemoteAddr\n\nIf you are not using any proxy in front of your Traefik instance, you can just use the `RemoteAddr` as default IP strategy.\nYou only need to specify a host to be allowlisted.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: RemoteAddr\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n```\n\n\u003c/details\u003e\n\n### Sourcerange IPs\n\nIf you want to add additional IP addresses to the allowlist (e.g. a server), you can use the `sourceRangeIps` option.\nThis might also be interesting to add your static IPv6 address (network prefix).\n\nYou are not only able to add IPv4 addresses but also IPv6 addresses.\nAlso it is possible to add an IP range (CIDR notation) to the list.\n\nKeep note that you always need to specify a source range host.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: Sourcerange IPs\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      sourceRangeIps:\n        - \"1.2.3.4\"\n        - \"192.168.1.0/24\"\n        - \"2a02:aaaa:bbbb:cccc::/64\"\n```\n\n\u003c/details\u003e\n\n### X-Forwarded-For\n\nIf you are using a reverse proxy in front of your Traefik instance, you can use the `X-Forwarded-For` header to determine the client IP address.\nYou can specify the depth of the IP address in the header to use.\nThe default value is `1` and will select the first IP address from the header (position starting from the right).\n\nYou are not able to specify a depth of 0 - otherwise the RemoteAddr method (default) will be used.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample: X-Forwarded-For\u003c/summary\u003e\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: Middleware\nmetadata:\n  name: ddnswl-dnsonly\nspec:\n  plugin:\n    ddns-allowlist:\n      sourceRangeHosts:\n        - my.router.ddns.tld\n      ipStrategy:\n        depth: 1\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaskmedia%2Fddns-allowlist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaskmedia%2Fddns-allowlist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaskmedia%2Fddns-allowlist/lists"}