1 What: /sys/class/firmware-attributes 1 What: /sys/class/firmware-attributes/*/attributes/*/
2 Date: February 2021 2 Date: February 2021
3 KernelVersion: 5.11 3 KernelVersion: 5.11
4 Contact: Divya Bharathi <Divya.Bharathi@ 4 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
5 Prasanth KSR <prasanth.ksr@dell 5 Prasanth KSR <prasanth.ksr@dell.com>
6 Dell.Client.Kernel@dell.com 6 Dell.Client.Kernel@dell.com
7 Description: 7 Description:
8 A sysfs interface for systems 8 A sysfs interface for systems management software to enable
9 configuration capability on su 9 configuration capability on supported systems. This directory
10 exposes interfaces for interac 10 exposes interfaces for interacting with configuration options.
11 11
12 Unless otherwise specified in 12 Unless otherwise specified in an attribute description all attributes are optional
13 and will accept UTF-8 input. 13 and will accept UTF-8 input.
14 14
15 type: 15 type:
16 A file that can be read to 16 A file that can be read to obtain the type of attribute.
17 This attribute is mandator 17 This attribute is mandatory.
18 18
19 The following are known types: 19 The following are known types:
20 20
21 - enumeration: a set o 21 - enumeration: a set of pre-defined valid values
22 - integer: a range of 22 - integer: a range of numerical values
23 - string 23 - string
24 24
25 HP specific types <<
26 ----------------- <<
27 - ordered-list - a set <<
28 <<
29 <<
30 All attribute types support th 25 All attribute types support the following values:
31 26
32 current_value: 27 current_value:
33 A file that ca 28 A file that can be read to obtain the current
34 value of the < 29 value of the <attr>.
35 30
36 This file can 31 This file can also be written to in order to update the value of a
37 <attr> 32 <attr>
38 33
39 This attribute 34 This attribute is mandatory.
40 35
41 default_value: 36 default_value:
42 A file that ca 37 A file that can be read to obtain the default
43 value of the < 38 value of the <attr>
44 39
45 display_name: 40 display_name:
46 A file that ca 41 A file that can be read to obtain a user friendly
47 description of 42 description of the at <attr>
48 43
49 display_name_language_code: 44 display_name_language_code:
50 45 A file that can be read to obtain
51 46 the IETF language tag corresponding to the
52 47 "display_name" of the <attr>
53 48
54 "enumeration"-type specific pr 49 "enumeration"-type specific properties:
55 50
56 possible_values: 51 possible_values:
57 A file 52 A file that can be read to obtain the possible
58 values 53 values of the <attr>. Values are separated using
59 semi-c 54 semi-colon (``;``).
60 55
61 "integer"-type specific proper 56 "integer"-type specific properties:
62 57
63 min_value: 58 min_value:
64 A file that ca 59 A file that can be read to obtain the lower
65 bound value of 60 bound value of the <attr>
66 61
67 max_value: 62 max_value:
68 A file that ca 63 A file that can be read to obtain the upper
69 bound value of 64 bound value of the <attr>
70 65
71 scalar_increment: 66 scalar_increment:
72 A file 67 A file that can be read to obtain the scalar value used for
73 increm 68 increments of current_value this attribute accepts.
74 69
75 "string"-type specific propert 70 "string"-type specific properties:
76 71
77 max_length: 72 max_length:
78 A file that ca 73 A file that can be read to obtain the maximum
79 length value o 74 length value of the <attr>
80 75
81 min_length: 76 min_length:
82 A file that ca 77 A file that can be read to obtain the minimum
83 length value o 78 length value of the <attr>
84 79
85 Dell specific class extensions 80 Dell specific class extensions
86 ------------------------------ 81 ------------------------------
87 82
88 On Dell systems the following 83 On Dell systems the following additional attributes are available:
89 84
90 dell_modifier: 85 dell_modifier:
91 A file that ca 86 A file that can be read to obtain attribute-level
92 dependency rul 87 dependency rule. It says an attribute X will become read-only or
93 suppressed, if 88 suppressed, if/if-not attribute Y is configured.
94 89
95 modifier rules 90 modifier rules can be in following format::
96 91
97 [ReadOnlyI 92 [ReadOnlyIf:<attribute>=<value>]
98 [ReadOnlyI 93 [ReadOnlyIfNot:<attribute>=<value>]
99 [SuppressI 94 [SuppressIf:<attribute>=<value>]
100 [SuppressI 95 [SuppressIfNot:<attribute>=<value>]
101 96
102 For example:: 97 For example::
103 98
104 AutoOnFri/ 99 AutoOnFri/dell_modifier has value,
105 [S 100 [SuppressIfNot:AutoOn=SelectDays]
106 101
107 This means Aut 102 This means AutoOnFri will be suppressed in BIOS setup if AutoOn
108 attribute is n 103 attribute is not "SelectDays" and its value will not be effective
109 through sysfs 104 through sysfs until this rule is met.
110 105
111 Enumeration attributes also su 106 Enumeration attributes also support the following:
112 107
113 dell_value_modifier: 108 dell_value_modifier:
114 A file 109 A file that can be read to obtain value-level dependency.
115 This f 110 This file is similar to dell_modifier but here, an
116 attrib 111 attribute's current value will be forcefully changed based
117 depend 112 dependent attributes value.
118 113
119 dell_v 114 dell_value_modifier rules can be in following format::
120 115
121 <v 116 <value>[ForceIf:<attribute>=<value>]
122 <v 117 <value>[ForceIfNot:<attribute>=<value>]
123 118
124 For ex 119 For example::
125 120
126 Le 121 LegacyOrom/dell_value_modifier has value:
127 122 Disabled[ForceIf:SecureBoot=Enabled]
128 123
129 This m 124 This means LegacyOrom's current value will be forced to
130 "Disab 125 "Disabled" in BIOS setup if SecureBoot is Enabled and its
131 value 126 value will not be effective through sysfs until this rule is
132 met. 127 met.
133 128
134 HP specific class extensions <<
135 ------------------------------ <<
136 <<
137 On HP systems the following ad <<
138 <<
139 "ordered-list"-type specific p <<
140 <<
141 elements: <<
142 A file <<
143 list o <<
144 semi-c <<
145 An ele <<
146 the li <<
147 the pr <<
148 <<
149 What: /sys/class/firmware-attributes 129 What: /sys/class/firmware-attributes/*/authentication/
150 Date: February 2021 130 Date: February 2021
151 KernelVersion: 5.11 131 KernelVersion: 5.11
152 Contact: Divya Bharathi <Divya.Bharathi@ 132 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
153 Prasanth KSR <prasanth.ksr@dell 133 Prasanth KSR <prasanth.ksr@dell.com>
154 Dell.Client.Kernel@dell.com 134 Dell.Client.Kernel@dell.com
155 Description: 135 Description:
156 Devices support various authen 136 Devices support various authentication mechanisms which can be exposed
157 as a separate configuration ob 137 as a separate configuration object.
158 138
159 For example a "BIOS Admin" pas 139 For example a "BIOS Admin" password and "System" Password can be set,
160 reset or cleared using these a 140 reset or cleared using these attributes.
161 141
162 - An "Admin" password is used 142 - An "Admin" password is used for preventing modification to the BIOS
163 settings. 143 settings.
164 - A "System" password is requi 144 - A "System" password is required to boot a machine.
165 145
166 Change in any of these two aut 146 Change in any of these two authentication methods will also generate an
167 uevent KOBJ_CHANGE. 147 uevent KOBJ_CHANGE.
168 148
169 is_enabled: 149 is_enabled:
170 A file 150 A file that can be read to obtain a 0/1 flag to see if
171 <attr> 151 <attr> authentication is enabled.
172 This a 152 This attribute is mandatory.
173 153
174 role: 154 role:
175 The ty 155 The type of authentication used.
176 This a 156 This attribute is mandatory.
177 157
178 Known 158 Known types:
179 159 bios-admin:
180 160 Representing BIOS administrator password
181 161 power-on:
182 162 Representing a password required to use
183 163 the system
184 164 system-mgmt:
185 165 Representing System Management password.
186 166 See Lenovo extensions section for details
187 167 HDD:
188 168 Representing HDD password
189 169 See Lenovo extensions section for details
190 170 NVMe:
191 171 Representing NVMe password
192 172 See Lenovo extensions section for details
193 173
194 mechanism: 174 mechanism:
195 The me 175 The means of authentication. This attribute is mandatory.
196 Only s 176 Only supported type currently is "password".
197 177
198 max_password_length: 178 max_password_length:
199 A file 179 A file that can be read to obtain the
200 maximu 180 maximum length of the Password
201 181
202 min_password_length: 182 min_password_length:
203 A file 183 A file that can be read to obtain the
204 minimu 184 minimum length of the Password
205 185
206 current_password: 186 current_password:
207 A writ 187 A write only value used for privileged access such as
208 settin 188 setting attributes when a system or admin password is set
209 or res 189 or resetting to a new password
210 190
211 This a 191 This attribute is mandatory when mechanism == "password".
212 192
213 new_password: 193 new_password:
214 A writ 194 A write only value that when used in tandem with
215 curren 195 current_password will reset a system or admin password.
216 196
217 Note, password management is s 197 Note, password management is session specific. If Admin password is set,
218 same password must be written 198 same password must be written into current_password file (required for
219 password-validation) and must 199 password-validation) and must be cleared once the session is over.
220 For example:: 200 For example::
221 201
222 echo "password" > curr 202 echo "password" > current_password
223 echo "disabled" > Touc 203 echo "disabled" > TouchScreen/current_value
224 echo "" > current_pass 204 echo "" > current_password
225 205
226 Drivers may emit a CHANGE ueve 206 Drivers may emit a CHANGE uevent when a password is set or unset
227 userspace may check it again. 207 userspace may check it again.
228 208
229 On Dell, Lenovo and HP systems !! 209 On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes
230 require password validation. 210 require password validation.
231 On Lenovo systems if you chang 211 On Lenovo systems if you change the Admin password the new password is not active until
232 the next boot. 212 the next boot.
233 213
234 Lenovo specific class extensio 214 Lenovo specific class extensions
235 ------------------------------ 215 --------------------------------
236 216
237 On Lenovo systems the followin 217 On Lenovo systems the following additional settings are available:
238 218
239 role: system-mgmt This g 219 role: system-mgmt This gives the same authority as the bios-admin password to control
240 securi 220 security related features. The authorities allocated can be set via
241 the BI 221 the BIOS menu SMP Access Control Policy
242 222
243 role: HDD & NVMe This p 223 role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see
244 'level 224 'level' and 'index' extensions below.
245 225
246 lenovo_encoding: 226 lenovo_encoding:
247 The en 227 The encoding method that is used. This can be either "ascii"
248 or "sc 228 or "scancode". Default is set to "ascii"
249 229
250 lenovo_kbdlang: 230 lenovo_kbdlang:
251 The ke 231 The keyboard language method that is used. This is generally a
252 two ch 232 two char code (e.g. "us", "fr", "gr") and may vary per platform.
253 Defaul 233 Default is set to "us"
254 234
255 level: 235 level:
256 Availa 236 Available for HDD and NVMe authentication to set 'user' or 'master'
257 privil 237 privilege level.
258 If onl 238 If only the user password is configured then this should be used to
259 unlock 239 unlock the drive at boot. If both master and user passwords are set
260 then e 240 then either can be used. If a master password is set a user password
261 is req 241 is required.
262 This a 242 This attribute defaults to 'user' level
263 243
264 index: 244 index:
265 Used w 245 Used with HDD and NVME authentication to set the drive index
266 that i 246 that is being referenced (e.g hdd1, hdd2 etc)
267 This a 247 This attribute defaults to device 1.
268 248
269 certificate, signature, save_s 249 certificate, signature, save_signature:
270 These 250 These attributes are used for certificate based authentication. This is
271 used i 251 used in conjunction with a signing server as an alternative to password
272 based 252 based authentication.
273 The us 253 The user writes to the attribute(s) with a BASE64 encoded string obtained
274 from t 254 from the signing server.
275 The at 255 The attributes can be displayed to check the stored value.
276 256
277 Some u 257 Some usage examples:
278 258
279 259 Installing a certificate to enable feature::
280 260
281 261 echo "supervisor password" > authentication/Admin/current_password
282 262 echo "signed certificate" > authentication/Admin/certificate
283 263
284 264 Updating the installed certificate::
285 265
286 266 echo "signature" > authentication/Admin/signature
287 267 echo "signed certificate" > authentication/Admin/certificate
288 268
289 269 Removing the installed certificate::
290 270
291 271 echo "signature" > authentication/Admin/signature
292 272 echo "" > authentication/Admin/certificate
293 273
294 274 Changing a BIOS setting::
295 275
296 276 echo "signature" > authentication/Admin/signature
297 277 echo "save signature" > authentication/Admin/save_signature
298 278 echo Enable > attribute/PasswordBeep/current_value
299 279
300 You ca 280 You cannot enable certificate authentication if a supervisor password
301 has no 281 has not been set.
302 Cleari 282 Clearing the certificate results in no bios-admin authentication method
303 being 283 being configured allowing anyone to make changes.
304 After 284 After any of these operations the system must reboot for the changes to
305 take e 285 take effect.
306 286
307 certificate_thumbprint: 287 certificate_thumbprint:
308 Read o 288 Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints
309 for th 289 for the certificate installed in the BIOS.
310 290
311 certificate_to_password: 291 certificate_to_password:
312 Write 292 Write only attribute used to switch from certificate based authentication
313 back t 293 back to password based.
314 Usage: 294 Usage::
315 295
316 296 echo "signature" > authentication/Admin/signature
317 297 echo "password" > authentication/Admin/certificate_to_password
318 298
319 HP specific class extensions <<
320 ------------------------------ <<
321 <<
322 On HP systems the following ad <<
323 <<
324 role: enhanced-bios-auth: <<
325 This r <<
326 It req <<
327 <<
328 299
329 What: /sys/class/firmware-attributes 300 What: /sys/class/firmware-attributes/*/attributes/pending_reboot
330 Date: February 2021 301 Date: February 2021
331 KernelVersion: 5.11 302 KernelVersion: 5.11
332 Contact: Divya Bharathi <Divya.Bharathi@ 303 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
333 Prasanth KSR <prasanth.ksr@dell 304 Prasanth KSR <prasanth.ksr@dell.com>
334 Dell.Client.Kernel@dell.com 305 Dell.Client.Kernel@dell.com
335 Description: 306 Description:
336 A read-only attribute reads 1 307 A read-only attribute reads 1 if a reboot is necessary to apply
337 pending BIOS attribute changes 308 pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
338 generated when it changes to 1 309 generated when it changes to 1.
339 310
340 == ============== 311 == =========================================
341 0 All BIOS attri 312 0 All BIOS attributes setting are current
342 1 A reboot is ne 313 1 A reboot is necessary to get pending BIOS
343 attribute chan !! 314 attribute changes applied
344 == ============== 315 == =========================================
345 316
346 Note, userspace applications n 317 Note, userspace applications need to follow below steps for efficient
347 BIOS management, 318 BIOS management,
348 319
349 1. Check if admin passwor 320 1. Check if admin password is set. If yes, follow session method for
350 password management as 321 password management as briefed under authentication section above.
351 2. Before setting any att 322 2. Before setting any attribute, check if it has any modifiers
352 or value_modifiers. If 323 or value_modifiers. If yes, incorporate them and then modify
353 attribute. 324 attribute.
354 325
355 Drivers may emit a CHANGE ueve 326 Drivers may emit a CHANGE uevent when this value changes and userspace
356 may check it again. 327 may check it again.
357 328
358 What: /sys/class/firmware-attributes 329 What: /sys/class/firmware-attributes/*/attributes/reset_bios
359 Date: February 2021 330 Date: February 2021
360 KernelVersion: 5.11 331 KernelVersion: 5.11
361 Contact: Divya Bharathi <Divya.Bharathi@ 332 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
362 Prasanth KSR <prasanth.ksr@dell 333 Prasanth KSR <prasanth.ksr@dell.com>
363 Dell.Client.Kernel@dell.com 334 Dell.Client.Kernel@dell.com
364 Description: 335 Description:
365 This attribute can be used to 336 This attribute can be used to reset the BIOS Configuration.
366 Specifically, it tells which t 337 Specifically, it tells which type of reset BIOS configuration is being
367 requested on the host. 338 requested on the host.
368 339
369 Reading from it returns a list 340 Reading from it returns a list of supported options encoded as:
370 341
371 - 'builtinsafe' (Built 342 - 'builtinsafe' (Built in safe configuration profile)
372 - 'lastknowngood' (Las 343 - 'lastknowngood' (Last known good saved configuration profile)
373 - 'factory' (Default f 344 - 'factory' (Default factory settings configuration profile)
374 - 'custom' (Custom sav 345 - 'custom' (Custom saved configuration profile)
375 346
376 The currently selected option 347 The currently selected option is printed in square brackets as
377 shown below:: 348 shown below::
378 349
379 # echo "factory" > /sys/cl 350 # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
380 # cat /sys/class/firmware- 351 # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
381 builtinsafe lastknowngood 352 builtinsafe lastknowngood [factory] custom
382 353
383 Note that any changes to this 354 Note that any changes to this attribute requires a reboot
384 for changes to take effect. 355 for changes to take effect.
385 356
386 What: /sys/class/firmware-attributes <<
387 Date: August 2023 <<
388 KernelVersion: 6.6 <<
389 Contact: Mark Pearson <mpearson-lenovo@s <<
390 Description: <<
391 On Lenovo platforms there is a <<
392 saved. This is an architectura <<
393 that can be modified to 48. <<
394 A solution for this is instead <<
395 to allow a user to bulk set th <<
396 unlimited attributes. <<
397 <<
398 Read the attribute to check wh <<
399 E.g: <<
400 # cat /sys/class/firmware-attr <<
401 single <<
402 <<
403 Write the attribute with 'bulk <<
404 Write the attribute with 'sing <<
405 The default setting is single <<
406 E.g: <<
407 # echo bulk > /sys/class/firmw <<
408 <<
409 When in bulk mode write 'save' <<
410 Note, once a save has been tri <<
411 will return a permissions erro <<
412 (which requires entering the B <<
413 E.g: <<
414 # echo save > /sys/class/firmw <<
415 <<
416 What: /sys/class/firmware-attributes 357 What: /sys/class/firmware-attributes/*/attributes/debug_cmd
417 Date: July 2021 358 Date: July 2021
418 KernelVersion: 5.14 359 KernelVersion: 5.14
419 Contact: Mark Pearson <markpearson@lenov 360 Contact: Mark Pearson <markpearson@lenovo.com>
420 Description: 361 Description:
421 This write only attribute can 362 This write only attribute can be used to send debug commands to the BIOS.
422 This should only be used when 363 This should only be used when recommended by the BIOS vendor. Vendors may
423 use it to enable extra debug a 364 use it to enable extra debug attributes or BIOS features for testing purposes.
424 365
425 Note that any changes to this 366 Note that any changes to this attribute requires a reboot for changes to take effect.
426 <<
427 <<
428 HP specific class extensions - <<
429 ------------------------------ <<
430 <<
431 What: /sys/class/firmware-attributes <<
432 Date: March 2023 <<
433 KernelVersion: 5.18 <<
434 Contact: "Jorge Lopez" <jorge.lopez2@hp. <<
435 Description: <<
436 'kek' Key-Encryption-Key is a <<
437 RSA public key that will be us <<
438 signatures when setting the si <<
439 the bytes should correspond to <<
440 (x509 .DER format containing a <<
441 certificate must be less than <<
442 <<
443 What: /sys/class/firmware-attributes <<
444 Date: March 2023 <<
445 KernelVersion: 5.18 <<
446 Contact: "Jorge Lopez" <jorge.lopez2@hp. <<
447 Description: <<
448 'sk' Signature Key is a write- <<
449 public key that will be used b <<
450 when configuring BIOS settings <<
451 written, the bytes should corr <<
452 public key. The exponent is a <<
453 <<
454 What: /sys/class/firmware-attributes <<
455 Date: March 2023 <<
456 KernelVersion: 5.18 <<
457 Contact: "Jorge Lopez" <jorge.lopez2@hp. <<
458 Description: <<
459 'status' is a read-only file t <<
460 the status information. <<
461 <<
462 "State": "not provisioned | <<
463 "Version": "Major.Minor", <<
464 "Nonce": <16-bit unsigned nu <<
465 "FeaturesInUse": <16-bit uns <<
466 "EndorsementKeyMod": "<256 b <<
467 "SigningKeyMod": "<256 bytes <<
468 <<
469 What: /sys/class/firmware-attributes <<
470 Date: March 2023 <<
471 KernelVersion: 5.18 <<
472 Contact: "Jorge Lopez" <jorge.lopez2@hp. <<
473 Description: <<
474 'audit_log_entries' is a read- <<
475 <<
476 Audit log entry format <<
477 <<
478 Byte 0-15: Requested <<
479 Byte 16-127: Unused <<
480 <<
481 What: /sys/class/firmware-attributes <<
482 Date: March 2023 <<
483 KernelVersion: 5.18 <<
484 Contact: "Jorge Lopez" <jorge.lopez2@hp. <<
485 Description: <<
486 'audit_log_entry_count' is a r <<
487 audit log events available to <<
488 <<
489 [No of entries],[log e <<
490 <<
491 log entry size identifies audi <<
492 The current size is 16 bytes b <<
493 versions. <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.