{"id":13511661,"url":"https://github.com/shadowsocks/overture","last_synced_at":"2025-09-27T05:31:33.410Z","repository":{"id":57482243,"uuid":"87497032","full_name":"shadowsocks/overture","owner":"shadowsocks","description":"A DNS server/dispatcher written in Go.","archived":false,"fork":true,"pushed_at":"2019-01-17T22:54:14.000Z","size":220,"stargazers_count":54,"open_issues_count":0,"forks_count":41,"subscribers_count":16,"default_branch":"shadowsocks","last_synced_at":"2024-12-08T00:59:58.682Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"shawn1m/overture","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shadowsocks.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":"2017-04-07T02:43:36.000Z","updated_at":"2024-10-17T10:16:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shadowsocks/overture","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowsocks%2Foverture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowsocks%2Foverture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowsocks%2Foverture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowsocks%2Foverture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shadowsocks","download_url":"https://codeload.github.com/shadowsocks/overture/tar.gz/refs/heads/shadowsocks","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234391381,"owners_count":18824810,"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":[],"created_at":"2024-08-01T03:01:04.331Z","updated_at":"2025-09-27T05:31:33.021Z","avatar_url":"https://github.com/shadowsocks.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# overture\n[![Build Status](https://travis-ci.org/shawn1m/overture.svg)](https://travis-ci.org/shawn1m/overture)\n[![GoDoc](https://godoc.org/github.com/shawn1m/overture?status.svg)](https://godoc.org/github.com/shawn1m/overture)\n[![Go Report Card](https://goreportcard.com/badge/github.com/shawn1m/overture)](https://goreportcard.com/report/github.com/shawn1m/overture)\n\nOverture is a DNS server/forwarder/dispatcher written in Go.\n\nOverture means an orchestral piece at the beginning of a classical music composition, just like DNS which is nearly the\nfirst step of surfing the Internet.\n\n**Please note: If you are using the binary releases, please follow the instructions in the README file with\ncorresponding git version tag. The README in master branch are subject to change and does not always reflect the correct\n instructions to your binary release version.**\n\n## Features\n\n+ Full IPv6 support\n+ Multiple DNS upstream\n    + Via UDP/TCP with custom port\n    + Via SOCKS5 proxy (TCP only)\n    + With EDNS Client Subnet (ECS) [RFC7871](https://tools.ietf.org/html/rfc7871)\n+ Dispatcher\n    + IPv6 record (AAAA) redirection\n    + Custom domain\n    + Custom IP network\n+ Minimum TTL modification\n+ Hosts (Random order if there are multiple answers)\n+ Cache with ECS\n\n### Dispatch process\n\nOverture can force custom domain DNS queries to use selected DNS when applicable.\n\nFor custom IP network, overture will query the domain with primary DNS firstly. If the answer is empty or the IP\nis not matched then overture will finally use the alternative DNS servers.\n\n## Installation\n\nYou can download binary releases from the [release](https://github.com/shawn1m/overture/releases).\n\nFor ArchLinux users, package `overture` is available in AUR. If you use a AUR helper i.e. `yaourt`, you can simply run:\n\n    yaourt -S overture\n\n## Usages\n\nStart with the default config file -\u003e ./config.json\n\n    $ ./overture\n\nOr use your own config file:\n\n    $ ./overture -c /path/to/config.json\n\nVerbose mode:\n\n    $ ./overture -v\n\nLog to file:\n\n    $ ./overture -l /path/to/overture.log\n\nFor other options, please see help:\n\n    $ ./overture -h\n\nTips:\n\n+ Root privilege is required if you are listening on port 53.\n+ For Windows users, you can run overture on command prompt instead of double click.\n\n###  Configuration Syntax\n\nConfiguration file is \"config.json\" by default:\n\n```json\n{\n  \"BindAddress\": \":53\",\n  \"HTTPAddress\": \":5555\",\n  \"PrimaryDNS\": [\n    {\n      \"Name\": \"DNSPod\",\n      \"Address\": \"119.29.29.29:53\",\n      \"Protocol\": \"udp\",\n      \"SOCKS5Address\": \"\",\n      \"Timeout\": 6,\n      \"EDNSClientSubnet\": {\n        \"Policy\": \"disable\",\n        \"ExternalIP\": \"\",\n        \"NoCookie\": true\n      }\n    }\n  ],\n  \"AlternativeDNS\": [\n    {\n      \"Name\": \"OpenDNS\",\n      \"Address\": \"208.67.222.222:443\",\n      \"Protocol\": \"tcp\",\n      \"SOCKS5Address\": \"\",\n      \"Timeout\": 6,\n      \"EDNSClientSubnet\": {\n        \"Policy\": \"disable\",\n        \"ExternalIP\": \"\",\n        \"NoCookie\": true\n      }\n    }\n  ],\n  \"OnlyPrimaryDNS\": false,\n  \"IPv6UseAlternativeDNS\": false,\n  \"IPNetworkFile\": {\n    \"Primary\": \"./ip_network_primary_sample\",\n    \"Alternative\": \"./ip_network_alternative_sample\"\n  },\n  \"DomainFile\": {\n    \"Primary\": \"./domain_primary_sample\",\n    \"Alternative\": \"./domain_alternative_sample\"\n  },\n  \"HostsFile\": \"./hosts_sample\",\n  \"MinimumTTL\": 0,\n  \"CacheSize\" : 0,\n  \"RejectQtype\": [255]\n}\n```\n\nTips:\n\n+ BindAddress: Specifying only port (e.g. `:53`) will have overture listen on all available addresses (both IPv4 and\nIPv6). Overture will handle both TCP and UDP requests. Literal IPv6 addresses are enclosed in square brackets (e.g. `[2001:4860:4860::8888]:53`)\n+ HTTPAddress: Specifying an HTTP port for debugging, currently used to dump DNS cache, and the request url is `/cache`, available query argument is `nobody`(boolean)\n\n    * true(default): only get the cache size;\n\n        ```bash\n        $ curl 127.0.0.1:5555/cache | jq\n        {\n          \"length\": 1,\n          \"capacity\": 100,\n          \"body\": {}\n        }\n        ```\n\n    * false: get cache size along with cache detail.\n\n        ```bash\n        $ curl 127.0.0.1:5555/cache?nobody=false | jq\n        {\n          \"length\": 1,\n          \"capacity\": 100,\n          \"body\": {\n            \"www.baidu.com. 1\": [\n              {\n                \"name\": \"www.baidu.com.\",\n                \"ttl\": 1140,\n                \"type\": \"CNAME\",\n                \"rdata\": \"www.a.shifen.com.\"\n              },\n              {\n                \"name\": \"www.a.shifen.com.\",\n                \"ttl\": 300,\n                \"type\": \"CNAME\",\n                \"rdata\": \"www.wshifen.com.\"\n              },\n              {\n                \"name\": \"www.wshifen.com.\",\n                \"ttl\": 300,\n                \"type\": \"A\",\n                \"rdata\": \"104.193.88.123\"\n              },\n              {\n                \"name\": \"www.wshifen.com.\",\n                \"ttl\": 300,\n                \"type\": \"A\",\n                \"rdata\": \"104.193.88.77\"\n              }\n            ]\n          }\n        }\n        ```\n\n+ DNS: You can specify multiple DNS upstream servers here.\n    + Name: This field is only used for logging.\n    + Address: Same as BindAddress.\n    + Protocol: `tcp`, `udp` or `tcp-tls`\n        + `tcp-tls`: Address format is \"servername:port@serverAddress\", try one.one.one.one:853 or one.one.one.one:853@1.1.1.1\n    + SOCKS5Address: Forward dns query to this SOCKS5 proxy, `“”` to disable.\n    + EDNSClientSubnet: Used to improve DNS accuracy. Please check [RFC7871](https://tools.ietf.org/html/rfc7871) for\n    details.\n        + Policy\n            + `auto`: If client IP is not in the reserved IP network, use client IP. Otherwise, use external IP.\n            + `manual`: Use external IP if this field is not empty, otherwise use client IP if it is not reserved IP.\n            + `disable`: Disable this feature.\n        + ExternalIP: If this field is empty, ECS will be disabled when the inbound IP is not an external IP.\n        + NoCookie: Disable cookie.\n+ OnlyPrimaryDNS: Disable dispatcher feature, use primary DNS only.\n+ IPv6UseAlternativeDNS: Redirect IPv6 DNS queries to alternative DNS servers.\n+ File: Absolute path like `/path/to/file` is allowed. For Windows users, please use properly escaped path like\n  `C:\\\\path\\\\to\\\\file.txt` in the configuration.\n+ MinimumTTL: Set the minimum TTL value (in seconds) in order to improve caching efficiency, use `0` to disable.\n+ CacheSize: The number of query record to cache, use `0` to disable.\n+ RejectQtype: Reject inbound query with specific DNS record types, check [List of DNS record types](https://en.wikipedia.org/wiki/List_of_DNS_record_types) for details.\n\n#### Domain file example (Suffix match)\n\n    example.com\n    xxx.xx\n\n#### IP network file example\n\n    1.0.1.0/24\n    10.8.0.0/16\n    ::1/128\n\n#### Hosts file example\n\n    127.0.0.1 localhost\n    ::1 localhost\n    10.8.0.1 example.com\n\n#### DNS servers with ECS support\n\n+ DNSPod 119.29.29.29:53\n\n**For DNSPod, ECS only works via udp, you can test it by [patched dig](https://www.gsic.uva.es/~jnisigl/dig-edns-client-subnet.html)**\n\nYou can compare the response IP with the client IP to test the feature. The accuracy depends on the server side.\n\n```\n$ dig @119.29.29.29 www.qq.com +client=119.29.29.29\n\n; \u003c\u003c\u003e\u003e DiG 9.9.3 \u003c\u003c\u003e\u003e @119.29.29.29 www.qq.com +client=119.29.29.29\n; (1 server found)\n;; global options: +cmd\n;; Got answer:\n;; -\u003e\u003eHEADER\u003c\u003c- opcode: QUERY, status: NOERROR, id: 64995\n;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1\n\n;; OPT PSEUDOSECTION:\n; EDNS: version: 0, flags:; udp: 4096\n; CLIENT-SUBNET: 119.29.29.29/32/24\n;; QUESTION SECTION:\n;www.qq.com.            IN  A\n\n;; ANSWER SECTION:\nwww.qq.com.     300 IN  A   101.226.103.106\n\n;; Query time: 52 msec\n;; SERVER: 119.29.29.29#53(119.29.29.29)\n;; WHEN: Wed Mar 08 18:00:52 CST 2017\n;; MSG SIZE  rcvd: 67\n```\n\n```\n$ dig @119.29.29.29 www.qq.com +client=119.29.29.29 +tcp\n\n; \u003c\u003c\u003e\u003e DiG 9.9.3 \u003c\u003c\u003e\u003e @119.29.29.29 www.qq.com +client=119.29.29.29 +tcp\n; (1 server found)\n;; global options: +cmd\n;; Got answer:\n;; -\u003e\u003eHEADER\u003c\u003c- opcode: QUERY, status: NOERROR, id: 58331\n;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1\n\n;; OPT PSEUDOSECTION:\n; EDNS: version: 0, flags:; udp: 4096\n;; QUESTION SECTION:\n;www.qq.com.            IN  A\n\n;; ANSWER SECTION:\nwww.qq.com.     43  IN  A   59.37.96.63\nwww.qq.com.     43  IN  A   14.17.32.211\nwww.qq.com.     43  IN  A   14.17.42.40\n\n;; Query time: 81 msec\n;; SERVER: 119.29.29.29#53(119.29.29.29)\n;; WHEN: Wed Mar 08 18:01:32 CST 2017\n;; MSG SIZE  rcvd: 87\n```\n\n## Acknowledgements\n\n+ Dependencies:\n    + [dns](https://github.com/miekg/dns): BSD-3-Clause\n    + [logrus](https://github.com/sirupsen/logrus): MIT\n+ Code reference:\n    + [skydns](https://github.com/skynetservices/skydns): MIT\n    + [go-dnsmasq](https://github.com/janeczku/go-dnsmasq):  MIT\n+ Contributors: @V-E-O, @sh1r0, @maddie, @hexchain, @everfly, @simonsmh, @jemyzhang, @hexchain, @sh1r0, @yujinqiu, @qyb\n\n## License\n\nThis project is under the MIT license. See the [LICENSE](LICENSE) file for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowsocks%2Foverture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshadowsocks%2Foverture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowsocks%2Foverture/lists"}