Ubuntu Manpage: thinkfan.conf - YAML-formatted config for thinkfan(1)

NAME

       thinkfan.conf - YAML-formatted config for thinkfan(1)

DESCRIPTION

YAML is a very powerful, yet concise notation for structured data. Its full specification
is available at https://yaml.org/spec/1.2/spec.html. Thinkfan uses only a small subset of
the full YAML syntax, so it may be helpful, but not strictly necessary for users to take a
look at the spec.

The most important thing to note is that indentation is syntactically relevant. In
particular, tabs should not be mixed with spaces. We recommend using two spaces for
indentation, like it is shown below.

The thinkfan config has three main sections:

sensors: Where temperatures should be read from. All hwmon-style drivers are supported,
as well as /proc/acpi/ibm/thermal, and, depending on the compile-time options,
libatasmart (to read temperatures directly from hard disks) and NVML (via the
proprietary nvidia driver).

fans: Which fans should be used (currently only one allowed). Support for multiple
fans is currently in development and planned for a future release. Both hwmon-
style PWM controls and /proc/acpi/ibm/fan can be used.

levels: Maps temperatures to fan speeds. A “simple mapping” just specifies one
temperature as the lower and upper bound (respectively) for a given fan speed.
In a “detailed mapping”, the upper and lower bounds are specified for each
driver/sensor configured under sensors:. This mode should be used when
thinkfan is monitoring multiple devices that can tolerate different amounts of
heat.

Under each of these sections, there must be a list of key-value maps, each of which
configures a sensor driver, fan driver or fan speed mapping.

SENSOR & FAN DRIVERS

For thinkfan to work, it first needs to know which temperature sensor drivers and which
fan drivers it should use. The mapping between temperature readings and fan speeds is
specified in a separate config section (see the FAN SPEEDS section below).

Sensor Syntax
The entries under the sensors: section can specify hwmon, thinkpad_acpi, NVML or atasmart
drivers, where the latter two must be enabled at compile-time. There can be any number
(greater than zero) and combination of hwmon, tpacpi, nvml and atasmart entries. However
there may be at most one instance of the tpacpi entry.

sensors:
- hwmon: hwmon-path
name: hwmon-name
indices: index-list
correction: correction-list
optional: bool-allow-errors

- tpacpi: /proc/acpi/ibm/thermal
indices: index-list
correction: correction-list
optional: bool-allow-errors

- nvml: nvml-bus-id
correction: correction-list
optional: bool-allow-errors

- atasmart: disk-device-file
correction: correction-list
optional: bool-allow-errors

- ...

Fan Syntax
Currently, thinkfan supports only one fan, so there can be only one entry in the list.
Support for multiple fans is currently in development and planned for a future release.
The fan is either an hwmon fan:

fans:
- hwmon: hwmon-path
name: hwmon-name
indices: index-list

or a tpacpi fan:

fans:
- tpacpi: /proc/acpi/ibm/fan

Values
hwmon-path There are three ways of specifying hwmon fans or sensors:

1) A full path of a “temp*_input” or “pwm*” file, like
“/sys/class/hwmon/hwmon0/pwm1” or “/sys/class/hwmon/hwmon0/temp1_input”. In
this case, the “indices: index-list” and “name: hwmon-name” entries are
unnecessary since the path uniquely identifies a specific fan or sensor.

Note that this method may lead to problems when the load order of the drivers
changes across bootups, because in the “hwmonX” folder name, the X actually
corresponds to the load order. Use method 2) or 3) to avoid this problem.

2) A directory that contains a specific hwmon driver, for example
“/sys/devices/platform/nct6775.2592”. Note that this path does not contain
the load-order dependent “hwmonX” folder. As long as it contains only a
single hwmon driver/interface it is sufficient to specify the “indices: index-
list” entry to tell thinkfan which specific sensors to use from that
interface. The “name: hwmon-name” entry is unnecessary.

3) A directory that contains multiple or all of the hwmon drivers, for example
“/sys/class/hwmon”. Here, both the “name: hwmon-name” and “indices: index-
list” entries are required to tell thinkfan which interface to select below
that path, and which sensors or which fan to use from that interface.

hwmon-name The name of a hwmon interface, typically found in a file called “name”. This
has to be specified if hwmon-path is a base path that contains multiple
hwmons. This method of specifying sensors is particularly useful if the full
path to a particular hwmon keeps changing between bootups, e.g. due to
changing load order of the driver modules.

index-list A YAML list [ X1, X2, ... ] that specifies which sensors, resp. which fan to
use from a given interface. Both /proc/acpi/ibm/thermal and also many hwmon
interfaces contain multiple sensors, and not all of them may be relevant for
fan control.

