{"id":21708130,"url":"https://github.com/fullstack-devops/dns-bind","last_synced_at":"2026-05-19T10:04:57.074Z","repository":{"id":44719573,"uuid":"448271675","full_name":"fullstack-devops/dns-bind","owner":"fullstack-devops","description":"A small docker image for providing wildcart DNS entrys and more.","archived":false,"fork":false,"pushed_at":"2022-01-28T17:15:05.000Z","size":66,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-20T17:30:24.784Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/fullstack-devops.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}},"created_at":"2022-01-15T12:31:11.000Z","updated_at":"2022-01-22T18:30:27.000Z","dependencies_parsed_at":"2022-09-05T10:41:53.038Z","dependency_job_id":null,"html_url":"https://github.com/fullstack-devops/dns-bind","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/fullstack-devops/dns-bind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-devops%2Fdns-bind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-devops%2Fdns-bind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-devops%2Fdns-bind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-devops%2Fdns-bind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullstack-devops","download_url":"https://codeload.github.com/fullstack-devops/dns-bind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-devops%2Fdns-bind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274046000,"owners_count":25212982,"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","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-25T22:20:49.783Z","updated_at":"2026-05-19T10:04:57.048Z","avatar_url":"https://github.com/fullstack-devops.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dns-bind\n[![Release container and chart](https://github.com/fullstack-devops/dns-bind/actions/workflows/release.yaml/badge.svg)](https://github.com/fullstack-devops/dns-bind/actions/workflows/release.yaml)\n\n----\n\nBind caching DNS server based on Debian slim with support for DNS forwarders, infinite wild-card DNS, infinite extra hosts, reverse DNS, DNSSEC timing settings and others.\n\nThanks to [cytopia](https://github.com/cytopia) for the parent project.\nThis repo also includes an helm chart repository\n\n----\n\n**Table of Contents**\n\n1. [Environmental variables](#environmental-variables)\n    1. [Required environmental variables](#required-environmental-variables)\n    2. [Optional environmental variables](#optional-environmental-variables)\n        1. [DEBUG_ENTRYPOINT](#debug_entrypoint)\n        2. [DOCKER_LOGS](#docker_logs)\n        3. [WILDCARD_DNS](#wildcard_dns)\n        4. [EXTRA_HOSTS](#extra_hosts)\n        5. [DNSSEC_VALIDATE](#dnssec_validate)\n        5. [DNS_FORWARDER](#dns_forwarder)\n        6. [TTL_TIME](#ttl_time)\n        7. [REFRESH_TIME](#refresh_time)\n        8. [RETRY_TIME](#retry_time)\n        9. [EXPIRY_TIME](#expiry_time)\n        10. [MAX_CACHE_TIME](#max_cache_time)\n        11. [ALLOW_QUERY](#allow_query)\n        12. [ALLOW_RECURSION](#allow_recursion)        \n2. [Default mountpoints](#default-mountpoints)\n3. [Default ports](#default-ports)\n4. [Examples](#examples)\n    1. [Default run](#default-run)\n    2. [Wildcard domain](#wildcard-domain)\n    3. [Wildcard subdomain](#wildcard-subdomain)\n    4. [Wildcard TLD](#wildcard-tld)\n    5. [Wildcard TLD and reverse DNS entry](#wildcard-tld-and-reverse-dns-entry)\n    6. [Wildcard TLD and DNS resolver](#wildcard-tld-and-dns-resolver)\n    7. [Wildcard TLD, DNS resolver and extra hosts](#wildcard-tld-dns-resolver-and-extra-hosts)\n    8. [Extra hosts, DNS resolver, allow query, and allow recursion](#extra-hosts-dns-resolver-allow-query-and-allow-recursion)\n5. [Host integration](#host-integration)\n6. [Support](#support)\n7. [License](#license)\n\n---\n\n## Environmental variables\n\n### Required environmental variables\n\n- None\n\n### Optional environmental variables\n\nFor the helm values see the [values.yaml](helm/values.yaml), section `envValues`\n\n| Variable           | Type   | Default   | Description |\n|--------------------|--------|-----------|-------------|\n| `DEBUG_ENTRYPOINT` | bool   | `0`       | Show shell commands executed during start.\u003cbr/\u003eValues: `0`, `1` or `2` |\n| `DOCKER_LOGS`      | bool   | `0`       | Set to `1` to log info and queries to Docker logs. |\n| `WILDCARD_DNS`     | string |           | Add one or more tld's, domains or subdomains as catch-all for a specific IP address or CNAME. Reverse DNS is optional and can also be specified. |\n| `EXTRA_HOSTS`      | string |           | Add one or more hosts (CNAME: tld's, domains, subdomains) to map to a specific IP address or CNAME. Reverse DNS is optional and can also be specified. |\n| `DNSSEC_VALIDATE`  | string | `no`      | Control the behaviour of DNSSEC validation. The default is to not validate: `no`. Other possible values are: `yes` and `auto`. |\n| `DNS_FORWARDER`    | string |           | Specify a comma separated list of IP addresses as custom DNS resolver. This is useful if your LAN already has a DNS server which adds custom/internal domains and you still want to keep them in this DNS server\u003cbr/\u003eExample: `DNS_FORWARDER=8.8.8.8,8.8.4.4` |\n| `TTL_TIME`         | int    | `3600`    | (Time in seconds) See [BIND TTL](http://www.zytrax.com/books/dns/apa/ttl.html) and [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html)|\n| `REFRESH_TIME`     | int    | `1200`    | (Time in seconds) See [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html) |\n| `RETRY_TIME`       | int    | `180`     | (Time in seconds) See [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html) |\n| `EXPIRY_TIME`      | int    | `1209600` | (Time in seconds) See [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html) |\n| `MAX_CACHE_TIME`   | int    | `10800`   | (Time in seconds) See [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html) |\n| `ALLOW_QUERY`      | string |           | Specify a comma separated list of IP addresses with optional CIDR mask to allow queries from a specific IP address or ranges of IP addresses. This allows for control over who is allowed to query the DNS server. If not specified all hosts are allowed to make queries (defaults to `any`). See [BIND QUERIES](http://www.zytrax.com/books/dns/ch7/queries.html) \u003cbr/\u003eExample: `ALLOW_QUERY=192.168.1.0/24,127.0.0.1` |\n| `ALLOW_RECURSION`  | string |           | Specify a comma separated list of IP addresses with optional CIDR mask to allow queries from a specific IP address or ranges of IP addresses.  This option allows this DNS server to forward a request to another DNS server when an address cannot be resolved. If not present the allow-query-cache default is assumed. See [BIND QUERIES](http://www.zytrax.com/books/dns/ch7/queries.html) \u003cbr/\u003eExample: `ALLOW_RECURSION=192.168.1.0/24,127.0.0.1` |\n#### DEBUG_ENTRYPOINT\n\n* If set to `0`, only warnings and errors are shown\n* If set to `1`, info, warnings and errors are shown\n* If set to `2`, info, warnings and errors are shown, as well as commands executed during startup\n\n#### DOCKER_LOGS\n\n* If set to `0`, no additional logging is done during run-time\n* If set to `1`, BIND is more verbose during run-time and shows asked queries as well as general information\n\n#### WILDCARD_DNS\n\nThe `WILDCARD_DNS` option allows you to specify one or more multiple catch-all DNS zones which can either\nbe a full TLD, a domain or any kind of subdomain. It allows you to map your catch-all to a specific\nIP address or even a CNAME (if it is resolvable by public DNS servers). Optionally you can also assign\nthe reverse DNS name (PTR record).\n\nThe general format is as follows, whereas the string in square brackets it optional and responsible\nfor the reverse DNS (PTR records):\n```bash\n# Structure\nWILDCARD_DNS='tld1=1.1.1.1[=tld],tld2=2.2.2.2[=tld2]'\nWILDCARD_DNS='tld1=CNAME1[=tld],tld2=CNAME2[=tld2]'\n```\n\nSome examples:\n```bash\n# 1. One entry:\n# The following catches all queries to *.tld and redirects them to 192.168.0.1\nWILDCARD_DNS='tld=192.168.0.1'\n\n# 2. Two entries:\n# The following catches all queries to *.tld and redirects them to 192.168.0.1\n# As well as all queries from *.example.org and redirects them to 192.168.0.2\nWILDCARD_DNS='tld=192.168.0.1,example.org=192.168.0.2'\n\n# 3. Using CNAME's for resolving:\n# The following catches all queries to *.tld and redirects them to whatever\n# IP example.org resolved to\nWILDCARD_DNS='tld=example.org'\n\n# 4. Adding reverse DNS:\n# The following catches all queries to *.tld and redirects them to 192.168.0.1\n# As well as adding reverse DNS from 192.168.0.1 to resolve to tld\nWILDCARD_DNS='tld=192.168.0.1=tld'\n\n# 5. Complex example\n# The following catches all queries to *.tld and redirects them to whatever\n# IP example.org resolved to. Additionally it adds a reverse DNS record from example.org's\n# IP to resolve to tld (PTR record)\n# It also adds another catch-all for the subdomain of *.cytopia.tld which will point to 192.168.0.1\n# Including a reverse DNS record back to cytopia.tld\nWILDCARD_DNS='tld=example.org=tld,cytopia.tld=192.168.0.1=cytopia.tld'\n```\n\n#### EXTRA_HOSTS\n\nThe `EXTRA_HOSTS` option almost works like the `WILDCARD_DNS` option, except that no wildcard is added,\nbut rather exactly the host you have specified.\n\nThis is useful if you want to add extra hosts to your setup just like the Docker Compose option\n[extra_hosts](https://docs.docker.com/compose/compose-file/#extra_hosts)\n\n```bash\n# Structure\nEXTRA_HOSTS='host1=1.1.1.1[=host1],host2=2.2.2.2[=host2]'\nEXTRA_HOSTS='host1=CNAME1[=host1],host2=CNAME2[=host2]'\n```\n\nSome examples:\n```bash\n# 1. One entry:\n# The following extra host 'tld' is added and will always point to 192.168.0.1.\n# When reverse resolving '192.168.0.1' it will answer with 'tld'.\nEXTRA_HOSTS='tld=192.168.0.1'\n\n# 2. One entry:\n# The following extra host 'my.host' is added and will always point to 192.168.0.1.\n# When reverse resolving '192.168.0.1' it will answer with 'my.host'.\nEXTRA_HOSTS='my.host=192.168.0.1'\n\n# 3. Two entries:\n# The following extra host 'tld' is added and will always point to 192.168.0.1.\n# When reverse resolving '192.168.0.1' it will answer with 'tld'.\n# A second extra host 'example.org' is added and always redirects to 192.168.0.2\n# When reverse resolving '192.168.0.2' it will answer with 'example.org'.\nEXTRA_HOSTS='tld=192.168.0.1,example.org=192.168.0.2'\n\n# 4. Using CNAME's for resolving:\n# The following extra host 'my.host' is added and will always point to whatever\n# IP example.org resolves to.\n# When reverse resolving '192.168.0.1' it will answer with 'my.host'.\nEXTRA_HOSTS='my.host=example.org'\n\n# 5. Adding reverse DNS:\n# The following extra host 'my.host' is added and will always point to whatever\n# IP example.org resolves to.\n# As well as adding reverse DNS from 192.168.0.1 to resolve to tld\nEXTRA_HOSTS='tld=192.168.0.1=tld'\n```\n\n#### DNSSEC_VALIDATE\n\nThe `DNSSEC_VALIDATE` variable defines the DNSSEC validation. Default is to not validate (`no`).\nPossible values are:\n\n* `yes` - DNSSEC validation is enabled, but a trust anchor must be manually configured. No validation will actually take place.\n* `no` - DNSSEC validation is disabled, and recursive server will behave in the \"old fashioned\" way of performing insecure DNS lookups, until you have manually configured at least one trusted key.\n* `auto` - DNSSEC validation is enabled, and a default trust anchor (included as part of BIND) for the DNS root zone is used.\n\n#### DNS_FORWARDER\n\nBy default this dockerized BIND is not acting as a DNS forwarder, so it will not have any external\nDNS available. In order to apply external DNS forwarding, you will have to specify one or more external\nDNS server. This could be the one's from google for example (`8.8.8.8` and `8.8.4.4`) or any others\nyou prefer. In case your LAN has its own DNS server with already defined custom DNS records that you\nneed to make available, you should use them.\n\n```bash\n# Structure (comma separated list of IP addresses)\nDNS_FORWARDER='8.8.8.8,8.8.4.4'\n```\n\nSome examples\n```bash\nDNS_FORWARDER='8.8.8.8'\nDNS_FORWARDER='8.8.8.8,192.168.0.10'\n```\n\n#### TTL_TIME\nSpecify time in seconds.\nFor more information regarding this setting, see [BIND TTL](http://www.zytrax.com/books/dns/apa/ttl.html) and [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html)\n\n#### REFRESH_TIME\nSpecify time in seconds.\nFor more information regarding this setting, see [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html)\n\n#### RETRY_TIME\nSpecify time in seconds.\nFor more information regarding this setting, see [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html)\n\n#### EXPIRY_TIME\nSpecify time in seconds.\nFor more information regarding this setting, see [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html)\n\n#### MAX_CACHE_TIME\nSpecify time in seconds.\nFor more information regarding this setting, see [BIND SOA](http://www.zytrax.com/books/dns/ch8/soa.html)\n\n#### ALLOW_QUERY\n\nBy default this dockerized BIND does not specify query rules.  This exposes the\nallow-query options to specify who is allowed to query for results.\nNote that ACLs are not yet handled.\n\n```bash\n# Structure (comma separated list of IP addresses, IP addresses with CIDR mask, or address match list names \"none\", \"any\", \"localhost\", and \"localnets\")\nALLOW_QUERY='192.168.1.0/24,127.0.0.1'\n```\n\nSome examples\n```bash\nALLOW_QUERY='any'\nALLOW_QUERY='192.168.1.0/24,127.0.0.1'\n```\n\n#### ALLOW_RECURSION\n\nBy default this dockerized BIND does not allow DNS recursion. If BIND cannot resolve an address it\nwill act as a DNS client and forward the request to another DNS server.  This server is specified in the DNS_FORWARDER list.\nNote that ACLs are not yet handled.\n\n```bash\n# Structure (comma separated list of IP addresses, IP addresses with CIDR mask, or address match list names \"none\", \"any\", \"localhost\", and \"localnets\")\nALLOW_RECURSION='192.168.1.0/24,127.0.0.1'\n```\n\nSome examples\n```bash\nALLOW_RECURSION='any'\nALLOW_RECURSION='192.168.1.0/24,127.0.0.1'\n```\n\n## Default mount points\n\n- None\n\n\n## Default ports\n\n| Docker | Description  |\n|--------|--------------|\n| 53     | DNS Resolver |\n| 53/udp | DNS Resolver |\n\n\n## Examples\n\nThe following examples start the container in foreground and use `-i`, so you can easily stop\nit by pressing `\u003cCtrl\u003e + c`. For a production run, you would rather use `-d` to send it to the\nbackground.\n\n#### Default run\n\nExposing the port is mandatory if you want to use it for your host operating system.\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -t cytopia/bind\n```\n\n#### Wildcard domain\n\nLet's add a wildcard zone for `*.example.com`. All subdomains as well as the main domain will resolve\nto `192.168.0.1`.\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e WILDCARD_DNS='example.com=192.168.0.1' \\\n    -t cytopia/bind\n```\n\n#### Wildcard subdomain\n\nLet's add a wildcard zone for `*.aws.example.com`. All subdomains as well as the main subdomain will resolve\nto `192.168.0.1`.\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e WILDCARD_DNS='aws.example.com=192.168.0.1' \\\n    -t cytopia/bind\n```\n\n#### Wildcard TLD\n\nLet's add a wildcard zone for `*.loc`. All domains, subdomain as well as the TLD itself will resolve\nto `192.168.0.4`.\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e WILDCARD_DNS='loc=192.168.0.4' \\\n    -t cytopia/bind\n```\n\n#### Wildcard TLD and reverse DNS entry\n\nLet's add a wildcard zone for `*.loc`. All domains, subdomain as well as the TLD itself will resolve\nto `192.168.0.4`. Additionally we specify that `host.loc` will be the reverse loopup for `192.168.0.4`.\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e WILDCARD_DNS='loc=192.168.0.4=host.loc' \\\n    -t cytopia/bind\n```\n\n#### Wildcard TLD and DNS resolver\n\nLet's add a wildcard zone for `*.loc`. All domains, subdomain as well as the TLD itself will resolve\nto `192.168.0.4`.\n\nLet's also hook in our imaginary corporate DNS server into this container, so we can make use of\nany already defined custom DNS entries by that nameserver.\n\n* `loc` and all its subdomains (such as: `hostname.loc`) will point to `192.168.0.1`:\n* Your corporate DNS servers are `10.0.15.1` and `10.0.15.2`\n\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e WILDCARD_DNS='loc=192.168.0.1' \\\n    -e DNS_FORWARDER=10.0.15.1,10.0.15.2 \\\n    -t cytopia/bind\n```\n\n#### Wildcard TLD, DNS resolver and extra hosts\n\n* `loc` and all its subdomains (such as: `hostname.loc`) will point to `192.168.0.1`:\n* Your corporate DNS servers are `10.0.15.1` and `10.0.15.2`\n* Also add two extra hosts with custom DNS:\n    - host5.loc -\u003e 192.168.0.2\n    - host5.org -\u003e 192.168.0.3\n\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e WILDCARD_DNS='loc=192.168.0.1' \\\n    -e EXTRA_HOSTS='host5.loc=192.168.0.2,host5.org=192.168.0.3' \\\n    -e DNS_FORWARDER=10.0.15.1,10.0.15.2 \\\n    -t cytopia/bind\n```\n\n#### Extra hosts, DNS resolver, allow query, and allow recursion\n\n* Your trusted external DNS servers are `8.8.8.8` and `8.8.4.4` (google DNS servers)\n* Allow queries from:\n    - All 192.168.0.xxx addresses\n    - Localhost aka 127.0.0.1\n* Allow recursion to resolve other queries (such as www.google.com) from:\n    - All 192.168.0.xxx addresses\n    - Localhost aka 127.0.0.1\n* Add an extra hosts with custom DNS:\n    - host1 -\u003e 192.168.0.11\n\n```bash\n$ docker run -i \\\n    -p 53:53/tcp \\\n    -p 53:53/udp \\\n    -e EXTRA_HOSTS='host1=192.168.0.11' \\\n    -e DNS_FORWARDER=8.8.8.8,8.8.4.4 \\\n    -e ALLOW_QUERY=192.168.0.0/24,127.0.0.1 \\\n    -e ALLOW_RECURSION=192.168.0.0/24,127.0.0.1 \\\n    -t cytopia/bind\n```\n\n## Host integration\n\nYou can run this DNS container locally without having to worry to affect any corporate DNS server\nthat are given to you via DHCP.\n\nAdd the following line to the very beginning to `/etc/dhcp/dhclient.conf`:\n```bash\nprepend domain-name-servers 127.0.0.1;\n```\nRestart network manager\n```bash\n# Via service command\n$ sudo service network-manager restart\n\n# Or the systemd way\n$ sudo systemctl restart network-manager\n```\n\nThis will make sure that whenever your `/etc/resolv.conf` is deployed, you will have `127.0.0.1`\nas the first entry and also make use of any other DNS server which are deployed via the LAN's DHCP server.\n\nIf `cytopia/bind` is not running, it does not affect the name resolution, because you will still\nhave entries in `/etc/resolv.conf`.\n\n\n## License\n\n**[Apache-2.0 License ](LICENSE)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstack-devops%2Fdns-bind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullstack-devops%2Fdns-bind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstack-devops%2Fdns-bind/lists"}