{"id":15148427,"url":"https://github.com/luckyturtledev/crab-hole","last_synced_at":"2025-04-05T13:02:18.783Z","repository":{"id":154841619,"uuid":"629112652","full_name":"LuckyTurtleDev/crab-hole","owner":"LuckyTurtleDev","description":"🦀 Pi-Hole clone written in rust using hickory-dns/trust-dns","archived":false,"fork":false,"pushed_at":"2025-01-11T09:04:07.000Z","size":96311,"stargazers_count":52,"open_issues_count":16,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-05T13:02:04.445Z","etag":null,"topics":["dns","dns-over-https","dns-over-quic","dns-over-tls","dns-server","pihole","trust-dns"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LuckyTurtleDev.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":"2023-04-17T16:38:19.000Z","updated_at":"2025-03-17T22:21:47.000Z","dependencies_parsed_at":"2025-02-26T18:11:31.850Z","dependency_job_id":"b0dfa9c8-85fd-4628-b199-308fc28386f4","html_url":"https://github.com/LuckyTurtleDev/crab-hole","commit_stats":{"total_commits":107,"total_committers":4,"mean_commits":26.75,"dds":"0.22429906542056077","last_synced_commit":"90a20205dbb156e479425dac0135b4c84f27cfb6"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuckyTurtleDev%2Fcrab-hole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuckyTurtleDev%2Fcrab-hole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuckyTurtleDev%2Fcrab-hole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuckyTurtleDev%2Fcrab-hole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LuckyTurtleDev","download_url":"https://codeload.github.com/LuckyTurtleDev/crab-hole/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339148,"owners_count":20923013,"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-over-https","dns-over-quic","dns-over-tls","dns-server","pihole","trust-dns"],"created_at":"2024-09-26T13:03:45.242Z","updated_at":"2025-04-05T13:02:18.765Z","avatar_url":"https://github.com/LuckyTurtleDev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦀 crab-hole\n![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue)\n[![crab-hole on crates.io](https://img.shields.io/crates/v/crab-hole)](https://crates.io/crates/crab-hole)\n[![Source Code Repository](https://img.shields.io/badge/Code-On%20GitHub-blue?logo=GitHub)](https://github.com/LuckyTurtleDev/crab-hole)\n[![Packaging status](https://repology.org/badge/tiny-repos/crab-hole.svg)](https://repology.org/project/crab-hole/versions) \n[![AUR package](https://repology.org/badge/version-for-repo/aur/crab-hole.svg)](https://aur.archlinux.org/packages/crab-hole)\n\nCrab-hole is a cross platform Pi-hole clone written in Rust using [hickory-dns/trust-dns](https://github.com/hickory-dns/hickory-dns).\nIt can be used as a network wide Ad and spy blocker or run on your local pc.\n\nFor a secure and private communication, crab-hole has builtin support for doh(https), doq(quic) and dot(tls) for down- and upstreams and dnssec for upstreams.\nIt also comes with privacy friendly default logging settings.\n\n# Installation: \nCrab-hole is available in the following repositories:\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/crab-hole.svg)](https://repology.org/project/crab-hole/versions)\n\nPrebuilt binaries can also been downloaded from the [Github release](https://github.com/LuckyTurtleDev/crab-hole/releases/latest).\n\n\n### Building from source: \nAlternatively you can easily build crab-hole yourself.\n* [Install Rust](https://www.rust-lang.org/tools/install)\n* Run `cargo install crab-hole --locked`\nSee the [Rust book](https://doc.rust-lang.org/cargo/commands/cargo-install.html) for more information about cargo install.\n* Make sure that `~/.cargo/bin` is listed in the `PATH` environment variable\n\n### Docker\nA docker image is available at the Github Container Registry.\nExample `docker-compose.yml`:\n```yml\nversion: '3.3'\nservices:\n    crab-hole:\n        image: 'ghcr.io/luckyturtledev/crab-hole:latest' #semver tags are available\n        ports: #required ports depend on downstream configuration\n            - \"53:53/tcp\"\n            - \"53:53/udp\"\n        volumes:\n            - './data:/data'\n            - './config.toml:/data/config.toml:ro'\n```\n[Semver](https://semver.org/) tags like `v0`, `v0.1` and `v0.1.3` are available to safely allow automatic updates.\n\n# Configuration:\nExample config file using cloudflare as dot (dns-over-tls) upstream.\n```toml\n[blocklist]\ninclude_subdomains = true\nlists = [\n\t\"https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews-gambling-porn/hosts\",\n\t\"https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt\",\n\t\"file:///blocked.txt\"\n]\n# allow domains blocked by the blocklist again\nallow_list = [\"file:///allowed.txt\"]\n\n# optional\n[api]\nport = 8080\nlisten = \"127.0.0.1\"\n# optional (default = false)\nshow_doc = true # OpenAPI doc loads content from third party websites\n# optional\nadmin_key = \"1234\"\n\n[[downstream]]\nprotocol = \"udp\"\nlisten = \"localhost\"\nport = 8080\n\n[[downstream]]\nprotocol = \"udp\"\nlisten = \"[::]\" #all ipv6 and ipv4 adress\nport = 8053\n\n[[downstream]]\nprotocol = \"tls\"\nlisten = \"[::]\"\nport = 8054\ncertificate = \"dns.example.com.crt\"\nkey = \"dns.example.com.key\"\n# optional (default = 3000)\ntimeout_ms = 3000\n\n[[downstream]]\nprotocol = \"https\"\nlisten = \"[::]\"\nport = 8055\ncertificate = \"dns.example.com.crt\"\nkey = \"dns.example.com.key\"\ndns_hostname = \"dns.example.com\"\n# optional (default = 3000)\ntimeout_ms = 3000\n\n[[downstream]]\nprotocol = \"quic\"\nlisten = \"127.0.0.1\"\nport = 8055\ncertificate = \"dns.example.com.crt\"\nkey = \"dns.example.com.key\"\ndns_hostname = \"dns.example.com\"\n# optional (default = 3000)\ntimeout_ms = 3000\n\n# optional\n[upstream.options]\n# optional (default = false)\n# Keep DNSSEC disabled due to Hickory DNS issue, see https://github.com/hickory-dns/hickory-dns/issues/2429\n# validate = true # use DNSSEC\n# see https://docs.rs/hickory-resolver/0.24/hickory_resolver/config/struct.ResolverOpts.html for all options\n\n[[upstream.name_servers]]\nsocket_addr = \"[2606:4700:4700::1111]:853\"\nprotocol = \"tls\"\ntls_dns_name = \"1dot1dot1dot1.cloudflare-dns.com\"\ntrust_nx_responses = false\n\n[[upstream.name_servers]]\nsocket_addr = \"[2606:4700:4700::1001]:853\"\nprotocol = \"tls\"\ntls_dns_name = \"1dot1dot1dot1.cloudflare-dns.com\"\ntrust_nx_responses = false\n\n[[upstream.name_servers]]\nsocket_addr = \"1.1.1.1:853\"\nprotocol = \"tls\"\ntls_dns_name = \"1dot1dot1dot1.cloudflare-dns.com\"\ntrust_nx_responses = false\n\n[[upstream.name_servers]]\nsocket_addr = \"1.0.0.1:853\"\nprotocol = \"tls\"\ntls_dns_name = \"1dot1dot1dot1.cloudflare-dns.com\"\ntrust_nx_responses = false\n```\n\n## Starting the Server\nTo start the server just execute the binary without any subcommands.\n\n`crab-hole`\n\n## Syntax check\nTo check if the config has a valid syntax, the following command can be used.\n\n`crab-hole validate-config`\n\nThis loads the config to check for syntax issues, but does not start the DNS server.\n\n## Validation\nThe config and blocklists can be validated by running the following command.\n\n`crab-hole validate-lists`\n\nThis only validates the config, block- and allowlists, and does not start the DNS server. If the validation fails, the program exits with the error code `1`.\n\n## DNSSEC Issues\nDue to an upstream issue of [hickory-dns](https://github.com/hickory-dns/hickory-dns/issues/2429), non DNSSEC sites will not be resolved if `validate = true`.\nOnly DNSSEC capable sites will be resolved with this setting.\nTo prevent this, set `validate = false` or omit the `[upstream.options]`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluckyturtledev%2Fcrab-hole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluckyturtledev%2Fcrab-hole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluckyturtledev%2Fcrab-hole/lists"}