0001 What: /sys/class/firmware-attributes/*/attributes/*/
0002 Date: February 2021
0003 KernelVersion: 5.11
0004 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
0005 Prasanth KSR <prasanth.ksr@dell.com>
0006 Dell.Client.Kernel@dell.com
0007 Description:
0008 A sysfs interface for systems management software to enable
0009 configuration capability on supported systems. This directory
0010 exposes interfaces for interacting with configuration options.
0011
0012 Unless otherwise specified in an attribute description all attributes are optional
0013 and will accept UTF-8 input.
0014
0015 type:
0016 A file that can be read to obtain the type of attribute.
0017 This attribute is mandatory.
0018
0019 The following are known types:
0020
0021 - enumeration: a set of pre-defined valid values
0022 - integer: a range of numerical values
0023 - string
0024
0025 All attribute types support the following values:
0026
0027 current_value:
0028 A file that can be read to obtain the current
0029 value of the <attr>.
0030
0031 This file can also be written to in order to update the value of a
0032 <attr>
0033
0034 This attribute is mandatory.
0035
0036 default_value:
0037 A file that can be read to obtain the default
0038 value of the <attr>
0039
0040 display_name:
0041 A file that can be read to obtain a user friendly
0042 description of the at <attr>
0043
0044 display_name_language_code:
0045 A file that can be read to obtain
0046 the IETF language tag corresponding to the
0047 "display_name" of the <attr>
0048
0049 "enumeration"-type specific properties:
0050
0051 possible_values:
0052 A file that can be read to obtain the possible
0053 values of the <attr>. Values are separated using
0054 semi-colon (``;``).
0055
0056 "integer"-type specific properties:
0057
0058 min_value:
0059 A file that can be read to obtain the lower
0060 bound value of the <attr>
0061
0062 max_value:
0063 A file that can be read to obtain the upper
0064 bound value of the <attr>
0065
0066 scalar_increment:
0067 A file that can be read to obtain the scalar value used for
0068 increments of current_value this attribute accepts.
0069
0070 "string"-type specific properties:
0071
0072 max_length:
0073 A file that can be read to obtain the maximum
0074 length value of the <attr>
0075
0076 min_length:
0077 A file that can be read to obtain the minimum
0078 length value of the <attr>
0079
0080 Dell specific class extensions
0081 ------------------------------
0082
0083 On Dell systems the following additional attributes are available:
0084
0085 dell_modifier:
0086 A file that can be read to obtain attribute-level
0087 dependency rule. It says an attribute X will become read-only or
0088 suppressed, if/if-not attribute Y is configured.
0089
0090 modifier rules can be in following format::
0091
0092 [ReadOnlyIf:<attribute>=<value>]
0093 [ReadOnlyIfNot:<attribute>=<value>]
0094 [SuppressIf:<attribute>=<value>]
0095 [SuppressIfNot:<attribute>=<value>]
0096
0097 For example::
0098
0099 AutoOnFri/dell_modifier has value,
0100 [SuppressIfNot:AutoOn=SelectDays]
0101
0102 This means AutoOnFri will be suppressed in BIOS setup if AutoOn
0103 attribute is not "SelectDays" and its value will not be effective
0104 through sysfs until this rule is met.
0105
0106 Enumeration attributes also support the following:
0107
0108 dell_value_modifier:
0109 A file that can be read to obtain value-level dependency.
0110 This file is similar to dell_modifier but here, an
0111 attribute's current value will be forcefully changed based
0112 dependent attributes value.
0113
0114 dell_value_modifier rules can be in following format::
0115
0116 <value>[ForceIf:<attribute>=<value>]
0117 <value>[ForceIfNot:<attribute>=<value>]
0118
0119 For example::
0120
0121 LegacyOrom/dell_value_modifier has value:
0122 Disabled[ForceIf:SecureBoot=Enabled]
0123
0124 This means LegacyOrom's current value will be forced to
0125 "Disabled" in BIOS setup if SecureBoot is Enabled and its
0126 value will not be effective through sysfs until this rule is
0127 met.
0128
0129 What: /sys/class/firmware-attributes/*/authentication/
0130 Date: February 2021
0131 KernelVersion: 5.11
0132 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
0133 Prasanth KSR <prasanth.ksr@dell.com>
0134 Dell.Client.Kernel@dell.com
0135 Description:
0136 Devices support various authentication mechanisms which can be exposed
0137 as a separate configuration object.
0138
0139 For example a "BIOS Admin" password and "System" Password can be set,
0140 reset or cleared using these attributes.
0141
0142 - An "Admin" password is used for preventing modification to the BIOS
0143 settings.
0144 - A "System" password is required to boot a machine.
0145
0146 Change in any of these two authentication methods will also generate an
0147 uevent KOBJ_CHANGE.
0148
0149 is_enabled:
0150 A file that can be read to obtain a 0/1 flag to see if
0151 <attr> authentication is enabled.
0152 This attribute is mandatory.
0153
0154 role:
0155 The type of authentication used.
0156 This attribute is mandatory.
0157
0158 Known types:
0159 bios-admin:
0160 Representing BIOS administrator password
0161 power-on:
0162 Representing a password required to use
0163 the system
0164 system-mgmt:
0165 Representing System Management password.
0166 See Lenovo extensions section for details
0167 HDD:
0168 Representing HDD password
0169 See Lenovo extensions section for details
0170 NVMe:
0171 Representing NVMe password
0172 See Lenovo extensions section for details
0173
0174 mechanism:
0175 The means of authentication. This attribute is mandatory.
0176 Only supported type currently is "password".
0177
0178 max_password_length:
0179 A file that can be read to obtain the
0180 maximum length of the Password
0181
0182 min_password_length:
0183 A file that can be read to obtain the
0184 minimum length of the Password
0185
0186 current_password:
0187 A write only value used for privileged access such as
0188 setting attributes when a system or admin password is set
0189 or resetting to a new password
0190
0191 This attribute is mandatory when mechanism == "password".
0192
0193 new_password:
0194 A write only value that when used in tandem with
0195 current_password will reset a system or admin password.
0196
0197 Note, password management is session specific. If Admin password is set,
0198 same password must be written into current_password file (required for
0199 password-validation) and must be cleared once the session is over.
0200 For example::
0201
0202 echo "password" > current_password
0203 echo "disabled" > TouchScreen/current_value
0204 echo "" > current_password
0205
0206 Drivers may emit a CHANGE uevent when a password is set or unset
0207 userspace may check it again.
0208
0209 On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes
0210 require password validation.
0211 On Lenovo systems if you change the Admin password the new password is not active until
0212 the next boot.
0213
0214 Lenovo specific class extensions
0215 --------------------------------
0216
0217 On Lenovo systems the following additional settings are available:
0218
0219 role: system-mgmt This gives the same authority as the bios-admin password to control
0220 security related features. The authorities allocated can be set via
0221 the BIOS menu SMP Access Control Policy
0222
0223 role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see
0224 'level' and 'index' extensions below.
0225
0226 lenovo_encoding:
0227 The encoding method that is used. This can be either "ascii"
0228 or "scancode". Default is set to "ascii"
0229
0230 lenovo_kbdlang:
0231 The keyboard language method that is used. This is generally a
0232 two char code (e.g. "us", "fr", "gr") and may vary per platform.
0233 Default is set to "us"
0234
0235 level:
0236 Available for HDD and NVMe authentication to set 'user' or 'master'
0237 privilege level.
0238 If only the user password is configured then this should be used to
0239 unlock the drive at boot. If both master and user passwords are set
0240 then either can be used. If a master password is set a user password
0241 is required.
0242 This attribute defaults to 'user' level
0243
0244 index:
0245 Used with HDD and NVME authentication to set the drive index
0246 that is being referenced (e.g hdd0, hdd1 etc)
0247 This attribute defaults to device 0.
0248
0249 certificate, signature, save_signature:
0250 These attributes are used for certificate based authentication. This is
0251 used in conjunction with a signing server as an alternative to password
0252 based authentication.
0253 The user writes to the attribute(s) with a BASE64 encoded string obtained
0254 from the signing server.
0255 The attributes can be displayed to check the stored value.
0256
0257 Some usage examples:
0258
0259 Installing a certificate to enable feature::
0260
0261 echo "supervisor password" > authentication/Admin/current_password
0262 echo "signed certificate" > authentication/Admin/certificate
0263
0264 Updating the installed certificate::
0265
0266 echo "signature" > authentication/Admin/signature
0267 echo "signed certificate" > authentication/Admin/certificate
0268
0269 Removing the installed certificate::
0270
0271 echo "signature" > authentication/Admin/signature
0272 echo "" > authentication/Admin/certificate
0273
0274 Changing a BIOS setting::
0275
0276 echo "signature" > authentication/Admin/signature
0277 echo "save signature" > authentication/Admin/save_signature
0278 echo Enable > attribute/PasswordBeep/current_value
0279
0280 You cannot enable certificate authentication if a supervisor password
0281 has not been set.
0282 Clearing the certificate results in no bios-admin authentication method
0283 being configured allowing anyone to make changes.
0284 After any of these operations the system must reboot for the changes to
0285 take effect.
0286
0287 certificate_thumbprint:
0288 Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints
0289 for the certificate installed in the BIOS.
0290
0291 certificate_to_password:
0292 Write only attribute used to switch from certificate based authentication
0293 back to password based.
0294 Usage::
0295
0296 echo "signature" > authentication/Admin/signature
0297 echo "password" > authentication/Admin/certificate_to_password
0298
0299
0300 What: /sys/class/firmware-attributes/*/attributes/pending_reboot
0301 Date: February 2021
0302 KernelVersion: 5.11
0303 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
0304 Prasanth KSR <prasanth.ksr@dell.com>
0305 Dell.Client.Kernel@dell.com
0306 Description:
0307 A read-only attribute reads 1 if a reboot is necessary to apply
0308 pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
0309 generated when it changes to 1.
0310
0311 == =========================================
0312 0 All BIOS attributes setting are current
0313 1 A reboot is necessary to get pending BIOS
0314 attribute changes applied
0315 == =========================================
0316
0317 Note, userspace applications need to follow below steps for efficient
0318 BIOS management,
0319
0320 1. Check if admin password is set. If yes, follow session method for
0321 password management as briefed under authentication section above.
0322 2. Before setting any attribute, check if it has any modifiers
0323 or value_modifiers. If yes, incorporate them and then modify
0324 attribute.
0325
0326 Drivers may emit a CHANGE uevent when this value changes and userspace
0327 may check it again.
0328
0329 What: /sys/class/firmware-attributes/*/attributes/reset_bios
0330 Date: February 2021
0331 KernelVersion: 5.11
0332 Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
0333 Prasanth KSR <prasanth.ksr@dell.com>
0334 Dell.Client.Kernel@dell.com
0335 Description:
0336 This attribute can be used to reset the BIOS Configuration.
0337 Specifically, it tells which type of reset BIOS configuration is being
0338 requested on the host.
0339
0340 Reading from it returns a list of supported options encoded as:
0341
0342 - 'builtinsafe' (Built in safe configuration profile)
0343 - 'lastknowngood' (Last known good saved configuration profile)
0344 - 'factory' (Default factory settings configuration profile)
0345 - 'custom' (Custom saved configuration profile)
0346
0347 The currently selected option is printed in square brackets as
0348 shown below::
0349
0350 # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
0351 # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
0352 builtinsafe lastknowngood [factory] custom
0353
0354 Note that any changes to this attribute requires a reboot
0355 for changes to take effect.
0356
0357 What: /sys/class/firmware-attributes/*/attributes/debug_cmd
0358 Date: July 2021
0359 KernelVersion: 5.14
0360 Contact: Mark Pearson <markpearson@lenovo.com>
0361 Description:
0362 This write only attribute can be used to send debug commands to the BIOS.
0363 This should only be used when recommended by the BIOS vendor. Vendors may
0364 use it to enable extra debug attributes or BIOS features for testing purposes.
0365
0366 Note that any changes to this attribute requires a reboot for changes to take effect.
