{"id":22675531,"url":"https://github.com/chamilad/pihole-restore","last_synced_at":"2026-01-25T08:39:33.788Z","repository":{"id":168223865,"uuid":"638911709","full_name":"chamilad/pihole-restore","owner":"chamilad","description":"A CLI tool to restore a Pihole Backup","archived":false,"fork":false,"pushed_at":"2024-11-02T03:53:48.000Z","size":622,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-06T17:54:24.494Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chamilad.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-05-10T11:18:52.000Z","updated_at":"2024-11-02T03:53:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"7253e7e3-2e68-4a3c-9d67-fc322b57f243","html_url":"https://github.com/chamilad/pihole-restore","commit_stats":null,"previous_names":["chamilad/pihole-restore"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/chamilad/pihole-restore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chamilad%2Fpihole-restore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chamilad%2Fpihole-restore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chamilad%2Fpihole-restore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chamilad%2Fpihole-restore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chamilad","download_url":"https://codeload.github.com/chamilad/pihole-restore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chamilad%2Fpihole-restore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28749735,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T08:31:04.260Z","status":"ssl_error","status_checked_at":"2026-01-25T08:30:28.859Z","response_time":113,"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":[],"created_at":"2024-12-09T17:45:51.566Z","updated_at":"2026-01-25T08:39:33.735Z","avatar_url":"https://github.com/chamilad.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pihole-restore\n\n`pihole_restore` is a CLI tool to restore a Pihole Backup archive file. It can\nbe used in a setup where multiple Pihole servers are configured that needs\nsyncing from a given master configuration point. This CLI is intended to be run\non the same runtime as the target Pihole server itself. It cannot run in a\ndetached runtime, since it depends on being able to access the `pihole` CLI.\n\n![design](./img/pihole-restore-design.png)\n\n![restore](./img/restore.png)\n\nThe motivation to write this tool was the absence of a `restore` command in the\n`pihole` CLI shipped with Pi-hole.\n\n## Compile Time Dependencies\n\n1. `glibc` - At most v2.28 (since the oldest pihole setup I could get my hands\n   on had this version)\n\n### Ubuntu\n\nThe following dev headers will be needed to compile the binary.\n\n1. `libsqlite3-dev`\n\n## Runtime Dependencies\n\n1. `glibc` - At least v2.28 (if your runtime is older than this, please open an\n   issue. I haven't explored far back enough to see if the older docker images\n   have runtimes older than this.)\n\n## Usage\n\n```\n$ pihole_restore -h\nUsage: pihole_restore [OPTIONS] --file \u003cFILE\u003e\n\nOptions:\n  -f, --file \u003cFILE\u003e          teleporter archive file to restore from\n  -d, --database \u003cDATABASE\u003e  gravity db file location [default: /etc/pihole/gravity.db]\n  -c, --clear                clean existing tables and files\n      --filters \u003cFILTERS\u003e    filter which config to restore, specify in comma separated keywords [default: all]\n  -h, --help                 Print help\n  -V, --version              Print version\n```\n\nIn a typical scenario, the following command will restore from the archive to\nthe `/etc/pihole/gravity.db` and the other locations inside Pihole\ninstallation.\n\n```\npihole_restore -f pihole-backup.tar.gz\n```\n\nIf the current configuration needs to be cleared before restoring from the\narchive, `-c` (`--clear`) flag can be used. Doing so will clear out the tables\nand the configuration files.\n\nBy default, the following configuration is restored.\n\n1. `blacklist` - Blacklist (exact)\n1. `blacklistregex` - Blacklist (regex)\n1. `whitelist` - Whitelist (exact)\n1. `whitelistregex` - Whitelist (regex)\n1. `adlist` - Adlists\n1. `auditlog` - Audit log\n1. `group` - Group\n1. `client` - Client\n1. `staticdhcp` - Static DHCP Leases\n1. `localdns` - Local DNS Records\n1. `localcname` - Local CNAME Records\n\nIf only a subset of this configuration needs to be applied, use the `--filter`\nargument. For an example, to restore only the Local DNS records run,\n\n```\npihole_restore -f \u003carchive_file.tar.gz\u003e --filter localdns\n```\n\n\u003e use `sudo` in Raspbian since Pihole runs as `pihole` `nologin` user\n\nMultiple filters can be specified as a comma separated string.\n\n```\n# restore blacklist (exact), adlists, groups, and clients\npihole_restore -f \u003carchive_file.tar.gz\u003e --filter blacklist,adlist,group,client\n```\n\n## TODO\n\n1. test more use cases\n1. automated testing to cover most code\n1. edge cases on deduplication\n1. support for older glibc runtimes\n1. possibility on a fully independent binary (musl C?)\n\n## Development\n\nUse the `makefile` target `test` to spin up a pihole Docker container. It\ncompiles the binary on a Debian Buster container (to link to glibc 2.28), \ncopies the result to the Pihole container, copies the sample backup archive to\nthe container, and runs a restore job. The directories `test/pihole` and\n`test/dnsmasq` are mounted to `/etc/pihole` and `/etc/dnsmasq.d` respectively.\n\nSo the sample archive should exist in the `test` directory before running `make\ntest`. For this, create a backup of a Pihole setup\nand copy it to the `test` directory as `test/pi-hole_backup.tar.gz`.\n\nAt the end of the run, `make test` will output the IP address of the pihole\ncontainer and the randomly generated admin password from the logs.\n\n`make test-clean` will stop and clean the test container (named\n`test-pihole-test`, so make sure you don't have any existing containers named\nwith that ID), and move the `pihole` and `dnsmasq` directories to the\n`test/archive` directory for post-test analysis.\n\n## License\n\nThis source code and the binary is licensed under Apache v2 license. It is not\ndistributed with the official Pihole distribution, and it is not endorsed by\nofficial Pi-hole community at this moment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchamilad%2Fpihole-restore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchamilad%2Fpihole-restore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchamilad%2Fpihole-restore/lists"}