Greater API capabilities in cli

Feature Requests
1

So I used to manage my local network’s DNS entries with custom.list in my github repo, and actions runner did stuff to push out, symlink the changes to /etc/pihole/custom.list, restart pihole, etc.

This no longer works, and in fact while I’m having trouble finding documentation around custom DNS entries, programmatic management of them, etc, it appears that the only real good way is to do so through the API.

There also seem to be no ways to write any changes via api when using pihole api … to address the API endpoints.

It would be super nice to see some capabilities around creating/changing/deleting data/settings via the API when using the pihole command.

(Or maybe we could revisit how we can enable automated management of pihole around custom DNS entries)

But, PUT and DELETE operations would be pretty cool for the config/dns/hosts endpoint.

2

This is possible using PUT and DELETE with config endpoint

Just use this:

curl -X PUT "http://192.168.0.201:80/api/config/dns%2Fhosts/1.1.1.1%20aaaa.com" \
 -H 'accept: application/json'\
 -H 'sid: <valid_SID>'

To use it with curl you need to URL encode the string, So 1.1.1.1 aaaa.com will become 1.1.1.1%20aaaa.com.

PUT:

image
image851×697 14.7 KB

DELETE:

image
image854×701 23 KB

3

I was referring to use of the api command when executing the pihole application.

So, pihole api config/dns/hosts might return your current custom DNS configuration.

But something like pihole api <endpoint> <command> <arguments>, like:

pihole api config/dns/hosts PUT "10.1.1.2 my.host" to add an entry for the system my.host using IP 10.1.1.2.

I’m not opposed to making curl API calls or writing wrapper scripts, and I’m all for shift-left mentality, but there were once pretty simple methods for managing custom DNS entries relying on basic OS, filesystem, user permission guardrails. That’s been made more difficult requiring additional authentication, getting a session ID, etc.

So I’m looking for thoughts on adding functionality to the binary pihole API call methods to allow more than getting/displaying existing data/config.

4

That file was introduced to hold the definitions of A/AAAA records as defined via Pi-hole's Local DNS records UI, i.e it was meant to populated via UI interaction, and it still exists with Pi-hole 6, if in a different location.
Besides, Pi-hole 6 honours definitions from /etc/hosts, just as Pi-hole 5.

As detailed in Introducing Pi-hole v6, Pi-hole's configuration has been consolidated into a single file, /etc/pihole.toml.
It is fully documented, and beyond editing it, there are quite a few ways to change configurations options:

For your specific question, while it is not possible any more to edit custom.list in the way that Pi-hole 5 would have tolerated, you may just edit dns.hosts in /etc/pihole.toml instead, e.g.:

# Pi-hole configuration file (v6.1)
# Encoding: UTF-8
# This file is managed by pihole-FTL
# Last updated on 2025-05-30 12:31:03 CEST

[dns]
(…)
  hosts = [
    "127.0.0.1 mylocal",
    "192.168.0.1 therouter"
  ] ### CHANGED, default = []

Pi-hole monitors pihole.toml, so any changes to your dns.hosts should be picked up automatically.

5

Ok thank you, yeah, I wasn’t sure what would happen with pihole.toml, specifically, around registering or updating configuration changes on the fly - and so didn’t want do dive into automating updates to the file if it might cause issues, or simply be overwritten from some other source.

For my purposes, this is probably sufficient, I’ll just work out how I want to manage updating the toml file in my workflow.

Thanks!

(PS: An optional local/custom DNS ingestion point wouldn’t be unappreciated a la the old custom.list file, but this should take care of my needs.)

6

You can use the /etc/hosts file on the OS.

7

Oh my god you have to be kidding me. Yeah, then I’ll most likely retool my pipeline to simply update /etc/hosts instead of rewriting TOML.