In loader.efi(8), there is a section, "Additional Environment Variables". It currently reads: loader.efi loads some extra variables early in startup from /efi/freebsd/loader.env from the EFI partition. Only simple variables can be set here. It can be useful to specify the root filesystem: rootdev=disk0s1a What it doesn't say is that that pathname is a default that can be changed. Specifically, the FreeBSD EFI variable LoaderEnv sets that pathname, which defaults to /efi/freebsd/loader.env if the variable does not exist. Also, NextLoaderEnv can be set to a pathname and that variable is then deleted after it is used. My suggested documentation change is: ======== loader.efi can set variables early in startup from a file on the EFI partition. By default, that file is /efi/freebsd/loader.env. It can be changed by setting the FreeBSD EFI variable LoaderEnv, as in: echo -n /efi/freebsd/alt.env | efivar -w -t 7 -n cfee69ad-a0de-47a9-93a8-f63106f8ae99-LoaderEnv After that is executed, the file /efi/freebsd/alt.env is used instead of /efi/freebsd/loader.env. See efivar(8) for more information on setting EFI variables. In addition, the EFI variable NextLoaderEnv can be set to the pathname of a second startup file. That variable is deleted immediately after its value is retrieved, so setting it will affect only the next boot attempt. For either variable, a missing file is silently ignored. A typical use for the startup file is to change the boot partition. To do that, you can put something like rootdev=disk0p15 into the file. The set of useful variables is small, as most will be changed later. In addition, setting those variables that are supposed to cause side effects when set does not work and may cause breakage; don't do that. The startup file contains a series of assignments separated by spaces, tabs, or newlines. Quotes are not given any special treatment. If no =value is given, the value 1 is used. Invalid syntax and the like are silently ignored. ======== loader.efi uses code from sys/kern/subr_boot.c to parse the files and that code parses boot flags as well. But the "howto" variable is discarded, making that useless. However, -S<text> is handled exactly as if comconsole_speed=<text> had been entered, setting the variable. That's probably unintentional since none of the other boot flags can be set from the files, so this probably shouldn't be documented. Still, if one wanted to be completist, an additional paragraph could be added to the description.
Created attachment 268691 [details] Document LoaderEnv and NextLoaderEnv EFI variables in loader.efi(8) This patch expands the documentation of a section named "Additional Environment Variables" in loader.efi(8). Now it covers both the variables (LoaderEnv and NextLoaderEnv), their behavior, a usage example via efivar(8) and the syntax rules of the startup file. The original rootdev example is kept the same. Tested with mandoc to ensure correct rendering.
I've created a review for the submitted patch (thank you!): https://reviews.freebsd.org/D56633
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=cf7d4b04e9ae890f2a0f5811234e926f75a0c237 commit cf7d4b04e9ae890f2a0f5811234e926f75a0c237 Author: Bill Blake <billblake2018@protonmail.com> AuthorDate: 2026-04-25 14:56:24 +0000 Commit: Benedict Reuschling <bcr@FreeBSD.org> CommitDate: 2026-04-25 15:01:43 +0000 loader.efi(8): Document LoaderEnv and NextLoaderEnv EFI variables Describe how the LoaderEnv and NextLoaderEnv variables can be used. PR: 293054 Reviewed by: imp Sponsored by: Wiesbaden Hackathon 202604 Differential Revision: https://reviews.freebsd.org/D56633 stand/man/loader.efi.8 | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-)
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=4137c673fa963fdf409eba2f48d615350c988ffe commit 4137c673fa963fdf409eba2f48d615350c988ffe Author: Paarth Shirsat <paarthshirsat123@gmail.com> AuthorDate: 2026-04-25 15:10:27 +0000 Commit: Benedict Reuschling <bcr@FreeBSD.org> CommitDate: 2026-04-25 15:12:04 +0000 loader.efi(8): Document LoaderEnv and NextLoaderEnv EFI variables Describe how the LoaderEnv and NextLoaderEnv variables can be used. PR: 293054 Reviewed by: imp Sponsored by: Wiesbaden Hackathon 202604 Differential Revision: https://reviews.freebsd.org/D56633 stand/man/loader.efi.8 | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-)
The patch was commmitted as is. PR closed!
A commit in branch stable/15 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=3bd3b6b9fe4f221a90a1bea2817d6c4a5f0b51a3 commit 3bd3b6b9fe4f221a90a1bea2817d6c4a5f0b51a3 Author: Paarth Shirsat <paarthshirsat123@gmail.com> AuthorDate: 2026-04-25 15:10:27 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2026-06-15 08:55:26 +0000 loader.efi(8): Document LoaderEnv and NextLoaderEnv EFI variables Describe how the LoaderEnv and NextLoaderEnv variables can be used. PR: 293054 Reviewed by: imp Sponsored by: Wiesbaden Hackathon 202604 Differential Revision: https://reviews.freebsd.org/D56633 (cherry picked from commit 4137c673fa963fdf409eba2f48d615350c988ffe) stand/man/loader.efi.8 | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-)