{"id":15130614,"url":"https://github.com/net-dev-id/dns-wrapper","last_synced_at":"2026-01-21T22:32:55.684Z","repository":{"id":256077783,"uuid":"853880237","full_name":"net-dev-id/dns-wrapper","owner":"net-dev-id","description":"A DNS wrapper service","archived":false,"fork":false,"pushed_at":"2024-09-29T14:34:35.000Z","size":1352,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-19T15:12:49.479Z","etag":null,"topics":["boost","c","cpp","dns","linux","networking","unix","windows"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/net-dev-id.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,"zenodo":null}},"created_at":"2024-09-07T19:41:33.000Z","updated_at":"2024-09-29T14:13:06.000Z","dependencies_parsed_at":"2024-10-09T17:00:53.104Z","dependency_job_id":"a15cb825-a1b3-4fed-8bc5-292cf84e2cfb","html_url":"https://github.com/net-dev-id/dns-wrapper","commit_stats":null,"previous_names":["net-dev-id/dns-wrapper"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/net-dev-id/dns-wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-dev-id%2Fdns-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-dev-id%2Fdns-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-dev-id%2Fdns-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-dev-id%2Fdns-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/net-dev-id","download_url":"https://codeload.github.com/net-dev-id/dns-wrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-dev-id%2Fdns-wrapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28645549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T21:29:11.980Z","status":"ssl_error","status_checked_at":"2026-01-21T21:24:31.872Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["boost","c","cpp","dns","linux","networking","unix","windows"],"created_at":"2024-09-26T03:03:01.169Z","updated_at":"2026-01-21T22:32:55.670Z","avatar_url":"https://github.com/net-dev-id.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n[![LinkedIn][linkedin-shield]][linkedin-url]\n\n# DNS Wrapper Service\n\nDNS Wrapper Service is a versatile tool that enhances DNS functionality by wrapping and forwarding requests based on customized rules. It can seamlessly serve as a recursive DNS Server for specific clients or as a redirector for other clients. By matching incoming DNS requests against tailored configurations, it intelligently redirects queries to external DNS or designated hosts. With DNS Wrapper Service, users can effectively manage and optimize DNS traffic flow, ensuring efficient and secure connections.\n\n## Overall functionality\n\n![Flow Diagram](http://www.plantuml.com/plantuml/png/dL7HJi8m57tlLzn7U5aO8b4mIYAQy688ll9IsxkjiMjdUmVkxxsRGuYye5coDhtdd9npxYAI35INLeZk9iHivPGlZSjX-V8A0JzgZ0HPy2KeQz3Hrl57cGyGPGDtkVUvnOGvztEnBun56BH3bAg0K5iS2W2JmU2nOyDg3JnzeWA3GmAfTS0OeMGuHiZD3br7UnW2OnmC6eojH2_YNMRoEg06gSXuTq2nsMyKmEpPXxqC-iSyUS1Fmk2aRKFD3xWDniex3MzIlJEepmTxGyNMKL572AYG7Uc-YyesRVekNf8dSCpEm-Zj3YCJFQIJSJA-7YNfBP-ZASW85OQjEtU1Dd9V6zGceABXHSxKiOF2Hxh8qGcdDPLERv8qcLpr9fmsMNUBv2jnUE1_jqyXskQNcCdQqgdIsbkZcbyRkAJzVpK_5-Tb_Qae5kXoYGMVTMc_0000)\n\n## Flow daigram\n\n![Flow Diagram](https://www.plantuml.com/plantuml/png/bLInRjmw4Epr5GkuELSk7buZ5N6Gn4408qNSfk4THn8HYdlPfUxiV7r0KRBEL8muAYpvoDcT6GxtLgEHE0w-ggQlgghldKO4Sk70WmiT2NwEq4WSwCWIwV__QCT21mwjwqQ1dNw-RghAjRJxKi2-XrPu84C7xn3YkskAFGBjdg3N5L7z6P7mw3HUjX8SM2orB6atgHb0FMkywOtsJKKqTTAqA22dhrKeccNSft9lRvIY6s29nvLWu0p9804dHfQX53XXJY24A4ypIwUlA5nhV1s7FOIuNJfhBhC70WtcCHCe--UdVc_jt82KHpc0N6YP8izIculD6ldu_2-yeY23O5rRhSk9tD4SVc3o8lCH764YB4LcKkRmPrsrvuxEHa8oT82gwT1SbCuwIc85XoiM4phK3mYM1EseI6yzSb1Gv5buKnLLDjBgRnZu13BUpoxfT3nBF0glwZi1jeihlL93CiejiJDbNDLp97CopfkznpP89Tm4Jf_RyCRU_3sLHFKzTmGHbjBvVxMqE9hIriMfzLgkp1RIJNckPPcyiBxh3m8JGG7dkV3DgA1M0BiUnHk2dwT8WApLietEFi-BS-yyQ3TbmHnw6eyQ1MOWXPmWcU6LTrqVEm52VSToDcBN8-4Lyp1XjCbYfj9L4bkCl-nrddzbmxUDmHVppraomMx7uFCCDBCXPUsj-iN7Y85Sc65vw-B2tezBU3QXeL4JoulJaC54nw6XvM9PU4IyQ9HiAAzOzcv2VCo8l24fdP90PhfLJN4JNvyxELtvRpLbkhf5iEFWVwNdDm00)\n\n# Building\n\nThis project uses cmake. So it should be possible to build this on any system with properly configured CMake and C++ compiler.\n\n## Dependencies\n\n[Boost](https://www.boost.org/) libraries. Specifically following component libraries from boost are used: system, program_options, log, thread, log_setup.\n\n## Linux/UNIX\n\nOn Linux following are the build steps:\n1. Configure build: `cmake -DCMAKE_BUILD_TYPE=Debug -S. -Bbuild`\n2. Build the project: `make -C build`\n\nThis will create an executable at the following location: `build/dns-wrapper`\n\n## Windows\n\nThe project can be imported in MS Visual Studio as a CMake project. Visual Studio support building, executing and debugging this project.\n\nThis will create executable at the following location: `out\\build\\x64-Debug\\dns-wrapper.exe`\n\nOtherwise cmake along with cl compiler can be used to build it on windows. Specifically the following are the build steps:\n\n1. Configure build: \n   ```\n     cmake -Bbuild -S. \n        -DCMAKE_CXX_COMPILER=cl\n        -DCMAKE_C_COMPILER=cl\n        -DCMAKE_BUILD_TYPE:STRING=\"Debug\"\n   ```\n2. Build the project:`cmake --build build`\n\n# Configuration\n\n`dns-wrapper` supports the following configuraion:\n\n| Option | Type | Default | Required | Description |\n| -- | -- | -- | -- | -- |\n| logToConsoleAlso | bool | true | No | Confiures service to log to screen along with logging to file. |\n| logFile | string | /var/log/dns-wrapper.log (UNIX) | No | Log file to use. |\n| | | c:\\temp\\dns-wrapper.log | | |\n| logLevel | string | info | No | Log level (one of the following: trace, debug, info, warning, error, fatal. |\n| dnsPort | number | 53 | No | DNS port to use. |\n| ruleFile | string | /etc/dns-wrapper/rules.txt | No | Rule configuration file. |\n| | | c:\\temp\\rules.txt | | |\n| pidFile | string | /var/run/dns-wrapper.pid | No | PID file (only applicable on UNIX). |\n| serverIp1 | string | 1.1.1.1 | No | Primary DNS Server |\n| serverPort1 | number | 53 | No | DNS port to be used for Primary DNS Server. |\n| protocol1 | string | udp | No | Protocol for primary DNS server (one of the following: udp, tcp). |\n| serverIp2 | string | | No | Additional DNS Server |\n| serverPort2 | number | 53 | No | DNS port to be used for additional DNS Server. |\n| protocol2 | string | udp | No | Protocol for additional DNS server (one of the following: udp, tcp). |\n| serverIp3 | string | | No | Additional DNS Server |\n| serverPort3 | number | 53 | No | DNS port to be used for additional DNS Server. |\n| protocol3 | string | udp | No | Protocol for additional DNS server (one of the following: udp, tcp). |\n\nAll configuration options should be present under section `main`.\n\n## Configuration on UNIX\n\nOn UNIX the default location for configuration file is: `/etc/dnswrapper/config.ini`. Command line option `--config` can be specified to configure alternate location.\n\n## Configuration on Windows\n\nOn Windows configuration can be done using either configuration file specified using command line option `--config` or using Windows registry. If command line option is not specified configuration is read from Windows Registry `HKEY_LOCAL_MACHINE\\SOFTWARE\\NetDevId\\DnsWrapper\\main`.\n\n# Running Service\n\nDns Wrapper Service is can be executed as long running command line utility (on both UNIX and Windows) or as UNIX Daemon or as a Windows Svc Service.\nTo run it as UNIX daemon or Windows Svc Service command line option `--daemon` needs to be specified.\n\n## Command line execution\nTo run as command line execute: `./build/dns-wrapper --config-file config/config.ini`\n\n## Running as UNIX daemon\nTo run as UNIX daemon execute the command: `./build/dns-wrapper --config-file config/config.ini --daemon`\n\n## Running as Windows Svc Service\n### Creating Windows Service\nTo create service execute as (ADMIN user): `sc create dns-wrapper-service DisplayName= \"Dns Wrapper Service\" binPath= \"\u003cpath\u003e\\dns-wrapper.exe --daemon\"`\n### Execute the service\n\nOnce service is created as per previous step, start Windows services (services.msc) and click on start for `DNS Wrapper Service`.\n\n![Screenshot](doc/screenshots/WindowsServiceScreenshot.png \"Screenshot\")\n\n# Running Service and configuring rules\n\n## Starting the daemon service\nStarting the daemon service: \n![Screenshot](doc/screenshots/001.png \"Starting service\")\n\n## Help about command line options\nHelp regarding options can be accessed using --help command line option:\n\n![Screenshot](doc/screenshots/002.png \"--help\")\n\n![Screenshot](doc/screenshots/002a.png \"rules --help\")\n\n![Screenshot](doc/screenshots/002b.png \"rules add --help\")\n\n## Listing configured rules and actions\n\n![Screenshot](doc/screenshots/003.png)\n\n## Clearing configured rules and actions\n\n![Screenshot](doc/screenshots/004.png)\n\nAs you can see policy action remains unchanged. There has to be a policy action configured always. You can change it but not delete it altogether\n\n## Dig command with policy set to redirect with no rules\n\n![Screenshot](doc/screenshots/005.png)\n\nSince there is no rule configured, DNS resolution happens using the configured default policy. For the record configured default policy has target set to 0.0.0.0. It can very well be any other IP address.\n\n## Dig command with rule set to dns for specific IP address\n\nLets first set a rule as follows:\n\n![Screenshot](doc/screenshots/006.png)\n\nThe corresponding dig command output is as follows:\n\n![Screenshot](doc/screenshots/007.png)\n\nNote the above dig command was executed from IP address 192.168.1.13. Since the rule is set to DNS the DNS query is resolved using the configured DNS.\n\n## Lets delete the rule created above run dig command again\n\n![Screenshot](doc/screenshots/008.png)\n\n![Screenshot](doc/screenshots/009.png)\n\n## Dig command with rule set to a specific MAC address\n\n![Screenshot](doc/screenshots/010.png)\n\n![Screenshot](doc/screenshots/011.png)\n\nIn this case if DNS query comes from the machine with the above MAC address, it is resolved using configured DNS. For DNS query coming from any other client, the default policy kicks in.\n\n## Dig command with rule set to a specific IP and MAC address\n\n![Screenshot](doc/screenshots/012.png)\n\n![Screenshot](doc/screenshots/013.png)\n\nBoth IP address and MAC address must match from that of incoming DNS query for rule to come into effect.\n\n## You can configure as many rules as you want (within an upper bound as defined in code)\n\n![Screenshot](doc/screenshots/014.png)\n\n## Saving rules and policy to a file\n\n![Screenshot](doc/screenshots/015.png)\n\nThese saved rules and policy can be loaded at any time using the load subcommand. Further the corresponding config file parameter can be configured to load rules at service startup.\n\n# Testing Service\n\n## UNIX\n\nOn UNIX execute the command: `dig +retry=0 @127.0.0.1 +noedns google.com`\n\n```bash\n; \u003c\u003c\u003e\u003e DiG 9.20.1 \u003c\u003c\u003e\u003e +retry -p 10053 @127.0.0.1 +noedns google.com\n; (1 server found)\n;; global options: +cmd\n;; Got answer:\n;; -\u003e\u003eHEADER\u003c\u003c- opcode: QUERY, status: NOERROR, id: 44976\n;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0\n\n;; QUESTION SECTION:\n;google.com.\t\t\tIN\tA\n\n;; ANSWER SECTION:\ngoogle.com.\t\t300\tIN\tA\t142.250.194.46\n\n;; Query time: 100 msec\n;; SERVER: 127.0.0.1#10053(127.0.0.1) (UDP)\n;; WHEN: Wed Sep 11 18:15:26 IST 2024\n;; MSG SIZE  rcvd: 54\n```\n\n## Windows\n\nOn Powershell execute the command: `Resolve-DnsName -Name google.com -server localhost`\n```bash\nName                                           Type   TTL   Section    IPAddress\n----                                           ----   ---   -------    ---------\ngoogle.com                                     A      275   Answer     142.250.194.46\n```\n\n# Future/Planned features\n\n1. Macaddress based rule matching is not implemented on Windows.\n2. Conflicts, and inconsistencies between rules, actions and policies are not validated. Duplicate rules or inconsistent rules will lead to undesirable results.\n3. TCP Support\n4. Rule can include query domain.\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/net-dev-id/dns-wrapper.svg?style=for-the-badge\n[contributors-url]: https://github.com/net-dev-id/dns-wrapper/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/net-dev-id/dns-wrapper.svg?style=for-the-badge\n[forks-url]: https://github.com/net-dev-id/dns-wrapper/network/members\n[stars-shield]: https://img.shields.io/github/stars/net-dev-id/dns-wrapper.svg?style=for-the-badge\n[stars-url]: https://github.com/net-dev-id/dns-wrapper/stargazers\n[issues-shield]: https://img.shields.io/github/issues/net-dev-id/dns-wrapper.svg?style=for-the-badge\n[issues-url]: https://github.com/net-dev-id/dns-wrapper/issues\n[license-shield]: https://img.shields.io/github/license/net-dev-id/dns-wrapper.svg?style=for-the-badge\n[license-url]: https://github.com/net-dev-id/dns-wrapper/blob/master/LICENSE\n[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge\u0026logo=linkedin\u0026colorB=555\n[linkedin-url]: https://linkedin.com/in/neeraj-jakhar-39686212b\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnet-dev-id%2Fdns-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnet-dev-id%2Fdns-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnet-dev-id%2Fdns-wrapper/lists"}