1THINKFAN.CONF(5) File Formats Manual THINKFAN.CONF(5)
2
3
4
6 thinkfan.conf - YAML-formatted config for thinkfan(1)
7
8
9
10
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
18 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
22 The thinkfan config has three main sections:
23
24
25 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
31
32 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
37
38 levels: Maps temperatures to fan speeds. A “simple mapping” just
39 specifies one temperature as the lower and upper bound (re‐
40 spectively) for a given fan speed. In a “detailed mapping”,
41 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
46
47 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
51
52
53
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
60
61
62 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
69 sensors:
70 - hwmon: hwmon-path
71 name: hwmon-name
72 indices: index-list
73 correction: correction-list
74 optional: bool-allow-errors
75
76 - tpacpi: /proc/acpi/ibm/thermal
77 indices: index-list
78 correction: correction-list
79 optional: bool-allow-errors
80
81 - nvml: nvml-bus-id
82 correction: correction-list
83 optional: bool-allow-errors
84
85 - atasmart: disk-device-file
86 correction: correction-list
87 optional: bool-allow-errors
88
89 - ...
90
91
92
93 Fan Syntax
94 Currently, thinkfan supports only one fan, so there can be only one en‐
95 try in the list. Support for multiple fans is currently in development
96 and planned for a future release. The fan is either an hwmon fan:
97
98 fans:
99 - hwmon: hwmon-path
100 name: hwmon-name
101 indices: index-list
102
103 or a tpacpi fan:
104
105 fans:
106 - tpacpi: /proc/acpi/ibm/fan
107
108
109
110 Values
111 hwmon-path There are three ways of specifying hwmon fans or sensors:
112
113
114 1) A full path of a “temp*_input” or “pwm*” file, like
115 “/sys/class/hwmon/hwmon0/pwm1” or “/sys/class/hwmon/hw‐
116 mon0/temp1_input”. In this case, the “indices: index-list”
117 and “name: hwmon-name” entries are unnecessary since the
118 path uniquely identifies a specific fan or sensor.
119
120 Note that this method may lead to problems when the load
121 order of the drivers changes across bootups, because in the
122 “hwmonX” folder name, the X actually corresponds to the
123 load order. Use method 2) or 3) to avoid this problem.
124
125
126 2) A directory that contains a specific hwmon driver, for ex‐
127 ample “/sys/devices/platform/nct6775.2592”. Note that this
128 path does not contain the load-order dependent “hwmonX”
129 folder. As long as it contains only a single hwmon
130 driver/interface it is sufficient to specify the “indices:
131 index-list” entry to tell thinkfan which specific sensors
132 to use from that interface. The “name: hwmon-name” entry
133 is unnecessary.
134
135
136
137 3) A directory that contains multiple or all of the hwmon
138 drivers, for example “/sys/class/hwmon”. Here, both the
139 “name: hwmon-name” and “indices: index-list” entries are
140 required to tell thinkfan which interface to select below
141 that path, and which sensors or which fan to use from that
142 interface.
143
144
145 hwmon-name The name of a hwmon interface, typically found in a file
146 called “name”. This has to be specified if hwmon-path is a
147 base path that contains multiple hwmons. This method of
148 specifying sensors is particularly useful if the full path
149 to a particular hwmon keeps changing between bootups, e.g.
150 due to changing load order of the driver modules.
151
152
153 index-list A YAML list [ X1, X2, ... ] that specifies which sensors,
154 resp. which fan to use from a given interface. Both
155 /proc/acpi/ibm/thermal and also many hwmon interfaces con‐
156 tain multiple sensors, and not all of them may be relevant
157 for fan control.
158
159
160 • For hwmon entries, this is required if hwmon-path does not
161 refer directly to a single “tempXi_input” file, but to a
162 folder that contains one or more of them. In this case,
163 index-list specifies the Xi for the “tempXi_input” files
164 that should be used. A hwmon interface may also contain
165 multiple PWM controls for fans, so in that case, index-list
166 must contain exactly one entry.
167
168
169 • For tpacpi sensors, this entry is optional. If it is omit‐
170 ted, all temperatures found in /proc/acpi/ibm/thermal will
171 be used.
172
173
174 nvml-bus-id NOTE: only available if thinkfan was compiled with USE_NVML
175 enabled.
176
177 The PCI bus ID of an nVidia graphics card that is run with
178 the proprietary nVidia driver. Can be obtained with e.g.
179 “lspci | grep -i vga”. Usually, nVidia cards will use the
180 open source nouveau driver, which should support hwmon sen‐
181 sors instead.
182
183
184 disk-device-file
185 NOTE: only available if thinkfan was compiled with
186 USE_ATASMART enabled.
187
188 Full path to a device file for a hard disk that supports
189 S.M.A.R.T. See also the -d option in thinkfan(1) that pre‐
190 vents thinkfan from waking up sleeping (mechanical) disks
191 to read their temperature.
192
193
194 correction-list (always optional)
195 A YAML list that specifies temperature offsets for each
196 sensor in use by the given driver. Use this if you want to
197 use the “simple” level syntax, but need to compensate for
198 devices with a lower heat tolerance. Note however that the
199 detailed level syntax is usually the better (i.e. more
200 fine-grained) choice.
201
202
203 bool-allow-errors (always optional, false by default)
204 A truth value (yes/no/true/false) that specifies whether
205 thinkfan should accept errors when reading from this sen‐
206 sor. Normally, thinkfan will exit with an error message if
207 reading the temperature from any configured sensor fails.
208 Marking a sensor as optional may be useful for removable
209 hardware or devices that may get switched off entirely to
210 save power.
211
212
213
214
216 The levels: section specifies a list of fan speeds with associated
217 lower and upper temperature bounds. If temperature(s) drop below the
218 lower bound, thinkfan switches to the previous level, and if the upper
219 bound is reached, thinkfan switches to the next level.
220
221
222 Simple Syntax
223 In the simplified form, only one temperature is specified as an up‐
224 per/lower limit for a given fan speed. In that case, the lower-bound
225 and upper-bound are compared only to the highest temperature found
226 among all configured sensors. All other temperatures are ignored.
227 This mode is suitable for small systems (like laptops) where there is
228 only one device (e.g. the CPU) whose temperature needs to be con‐
229 trolled, or where the required fan behaviour is similar enough for all
230 heat-generating devices.
231
232 levels:
233 - [ fan-speed, lower-bound, upper-bound ]
234 - ...
235
236
237
238 Detailed Syntax
239 This mode is suitable for more complex systems, with devices that have
240 different temperature ratings. For example, many modern CPUs and GPUs
241 can deal with temperatures above 80°C on a daily basis, whereas a hard
242 disk will die quickly if it reaches such temperatures. In detailed
243 mode, upper and lower temperature limits are specified for each sensor
244 individually:
245
246 levels:
247 - speed: fan-speed
248 lower_limit: [ l1, l2, ... ]
249 upper_limit: [ u1, u2, ... ]
250 - ...
251
252
253
254 Values
255 fan-speed The possible speed values are different depending on which
256 fan driver is used.
257
258 For a hwmon fan, fan-speed is a numeric value ranging from
259 0 to 255, corresponding to the PWM values accepted by the
260 various kernel drivers.
261
262 For a tpacpi fan on Lenovo/IBM ThinkPads and some other
263 Lenovo laptops (see SENSORS & FAN DRIVERS above), numeric
264 values and strings can be used. The numeric values range
265 from 0 to 7. The string values take the form "level lvl-
266 id", where lvl-id may be a value from 0 to 7, auto, full-
267 speed or disengaged. The numeric values 0 to 7 correspond
268 to the regular fan speeds used by the firmware, although
269 many firmwares don't even use level 7. The value "level
270 auto" gives control back to the firmware, which may be use‐
271 ful if the fan behavior only needs to be changed for cer‐
272 tain specific temperature ranges (usually at the high and
273 low end of the range). The values "level full-speed" and
274 "level disengaged" take the fan speed control away from the
275 firmware, causing the fan to slowly ramp up to an absolute
276 maximum that can be achieved within electrical limits.
277 Note that this will run the fan out of specification and
278 cause increased wear, though it may be helpful to combat
279 thermal throttling.
280
281
282 l1, l2, ...
283
284 u1, u2, ... The lower and upper limits refer to the sensors in the same
285 order in which they were found when processing the sensors:
286 section (see SENSOR & FAN DRIVERS above). For the first
287 level entry, the lower_limit may be omitted, and for the
288 last one, the upper_limit may be omitted. For all levels
289 in between, the lower limits must overlap with the upper
290 limits of the previous level, to make sure the entire tem‐
291 perature range is covered and that there is some hysteresis
292 between speed levels.
293
294
295
297 The thinkfan manpage:
298 thinkfan(1)
299
300 Example configs shipped with the source distribution, also available at:
301 https://github.com/vmatare/thinkfan/tree/master/examples
302
303 The Linux hwmon user interface documentation:
304 https://www.kernel.org/doc/html/latest/hwmon/sysfs-interface.html
305
306 The thinkpad_acpi interface documentation:
307 https://www.kernel.org/doc/html/latest/admin-guide/laptops/thinkpad-acpi.html
308
309
310
312 Report bugs on the github issue tracker:
313 https://github.com/vmatare/thinkfan/issues
314
315
316
317
318thinkfan 1.3.1 December 2021 THINKFAN.CONF(5)