UEFI command-line tool for read/write access of variables

Overview

UEFI Command Line Tool for Reading/Writing UEFI Variables

This tool is a rewritten version of the modded grub with setup_var commands, enhanced with much cleaner code, aarch64 support and ability to be automated. The tool is able to read/write UEFI variables, and is usually used for changing BIOS settings which are hidden from UI.

Use this tool with extreme caution as accessing wrong varstore or variable may completely brick your computer!

Note: If you have been using the modded grub tool, you may want to refer to the cheatsheet.

Term definitions

The legacy names used in grub version of the tool and some other related tools (e.g. IFR extractor) used varstore and variable. The former word is not used in UEFI specification, and is actually the variable in UEFI runtime services (sometimes referred to as "variable store", which is possibly where "varstore" came from). So to clarify this, this project uses "variable" and "value":

  • Variable is the former varstore, which means a named storage with varying size from several to several thousands of bytes. Maybe used for storing many values of many BIOS setting items.
  • Value is the former variable, which represents a value in the variable with few (often one to two) bytes, referred with variable and offset. While changing BIOS settings, this means the value of one BIOS setting item.

Usage

Run setup_var.efi in UEFI shell without arguments to get this help:

setup_var.efi <OFFSET> [<VALUE>] [-s <VALUE_SIZE>] [-n <VAR_NAME>] [-i <VAR_ID>]

OFFSET: The offset of value to be altered in the UEFI variable.
VALUE: The new value to write, capped at 64-bit. If not specified, the value at OFFSET will be read and shown.
VALUE_SIZE: Bytes of value to write, must be equal or larger than the size of <VALUE>, defaults to 0x1.
VAR_NAME: The name of UEFI variable to be altered, defaults to "Setup".
VAR_ID: Unique id for distinguishing variables with same name, which will be provided by setup_var.efi (when required).

OFFSET, VALUE, VALUE_SIZE and VAR_ID are numbers, and must be specified in hexadecimal with prefix "0x".

The program defaults to little endian for values ONLY while operating UEFI variables,
though it's recommended to only operate on one byte if you are not sure what this is or means.

Example: .\setup_var.efi 0x10E 0x1a -n CpuSetup

For changing BIOS settings, you may use those following steps to obtain the variable name and value offset:

  1. Obtain (raw) BIOS image, some motherboard OEMs provides BIOS image that can be directly opened but it's not commonly the case for branded PCs. For Intel CPU-based systems, you may use Flash Programming Tool from CSME System Tools to directly extract raw BIOS image.
  2. Use UEFITool to open the BIOS image, and find Setup as string, there would be image sections named "Setup/*", navigate to that and extract body of the Setup folder to a file.
  3. Use IFR-Extractor to export setup info to a text file.
  4. Find your desired setting in the text file, note the offset after VarStoreInfo (VarOffset/VarName): and the id after VarStore:.
  5. Search for VarStoreId: {id}, where {id} is the id found earlier. And note the Name after it.
  6. Change the value using noted variable(varstore) name, offset, and size.

GRUB Cheatsheet

The legacy grub commands can be mapped to these usages of this tool:

  • setup_var offset [value]: The default arguments of setup_var.efi, just setup_var.efi offset [value].
  • setup_var2 offset [value]: This command searches for named Custom, so setup_var.efi offset [value] -n Custom.
  • setup_var_3 offset [value]: This command discards variables that are too small, setup_var.efi has the -i VAR_ID argument to handle this. Though it's not tested as the problemed firmware used to test this command has been updated and the issue was solved.
  • setup_var_vs offset [value_size] [value]: This command processes variable-sized values, and is mapped to setup_var.efi offset [value] [-s value_size].
  • setup_var_cv name offset [value_size] [value]: This was the full-featured command, to use full features, use setup_var.efi offset [value] [-s value_size] [-n name], in which the -s value_size can be omitted for 1-byte value.

Build

Install nightly rust as it's required by uefi-rs, and

cargo build --target x86_64-unknown-uefi [--release]

Use aarch64-unknown-uefi for aarch64 target.