• For hwmon entries, this is required if hwmon-path does not refer directly to a
single “tempXi_input” file, but to a folder that contains one or more of them.
In this case, index-list specifies the Xi for the “tempXi_input” files that
should be used. A hwmon interface may also contain multiple PWM controls for
fans, so in that case, index-list must contain exactly one entry.

• For tpacpi sensors, this entry is optional. If it is omitted, all
temperatures found in /proc/acpi/ibm/thermal will be used.

nvml-bus-id NOTE: only available if thinkfan was compiled with USE_NVML enabled.

The PCI bus ID of an nVidia graphics card that is run with the proprietary
nVidia driver. Can be obtained with e.g. “lspci | grep -i vga”. Usually,
nVidia cards will use the open source nouveau driver, which should support
hwmon sensors instead.

disk-device-file
NOTE: only available if thinkfan was compiled with USE_ATASMART enabled.

Full path to a device file for a hard disk that supports S.M.A.R.T. See also
the -d option in thinkfan(1) that prevents thinkfan from waking up sleeping
(mechanical) disks to read their temperature.

correction-list (always optional)
A YAML list that specifies temperature offsets for each sensor in use by the
given driver. Use this if you want to use the “simple” level syntax, but need
to compensate for devices with a lower heat tolerance. Note however that the
detailed level syntax is usually the better (i.e. more fine-grained) choice.

bool-allow-errors (always optional, false by default)
A truth value (yes/no/true/false) that specifies whether thinkfan should
accept errors when reading from this sensor. Normally, thinkfan will exit
with an error message if reading the temperature from any configured sensor
fails. Marking a sensor as optional may be useful for removable hardware or
devices that may get switched off entirely to save power.

FAN SPEEDS

The levels: section specifies a list of fan speeds with associated lower and upper
temperature bounds. If temperature(s) drop below the lower bound, thinkfan switches to
the previous level, and if the upper bound is reached, thinkfan switches to the next
level.

Simple Syntax
In the simplified form, only one temperature is specified as an upper/lower limit for a
given fan speed. In that case, the lower-bound and upper-bound are compared only to the
highest temperature found among all configured sensors. All other temperatures are
ignored. This mode is suitable for small systems (like laptops) where there is only one
device (e.g. the CPU) whose temperature needs to be controlled, or where the required fan
behaviour is similar enough for all heat-generating devices.

levels:
- [ fan-speed, lower-bound, upper-bound ]
- ...

Detailed Syntax
This mode is suitable for more complex systems, with devices that have different
temperature ratings. For example, many modern CPUs and GPUs can deal with temperatures
above 80°C on a daily basis, whereas a hard disk will die quickly if it reaches such
temperatures. In detailed mode, upper and lower temperature limits are specified for each
sensor individually:

levels:
- speed: fan-speed
lower_limit: [ l1, l2, ... ]
upper_limit: [ u1, u2, ... ]
- ...

Values
fan-speed The possible speed values are different depending on which fan driver is used.

For a hwmon fan, fan-speed is a numeric value ranging from 0 to 255,
corresponding to the PWM values accepted by the various kernel drivers.

For a tpacpi fan on Lenovo/IBM ThinkPads and some other Lenovo laptops (see
SENSORS & FAN DRIVERS above), numeric values and strings can be used. The
numeric values range from 0 to 7. The string values take the form "level lvl-
id", where lvl-id may be a value from 0 to 7, auto, full-speed or disengaged.
The numeric values 0 to 7 correspond to the regular fan speeds used by the
firmware, although many firmwares don't even use level 7. The value "level
auto" gives control back to the firmware, which may be useful if the fan
behavior only needs to be changed for certain specific temperature ranges
(usually at the high and low end of the range). The values "level full-speed"
and "level disengaged" take the fan speed control away from the firmware,
causing the fan to slowly ramp up to an absolute maximum that can be achieved
within electrical limits. Note that this will run the fan out of
specification and cause increased wear, though it may be helpful to combat
thermal throttling.

l1, l2, ...

u1, u2, ... The lower and upper limits refer to the sensors in the same order in which
they were found when processing the sensors: section (see SENSOR & FAN DRIVERS
above). For the first level entry, the lower_limit may be omitted, and for
the last one, the upper_limit may be omitted. For all levels in between, the
lower limits must overlap with the upper limits of the previous level, to make
sure the entire temperature range is covered and that there is some hysteresis
between speed levels.

BUGS

       Report bugs on the github issue tracker:
       https://github.com/vmatare/thinkfan/issues

NAME

DESCRIPTION

SENSOR & FAN DRIVERS

FAN SPEEDS

SEE ALSO

BUGS