linuxboot / uefisettings

The tool to read/get/extract and write/change/modify BIOS/UEFI settings from Linux terminal.

uefisettings

About

uefisettings is a tool to read and write BIOS settings on a local host. It currently supports two interfaces:

• HiiDB (used in OCP and also has partial support in other platforms)
• iLO BlobStore (used in HPE)

---

Install

cargo install uefisettings

Build manually

cd /tmp
git clone https://github.com/linuxboot/uefisettings
cd uefisettings
cargo install --path .
~/.cargo/bin/uefisettings --help

---

Usage examples

Reset TPM

uefisettings hii set 'Pending operation' 'TPM Clear'

Check if TXT is enabled

if [[ "$(uefisettings hii get --json 'Enable Intel(R) TXT' | jq -r '.responses | .[].question.answer')" = "Enable" ]]; then
    # Do something if TXT is enabled
fi

---

Available commands

SUBCOMMANDS:
    get         Auto-identify backend and get the current value of a question
    help        Print this message or the help of the given subcommand(s)
    hii         Commands which work on machines exposing the UEFI HiiDB
    identify    Auto-identify backend and display hardware/bios-information
    ilo         Commands which work on machines having HPE's Ilo BMC
    set         Auto-identify backend and set/change the value of a question

hii:

SUBCOMMANDS:
    extract-db      Dump HiiDB into a file
    get             Get the current value of a question
    help            Print this message or the help of the given subcommand(s)
    list-strings    List all strings-id, string pairs in HiiDB
    set             Set/change the value of a question
    show-ifr        Show a human readable representation of the Hii Forms

ilo:

SUBCOMMANDS:
    get                Get the current value of a question
    help               Print this message or the help of the given subcommand(s)
    set                Set/change the value of a question
    show-attributes    List bios attributes and their current values

---

Changing UEFI settings with automation

To change BIOS settings from Linux terminal there are usually next ways available:

• On Open Compute Project hardware - read/parse a binary database called Hii (defined in the UEFI spec) and manipulate binary files in the /sys file system to change settings. This approach may also work on some non-OCP consumer hardware like your laptops.
• On Hewlett Packard Enterprise hardware - use HPE's redfish API to read/write settings. This requires the presence of HPE's iLO BMC.
• Use different proprietary tools like SCELNX from AMI or conrep from HPE. However, these require additional kernel modules to be loaded.

But this tool is an unified opensource approach to manipulate UEFI settings on any platform.

---

How it works

For OCP hardware

• Extract HiiDB from /dev/mem after getting offsets from efivarfs.
• Library (hii) in Rust partially implements the UEFI Hii specification.
• It parses the HiiDB op-codes into a DOM tree like representation which can be read by machines and humans.
• It can ask questions about UEFI settings from HiiDB and get their answers.
• Change UEFI settings by calculating the correct offsets and writing to entries in efivarfs.

For HPE hardware

• Unlike OCP Hardware, HPE does not expose HiiDB in efivarfs.
• Instead they provide a way to change UEFI settings via iLO using the Redfish API.
• Redfish can be consumed over:
  • Standard networking protocols like TCP but this requires authentication credentials and network access to the BMC.
  • By accessing /dev/hpilo directly. This doesn't require authentication credentials. HPE doesn't provide any documentation for this approach but they provide an opensource ilorest CLI tool which calls a closed-source dynamically loaded shared object library called ilorest_chif.so which does the magic. The transport method used here instead of TCP is called Blobstore2.
• We are forbidden from disassembling ilorest_chif.so but we figured out most of its function signatures by looking at Apache2-licensed HPE's python ilorest CLI tool which calls it.
• Blobstore2 communication logic and rust bindings to ilorest_chif.so are implemented in the ilorest library. Feel free to use opensource implementation instead of ilorest_chif.so to avoid license problems.

The opensource ilorest study results are published in doc/ilorest.md.

---

Update Thrift files

If one needs to update a file inside thrift directory then:

1. Install fbthrift compiler: cargo install fbthrift_compiler && (sudo dnf install -y fbthrift || sudo apt install -y fbthrift)
2. Update the .thrift file.
3. Run ~/.cargo/bin/compiler path/to/updated/file.thrift.
4. Run mv lib.rs path/to/generated/rust/file.rs.

For example:

# Install fbthrift compiler
cargo install fbthrift_compiler
sudo dnf install -y fbthrift

# Update file
vi thrift/uefisettings_spellings_db.thrift

# Re-generate the rust file from the thrift file.
cargo install fbthrift_compiler
~/.cargo/bin/compiler thrift/uefisettings_spellings_db.thrift
mv lib.rs thrift/rust/uefisettings_spellings_db_thrift/uefisettings_spellings_db.rs

uefisettings's Issues

failed to write to efivarfs file :read-only file system (os error 30)