[{"_1":2,"_183":-5,"_184":-5},"loaderData",{"_3":4,"_18":19,"_25":26,"_162":163},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16,"_17":11},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","dockerRebrandTour","routes/_layout",{"_20":-5,"_21":22,"_23":11,"_24":22},"username","isAskGordonEnabled",true,"showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":89,"_112":113,"_150":-5,"_151":11,"_152":22,"_153":11,"_154":11,"_155":-5,"_156":11,"_157":-5,"_158":159,"_160":114,"_161":-7},"canonicalUrl","https://hub.docker.com/r/nutshells/dnscrypt-wrapper/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","nutshells","reponame","dnscrypt-wrapper","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":22,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2017-08-05T12:41:19.471492Z","description","DNSCrypt-Wrapper Docker Image","is_private","last_updated","2020-01-28T09:16:57.385203Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",1159,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# DNSCrypt-Wrapper Docker Image\n\n[![Project Nutshells](https://img.shields.io/badge/Project-_Nutshells_🌰-orange.svg?maxAge=2592000)](https://github.com/quchao/nutshells/) [![Docker Build Build Status](https://img.shields.io/docker/build/nutshells/dnscrypt-wrapper.svg?maxAge=3600&label=Build%20Status)](https://hub.docker.com/r/nutshells/dnscrypt-wrapper/) [![Alpine Based](https://img.shields.io/badge/Alpine-3.6-0D597F.svg?maxAge=2592000)](https://alpinelinux.org/) [![MIT License](https://img.shields.io/github/license/quchao/nutshells.svg?maxAge=2592000&label=License)](https://github.com/quchao/nutshells/blob/master/LICENSE) [![dnscrypt-wrapper](https://img.shields.io/badge/DNSCrypt--Wrapper-0.3-lightgrey.svg?maxAge=2592000)](https://github.com/cofyc/dnscrypt-wrapper/)\n\n[DNSCrypt-Wrapper](https://github.com/cofyc/dnscrypt-wrapper/) is the server-end of [DNSCrypt](http://dnscrypt.org/) proxy, which is a protocol to improve DNS security, now with xchacha20 cipher support.\nThis image features certficate management & rotation.\n\n\n## Variants:\n\n| Tag | Description | 🐳 |\n|:-- |:-- |:--:|\n| `:latest` | DNSCrypt-Wrapper `0.3` on `alpine:latest`. | [![Dockerfile](https://img.shields.io/badge/Dockerfile-latest-22B8EB.svg?maxAge=2592000&style=flat-square)](https://github.com/quchao/nutshells/blob/master/dnscrypt-wrapper/Dockerfile/) |\n\n\n## Usage\n\n### Synopsis\n\n```\ndocker container run [OPTIONS] nutshells/dnscrypt-wrapper [COMMAND] [ARG...]\n```\n\n- Learn more about `docker container run` and its `OPTIONS` [here](https://docs.docker.com/edge/engine/reference/commandline/container_run/);\n- List all available `COMMAND`s: \n `docker container run --rm --read-only nutshells/dnscrypt-wrapper help`\n- List all `ARG`s:\n `docker container run --rm --read-only nutshells/dnscrypt-wrapper --help`\n\n### Getting Started\n\nA DNScrypt proxy server cannot go without a so-called **provider key pair**.\nIt's rather easy to generate a new pair by running the `init` [command](#commands) as below:\n\n> `` is the host directory where you store the key pairs.\n> The provider key pair should NEVER be changed as you may inform the world of the public key, unless the secret key is compromised.\n\n``` bash\ndocker container run -d -p 5353:12345/udp -p 5353:12345/tcp \\\n --name=dnscrypt-server --restart=unless-stopped --read-only \\\n --mount=type=bind,src=,dst=/usr/local/etc/dnscrypt-wrapper \\\n nutshells/dnscrypt-wrapper \\\n init\n```\n\nNow, a server is initialized with [default settings](#environment-variables) and running on port `5353` as a daemon.\n\nDig the *public key* fingerprint out of logs:\n\n``` bash\ndocker container logs dnscrypt-server | grep --color 'Provider public key: '\n```\n\nThen [see if it works](#how-to-test).\n\n### Using an existing key pair\n\nIf you used to run a DNScrypt proxy server and have been keeping the keys securely, make sure they are put into `` and renamed to `public.key` and `secret.key`, then run the `start` [command](#commands) instead.\n\n> Incidentally, `start` is the default one which could be just omitted.\n\nLost the *public key* fingerprint but couldn't find it from logs? Try the `pubkey` command:\n\n``` bash\ndocker container run --rm --read-only \\\n --mount=type=bind,src=,dst=/usr/local/etc/dnscrypt-wrapper \\\n nutshells/dnscrypt-wrapper \\\n pubkey\n```\n\n### How to test\n\nGet `` by following the instructions above,\nand check [this section](#environment-variables) to determin the default value of ``.\n\n> Please install [`dnscrypt-proxy`](https://hub.docker.com/r/nutshells/dnscrypt-proxy/) and `dig` first.\n\n``` bash\ndnscrypt-proxy --local-address=127.0.0.1:53 \\\n --resolver-address=127.0.0.1:5353 \\\n --provider-name=2.dnscrypt-cert. \\\n --provider-key=\n --loglevel=7\ndig -p 53 +tcp google.com @127.0.0.1\n```\n\n### Utilities\n\nAs you can see from the examples of the previous sections: the container accepts original [command-line options](https://github.com/shadowsocks/shadowsocks-libev/#usage) of *ss-libev* as arguments.\n\nHere are a few more examples:\n\n#### Printing the version:\n\n``` bash\ndocker container run --rm --read-only nutshells/dnscrypt-wrapper --version\n```\n\n#### Enabling verbose mode:\n\n``` bash\ndocker container run [OPTIONS] nutshells/dnscrypt-wrapper [COMMAND] [ARG...] -V\n```\n\n#### Printing command-line options:\n\n``` bash\ndocker container run --rm --read-only nutshells/dnscrypt-wrapper --help\n```\n\nHowever, please be informed that **some** of the options are managed by [the entrypoint script](https://github.com/quchao/nutshells/blob/master/dnscrypt-wrapper/docker-entrypoint.sh) of the container. You will encounter an error while trying to set any of them, just use the [environment variables](#environment-variables) instead; as for other exceptions, just follow the message to get rid of them.\n\n\n## Reference\n\n### Environment Variables\n\n| Name | Default | Relevant Option | Description |\n|:-- |:-- |:-- |:-- |\n| `RESOLVER_IP` | `8.8.8.8` | `-r`, `--resolver-address` | Hostname or IP address of the upstream dns resolver. |\n| `RESOLVER_PORT` | `53` | `-r`, `--resolver-address` | Port number of the upstream dns resolver. |\n| `PROVIDER_BASENAME` | `example.com` | `--provider-name` | Basename of the provider, which forms the whole provide name with a prefix `2.dnscrypt-cert.`. |\n| `CRYPT_KEYS_LIFESPAN` | `365` | `--cert-file-expire-days` | For how long (in days) the crypt key & certs would be valid. Refer to [this topic](#rotating-the-crypt-key-and-certs) to automate the rotation. |\n\nFor instance, if you want to use [OpenDNS](https://www.opendns.com) as the upstream DNS resolver other than [Google's Public DNS](https://developers.google.com/speed/public-dns/), the default one, just [set an environment variable](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e-env-env-file) like this:\n\n```\ndocker container run \\\n -e RESOLVER_IP=208.67.222.222 -e RESOLVER_PORT=5353 \\\n [OTHER_OPTIONS] ...\n```\n\n### Data Volumes\n\n| Path in Container | Description | Mount as Writeable |\n|:-- |:-- |:--:|\n| `/usr/local/etc/dnscrypt-wrapper` | Directory where keys are stored | Y |\n\n\n## Advanced Topics\n\n### Using Docker-compose\n\nSee [the sample file](https://github.com/quchao/nutshells/blob/master/dnscrypt-wrapper/docker-compose.yml).\n\n### Better Performance\n\nIt's a good idea to speed up the high-frequency queries by adding a caching upstream resolver, we choose [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) for its lightweight and configurability. Though there're many other options, such as [unbound](https://www.unbound.net/).\n\nFirstly, let's create a new bridge network named `dnscrypt`:\n\n> Add `--driver overlay` if it's in swarm mode.\n\n``` bash\ndocker network create dnscrypt\n```\n\nSecondly, create a *dnsmasq* container (as an *upstream* resolver) into the network with an increased cache size:\n\n> Refer to [this page](https://hub.docker.com/r/nutshells/dnsmasq-fast-lookup/) for more about the `nutshells/dnsmasq-fast-lookup` image.\n\n``` bash\ndocker container run -d --network=dnscrypt --network-alias=upstream \\\n --name=upstream --restart=unless-stopped --read-only \\\n nutshells/dnsmasq-fast-lookup \\\n --domain-needed --bogus-priv \\\n --server=8.8.8.8 --no-resolv --no-hosts \\\n --cache-size=10240\n```\n\nThen start a *dnscrypt server* into the same network too:\n\n> To add an existing container into the network, use [`docker network connect`](https://docs.docker.com/engine/userguide/networking/#user-defined-networks) please.\n\n``` bash\ndocker container run -d --network=dnscrypt \\\n -p 5353:12345/udp -p 5353:12345/tcp \\\n --name=dnscrypt-server --restart=unless-stopped --read-only \\\n --mount=type=bind,src=,dst=/usr/local/etc/dnscrypt-wrapper \\\n -e RESOLVER_IP=upstream -e RESOLVER_PORT=12345 \\\n nutshells/dnscrypt-wrapper \\\n init\n```\n\nDone!\n\nA [compose file](#using-docker-compose), which helps you to manage both of the containers concurrently, is highly recommended for this situation.\n\nAlternatively, the `--net=host` option provides the best network performance, use it if you know it exactly.\n\n### Backing-up the secret key\n\nIf you forgot to mount `` into the container,\nand now you want to locate the secret key in the anonymous volume,\njust do some inspection first:\n\n``` bash\ndocker container inspect -f '{{json .Mounts }}' dnscrypt-server | grep --color '\"Source\":'\n```\n\nThen backup it securely.\n\n### Rotating the crypt key and certs\n\nUnlike the lifelong provider key pair, a **crypt key** & two certs, which are time-limited and used to encrypt and authenticate DNS queries, will be generated only if they're missing or expiring on starting. Thus the container is supposed to be restarted before certs' expiration.\n\n> Two certs are issued right after the crypt key's generation, one of them uses xchacha20 cipher.\n\nLet's say we're planning to rotate them about once a week.\nFirstly, shrink [the cert's lifespan](#environment-variables) to `7` days:\n\n> Actually the rotation starts when the validity remaining is under `30%`, which would be on day `5` in this case.\n\n```\ndocker container run -e CRYPT_KEYS_LIFESPAN=7 ...\n```\n\nSecondly, restart the container every single day by creating a daily cronjob:\n\n``` bash\n0 4 * * * docker container restart dnscrypt-server\n```\n\n### Gaining a shell access\n\nGet an interactive shell to a **running** container:\n\n``` bash\ndocker container exec -it dnscrypt-server /bin/ash\n```\n\n### Customizing the image\n\n#### By modifying the dockerfile\n\nYou may want to make some modifications to the image.\nPull the source code from GitHub, customize it, then build one by yourself:\n\n``` bash\ngit clone --depth 1 https://github.com/quchao/nutshells.git\ndocker image build -q=false --rm=true --no-cache=true \\\n -t nutshells/dnscrypt-wrapper \\\n -f ./dnscrypt-wrapper/Dockerfile \\\n ./dnscrypt-wrapper\n```\n\n#### By committing the changes on a container\n\nOtherwise just pull the image from the official registry, start a container and [get a shell](#gaining-a-shell-access) to it, [commit the changes](https://docs.docker.com/engine/reference/commandline/commit/) afterwards.\n\n``` bash\ndocker container commit --change \"Commit msg\" dnscrypt-server nutshells/dnscrypt-wrapper\n```\n\n\n## Caveats\n\n## Declaring the Health Status\n\nStatus of this container-specified health check merely indicates whether the crypt certs are *about to expire*, you'd better **restart** the container to [rotate the keys](#rotating-the-crypt-key-and-certs) ASAP if it's shown as *unhealthy*.\n\nTo confirm the status, run this command:\n\n``` bash\ndocker container inspect --format='{{json .State.Health.Status}}' dnscrypt-server\n```\n\nAnd to check the logs:\n\n``` bash\ndocker container inspect --format='{{json .State.Health}}' dnscrypt-server | python -m json.tool\n```\n\nIf you think this is annoying, just add [the `--no-healthcheck` option](https://docs.docker.com/engine/reference/run/#healthcheck) to disable it.\n\n\n## Contributing\n\n[![Github Starts](https://img.shields.io/github/stars/quchao/nutshells.svg?maxAge=3600&style=social&label=Star)](https://github.com/quchao/nutshells/) [![Twitter Followers](https://img.shields.io/twitter/follow/chappell.svg?maxAge=3600&style=social&label=Follow)](https://twitter.com/chappell/)\n\n> Follow GitHub's [*How-to*](https://opensource.guide/how-to-contribute/) guide for the basis.\n\nContributions are always welcome in many ways:\n\n- Give a star to show your fondness;\n- File an [issue](https://github.com/quchao/nutshells/issues) if you have a question or an idea;\n- Fork this repo and submit a [PR](https://github.com/quchao/nutshells/pulls);\n- Improve the documentation.\n\n\n## Todo\n\n- [x] Serve with the old key & certs for another hour after the rotation.\n- [x] Add instructions on how to speed it up by caching the upstream dns queries.\n- [x] Add a `HealthCheck` instruction to indicate the expiration status of certs.\n- [ ] Add a command for checking the expire status.\n- [ ] Use another container to rotate the keys.\n\n\n## Acknowledgments & Licenses\n\nUnless specified, all codes of **Project Nutshells** are released under the [MIT License](https://github.com/quchao/nutshells/blob/master/LICENSE).\n\nOther relevant softwares:\n\n| Ware/Lib | License |\n|:-- |:--:|\n| [Docker](https://www.docker.com/) | [![License](https://img.shields.io/github/license/moby/moby.svg?maxAge=2592000&label=License)](https://github.com/moby/moby/blob/master/LICENSE) |\n| [DNSCrypt-Proxy](https://github.com/jedisct1/dnscrypt-proxy) | [![License](https://img.shields.io/badge/License-ISC_License-blue.svg?maxAge=2592000)](https://github.com/jedisct1/dnscrypt-proxy/blob/master/COPYING) |\n| [DNSCrypt-Wrapper](https://github.com/cofyc/dnscrypt-wrapper/) | [![License](https://img.shields.io/badge/License-ISC_License-blue.svg?maxAge=2592000)](https://github.com/cofyc/dnscrypt-wrapper/blob/master/COPYING) |\n| [DNSCrypt-Server-Docker](https://github.com/jedisct1/dnscrypt-server-docker/) | [![License](https://img.shields.io/github/license/jedisct1/dnscrypt-server-docker.svg?maxAge=2592000&label=License)](https://github.com/jedisct1/dnscrypt-server-docker/blob/master/LICENSE) |\n","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":22,"_83":11,"_84":11},"read","write","admin","user","storage_size",77475412,"orgData",{"_90":91,"_92":93,"_94":95,"_96":33,"_97":98,"_99":100,"_101":102,"_103":104,"_105":106,"_107":108,"_109":102,"_110":102,"_111":22},"id","81c96d265b874d799b945016eb3f30ca","uuid","81c96d26-5b87-4d79-9b94-5016eb3f30ca","type","organization","orgname","full_name","Team Nutshells","location","San Junipero","company","","profile_url","https://quchao.com/entry/project-nutshells","date_joined","2017-07-11T07:18:51.565591Z","gravatar_url","https://www.gravatar.com/avatar/b97dcfceccc5ff37a71268e3ffb45c5e?s=80&r=g&d=mm","gravatar_email","badge","is_active","recentTags",[114],{"_115":44,"_116":117,"_118":119,"_90":120,"_121":122,"_50":139,"_140":117,"_141":33,"_142":56,"_57":143,"_144":145,"_146":130,"_147":139,"_148":66,"_149":22},"content_type","creator",1928237,"full_size",4082253,13753722,"images",[123],{"_124":125,"_126":127,"_128":102,"_129":130,"_131":132,"_133":134,"_135":102,"_136":-5,"_137":119,"_63":66,"_138":-5},"architecture","amd64","digest","sha256:f0cccf074312f69fbef1e59674ba907c7c4b8f7ea4c54151211ecc051b94db89","features","last_pulled","2026-10-29T09:32:55.311955974Z","last_pushed","2020-01-28T09:16:57Z","os","linux","os_features","os_version","size","variant","2020-01-28T09:16:57.066795Z","last_updater","last_updater_username","media_type","latest","repository",1712141,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxRunInCloud","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":164,"_171":172,"_158":181,"_182":11},{"_40":165,"_42":166,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":167,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":168,"_79":22,"_80":170,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":169},[78],{"_82":22,"_83":11,"_84":11},"tags",{"_173":64,"_174":-5,"_175":-5,"_176":177},"count","next","previous","results",[178],{"_115":44,"_116":117,"_118":119,"_90":120,"_121":179,"_50":139,"_140":117,"_141":33,"_142":56,"_57":143,"_144":145,"_146":130,"_147":139,"_148":66,"_149":22},[180],{"_124":125,"_126":127,"_128":102,"_129":130,"_131":132,"_133":134,"_135":102,"_136":-5,"_137":119,"_63":66,"_138":-5},[],"canDeleteTags","actionData","errors"]

nutshells/dnscrypt-wrapper

Tags for nutshells/dnscrypt-wrapper