pihole.toml changes do not take effect

happyanimal55 · March 13, 2026, 8:52pm

Objective: Configure local DNS records through a configuration file.

It is absolutely unacceptable to configure local DNS records through the Web UI.

It is absolutely unacceptable to configure local DNS records through the pihole CLI.

Expected Behaviour:

I should be able to edit the configuration option [dns]::hosts in file /etc/pihole/pihole.toml and have my changes take place after systemctl restart pihole-FTL.

These instructions come from the /etc/pihole/hosts/custom.list

root@vox:/etc/pihole/hosts# head -n 23 custom.list 
# Pi-hole: A black hole for Internet advertisements
# (c) 2026 Pi-hole, LLC (https://pi-hole.net)
# Network-wide ad blocking via your own hardware.
#
# Custom DNS entries (HOSTS file)
#
##################################################################################
#                                                                                #
#                     FILE AUTOMATICALLY POPULATED BY PI-HOLE                    #
#    ANY CHANGES MADE TO THIS FILE WILL BE LOST WHEN THE CONFIGURATION CHANGES   #
#                                                                                #
#            IF YOU WISH TO CHANGE ANY OF THESE VALUES, CHANGE THEM IN           #
#                             /etc/pihole/pihole.toml                            #
#                             and restart pihole-FTL                             #
#                                                                                #
#           ANY OTHER CHANGES SHOULD BE MADE IN A SEPARATE CONFIG FILE           #
#                       WITHIN /etc/dnsmasq.d/yourname.conf                      #
#    (make sure misc.etc_dnsmasq_d is set to true in /etc/pihole/pihole.toml)    #
#                                                                                #
#                      Last updated: 2026-03-13 14:59:53 CDT                     #
#                               by FTL version v6.5                              #
#                                                                                #
##################################################################################
root@vox:/etc/pihole/hosts#

Operating System: Raspberry Pi Lite (Debian Trixie 13)
Hardware: Raspberry Pi 5 1GB
Docker compose file or Docker run command: N/A
Docker engine version: N/A

Actual Behaviour:

Nothing happens. As soon as I edit the file, FTL immediately overwrites the file with whatever was presently in there.
systemctl stop pihole-FTL followed by editing and systemctl start pihole-FTLimmediately overwrites /etc/pihole/pihole.toml with what’s currently in there.

printenv on the root account shows no environment variables starting with FTLCONF

Debug Token:

[✓] Your debug token is: https://tricorder.pi-hole.net/4Eec3Xsz/

happyanimal55 · March 13, 2026, 8:59pm

Further experimentation has revealed that
systemctl start pihole-FTL totally ignores the setting [misc]readOnly

rdwebdesign · March 13, 2026, 8:59pm

You can, but you need to use the correct format when manually entering data in pihole.toml.

Are you sure you are using the correct format?

[dns]
  hosts = [ "127.0.0.1 mylocal", "192.168.0.1 therouter" ]

Please check the documentation: Configuration - Pi-hole documentation - dns.hosts

happyanimal55 · March 13, 2026, 9:28pm

Yes, I am certain I have formatted my toml correctly.
Some further experimental results

PiHole’s TOML parser will strip blank lines, comments, and trailing commas from the [dns]hosts setting, even if the TOML is correctly formatted.
If I paste invalid TOML into [dns]hosts pihole will reload the last-known good [dns]hosts setting

The issue was that I was pasting in comments and blank space and they’d all just disappear, making it look like I’d made 0 progress.

I’m surprised by how invalid TOML is handled. Is there a setting somewhere I can flip which makes everything crash and burn instead of reloading last known good?

jfb · March 13, 2026, 9:47pm

You can use the file /etc/hosts on the host OS. You don’t need to use either the Web UI or the pihole CLI. You can use any text editor you choose.

An example of a file on one of my Pi’s

cat /etc/hosts
127.0.0.1	localhost
::1		localhost ip6-localhost ip6-loopback
ff02::1		ip6-allnodes
ff02::2		ip6-allrouters

127.0.1.1	Pi3BDev
192.168.0.1	TC-Extreme-3TB
192.168.0.2	TC-Extreme-3TB-extender
192.168.0.4	Printer
192.168.0.5	Airport-Express-PC
...

robgill · March 14, 2026, 12:21am

I'm reasonably certain that this is not a good idea, but it is possible to prevent pihole overwriting your bespoke toml file.

Edits will need to be made, and the file set to immutable while the pihole-FTL service stopped. Once you are done editing, make the toml file immutable using chattr and then Pi-hole won't be able to delete, rewrite or overwrite it.

sudo chattr +i /etc/pihole/pihole.toml

Then restart the pihole-FTL service.

