{"id":15167119,"url":"https://github.com/lkubb/salt-pihole-formula","last_synced_at":"2026-01-21T00:34:03.367Z","repository":{"id":134852537,"uuid":"525261666","full_name":"lkubb/salt-pihole-formula","owner":"lkubb","description":"Manage a PiHole installation with Salt. Includes custom execution and state modules.","archived":false,"fork":false,"pushed_at":"2025-06-17T22:32:13.000Z","size":228,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-17T23:29:25.750Z","etag":null,"topics":["devops","homelab","pihole","salt","salt-formula","saltstack","saltstack-formula"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lkubb.png","metadata":{"files":{"readme":"docs/README.rst","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":"2022-08-16T06:45:38.000Z","updated_at":"2025-06-17T22:32:17.000Z","dependencies_parsed_at":"2023-12-26T16:35:54.877Z","dependency_job_id":"1e3971cb-b1cf-4a47-9424-f549fad96d4a","html_url":"https://github.com/lkubb/salt-pihole-formula","commit_stats":{"total_commits":27,"total_committers":1,"mean_commits":27.0,"dds":0.0,"last_synced_commit":"c140c44e15fdafc0806c56c0c3ade77d3ef00b2d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lkubb/salt-pihole-formula","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-pihole-formula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-pihole-formula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-pihole-formula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-pihole-formula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lkubb","download_url":"https://codeload.github.com/lkubb/salt-pihole-formula/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkubb%2Fsalt-pihole-formula/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28619802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T23:49:58.628Z","status":"ssl_error","status_checked_at":"2026-01-20T23:47:29.996Z","response_time":117,"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":["devops","homelab","pihole","salt","salt-formula","saltstack","saltstack-formula"],"created_at":"2024-09-27T05:40:14.923Z","updated_at":"2026-01-21T00:34:03.361Z","avatar_url":"https://github.com/lkubb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. _readme:\n\nPiHole Formula\n==============\n\n|img_sr| |img_pc|\n\n.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\n   :alt: Semantic Release\n   :scale: 100%\n   :target: https://github.com/semantic-release/semantic-release\n.. |img_pc| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white\n   :alt: pre-commit\n   :scale: 100%\n   :target: https://github.com/pre-commit/pre-commit\n\nManage PiHole with Salt.\n\nThis formula also provides a custom execution and state module to manage PiHole beyond the setup.\n\nMind that automatic testing is currently not implemented, even if suggested otherwise from forking the official template formula.\n\n.. contents:: **Table of Contents**\n   :depth: 1\n\nGeneral notes\n-------------\n\nSee the full `SaltStack Formulas installation and usage instructions\n\u003chttps://docs.saltproject.io/en/latest/topics/development/conventions/formulas.html\u003e`_.\n\nIf you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section\n\u003chttps://docs.saltproject.io/en/latest/topics/development/conventions/formulas.html#writing-formulas\u003e`_.\n\nIf you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,\nwhich contains the currently released version. This formula is versioned according to `Semantic Versioning \u003chttp://semver.org/\u003e`_.\n\nSee `Formula Versioning Section \u003chttps://docs.saltproject.io/en/latest/topics/development/conventions/formulas.html#versioning\u003e`_ for more details.\n\nIf you need (non-default) configuration, please refer to:\n\n- `how to configure the formula with map.jinja \u003cmap.jinja.rst\u003e`_\n- the ``pillar.example`` file\n- the `Special notes`_ section\n\nSpecial notes\n-------------\n\n\nConfiguration\n-------------\nAn example pillar is provided, please see `pillar.example`. Note that you do not need to specify everything by pillar. Often, it's much easier and less resource-heavy to use the ``parameters/\u003cgrain\u003e/\u003cvalue\u003e.yaml`` files for non-sensitive settings. The underlying logic is explained in `map.jinja`.\n\n\nAvailable states\n----------------\n\nThe following states are found in this formula:\n\n.. contents::\n   :local:\n\n\n``pihole``\n^^^^^^^^^^\n*Meta-state*.\n\nThis installs the pihole package,\nmanages the pihole configuration file,\nadlists, blacklists, custom CNAME and DNS config,\ngroups, whitelists, then starts the pihole-FTL service.\n\n\n``pihole.package``\n^^^^^^^^^^^^^^^^^^\nInstalls PiHole only and syncs the custom modules found in this formula.\n\nWarning:\n  This pipes the output fetching the installation script from the URL in\n  ``pihole.lookup.setup_sh`` into a root shell because the setup is sadly\n  rather the antithesis of straightforward to reproduce with Salt.\n  It's possible to provide a local replacement\n  for the script by overriding ``pihole.lookup.setup_sh`` e.g. to a salt:// URI.\n\n\n``pihole.config``\n^^^^^^^^^^^^^^^^^\nManages the PiHole API password, the `pihole.toml` configuration as well as the dnsmasq one, if configured.\nHas a dependency on `pihole.package`_.\n\n\n``pihole.config.file``\n^^^^^^^^^^^^^^^^^^^^^^\nManages the `pihole.toml` configuration.\n\nIf `pihole:config:dnsmasq` is set, additionally manages a dnsmasq configuration file.\nThis is usually not necessary, just set `pihole:config:app:misc:dnsmasq_lines`.\nIf used anyways, this formula ensures `pihole:config:app:misc:etc_dnsmasq_d` is enabled.\n\n\n``pihole.config.secrets``\n^^^^^^^^^^^^^^^^^^^^^^^^^\nManages the PiHole API password.\nIf none was provided in `pihole:secrets:api_password:(pillar|plaintext)`\nand it is unset when rendering this state, a random one is generated\nto ensure it is set.\n\n\n``pihole.cert``\n^^^^^^^^^^^^^^^\nGenerates a TLS certificate + key for PiHole.\nDepends on `pihole.package`_.\n\n\n``pihole.adlist``\n^^^^^^^^^^^^^^^^^\nManages PiHole adlists and updates the gravity database.\nHas a dependency on `pihole.service`_.\n\n\n``pihole.blacklist``\n^^^^^^^^^^^^^^^^^^^^\nManages PiHole blacklist entries.\nHas a dependency on `pihole.service`_.\n\n\n``pihole.custom_cname``\n^^^^^^^^^^^^^^^^^^^^^^^\nManages PiHole custom CNAME entries.\nHas a dependency on `pihole.service`_.\n\n\n``pihole.custom_dns``\n^^^^^^^^^^^^^^^^^^^^^\nManages PiHole local DNS A/AAAA entries.\nHas a dependency on `pihole.service`_.\n\n\n``pihole.group``\n^^^^^^^^^^^^^^^^\nManages PiHole groups.\nHas a dependency on `pihole.service`_.\n\n\n``pihole.whitelist``\n^^^^^^^^^^^^^^^^^^^^\nManages PiHole whitelist entries.\nHas a dependency on `pihole.service`_.\n\n\n``pihole.service``\n^^^^^^^^^^^^^^^^^^\nStarts the pihole-FTL service and enables it at boot time.\nHas a dependency on `pihole.config`_.\n\n\n``pihole.clean``\n^^^^^^^^^^^^^^^^\n*Meta-state*.\n\nUndoes some operations performed in the ``pihole`` meta-state\nin reverse order, i.e.\nremoves generated TLS certificates,\nstops the service,\nremoves the configuration.\nThe package cannot be uninstalled automatically.\n\n\n``pihole.package.clean``\n^^^^^^^^^^^^^^^^^^^^^^^^\n**This state will fail.** PiHole currently cannot be removed without user interaction.\nHas a dependency on `pihole.config.clean`_.\n\n\n``pihole.config.clean``\n^^^^^^^^^^^^^^^^^^^^^^^\nRemoves the PiHole, pihole-FTL and custom dnsmasq configurations and has a\ndependency on `pihole.service.clean`_.\n\n\n``pihole.cert.clean``\n^^^^^^^^^^^^^^^^^^^^^\nRemoves generated PiHole TLS certificate + key.\nDepends on `pihole.service.clean`_.\n\n\n``pihole.adlist.clean``\n^^^^^^^^^^^^^^^^^^^^^^^\nRemoves managed PiHole adlists.\nThis does not restart PiHole on its own. To apply, you will need to restart manually.\n\n\n``pihole.blacklist.clean``\n^^^^^^^^^^^^^^^^^^^^^^^^^^\nRemoves managed PiHole blacklist entries.\nThis does not restart PiHole on its own. To apply, you will need to restart manually.\n\n\n``pihole.custom_cname.clean``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nRemoves managed PiHole custom CNAME entries.\nThis does not restart PiHole on its own. To apply, you will need to restart manually.\n\n\n``pihole.custom_dns.clean``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\nRemoves managed PiHole local DNS A/AAAA entries.\nThis does not restart PiHole on its own. To apply, you will need to restart manually.\n\n\n``pihole.group.clean``\n^^^^^^^^^^^^^^^^^^^^^^\nRemoves managed PiHole groups.\nThis does not restart PiHole on its own. To apply, you will need to restart manually.\n\n\n``pihole.whitelist.clean``\n^^^^^^^^^^^^^^^^^^^^^^^^^^\nRemoves managed PiHole whitelist entries.\nThis does not restart PiHole on its own. To apply, you will need to restart manually.\n\n\n``pihole.service.clean``\n^^^^^^^^^^^^^^^^^^^^^^^^\nStops the pihole-FTL service and disables it at boot time.\n\n\n\nContributing to this repo\n-------------------------\n\nCommit messages\n^^^^^^^^^^^^^^^\n\n**Commit message formatting is significant!**\n\nPlease see `How to contribute \u003chttps://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst\u003e`_ for more details.\n\npre-commit\n^^^^^^^^^^\n\n`pre-commit \u003chttps://pre-commit.com/\u003e`_ is configured for this formula, which you may optionally use to ease the steps involved in submitting your changes.\nFirst install  the ``pre-commit`` package manager using the appropriate `method \u003chttps://pre-commit.com/#installation\u003e`_, then run ``bin/install-hooks`` and\nnow ``pre-commit`` will run automatically on each ``git commit``. ::\n\n  $ bin/install-hooks\n  pre-commit installed at .git/hooks/pre-commit\n  pre-commit installed at .git/hooks/commit-msg\n\nState documentation\n~~~~~~~~~~~~~~~~~~~\nThere is a script that semi-autodocuments available states: ``bin/slsdoc``.\n\nIf a ``.sls`` file begins with a Jinja comment, it will dump that into the docs. It can be configured differently depending on the formula. See the script source code for details currently.\n\nThis means if you feel a state should be documented, make sure to write a comment explaining it.\n\nTodo\n----\n* `Automatically \u003chttps://github.com/jacklul/pihole-updatelists\u003e`_ import `meta-lists \u003chttps://v.firebog.net/hosts/lists.php?type=tick\u003e`_ and `whitelists \u003chttps://github.com/anudeepND/whitelist/\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkubb%2Fsalt-pihole-formula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flkubb%2Fsalt-pihole-formula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkubb%2Fsalt-pihole-formula/lists"}