1THINKFAN.CONF(5) File Formats Manual THINKFAN.CONF(5)
2
6 thinkfan.conf - YAML-formatted config for thinkfan(1)
7
12 YAML is a very powerful, yet concise notation for structured data. Its
13 full specification is available at https://yaml.org/spec/1.2/spec.html.
14 Thinkfan uses only a small subset of the full YAML syntax, so it may be
15 helpful, but not strictly necessary for users to take a look at the
16 spec.
17 The most important thing to note is that indentation is syntactically
19 relevant. In particular, tabs should not be mixed with spaces. We
20 recommend using two spaces for indentation, like it is shown below.
21 The thinkfan config has three main sections:
23 sensors: Where temperatures should be read from. All hwmon-style
26 drivers are supported, as well as /proc/acpi/ibm/thermal,
27 and, depending on the compile-time options, libatasmart (to
28 read temperatures directly from hard disks) and NVML (via
29 the proprietary nvidia driver).
30 fans: Which fans should be used (currently only one allowed).
33 Support for multiple fans is currently in development and
34 planned for a future release. Both hwmon-style PWM controls
35 and /proc/acpi/ibm/fan can be used.
36 levels: Maps temperatures to fan speeds. A “simple mapping” just
39 specifies one temperature as the lower and upper bound
40 (respectively) for a given fan speed. In a “detailed map‐
41 ping”, the upper and lower bounds are specified for each
42 driver/sensor configured under sensors:. This mode should
43 be used when thinkfan is monitoring multiple devices that
44 can tolerate different amounts of heat.
45 Under each of these sections, there must be a list of key-value maps,
48 each of which configures a sensor driver, fan driver or fan speed map‐
49 ping.
50
55 For thinkfan to work, it first needs to know which temperature sensor
56 drivers and which fan drivers it should use. The mapping between tem‐
57 perature readings and fan speeds is specified in a separate config sec‐
58 tion (see the FAN SPEEDS section below).
59 Sensor Syntax
63 The entries under the sensors: section can specify hwmon,
64 thinkpad_acpi, NVML or atasmart drivers, where the latter two must be
65 enabled at compile-time. There can be any number (greater than zero)
66 and combination of hwmon, tpacpi, nvml and atasmart entries. However
67 there may be at most one instance of the tpacpi entry.
68 sensors:
70 - hwmon: hwmon-path
71 name: hwmon-name
72 indices: index-list
73 correction: correction-list
74 optional: bool-allow-errors
75 - tpacpi: /proc/acpi/ibm/thermal
77 indices: index-list
78 correction: correction-list
79 optional: bool-allow-errors
80 - nvml: nvml-bus-id
82 correction: correction-list
83 optional: bool-allow-errors
84 - atasmart: disk-device-file
86 correction: correction-list
87 optional: bool-allow-errors
88 - ...
90 Fan Syntax
94 Currently, thinkfan supports only one fan, so there can be only one
95 entry in the list. Support for multiple fans is currently in develop‐
96 ment and planned for a future release. The fan is either an hwmon fan:
97 fans:
99 - hwmon: hwmon-path
100 name: hwmon-name
101 indices: index-list
102 or a tpacpi fan:
104 fans:
106 - tpacpi: /proc/acpi/ibm/fan
107 Values
111 hwmon-path There are three ways of specifying hwmon fans or sensors:
112 1) A full path of a “temp*_input” or “pwm*” file, like
115 “/sys/class/hwmon/hwmon0/pwm1” or
116 “/sys/class/hwmon/hwmon0/temp1_input”. In this case, the
117 “indices: index-list” and “name: hwmon-name” entries are
118 unncessary since the path uniquely identifies a specific
119 fan or sensor.
120 Note that this method may lead to problems when the load
122 order of the drivers changes across bootups, because in the
123 “hwmonX” folder name, the X actually corresponds to the
124 load order. Use method 2) or 3) to avoid this problem.
125 2) A directory that contains a specific hwmon driver, for
128 example “/sys/devices/platform/nct6775.2592”. Note that
129 this path does not contain the load-order dependent
130 “hwmonX” folder. As long as it contains only a single
131 hwmon driver/interface it is sufficient to specify the
132 “indices: index-list” entry to tell thinkfan which specific
133 sensors to use from that interface. The “name: hwmon-name”
134 entry is unnecessary.
135 3) A directory that contains multiple or all of the hwmon
139 drivers, for example “/sys/class/hwmon”. Here, both the
140 “name: hwmon-name” and “indices: index-list” entries are
141 required to tell thinkfan which interface to select below
142 that path, and which sensors or which fan to use from that
143 interface.
144 hwmon-name The name of a hwmon interface, typically found in a file
147 called “name”. This has to be specified if hwmon-path is a
148 base path that contains multiple hwmons. This method of
149 specifying sensors is particularly useful if the full path
150 to a particular hwmon keeps changing between bootups, e.g.
151 due to changing load order of the driver modules.
152 index-list A YAML list [ X1, X2, ... ] that specifies which sensors,
155 resp. which fan to use from a given interface. Both
156 /proc/acpi/ibm/thermal and also many hwmon interfaces con‐
157 tain multiple sensors, and not all of them may be relevant
158 for fan control.
159 · For hwmon entries, this is required if hwmon-path does not
162 refer directly to a single “tempXi_input” file, but to a
163 folder that contains one or more of them. In this case,
164 index-list specifies the Xi for the “tempXi_input” files
165 that should be used. A hwmon interface may also contain
166 multiple PWM controls for fans, so in that case, index-list
167 must contain exactly one entry.
168 · For tpacpi sensors, this entry is optional. If it is omit‐
171 ted, all temperatures found in /proc/acpi/ibm/thermal will
172 be used.
173 nvml-bus-id NOTE: only available if thinkfan was compiled with USE_NVML
176 enabled.
177 The PCI bus ID of an nVidia graphics card that is run with
179 the proprietary nVidia driver. Can be obtained with e.g.
180 “lspci | grep -i vga”. Usually, nVidia cards will use the
181 open source nouveau driver, which should support hwmon sen‐
182 sors instead.
183 disk-device-file
186 NOTE: only available if thinkfan was compiled with
187 USE_ATASMART enabled.
188 Full path to a device file for a hard disk that supports
190 S.M.A.R.T. See also the -d option in thinkfan(1) that pre‐
191 vents thinkfan from waking up sleeping (mechanical) disks
192 to read their temperature.
193 correction-list (always optional)
196 A YAML list that specifies temperature offsets for each
197 sensor in use by the given driver. Use this if you want to
198 use the “simple” level syntax, but need to compensate for
199 devices with a lower heat tolerance. Note however that the
200 detailed level syntax is usually the better (i.e. more
201 fine-grained) choice.
202 bool-allow-errors (always optional, false by default)
205 A truth value (yes/no/true/false) that specifies whether
206 thinkfan should accept errors when reading from this sen‐
207 sor. Normally, thinkfan will exit with an error message if
208 reading the temperature from any configured sensor fails.
209 Marking a sensor as optional may be useful for removable
210 hardware or devices that may get switched off entirely to
211 save power.
212
217 The levels: section specifies a list of fan speeds with associated
218 lower and upper temperature bounds. If temperature(s) drop below the
219 lower bound, thinkfan switches to the previous level, and if the upper
220 bound is reached, thinkfan switches to the next level.
221 Simple Syntax
224 In the simplified form, only one temperature is specified as an
225 upper/lower limit for a given fan speed. In that case, the lower-bound
226 and upper-bound are compared only to the highest temperature found
227 among all configured sensors. All other temperatures are ignored.
228 This mode is suitable for small systems (like laptops) where there is
229 only one device (e.g. the CPU) whose temperature needs to be con‐
230 trolled, or where the required fan behaviour is similar enough for all
231 heat-generating devices.
232 levels:
234 - [ fan-speed, lower-bound, upper-bound ]
235 - ...
236 Detailed Syntax
240 This mode is suitable for more complex systems, with devices that have
241 different temperature ratings. For example, many modern CPUs and GPUs
242 can deal with temperatures above 80°C on a daily basis, whereas a hard
243 disk will die quickly if it reaches such temperatures. In detailed
244 mode, upper and lower temperature limits are specified for each sensor
245 individually:
246 levels:
248 - speed: fan-speed
249 lower_limit: [ l1, l2, ... ]
250 upper_limit: [ u1, u2, ... ]
251 - ...
252 Values
256 fan-speed The possible speed values are different depending on which
257 fan driver is used.
258 For a hwmon fan, fan-speed is a numeric value ranging from
260 0 to 255, corresponding to the PWM values accepted by the
261 various kernel drivers.
262 For a tpacpi fan on Lenovo/IBM ThinkPads and some other
264 Lenovo laptops (see SENSORS & FAN DRIVERS above), numeric
265 values and strings can be used. The numeric values range
266 from 0 to 7. The string values take the form "level lvl-
267 id", where lvl-id may be a value from 0 to 7, auto, full-
268 speed or disengaged. The numeric values 0 to 7 correspond
269 to the regular fan speeds used by the firmware, although
270 many firmwares don't even use level 7. The value "level
271 auto" gives control back to the firmware, which may be use‐
272 ful if the fan behavior only needs to be changed for cer‐
273 tain specific temperature ranges (usually at the high and
274 low end of the range). The values "level full-speed" and
275 "level disengaged" take the fan speed control away from the
276 firmware, causing the fan to slowly ramp up to an absolute
277 maximum that can be achieved within electrical limits.
278 Note that this will run the fan out of specification and
279 cause increased wear, though it may be helpful to combat
280 thermal throttling.
281 l1, l2, ...
284 u1, u2, ... The lower and upper limits refer to the sensors in the same
286 order in which they were found when processing the sensors:
287 section (see SENSOR & FAN DRIVERS above). For the first
288 level entry, the lower_limit may be omitted, and for the
289 last one, the upper_limit may be omitted. For all levels
290 in between, the lower limits must overlap with the upper
291 limits of the previous level, to make sure the entire tem‐
292 perature range is covered and that there is some hysteresis
293 between speed levels.
294
298 The thinkfan manpage:
299 thinkfan(1)
300 Example configs shipped with the source distribution, also available at:
302 https://github.com/vmatare/thinkfan/tree/master/examples
303 The Linux hwmon user interface documentation:
305 https://www.kernel.org/doc/html/latest/hwmon/sysfs-interface.html
306 The thinkpad_acpi interface documenation:
308 https://www.kernel.org/doc/html/latest/admin-guide/laptops/thinkpad-acpi.html
309
313 Report bugs on the github issue tracker:
314 https://github.com/vmatare/thinkfan/issues
315thinkfan 1.2 April 2020 THINKFAN.CONF(5)