Tune thermald Safely with Thermal Zones and XML Trips

A laptop that throttles too early usually means thermald is ignoring the configuration you think it reads. This guide shows which control mode your installed daemon actually uses, how to read the thermal devices Linux exposes, and how to prepare a narrowly scoped thermal-conf.xml rule. Examples target thermald 2.5.6, shipped here as Ubuntu package 2.5.6-2ubuntu0.24.04.5. Allow about 20 minutes, longer if you still need to identify a fan or sensor before changing anything.

Before you change anything

You need a shell account with systemctl, journalctl, and read access to /sys/class/thermal. Reading those paths is unprivileged; editing /etc/thermald and restarting the daemon need sudo. Keep a root shell out of the copy-and-paste block until a step explicitly calls for it.

1. Confirm the installed daemon and service mode

Start with version and service information:

thermald --version
systemctl status thermald --no-pager --lines=12
systemctl cat thermald

If the service is inactive, check the recent reason before starting it:

journalctl -u thermald -b --no-pager --lines=40

Do not launch a second copy of thermald while the system service is active. Two controllers competing for the same thermal sysfs devices is a genuinely bad time.

2. Inspect the sensors and cooling devices

The daemon discovers thermal sensors and cooling drivers under /sys/class/thermal. List their names and read the values that are safe to inspect:

for zone in /sys/class/thermal/thermal_zone*; do
    printf '%s: ' "$zone"
    sed -n '1p' "$zone/type"
    printf '  temperature: '
    sed -n '1p' "$zone/temp"
done

for device in /sys/class/thermal/cooling_device*; do
    printf '%s: ' "$device"
    sed -n '1p' "$device/type"
    printf '  state: '
    sed -n '1p' "$device/cur_state"
    printf '  maximum: '
    sed -n '1p' "$device/max_state"
done

A temperature reading such as 36500 means 36.5 degrees Celsius: the kernel interface reports thousandths of a degree. Confirm what a sensor actually is from its type; never assume thermal_zone0 is the CPU. Cooling device state ranges are device-specific, so never copy a target state from one machine onto another.

3. Understand which XML file would be selected

In non-adaptive mode, thermald checks these files in order and uses the first one it finds:

1. /etc/thermald/thermal-conf.xml.auto
2. /var/run/thermald/thermal-conf.xml.auto
3. /etc/thermald/thermal-conf.xml

A path passed with --config-file overrides that search and the defaults get ignored entirely. In adaptive mode, the manpage says XML configuration is ignored outright, so reordering the search changes nothing visible. Check the actual service command again after any package or distribution update, since the unit file decides the effective mode.

4. Create a small passive trip

Only do this once you have confirmed the service actually runs in XML mode and you know the platform's sensor names. What follows is a template: replace every value marked REPLACE_.... It requests passive CPU cooling at 80 degrees Celsius, written as 80000 because XML temperatures here are thousandths of a degree.

<?xml version="1.0"?>
<ThermalConfiguration>
  <Platform>
    <Name>REPLACE_PLATFORM_NAME</Name>
    <ProductName>*</ProductName>
    <Preference>QUIET</Preference>
    <ThermalZones>
      <ThermalZone>
        <Type>REPLACE_ZONE_TYPE</Type>
        <TripPoints>
          <TripPoint>
            <SensorType>REPLACE_SENSOR_TYPE</SensorType>
            <Temperature>80000</Temperature>
            <type>passive</type>
          </TripPoint>
        </TripPoints>
      </ThermalZone>
    </ThermalZones>
  </Platform>
</ThermalConfiguration>

QUIET selects passive cooling in this configuration model. The format can also describe active cooling, cooling-device order, target states, sampling periods and PID parameters, but those are hardware-specific. Add one relationship at a time, and never paste a fan path, device index or PID constant from an online example without matching it to this machine's actual sysfs devices.

Validate the XML before it gets anywhere near the service. This only checks syntax; it proves nothing about whether the zone and sensor names actually exist:

xmllint --noout /etc/thermald/thermal-conf.xml

sudo install -D -m 0644 /etc/thermald/thermal-conf.xml \
  /etc/thermald/thermal-conf.xml.before-thermald-guide
sudoedit /etc/thermald/thermal-conf.xml

If the file does not exist yet, that backup command fails harmlessly. A missing file is not permission to drop an unverified configuration straight into place.

5. Apply and verify a configuration change

Reload the service only after the syntax check and the backup both succeed:

sudo systemctl restart thermald
systemctl is-active thermald
journalctl -u thermald -b --no-pager --lines=30

If the service fails or behaves unexpectedly, restore the saved file and restart:

sudo cp -- /etc/thermald/thermal-conf.xml.before-thermald-guide \
  /etc/thermald/thermal-conf.xml
sudo systemctl restart thermald
systemctl is-active thermald

If you created a new file and there was no previous configuration, move it out of the search path instead of deleting it outright:

sudo mv -- /etc/thermald/thermal-conf.xml \
  /etc/thermald/thermal-conf.xml.disabled
sudo systemctl restart thermald

Common traps

• XML appears to do nothing. The service may be running with --adaptive, which always wins over XML. Check the unit's ExecStart.
• The wrong file got edited. An auto-generated file can be selected before /etc/thermald/thermal-conf.xml. Check all three documented paths.
• Polling got disabled. --poll-interval 0 only works when the available sensors can report temperature changes asynchronously.
• Performance changed unexpectedly. --disable-active-power turns off active power management and can leave the system with lower power limits. It is not a general troubleshooting switch.
• A critical trip got waved away. --ignore-critical-trip can dodge a shutdown for a critical point set too low. Treat that as a temporary diagnostic move, never a safety improvement.