Comments
  • With multiple varstores named

    With multiple varstores named "Setup", using -i to select the variable ID has no effect

    I have Gigaybte X470 AORUS GAMING 5 WiFi F63c, which has two variables named Setup.

    setup_var.efi lists both of them and asks to rerun with the variable ID for selecting one of the two variables

    But when I re-run with -i option, the exact same thing happens again (option -i has no effect)

    opened by terminatorul 3
  • [BUG] `--write_on_demand`

    [BUG] `--write_on_demand`

    Good evening and thank you so much for taking care of issue #7. I can confirm that the bug got solved with the newest release. About the newest release, I noticed that there's a new argument (--write_on_demand) which aims to avoid useless writes on the offset unless it has a different value.

    In theory this is a good practice, but in the real-life tests, it seems that this argument is simply ignored, as I read Written offset blablabla. Is this just a matter of a wrong print statement, or the argument isn't properly parsed?

    From my very low RUST knowledge, the argument is properly parsed (source).

    opened by dreamwhite 2
  • [BUG] First argument is skipped

    [BUG] First argument is skipped

    Good morning and thank you so much for writing this tool. I'm using it and despite it serves the same purpose as modGRUBShell.efi it's way more portable (especially when having ESPs with low space issues).

    Anyway, I'm experiencing a weird bug while trying to execute the tool via OpenCore. I don't know if you ever had any Hackintoshing experience in the past or not, but basically it's a bootloader and for what concerns us, it can be used also for creating custom tools entries (e.g. CFG Lock unlock entry which runs .\setup_var.efi CFG_LOCK_OFFSET 0x00 -n VarStoreId).

    What basically happens is that after adding the tool in the bootloader configuration file, it skips the first argument.

    Below the code that I added to the bootloader configuration file:

    <dict>
    	<key>Arguments</key>
    	<string>0x527 0x00 -n Setup</string>
    	<key>Auxiliary</key>
    	<true/>
    	<key>Comment</key>
    	<string>UEFI command-line tool for read/write access of variables - CFG Lock unlock</string>
    	<key>Enabled</key>
    	<true/>
    	<key>Flavour</key>
    	<string>Auto</string>
    	<key>FullNvramAccess</key>
    	<true/>
    	<key>Name</key>
    	<string>setup_var - CFG Unlock</string>
    	<key>Path</key>
    	<string>setup_var.efi</string>
    	<key>RealPath</key>
    	<true/>
    	<key>TextMode</key>
    	<true/>
    </dict>
    

    What concerns us is the Arguments key with the value 0x527 0x00 -n Setup. If I run that custom entry, it doesn't write in the offset but rather reads the value of 0x00 under Setup VarStoreName, so it skips the first argument.

    I already discussed this with the devs of the bootloader (you can read more here), and they pointed out this line which may be the reason of the bug.

    The only way I could find to temporarily fix it is adding .\setup_var.efi (potentially can be literally any string, as it doesn't need to be any particular value) so the tool correctly parses the argument.

    Do you think this can be fixed? Thank you so much and have a great day

    -- dreamwhite

    opened by dreamwhite 2
  • [Feature request] Add argument to reboot

    [Feature request] Add argument to reboot

    Hello, I am very happy to know that this project exists. Amazing job.

    I immediately shared it with my friend @dreamwhite and I saw he has already pinged you to fix some niche things ad discrepancies, it's so nice to see that you've quickly fixed everything he noticed that was broken/missing :)

    By the way, we're mostly using this tool for BIOS mods (DVMT Pre Allocated / CFG Lock etc) but I have a weird laptop where the trackpad works for Linux and Windows when I set it to APIC interrupt, and this mode is unsupported for macOS; on the other hand, GPIO interrupt works for macOS but not for Windows/Linux.

    This tool comes very handy in conjuction with OpenCore Tools section, where you can send parameters when launching an option in the picker. However, after launching the tool, the user is forced to soft shutdown by pressing once the button (no force shutdown) and then boot back again with the edited BIOS option.

    Would it be possible to set an argument to reboot after the change is applied to speed things up?

    something like

    setup_var.efi 0x2CA 0x01 -n Setup --reboot
    
    opened by 1alessandro1 1
  • Feature request: Only write value if necessary

    Feature request: Only write value if necessary

    G'day and thank you very much for this. For my laptop which randomly likes to reset CFG Lock and such, this has been a lifesaver - my rEFInd bootloader entries are now using .nsh scripts that perform my desired setup_var calls then load a Linux kernel/Windows bootmgr/whatever, ensuring that every boot will have my ideal UEFI vars set.

    I am worried, however, that these values are being written on every boot, even if it's not necessary. I can't imagine UEFI storage (nvram?) is designed to be especially durable....

    ...so, with that said, it would be really great if the tool could read the existing value, and ONLY write your value if it's actually different. Just to save unnecessary writes.

    Thanks for your consideration!

    opened by cosmicdan 1
  • UEFI Spec

    UEFI Spec

    opened by BoringBoredom 0
Releases(0.2.2)
Owner
null
Quick example of displaying a BMP file with uefi-rs

