~nabijaczleweli/klapki

0a0e4462057640a628016591cba3630e9af8f96a — наб a year ago 92bd266
Unfucky/unwucky the manpage, as we in the industry say
2 files changed, 13 insertions(+), 11 deletions(-)

M README.md
M man/klapki.md
M README.md => README.md +1 -0
@@ 2,6 2,7 @@
EFI boot manager; or, well, an EFI bootorder [compiler](//twitter.com/nabijaczleweli/status/1306144037070569472).

## [Manpage](//git.sr.ht/~nabijaczleweli/klapki/tree/trunk/man/klapki.md)
<!-- TODO: move this to autodeployed branch so it doesn't look like absolute shit -->

### Building


M man/klapki.md => man/klapki.md +12 -11
@@ 12,10 12,11 @@ klapki(8) generates and manages EFI boot entries on platforms compatible therewi

This command-line interface is based on running a set of operations (see [OPS][]) which modify the state and context,
then settling the new set-up, then committing it; this means that, barring I/O errors,
{dump}ing after the last operation with -n is an accurate representation of what would be committed without it.
`{dump}`ing after the last operation with `-n` is an accurate representation of what would be committed without it.

Care is taken to only write what is needed and only when it's needed –
files and wanted entries are hashed with SHA1(3ssl) and only updated on mismatch.
files and wanted entries are hashed with SHA1(3ssl) and only updated on mismatch;
foreign entries are never touched, and klapki(8) prefers to abandon entries it doesn't understand than to accidentally mangle them.

Minimal state is stored, and it's only supplementary.
This means that removing all instances of a kernel boot entry with tools such as efibootmgr(8), efivar(1),


@@ 34,15 35,15 @@ The entry description and kernel cmdline are controlled via small executable fil
    Verbose operation.

  * `-V`:
    Very verbose – adds a {dump} op in-between each specified op.
    Very verbose – adds a `{dump}` op in-between each specified op.

  * `-E`:
    Increase libefivar verbosity level.

    At time of writing, libefivar supports `LOG_VERBOSE` and `LOG_DEBUG`,
    which require -E to be specified one and two times, respectively.
    which require `-E` to be specified one and two times, respectively.

    See the SEE ALSO sexion for details.
    See the [SEE ALSO][] sexion for details.

  * `-h`:
    Show a help message with these flags, recognised environment variables (see [ENVIRONMENT][]) and ops (see [OPS][]).


@@ 65,9 66,9 @@ The entry description and kernel cmdline are controlled via small executable fil

  * `KLAPKI_WISDOM`=:
    To obtain the description and cmdline, klapki(8) invokes respectively-named files under the wisdom root via execl(3),
    which is `/etc/klapki` by defailt. This value overrides that path. If not empty, a '/' is additionally appended before the executable name.
    which is `/etc/klapki` by default. This value overrides that path. If not empty, a '/' is additionally appended before the executable name.

    See also WISDOM below.
    See also [WISDOM][] below.

  * `KLAPKI_EFI_ROOT`=:
    By default, klapki(8) puts newly-installed files in `\klapki\{host}\{version}` under the ESP.


@@ 112,7 113,7 @@ The entry description and kernel cmdline are controlled via small executable fil

    The order of explicit variants is preserved within each version group, which are sorted highest-to-lowest.
    For example: a host with two kernels (*5.8.0-[12]-amd64*) and two explicit variants (*debug*, *silent*) will produce the following entries
    (assume `$KLAPKI_WISDOM/description` symlinked to `/bin/echo`); note how the highest kernel version is at the top:<br />
    (assume `$KLAPKI_WISDOM/description` linked to `/bin/echo`); note how the highest kernel version is at the top:<br />
    &nbsp;&nbsp;5.8.0-2-amd64<br />
    &nbsp;&nbsp;5.8.0-2-amd64 debug<br />
    &nbsp;&nbsp;5.8.0-2-amd64 silent<br />


@@ 142,14 143,14 @@ with the following arguments:<br />

And the standard output tied to a memfd (see memfd_create(2)), which is then trimmed, and all newlines are replaced with a single space.

klapki(8) stops processing if the child exits with a non-zero status or is killed by signal.
The special exit value 0x6B (107, ASCII 'k') is used to signal an error to execl(2) the wisdom binary.
klapki(8) stops processing if the child exits with a non-zero status or is killed by a signal.
The special exit value 0x6B (107, ASCII 'k') is used to signal an error in execl(3)ing the wisdom binary.

Additional `initrd=` statements *should* work (with warnings, since the should.
Please report on the bug tracker/mailing list (see [REPORTING BUGS][]) if you use them successfully!) and will not be managed by klapki(8),

The simplest `/etc/klapki/description` would be a link to `/bin/echo`.
A simple `cmdline` is a `/bin/sh` shebang + `echo` command,
A simple `cmdline` is a `/bin/sh` shebang + `echo` command.
A cursed `cmdline` would be a `/bin/sh` shebang and an `awk '{gsub(/initrd=[^ ]+ ?/, ""); print}' /proc/cmdline` command.

## EXIT VALUES