Debian Codegraph @

upstream/debian-unstable/man5/thinkfan.conf.5

raw
1 .TH THINKFAN.CONF 5 "November 2022" "thinkfan 2.0.0"
2 .SH NAME
3 thinkfan.conf \- YAML-formatted config for
4 .BR thinkfan (1)
5
6
7
8 .SH DESCRIPTION
9
10 YAML is a very powerful, yet concise notation for structured data.
11 Its full specification is available at https://yaml.org/spec/1.2/spec.html.
12 Thinkfan uses only a small subset of the full YAML syntax, so it may be helpful,
13 but not strictly necessary for users to take a look at the spec.
14
15 The most important thing to note is that indentation is syntactically relevant.
16 In particular, tabs should not be mixed with spaces.
17 We recommend using two spaces for indentation, like it is shown below.
18
19 The thinkfan config has three main sections:
20
21 .TP
22 .B sensors:
23 Where temperatures should be read from. All
24 .BR hwmon -style
25 drivers are supported, as well as
26 .BR /proc/acpi/ibm/thermal ,
27 and, depending on the compile-time options,
28 .B libatasmart
29 (to read temperatures directly from hard disks) and
30 .B NVML
31 (via the proprietary nvidia driver).
32
33 .TP
34 .B fans:
35 Which fans should be used (currently only one allowed).
36 Support for multiple fans is currently in development and planned for a future
37 release.
38 Both
39 .BR hwmon -style
40 PWM controls and
41 .B /proc/acpi/ibm/fan
42 can be used.
43
44 .TP
45 .B levels:
46 Maps temperatures to fan speeds.
47 A \*(lqsimple mapping\*(rq just specifies one temperature as the lower and
48 upper bound (respectively) for a given fan speed.
49 In a \*(lqdetailed mapping\*(rq, the upper and lower bounds are specified for
50 each driver/sensor configured under
51 .BR sensors: .
52 This mode should be used when thinkfan is monitoring multiple devices that can
53 tolerate different amounts of heat.
54
55 .PP
56 Under each of these sections, there must be a list of key-value maps, each of
57 which configures a sensor driver, fan driver or fan speed mapping.
58
59
60 .SH SENSOR & FAN DRIVERS
61
62 For thinkfan to work, it first needs to know which temperature sensor drivers
63 and which fan drivers it should use.
64 The mapping between temperature readings and fan speeds is specified in a
65 separate config section (see the
66 .B FAN SPEEDS
67 section below).
68
69 .SS Sensor Syntax
70
71 The entries under the
72 .B sensors:
73 section can specify sysfs/hwmon, lm_sensors, thinkpad_acpi, NVML or atasmart drivers.
74 Support for lm_sensors, NVML and atasmart requires the appropriate libraries
75 and must have been enabled at compile time.
76 There can be any number (greater than zero) and combination of
77 .BR hwmon ,
78 .BR tpacpi ,
79 .BR nvml
80 and
81 .BR atasmart
82 entries.
83 However there may be at most one instance of the
84 .BR tpacpi
85 entry.
86
87 The syntax for identifying each type of sensors looks as follows:
88
89 .nf
90 \f[C]
91 ########
92 \f[CB]sensors:
93 \f[CB] \- hwmon: \f[CI]hwmon-path\f[CR] # A path to a sysfs/hwmon sensor
94 \f[CB] name: \f[CI]hwmon-name\f[CR] # Optional entry
95 \f[CB] model: \f[CI]hwmon-model\f[CR] # Optional entry for nvme
96 \f[CB] indices: \f[CI]index-list\f[CR] # Optional entry
97
98 \f[CB] \- chip: \f[CI]chip-name\f[CR] # An lm_sensors/libsensors chip...
99 \f[CB] ids: \f[CI]id-list\f[CR] # ... with some feature IDs
100
101 \f[CB] \- tpacpi: /proc/acpi/ibm/thermal\f[CR] # Provided by the thinkpad_acpi kernel module
102 \f[CB] indices: \f[CI]index-list\f[CR] # Optional entry
103
104 \f[CB] \- nvml: \f[CI]nvml-bus-id\f[CR] # Uses the proprietary nVidia driver
105
106 \f[CB] \- atasmart: \f[CI]disk-device-file\f[CR] # Requires libatasmart support
107
108 \f[CB] \- \f[CR]...
109 \fR
110 .fi
111
112 Additionally, each sensor entry can have a number of settings that modify its
113 behavior:
114
115 .nf
116 \fC
117 ########
118 \f[CB]sensors:
119 \f[CB] \- \f[CR]...\f[CB]: \f[CR]... # A sensor specification as shown above
120 \f[CB] correction: \f[CI]correction-list\f[CR] # Optional entry
121 \f[CB] optional: \f[CI]bool-ignore-errors\f[CR] # Optional entry
122 \f[CB] max_errors: \f[CI]num-max-errors\f[CR] # Optional entry
123 \fR
124 .fi
125
126
127 .SS Fan Syntax
128
129 Since version 2.0, thinkfan can control multiple fans.
130 So any number of
131 .B hwmon
132 fan sections can be specified.
133 Note however that the thinkpad_acpi kernel module only supports one fan, so
134 there can be at most one
135 .B tpacpi
136 section:
137
138 .nf
139 \fC
140 # ...
141 \f[CB]fans:
142 \f[CB] \- tpacpi: /proc/acpi/ibm/fan
143
144 \f[CB] \- hwmon: \f[CI]hwmon-path
145 \f[CB] name: \f[CI]hwmon-name
146 \f[CB] indices: \f[CI]index-list
147
148 \f[CB] \- \f[CR]...
149 \fR
150 .fi
151
152 The behavior of any fan can optionally be controlled with the \fBoptional\fR
153 and \fBmax_errors\fR keywords, and by specifying a local fan speed config
154 under the \fBlevels:\fR keyword:
155
156 .nf
157 \fC
158 # ...
159 \f[CB]fans:
160 \f[CB] \- \f[CR]...\f[CB]: \f[CR] ... # A fan specification as shown above
161 \f[CB] optional: \f[CI]bool-ignore-errors\f[CR] # Optional entry
162 \f[CB] max_errors: \f[CI]num-max-errors\f[CR] # Optional entry
163 \f[CB] levels: \f[CI]levels-section\f[CR] # Optional entry
164
165
166 .SS Values
167
168 .TP
169 .I hwmon-path
170 There are three ways of specifying hwmon fans or sensors:
171
172 .RS
173 .IP 1) 3
174 A full path of a \*(lqtemp*_input\*(rq or \*(lqpwm*\*(rq file, like
175 \*(lq/sys/class/hwmon/hwmon0/pwm1\*(rq or
176 \*(lq/sys/class/hwmon/hwmon0/temp1_input\*(rq.
177 In this case, the \*(lq\c
178 .BI indices: " index-list"\c
179 \*(rq and \*(lq\c
180 .BI name: " hwmon-name"\c
181 \*(rq entries are unnecessary since the path uniquely identifies a specific fan or
182 sensor.
183
184 .RS
185 Note that this method may lead to problems when the load order of the drivers
186 changes across bootups, because in the \*(lqhwmon\fIX\fR\*(rq folder name, the
187 .I X
188 actually corresponds to the load order.
189 Use method 2) or 3) to avoid this problem.
190 .RE
191
192 .IP 2) 3
193 A directory that contains a specific hwmon driver, for example
194 \*(lq/sys/devices/platform/nct6775.2592\*(rq.
195 Note that this path does not contain the load-order dependent
196 \*(lqhwmon\fIX\fR\*(rq folder.
197 As long as it contains only a single hwmon driver/interface it is sufficient to
198 specify the
199 \*(lq\c
200 .BI indices: " index-list"\c
201 \*(rq
202 entry to tell thinkfan which specific sensors to use from that interface.
203 The
204 \*(lq\c
205 .BI name: " hwmon-name"\c
206 \*(rq
207 entry is unnecessary.
208
209 .P
210 .IP 3) 3
211 A directory that contains multiple or all of the hwmon drivers, for example
212 \*(lq/sys/class/hwmon\*(rq.
213 Here, both the \*(lq\c
214 .BI name: " hwmon-name"\c
215 \*(rq and \*(lq\c
216 .BI indices: " index-list"\c
217 \*(rq entries are required to tell thinkfan which interface to select below that
218 path, and which sensors or which fan to use from that interface.
219
220 .RE
221 .TP
222 .I hwmon-name
223 The name of a hwmon interface, typically found in a file called \*(lqname\*(rq.
224 This has to be specified if
225 .I hwmon-path
226 is a base path that contains multiple hwmons.
227 This method of specifying sensors is particularly useful if the full path to a
228 particular hwmon keeps changing between bootups, e.g. due to changing load order
229 of the driver modules.
230
231 .TP
232 .I hwmon-model
233 The model of a device in a hwmon interface usually found for NVME devices in a
234 file under \*(lqdevice\*(rq called \*(lqmodel\*(rq.
235 For example, you might have an NVME \*(lq/sys/class/hwmon/hwmon3/device/model\*(rq
236 and you might have an external NVME over USB or Thunderbolt that you don't want
237 to monitor or you might have two NVME's.
238
239 .TP
240 .I index-list
241 A YAML list
242 .BI "[ " X1 ", " X2 ", " "\fR...\fB ]"
243 that specifies which sensors, resp. which fan to use from a given
244 interface.
245 Both
246 .B /proc/acpi/ibm/thermal
247 and also many hwmon interfaces contain multiple sensors, and not
248 all of them may be relevant for fan control.
249
250 .RS
251 .IP \(bu 2
252 For
253 .B hwmon
254 entries, this is required if
255 .I hwmon-path
256 does not refer directly to a single \*(lqtemp\fIXi\fR_input\*(rq file, but to a folder
257 that contains one or more of them.
258 In this case,
259 .I index-list
260 specifies the
261 .I Xi
262 for the \*(lqtemp\fIXi\fR_input\*(rq files that should be used.
263 A hwmon interface may also contain multiple PWM controls for fans, so in that case,
264 .I index-list
265 must contain exactly one entry.
266
267 .IP \(bu
268 For
269 .B tpacpi
270 sensors, this entry is optional.
271 If it is omitted, all temperatures found in
272 .B /proc/acpi/ibm/thermal
273 will be used.
274 .RE
275
276 .TP
277 .I chip-name
278 The unique name of an lm-sensors hwmon chip. lm-sensors or libsensors is the
279 official client library to access the sysfs hwmon subsystem, and as such it is
280 the preferred way of specifying sensors.
281 Available chips can be listed by running the \fBsensors\fR command as root.
282 The header above each block will be the chip name.
283
284 .TP
285 .I ids
286 A list of lm-sensors feature IDs, for example \*(lq\fB[ SYSTIN, CPUTIN, "Sensor 2"
287 ]\fR\*(rq.
288 In the \fBsensors\fR command output, the name before the colon on each line
289 will be the feature ID.
290
291 .TP
292 .I nvml-bus-id
293 NOTE: only available if thinkfan was compiled with USE_NVML enabled.
294
295 The PCI bus ID of an nVidia graphics card that is run with the proprietary
296 nVidia driver. Can be obtained with e.g. \*(lqlspci | grep \-i vga\*(rq.
297 Usually, nVidia cards will use the open source
298 .B nouveau
299 driver, which should support hwmon sensors instead.
300
301 .TP
302 .I disk-device-file
303 NOTE: only available if thinkfan was compiled with USE_ATASMART enabled.
304
305 Full path to a device file for a hard disk that supports S.M.A.R.T.
306 See also the
307 .B \-d
308 option in
309 .BR thinkfan (1)
310 that prevents thinkfan from waking up sleeping (mechanical) disks to read their
311 temperature.
312
313 .TP
314 .IR correction-list " (optional, zeroes by default)"
315 A YAML list that specifies temperature offsets for each sensor in use by the
316 given driver. Use this if you want to use the \*(lqsimple\*(rq level syntax,
317 but need to compensate for devices with a lower heat tolerance.
318 Note however that the detailed level syntax is usually the better (i.e. more
319 fine-grained) choice.
320
321 .TP
322 .IR bool-ignore-errors " (optional, \fBfalse\fR by default)"
323 A truth value
324 .RB ( yes / no / true / false )
325 that specifies whether thinkfan should ignore all errors when using a given
326 sensor or fan.
327 Normally, thinkfan will exit with an error message if it fails reading
328 temperatures from a sensor or writing to a fan.
329
330 An optional device will not delay startup.
331 Instead, thinkfan will commence normal operation with the remaining devices and
332 re-try initializing unavailable optional devices in every loop until all are
333 found.
334
335 Marking a sensor/fan as optional may be useful for removable hardware or devices
336 that may get switched off entirely to save power.
337
338 .TP
339 .IR num-max-errors " (optional, \fB0\fR by default)"
340 A positive integer that specifies how often thinkfan is allowed to re-try if
341 if fails to initialize, read from or write to a given sensor or fan.
342 On startup, thinkfan will attempt to initialize the device \fInum-max-errors\fR
343 times before commencing normal operation.
344 If the device cannot be initialized after the given number of attempts,
345 thinkfan will fail.
346
347 When a device with a positive \fInum-max-errors\fR fails during runtime,
348 thinkfan will likewise attempt to re-initialize it the given number of times
349 before failing.
350
351 .TP
352 .IR levels-section " (optional, use global levels section by default)"
353 As of thinkfan 2.0, multiple fans can be configured.
354 To this end, each fan can now have its own \fBlevels:\fR section (cf. FAN
355 SPEEDS below).
356 The syntax of the global vs. the fan-specific \fBlevels:\fR section are
357 identical, the only difference being that in a fan-specific one, the speed
358 value(s) refer only the fans configured in that particular \fBfans:\fR entry.
359
360 NOTE: Global and fan-specific \fBlevels:\fR are mutually exclusive, i.e.
361 there cannot be both a global one and fan-specific sections.
362
363
364 .SH FAN SPEEDS
365
366 The
367 .B levels:
368 section specifies a list of fan speeds with associated lower and upper
369 temperature bounds.
370 If temperature(s) drop below the lower bound, thinkfan switches to the previous
371 level, and if the upper bound is reached, thinkfan switches to the next level.
372
373 Since thinkfan 2.0, this section can appear either under an individual fan
374 (cf. \fBlevels:\fR keyword under \fBFan Syntax\fR), or globally.
375
376 .SS Simple Syntax
377 In the simplified form, only one temperature is specified as an upper/lower
378 limit for a given fan speed.
379 In that case, the
380 .I lower-bound
381 and
382 .I upper-bound
383 are compared only to the highest temperature found among all configured sensors.
384 All other temperatures are ignored.
385 This mode is suitable for small systems (like laptops) where there is only one
386 device (e.g. the CPU) whose temperature needs to be controlled, or where the
387 required fan behaviour is similar enough for all heat-generating devices.
388
389 .nf
390 \fC
391 # ...
392 \f[CB]levels:
393 \f[CB] \- [ \f[CI]fan-speed\f[CB], \f[CI]lower-bound\f[CB], \f[CI]upper-bound\f[CB] ]
394 \f[CB] \- \f[CR]...
395 \fR
396 .fi
397
398
399 .SS Detailed Syntax
400 This mode is suitable for more complex systems, with devices that have
401 different temperature ratings.
402 For example, many modern CPUs and GPUs can deal with temperatures above
403 80\[char176]C on a daily basis, whereas a hard disk will die quickly if it
404 reaches such temperatures.
405 In detailed mode, upper and lower temperature limits are specified for each
406 sensor individually:
407
408 .nf
409 \fC
410 # ...
411 \f[CB]levels:
412 \f[CB] \- speed: [ \f[CI]fan1-speed\f[CB], \f[CI]fan2-speed\f[CB], \f[CR]...\f[CB] ]
413 \f[CB] lower_limit: [ \f[CI]l1\f[CB], \f[CI]l2\f[CB], \f[CR]...\f[CB] ]
414 \f[CB] upper_limit: [ \f[CI]u1\f[CB], \f[CI]u2\f[CB], \f[CR]...\f[CB] ]
415 \f[CB] \- \f[CR]...\f[CB]
416 \fR
417 .fi
418
419
420 .SS Values
421
422 .TP
423 .IB fan1-speed ", " fan2-speed ", " \fR...
424 .TP
425 .I fan-speed
426 When multiple fans are specified under the
427 .B fans:
428 section, value of the
429 .B speed:
430 keyword must be a list of as many
431 .I fanX-speed
432 values.
433 They are applied to the fans by their order of appearance, i.e. the first
434 speed value applies to the fan that has been specified first, the second value
435 to the second fan, and so on.
436 If there is just one fan, instead of a list with just one element, the speed
437 value can be given as a scalar.
438
439 The possible speed values for
440 .B fanX-speed
441 are different depending on which fan driver is used:
442
443 .RS
444 .IP \(bu 3
445 For a
446 .B hwmon
447 fan,
448 .I fanX-speed
449 is a numeric value ranging from
450 .B 0
451 to
452 .BR 255 ,
453 corresponding to the PWM values accepted by the various kernel drivers.
454
455 .IP \(bu
456 For a
457 .B tpacpi
458 fan on Lenovo/IBM ThinkPads and some other Lenovo laptops (see \fBSENSORS & FAN
459 DRIVERS\fR above), numeric values and strings can be used.
460 The numeric values range from 0 to 7.
461 The string values take the form \fB"level \fIlvl-id\fB"\fR, where
462 .I lvl-id
463 may be a value from
464 .BR 0 " to " 7 ,
465 .BR auto ,
466 .B full-speed
467 or
468 .BR disengaged .
469 The numeric values
470 .BR 0 " to " 7
471 correspond to the regular fan speeds used by the firmware, although many
472 firmwares don't even use level \fB7\fR.
473 The value \fB"level auto"\fR gives control back to the firmware, which may be
474 useful if the fan behavior only needs to be changed for certain specific
475 temperature ranges (usually at the high and low end of the range).
476 The values \fB"level full-speed"\fR and \fB"level disengaged"\fR take the fan
477 speed control away from the firmware, causing the fan to slowly ramp up to an
478 absolute maximum that can be achieved within electrical limits.
479 Note that this will run the fan out of specification and cause increased wear,
480 though it may be helpful to combat thermal throttling.
481 .RE
482
483 .TP
484 .IB l1 ", " l2 ", " \fR...
485 .TP
486 .IB u1 ", " u2 ", " \fR...
487 The lower and upper temperature limits refer to the sensors in the same order
488 in which they were found when processing the
489 .B sensors:
490 section (see
491 .B SENSOR & FAN DRIVERS
492 above).
493 For the first level entry, the
494 .B lower_limit
495 may be omitted, and for the last one, the
496 .B upper_limit
497 may be omitted.
498 For all levels in between, the lower limits must overlap with the upper limits
499 of the previous level, to make sure the entire temperature range is covered and
500 that there is some hysteresis between speed levels.
501
502 Instead of a temperature, an underscore (\fB_\fR) can be given.
503 An underscore means that the temperature of that sensor should be ignored at
504 the given speed level.
505
506
507 .SH SEE ALSO
508 The thinkfan manpage:
509 .BR thinkfan (1)
510
511 .nf
512 Example configs shipped with the source distribution, also available at:
513 .UR https://github.com/vmatare/thinkfan/tree/master/examples
514 .UE
515 .fi
516
517 .nf
518 The Linux hwmon user interface documentation:
519 .UR https://www.kernel.org/doc/html/latest/hwmon/sysfs\-interface.html
520 .UE
521 .fi
522
523 .nf
524 The thinkpad_acpi interface documentation:
525 .UR https://www.kernel.org/doc/html/latest/admin\-guide/laptops/thinkpad\-acpi.html
526 .UE
527 .fi
528
529 .SH BUGS
530
531 .nf
532 Report bugs on the github issue tracker:
533 .UR https://github.com/vmatare/thinkfan/issues
534 .UE
535 .fi
536