{"id":15440903,"url":"https://github.com/samuelcolvin/dnserver","last_synced_at":"2025-04-05T10:08:57.544Z","repository":{"id":59397247,"uuid":"83229463","full_name":"samuelcolvin/dnserver","owner":"samuelcolvin","description":"Simple development DNS server written in python","archived":false,"fork":false,"pushed_at":"2024-04-04T13:10:19.000Z","size":49,"stargazers_count":159,"open_issues_count":7,"forks_count":62,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T10:43:27.886Z","etag":null,"topics":["dns","dns-server","python","python3","testing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/dnserver/","language":"Python","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/samuelcolvin.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":"2017-02-26T18:04:39.000Z","updated_at":"2025-01-20T09:25:10.000Z","dependencies_parsed_at":"2024-10-30T20:07:55.329Z","dependency_job_id":"5a08b4db-c5ee-4e36-a099-b72c31c6aee4","html_url":"https://github.com/samuelcolvin/dnserver","commit_stats":{"total_commits":29,"total_committers":3,"mean_commits":9.666666666666666,"dds":"0.48275862068965514","last_synced_commit":"a99dfe946103a3b45b9bf627902177fed97a41aa"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelcolvin%2Fdnserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelcolvin%2Fdnserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelcolvin%2Fdnserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelcolvin%2Fdnserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samuelcolvin","download_url":"https://codeload.github.com/samuelcolvin/dnserver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247318745,"owners_count":20919484,"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","python","python3","testing"],"created_at":"2024-10-01T19:15:47.419Z","updated_at":"2025-04-05T10:08:57.529Z","avatar_url":"https://github.com/samuelcolvin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dnserver\n\n[![CI](https://github.com/samuelcolvin/dnserver/workflows/CI/badge.svg?event=push)](https://github.com/samuelcolvin/dnserver/actions?query=event%3Apush+branch%3Amain+workflow%3ACI)\n[![Coverage](https://codecov.io/gh/samuelcolvin/dnserver/branch/main/graph/badge.svg)](https://codecov.io/gh/samuelcolvin/dnserver)\n[![pypi](https://img.shields.io/pypi/v/dnserver.svg)](https://pypi.python.org/pypi/dnserver)\n[![docker](https://img.shields.io/docker/image-size/samuelcolvin/dnserver?sort=date)](https://hub.docker.com/r/samuelcolvin/dnserver/)\n[![versions](https://img.shields.io/pypi/pyversions/dnserver.svg)](https://github.com/samuelcolvin/dnserver)\n[![license](https://img.shields.io/github/license/samuelcolvin/dnserver.svg)](https://github.com/samuelcolvin/dnserver/blob/main/LICENSE)\n\nSimple DNS server written in python for use in development and testing.\n\nThe DNS serves its own records, if none are found it proxies the request to an upstream DNS server\neg. CloudFlare at [`1.1.1.1`](https://www.cloudflare.com/learning/dns/what-is-1.1.1.1/).\n\nYou can set up records you want to serve with a custom `zones.toml` file,\nsee [example_zones.toml](https://github.com/samuelcolvin/dnserver/blob/main/example_zones.toml) an example.\n\n## Installation from PyPI\n\nInstall with:\n\n```bash\npip install dnserver\n```\n\nUsage:\n\n```bash\ndnserver --help\n```\n\n(or `python -m dnserver --help`)\n\nFor example, to serve a file called `my_zones.toml` file on port `5053`, run:\n\n```bash\ndnserver --port 5053 my_zones.toml\n```\n\n## Usage with Python\n\n```python\nfrom dnserver import DNSServer\n\nserver = DNSServer.from_toml('example_zones.toml', port=5053)\nserver.start()\nassert server.is_running\n\n# now you can do some requests with your favorite dns library\n\nserver.stop()\n```\n\n## Usage with Docker\n\nTo use with docker:\n\n```bash\ndocker run -p 5053:53/udp -p 5053:53/tcp --rm samuelcolvin/dnserver\n```\n\n(See [dnserver on hub.docker.com](https://hub.docker.com/r/samuelcolvin/dnserver/))\n\nOr with a custom zone file:\n\n```bash\ndocker run -p 5053:53/udp -v `pwd`/zones.toml:/zones/zones.toml --rm samuelcolvin/dnserver\n```\n\n(assuming you have your zone records at `./zones.toml`,\nTCP isn't required to use `dig`, hence why it's omitted in this case.)\n\nYou can then test (either of the above) with\n\n```shell\n~ ➤  dig @localhost -p 5053 example.com MX\n...\n;; ANSWER SECTION:\nexample.com.\t\t300\tIN\tMX\t5 whatever.com.\nexample.com.\t\t300\tIN\tMX\t10 mx2.whatever.com.\nexample.com.\t\t300\tIN\tMX\t20 mx3.whatever.com.\n\n;; Query time: 2 msec\n;; SERVER: 127.0.0.1#5053(127.0.0.1)\n;; WHEN: Sun Feb 26 18:14:52 GMT 2017\n;; MSG SIZE  rcvd: 94\n\n~ ➤  dig @localhost -p 5053 tutorcruncher.com MX\n...\n;; ANSWER SECTION:\ntutorcruncher.com.\t299\tIN\tMX\t10 aspmx2.googlemail.com.\ntutorcruncher.com.\t299\tIN\tMX\t5 alt1.aspmx.l.google.com.\ntutorcruncher.com.\t299\tIN\tMX\t5 alt2.aspmx.l.google.com.\ntutorcruncher.com.\t299\tIN\tMX\t1 aspmx.l.google.com.\ntutorcruncher.com.\t299\tIN\tMX\t10 aspmx3.googlemail.com.\n\n;; Query time: 39 msec\n;; SERVER: 127.0.0.1#5053(127.0.0.1)\n;; WHEN: Sun Feb 26 18:14:48 GMT 2017\n;; MSG SIZE  rcvd: 176\n```\n\nYou can see that the first query took 2ms and returned results from `example_zones.toml`,\nthe second query took 39ms as dnserver didn't have any records for the domain so had to proxy the query to\nthe upstream DNS server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelcolvin%2Fdnserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelcolvin%2Fdnserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelcolvin%2Fdnserver/lists"}