{"id":13446507,"url":"https://github.com/MatthewVance/unbound-docker","last_synced_at":"2025-03-21T06:31:25.845Z","repository":{"id":37276124,"uuid":"51189383","full_name":"MatthewVance/unbound-docker","owner":"MatthewVance","description":"Unbound DNS Server Docker Image","archived":false,"fork":false,"pushed_at":"2024-10-19T11:55:39.000Z","size":188,"stargazers_count":578,"open_issues_count":39,"forks_count":142,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-10-28T09:54:42.503Z","etag":null,"topics":["dns","dns-server","docker","unbound"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatthewVance.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":"2016-02-06T04:29:07.000Z","updated_at":"2024-10-23T18:05:24.000Z","dependencies_parsed_at":"2024-03-14T12:49:40.686Z","dependency_job_id":"66c01523-eecc-4b56-9861-f689811bf165","html_url":"https://github.com/MatthewVance/unbound-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewVance%2Funbound-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewVance%2Funbound-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewVance%2Funbound-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewVance%2Funbound-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatthewVance","download_url":"https://codeload.github.com/MatthewVance/unbound-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244750782,"owners_count":20504146,"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":["dns","dns-server","docker","unbound"],"created_at":"2024-07-31T05:00:53.931Z","updated_at":"2025-03-21T06:31:25.238Z","avatar_url":"https://github.com/MatthewVance.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Unbound DNS Server Docker Image\n\n## Supported tags and respective `Dockerfile` links\n- [`1.22.0`, `latest` (*1.22.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.22.0)\n- [`1.21.1`, (*1.21.1/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.21.1)\n- [`1.21.0`, (*1.21.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.21.0)\n- [`1.20.0`, (*1.20.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.20.0)\n- [`1.19.3`, (*1.19.3/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.19.3)\n- [`1.19.2`, (*1.19.2/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.19.2)\n- [`1.19.1`, (*1.19.1/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.19.1)\n- [`1.19.0`, (*1.19.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.19.0)\n- [`1.18.0`, (*1.18.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.18.0)\n- [`1.17.1`, (*1.17.1/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.17.1)\n- [`1.17.0`, (*1.17.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.17.0)\n- [`1.16.3`, (*1.16.3/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.16.3)\n- [`1.16.2`, (*1.16.2/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.16.2)\n- [`1.16.1`, (*1.16.1/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.16.1)\n- [`1.16.0`, (*1.16.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.16.0)\n- [`1.15.0`, (*1.15.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.15.0)\n- [`1.14.0`, (*1.14.0/Dockerfile*)](https://github.com/MatthewVance/unbound-docker/tree/master/1.14.0)\n\n## What is Unbound?\n\nUnbound is a validating, recursive, and caching DNS resolver.\n\u003e [unbound.net](https://unbound.net/)\n\n## How to use this image\n\n### Standard usage\n\nRun this container with the following command:\n\n```console\ndocker run \\\n--name=my-unbound \\\n--detach=true \\\n--publish=53:53/tcp \\\n--publish=53:53/udp \\\n--restart=unless-stopped \\\nmvance/unbound:latest\n```\n\nBy default, this image forwards queries Cloudflare DNS server over TLS. In other words, it does not act as a recursive server. The [unbound.sh file](1.17.0/data/unbound.sh) provides the configuration unless it is overriden as described below.\n\n*Note: The example [unbound.conf](unbound.conf) file is different from the one set by [unbound.sh file](1.17.0/data/unbound.sh). The example is provided to help you re-configure this as a [recursive server](https://github.com/MatthewVance/unbound-docker#recursive-config).*\n\n### Override default forward\n\nBy default, forwarders are configured to use Cloudflare DNS. You can retrieve the configuration in the [forward-records.conf](1.17.0/data/opt/unbound/etc/unbound/forward-records.conf) file.\n\nYou can create your own configuration file and override the one placed in `/opt/unbound/etc/unbound/forward-records.conf` in the container. This is useful if you prefer to use something other than Cloudflare DNS but do not want to provide a custom unbound.conf file.\n\nExample `forward-records.conf`:\n```\nforward-zone:\n  # Forward all queries (except those in cache and local zone) to\n  # upstream recursive servers\n  name: \".\"\n\n  # my DNS\n  forward-addr: 192.168.0.1@53#home.local\n```\n\nAnother example `forward-records.conf`:\n```\nforward-zone:\n    # Forward all queries (except those in cache and local zone) to\n    # upstream recursive servers\n    name: \".\"\n    # Queries to this forward zone use TLS\n    forward-tls-upstream: yes\n\n    ## CleanBrowsing Family Filter\n    forward-addr: 185.228.168.168@853#family-filter-dns.cleanbrowsing.org\n    forward-addr: 185.228.169.168@853#family-filter-dns.cleanbrowsing.org\n```\n\nOnce the file has your entries in it, mount your version of the file as a volume\nwhen starting the container:\n\n```console\ndocker run \\\n--name my-unbound \\\n--detach=true \\\n--publish=53:53/tcp \\\n--publish=53:53/udp \\\n--restart=unless-stopped \\\n--volume $(pwd)/forward-records.conf:/opt/unbound/etc/unbound/forward-records.conf:ro \\\nmvance/unbound:latest\n```\n\n### Use a customized Unbound configuration\n\nInstead of using this image's default configuration for Unbound, you may supply your own configuration. If your customized configuration is located at `/my-directory/unbound/unbound.conf`, pass `/my-directory/unbound` as a volume when creating your container:\n\n```console\ndocker run --name=my-unbound \\\n--detach=true \\\n--publish=53:53/tcp \\\n--publish=53:53/udp \\\n--restart=unless-stopped \\\n--volume=/my-directory/unbound:/opt/unbound/etc/unbound/ \\\nmvance/unbound:latest\n```\n\nThis will expose all files in `/my-directory/unbound/` to the container. As an alternate way to serve custom DNS records for any local zones, either place them directly in your `unbound.conf`, or place the local zones in a separate file and use Unbound's include directive within your `unbound.conf`:\n\n```\ninclude: /opt/unbound/etc/unbound/local-zone-unbound.conf\n```\n\nYour volume's contents might eventually look something like this:\n\n```\n/my-directory/unbound/\n-- unbound.conf\n-- local-zone-unbound.conf\n-- secret-zone.conf\n-- some-other.conf\n```\n\nOverall, this approach is very similar to the `a-records.conf` approach described below. However, by passing your unbound directory rather than a single file, you have more options for customizing and segmenting your Unbound configuration.\n\n***Note:** Care has been taken in the image's default configuration to enable\nsecurity options so it is recommended to use it as a guide.*\n\n### Run on different port\n\nIf you want to run Unbound on a different port such as 5353, modify the publish flags:\n\n```console\nsudo docker run \\\n--name=my-unbound \\\n--publish=5353:53/tcp \\\n--publish=5353:53/udp \\\n--detach=true \\\n--restart=unless-stopped \\\n--volume=$(pwd)/my-directory/forward-records.conf:/opt/unbound/etc/unbound/forward-records.conf:ro \\\n--volume=$(pwd)/my-directory/a-records.conf:/opt/unbound/etc/unbound/a-records.conf:ro \\\nmvance/unbound:latest\n```\n\n### Serve Custom DNS Records for Local Network\n\nWhile Unbound is not a full authoritative name server, it supports resolving\ncustom entries on a small, private LAN. In other words, you can use Unbound to\nresolve fake names such as your-computer.local within your LAN.\n\nTo support such custom entries using this image, you need to provide an\n`a-records.conf` or `srv-records.conf` file.\nThis configuration file is where you will define your custom\nentries for forward and reverse resolution.\n\n#### A records\n\nThe `a-records.conf` file should use the following format:\n\n```\n# A Record\n  #local-data: \"somecomputer.local. A 192.168.1.1\"\n  local-data: \"laptop.local. A 192.168.1.2\"\n\n# PTR Record\n  #local-data-ptr: \"192.168.1.1 somecomputer.local.\"\n  local-data-ptr: \"192.168.1.2 laptop.local.\"\n```\n\nOnce the file has your entries in it, mount your version of the file as a volume\nwhen starting the container:\n\n```console\ndocker run \\\n--name my-unbound \\\n--detach=true \\\n--publish=53:53/tcp \\\n--publish=53:53/udp \\\n--restart=unless-stopped \\\n--volume $(pwd)/a-records.conf:/opt/unbound/etc/unbound/a-records.conf:ro \\\nmvance/unbound:latest\n```\n\n#### SRV records\n\nThe `srv-records.conf` file should use the following format:\n\n```\n# SRV records\n# _service._proto.name. | TTL | class | SRV | priority | weight | port | target.\n_etcd-server-ssl._tcp.domain.local.  86400 IN    SRV 0        10     2380 etcd-0.domain.local.\n_etcd-server-ssl._tcp.domain.local.  86400 IN    SRV 0        10     2380 etcd-1.domain.local.\n_etcd-server-ssl._tcp.domain.local.  86400 IN    SRV 0        10     2380 etcd-2.domain.local.\n```\n\nRun a container that use this SRV config file:\n```console\ndocker run \\\n--name my-unbound \\\n--detach=true \\\n--publish=53:53/tcp \\\n--publish=53:53/udp \\\n--restart=unless-stopped \\\n--volume $(pwd)/srv-records.conf:/opt/unbound/etc/unbound/srv-records.conf:ro \\\nmvance/unbound:latest\n```\n\n### Docker Compose\n\nThe following `docker-compose.yml` file is a starting point. The provided example shows how to override default forward and serve custom DNS records for your LAN. It requires `forward-records.conf` and `a-records.conf` files be provided at the `./my_conf/`. \n\n```\nversion: '3'\nservices:\n  unbound:\n    container_name: unbound\n    image: \"mvance/unbound:latest\"\n    expose:\n      - \"53\"\n    networks:\n      - dns\n    ports:\n      - \"53:53/tcp\"\n      - \"53:53/udp\"\n    volumes:\n      - \"/data/unbound/my_conf/forward-records.conf:/opt/unbound/etc/unbound/forward-records.conf\"\n      - \"/data/unbound/my_conf/a-records.conf:/opt/unbound/etc/unbound/a-records.conf\"\n    restart: unless-stopped\nnetworks:\n  dns:\n```\n\nIf you would rather provide a fully custom `unbound.conf` file, you will need to provide an `unbound.conf` file and mount it as a volume:\n\n```\n    volumes:\n      - type: bind\n        read_only: true\n        source: ./my_conf/unbound.conf\n        target: /opt/unbound/etc/unbound/unbound.conf\n```\n\n### Kubernetes usage\n\n\u003e The method described here is basic and not recommended for larger environments. While this example is provided, support for Kubernetes related issues is outside the scope of this project.\n\nTo spin the deployment up use:\n\n```\nkubectl apply -f unbound-main-conf.yml -f other-files.yml ...\n```\n\nWhen taking it down, remember to use the reverse order in which you spun the deployment up.\n\nRestarting:\n\n```\nkubectl rollout restart deployment dns \n```\n\nAn example deployment can be viewed [here](k8s/deployment.yml). It is not ready since you need to fill it with your\nrecords and the main unbound configuration file.\n\n\u003e A fair warning: The example is not using a Service but a hostPort, thus this is only a mock-up. One should not use hostPort \n\u003e in a production cluster.\n\n\u003e Additional warning: As per [this](https://kubernetes.io/docs/concepts/configuration/secret/) document the default\n\u003e secrets configuration is unencrypted per default. You are responsible to harden this yourself and should do so!\n\n# Notes\n\n## Recursive config\n\nThe default config forwards forwards DNS queries to another DNS server over TLS. If you would rather this work as a recursive DNS server, you must [use a customized Unbound configuration](https://github.com/MatthewVance/unbound-docker#use-a-customized-unbound-configuration). An [example unbound.conf](https://github.com/MatthewVance/unbound-docker/blob/master/unbound.conf) file to configure unbound as a recursive server is available as a guide.\n\n## Performance\n\n*For a DNS server with lots of short-lived connections, you may wish to consider\nadding `--net=host` to the run command for performance reasons. However, it is\nnot required and some shared container hosting services may not allow it. You\nshould also be aware that using `--net=host` can be a security risk in some situations. The\n[Center for Internet Security Docker 1.6\nBenchmark](https://benchmarks.cisecurity.org/tools2/docker/CIS_Docker_1.6_Benchmark_v1.0.0.pdf)\nrecommends against this mode since it essentially tells Docker to not\ncontainerize the container's networking, thereby giving it full access to the\nhost machine's network interfaces. It also mentions this option could cause the\ncontainer to do unexpected things such as shutting down the Docker host as\nreferenced in [Docker Issue #6401](https://github.com/docker/docker/issues/6401)\n. For the most secure deployment, unrelated services with confidential data\nshould not be run on the same host or VPS. In such cases, using `--net=host`\nshould have limited impact on security.*\n\n## Logging\n\nLogging is very limited in the default config created by [unbound.sh](https://github.com/MatthewVance/unbound-docker/blob/e0285a31ff4449010d5ad4bbeeda1adb7645a02c/1.17.0/data/unbound.sh#L86). If using the default config as an example starting point, a placeholder for a logfile (`unbound.log`) has been provided with the correct file ownership at the path `/opt/unbound/etc/unbound/` in case you want to increase logging and send to a file.\n\n## Healthcheck\n\nBy default, this image includes a healthcheck that performs a query for *cloudflare.com* on localhost at a regular interval.\n\nTo disable the healthcheck, add the `--no-healthcheck` flag to your Dockerfile. If using docker-compose, you can configure the healthcheck differently as explained in the [Docker docs](https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck).\n\n## Known issues\n\nThe following message may appears in the logs about IPv6 Address Assignment:\n\n`[1644625926] libunbound[24:0] error: udp connect failed: Cannot assign requested address for 2001:xxx:xx::x port 53`\n\nWhile annoying, the container works despite the error. Search this issues in this repo for \"udp connect\" to see more discussion.\n\n# User feedback\n\n## Documentation\n\nDocumentation for this image is stored right here in the [`README.md`](https://github.com/MatthewVance/unbound-docker/blob/master/README.md).\n\nDocumentation for Unbound is available on the [project's website](https://unbound.net/).\n\n## Issues\n\nIf you have any problems with or questions about this image, please contact me\nthrough a [GitHub issue](https://github.com/MatthewVance/unbound-docker/issues).\n\n## Contributing\n\nYou are invited to contribute new features, fixes, or updates, large or small. I\nimagine the upstream projects would be equally pleased to receive your\ncontributions.\n\nPlease familiarize yourself with the [repository's `README.md`\nfile](https://github.com/MatthewVance/unbound-docker/blob/master/README.md)\nbefore attempting a pull request.\n\nBefore you start to code, I recommend discussing your plans through a [GitHub\nissue](https://github.com/MatthewVance/unbound-docker/issues), especially for\nmore ambitious contributions. This gives other contributors a chance to point\nyou in the right direction, give you feedback on your design, and help you find\nout if someone else is working on the same thing.\n\n## Acknowledgments\n\nThe code in this image is heavily influenced by DNSCrypt server Docker image,\nthough the upstream projects most certainly also deserve credit for making this\nall possible.\n- [Docker](https://www.docker.com/)\n- [DNSCrypt server Docker image](https://github.com/jedisct1/dnscrypt-server-docker)\n- [OpenSSL](https://www.openssl.org/)\n- [Unbound](https://unbound.nlnetlabs.nl/)\n\n## Licenses\n\n### License\n\nUnless otherwise specified, all code is released under the MIT License (MIT).\nSee the [repository's `LICENSE`\nfile](https://github.com/MatthewVance/unbound-docker/blob/master/LICENSE) for\ndetails.\n\n### Licenses for other components\n\n- Docker: [Apache 2.0](https://github.com/docker/docker/blob/master/LICENSE)\n- DNSCrypt server Docker image: [ISC License](https://github.com/jedisct1/dnscrypt-server-docker/blob/master/LICENSE)\n- LibreSSL: [Various](http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/lib/libssl/src/LICENSE?rev=1.12\u0026content-type=text/x-cvsweb-markup)\n- OpenSSL: [Apache-style license](https://www.openssl.org/source/license.html)\n- Unbound: [BSD License](https://unbound.nlnetlabs.nl/svn/trunk/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMatthewVance%2Funbound-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMatthewVance%2Funbound-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMatthewVance%2Funbound-docker/lists"}