1THINKFAN.CONF(5)              File Formats Manual             THINKFAN.CONF(5)
2
3
4

NAME

6       thinkfan.conf - YAML-formatted config for thinkfan(1)
7
8
9
10

DESCRIPTION

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

SENSOR & FAN DRIVERS

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
139name:  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

FAN SPEEDS

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

SEE ALSO

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

BUGS

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)
Impressum