uefi-bmp Quick example of drawing a bitmap using uefi-rs and tinybmp. Not necessarily the most efficient :) Build and run (may need some modification

Nicholas Bishop 1 Jan 16, 2022
Scuffed UEFI video(bad apple) player

Bad UEFI Another day, another Bad Apple project. Video and audio are loaded from \video.uefiv and \audio.uefia respectively. (when running in QEMU esp

Matic Babnik 4 Nov 8, 2022
Rusty Bootkit - UEFI Bootkit in Rust

A UEFI Bootkit in Rust Note: This project is incomplete and work is in progress (W.I.P). A lot of things could be incorrect until this is complete. Wh

null 76 May 8, 2023
Zero-cost and safe interface to UEFI firmware

ZFI – Zero-cost and safe interface to UEFI firmware ZFI is a Rust crate for writing a UEFI application with the following goals: Provides base APIs th

Ultima Microsystems 22 Sep 14, 2023
A tetris game I wrote in rust using ncurses. I'm sure that there's a better way to write a tetris game, and the code may be sus, but it techinically works

rustetris A tetris game I wrote in rust using ncurses. I'm sure that there's a better way to write a tetris game, and the code may be sus, but it tech

Eric G 3 Oct 15, 2022
The official command-line interface for the makedeb Package Repository

Mist This is the repository for Mist, the official helper for the makedeb Package Repository. Installation Users have a few options for installing Mis

makedeb 5 Aug 4, 2022
Generate rust command line executables from gRPC protobuf services.

Rust template repository. An opinionated starting point for rust projects such as systemd services command line tools client programs server programs

Kris Nóva 8 Sep 18, 2022
Rust-based command-line language-learning game. Uses the Tatoeba database.

minicloze A command-line language learning game using Tatoeba's great database. Accelerate your studies by putting your knowledge to the test in an ad

benman 3 Mar 5, 2023
Decryption tool for assets.pie from Teenage Mutant Ninja Turtles: The Cowabunga Collection. This tool was made in its entirety by SowwyItsAnAlt.

Cowabunga Decryption tool for assets.pie from Teenage Mutant Ninja Turtles: The Cowabunga Collection. This tool was made in its entirety by SowwyItsAn

Masquerade 8 Dec 22, 2022
A prototype plugin providing a simple line drawing api for bevy.

bevy_debug_lines A prototype plugin providing a simple line drawing api for bevy. See docs.rs for documentation. Expect breakage on master. Click on t

Michael Palmos 92 Dec 31, 2022
A Rust implementation of the GMT game Battle Line.

rsbl A Rust implementation of the game Battle Line. Running Currently there is only the simplest prototype of the game: a text-based table with ⚑ char

Matan Lurey 2 Nov 6, 2022
Bevy plugin for a simple single-line text input widget.

bevy_simple_text_input An unambitious single-line text input widget for bevy_ui. Usage See examples/basic.rs. Alternatives If you need more features,

Rob Parrett 9 Oct 3, 2023
String processing with file/line/col information and the regular rust `str` API

Simple span handling for str and &[u8] This crate exposes some of the methods that exist on str or bstr. If you are missing any you need, please open

Oli Scherer 3 Oct 30, 2023
Terminal command correction, alternative to thefuck written in Rust

Pay Respects Typed a wrong command? Pay Respects will try to correct your wrong console command by simply pressing F! ?? Blazing fast suggestion: You

iff 11 Aug 7, 2023
A CLI tool to manage your godot-rust projects

ftw A CLI tool to manage your godot-rust project! Table of contents General Information Setup Usage Contact General Information This is a tool to help

Michael Angelo Calimlim 77 Dec 13, 2022
A tool to display the minimap of a game larger on a second screen

maximap A tool to display the minimap of a game larger on a second screen. Should work on all operating systems supported by captrs and rust_minifb, s

Richard Baumann 18 Oct 11, 2022
A tool to generate inbetweens for animated sprites, written in godot-rust

Bitmapflow is a tool to help you generate inbetweens for animated sprites. In other words, it makes your animations smoother. It uses optical flow to

null 411 Dec 21, 2022
This is a cross-platform tool to historicize different branches/depots/manifests and generating pseudocode for it to compare different game updates

CSHP This is a cross-platform tool to historicize different branches/depots/manifests and generating pseudocode for it to compare different game updat

raizo 6 Jan 28, 2022
This is a tool for solving the excellent Wordle puzzle

Wordle Tool This is a tool for solving the excellent Wordle puzzle. It mainly exists as an exercise to learn the (by all accounts) equally excellent R

Brett Henderson 2 Jan 17, 2022