So long as the file is parseable, pihole will read the file and use it but won't overwrite your file. You will see a warning in FTL.log:

WARNING: Cannot move temporary config file to final location (Operation not permitted), content not updated.

If the file is not parseable, pihole will use its last known good config, but leave the mangled file alone:

ERROR: Cannot parse config file: (line 15) invalid value
ERROR: Cannot parse TOML file: (line 15) invalid value
INFO: Using config backup /etc/pihole/config_backups/pihole.toml.1

If you later wanted to change the file yourself, you would need to first remove the immutability flag:

sudo chattr -i /etc/pihole/pihole.toml

rdwebdesign · March 14, 2026, 1:36am

No.

Pi-hole will always rewrite pihole.toml using only its own comments, which are part of the documentation.

Also, I don't know what will happen if you try to make the file immutable. This is not recommended.

If you really want to keep your comments, the only suggestion I have is: create your own pihole.toml file (with your settings and comments) and save it on your home directory.

Since you will never use the web interface or the CLI commands to change your settings, this file will contain all Pi-hole settings.
When you need to change something, you can edit this file and them copy it to /etc/pihole/.

happyanimal55 · March 14, 2026, 2:25am

Pi-hole will always rewrite pihole.toml using only its own comments, which are part of the documentation.

Do you have a link I can follow? Maybe there are hidden developer docs somewhere I haven’t found and I would have wanted to read those before making the post.

I didn’t see anything specifically in pihole.toml's comments
I couldn’t find a reference to this on docs.pi-hole.net: Almost all my information comes from the Docker > Configuration page, and the Advanced > Signals page seems to support the idea that pihole only reads from pihole.toml instead of overwriting it
I also didn’t see anything in a brief search of the github repo, and I didn’t have enough time to actually read through the code.

Since I like to manage everything from one place where possible, I think I’ll utilize the /home/username/pihole.toml approach. I’ll always have the ability to diff my personal config and the live config – I just need to keep those autoformat rules in mind.

Thanks for the suggestions all, this is closable.

rdwebdesign · March 14, 2026, 3:25am

Link for what exactly? I'm not sure what you want to see.

If you don't believe me when I say the file is recreated, you can easily test yourself.

Create a backup copy of your pihole.toml and then delete the original file. You will see that the file is really gone.

Pi-hole will keep working without the file until you execute any operation that restarts the DNS resolver, like changing a config option via CLI or the web interface. You can test that executing sudo pihole-FTL --config webserver.api.sessions 16.

After that, the file pihole.toml will be back, because it was recreated by FTL.

EDIT:

I think I found what you are looking for.
This is a comment that explains pihole.toml is always rewritten after FTL parsing it:

github.com/pi-hole/FTL

src/main.c

f88830982


      
          	// Process pihole.toml configuration file
          	// The file is rewritten after parsing to ensure that all
          	// settings are present and have a valid value
          	if(readFTLconf(&config, true))
          		log_info("Parsed config file "GLOBALTOMLPATH" successfully");

And:

github.com/pi-hole/FTL

src/config/config.c

f88830982


      
          bool readFTLconf(struct config *conf, const bool rewrite)
          {
          	// Initialize config with default values
          	initConfig(conf);
          
          	// First, read the environment
          	getEnvVars();
          
          	// Try to read TOML config file
          	// If we cannot parse /etc/pihole.toml (due to missing or invalid syntax),
          	// we try to read the rotated files in /etc/pihole/config_backup starting at
          	// the most recent one and going back in time until we find a valid config
          	for(unsigned int i = 0; i < MAX_ROTATIONS; i++)
          	{
          		toml_datum_t toml = { 0 };
          		if(readFTLtoml(NULL, conf, toml, rewrite, NULL, i, false))
          		{
          			// If successful, we write the config file back to disk
          			// to ensure that all options are present and comments
          			// about options deviating from the default are present

This file has been truncated. show original

And the whole toml_writer.c file:

github.com/pi-hole/FTL

src/config/toml_writer.c

f88830982

/* Pi-hole: A black hole for Internet advertisements
*  (c) 2021 Pi-hole, LLC (https://pi-hole.net)
*  Network-wide ad blocking via your own hardware.
*
*  FTL Engine
*  TOML config writer routines
*
*  This file is copyright under the latest version of the EUPL.
*  Please see LICENSE file for your rights under this license. */

#include "FTL.h"
#include "config.h"
// get_timestr(), get_FTL_version())
#include "log.h"
#include "tomlc17/tomlc17.h"
#include "toml_writer.h"
#include "toml_helper.h"
// get_blocking_mode_str()
#include "datastructure.h"
// watch_config()

This file has been truncated. show original