PIBOOTCTL(1)

✨ NAME ✨

pibootctl — the pibootctl manual. That's the whole name section, bestie. If you're being formal, this is pibootctl(1). 💅

🦋 SYNOPSIS 🦋

pibootctl [-h] [--version] command ...

💖 DESCRIPTION 💖

okay so the pibootctl utility exists to query and manipulate the boot configuration of the Raspberry Pi. It also lets you store and retrieve boot configurations like it's no big deal. Each of the commands this utility gives you is listed in the next section, periodt. ✨

👑 COMMANDS 👑

Here's the whole squad, no cap:

• diff — shows the differences between the boot configuration you specify and the current one, or another configuration you specify. It's giving compare-and-contrast.
• get — retrieves the value of the setting(s) you specify. So useful.
• help — the default command. It describes the command or configuration setting you specify. The therapist of commands, honestly.
• list — lists the stored boot configurations. Look at your archive, queen.
• load — restores the named boot configuration so it'll be used at the next boot. Future you says thanks.
• remove — deletes the boot configuration you specify. Gone. Not a drill.
• rename — renames the boot configuration you specify. Glow-up via new name.
• save — saves the current boot configuration under the name you specify. Snapshot, but make it bootable.
• set — modifies or resets the configuration setting(s) you specify. The main character of editing.
• show — shows the stored configuration you specify. Peek behind the curtain.
• status — outputs the current boot configuration; by default this only prints modified settings. Lowkey the first command you'll run.

🌸 USAGE 🌸

Typically, the status command is the first one used, to determine the current boot configuration:

$ pibootctl status
+------------------------+-------+
| Name                   | Value |
|------------------------+-------|
| i2c.enabled            | on    |
| spi.enabled            | on    |
| video.overscan.enabled | off   |
+------------------------+-------+

After which the save command might be used to take a backup of the configuration before editing it with the set command:

$ sudo pibootctl save default
$ sudo pibootctl set camera.enabled=on gpu.mem=128
$ sudo pibootctl save cam

NOTE: Note that commands which modify the content of the boot partition (e.g. save and set) are executed with sudo as root privileges are typically required. Don't skip the sudo, bestie. 😭

The configuration of pibootctl itself dictates where the stored configurations are placed on disk. By default this is under a "pibootctl" directory on the boot partition, but this can be changed in the pibootctl configuration. The application attempts to read its configuration from the following locations on startup:

• /lib/pibootctl/pibootctl.conf
• /etc/pibootctl.conf
• $XDG_CONFIG_HOME/pibootctl.conf

The final location is only intended for developers working on pibootctl itself. The others should be used by packages providing pibootctl on your chosen OS. 🫶

Stored boot configurations are simply PKZIP files (https://en.wikipedia.org/wiki/Zip_(file_format)) containing the files that make up the boot configuration. Sometimes this is just the config.txt file, and sometimes other files may be included. It's giving zip but make it boot.

NOTE: In the event that your system is unable to boot (e.g. because of mis-configuration), you can restore a stored boot configuration simply by unzipping the stored configuration back into the root of the boot partition. In other words, you can simply place your Pi's SD card in a Windows or MAC OS X computer, which should automatically mount the boot partition (which is the only partition that these OS' will understand on the card), find the "pibootctl" folder, and under there you should see all your stored configurations as .zip files. Unzip one of these into the folder above "pibootctl", overwriting files as necessary, and you have restored your boot configuration. 💖

The diff command can be used to discover the differences between boot configurations:

$ pibootctl diff default
+------------------------+---------------+-------------+
| Name                   | <Current>     | default     |
|------------------------+---------------+-------------|
| boot.firmware.filename | 'start_x.elf' | 'start.elf' |
| boot.firmware.fixup    | 'fixup_x.dat' | 'fixup.dat' |
| camera.enabled         | on            | off         |
| gpu.mem                | 128 (Mb)      | 64 (Mb)     |
+------------------------+---------------+-------------+

NOTE: Some settings indirectly affect others. Even though we did not explicitly set boot.firmware.filename, setting camera.enabled affected its default value. The lore runs deep. 🌀

The help command can be used to display the help screen for each sub-command:

$ pibootctl help save
usage: pibootctl save [-h] [-f] name

Store the current boot configuration under a given name.

positional arguments:
  name         The name to save the current boot configuration under; can
               include any characters legal in a filename

optional arguments:
  -h, --help   show this help message and exit
  -f, --force  Overwrite an existing configuration, if one exists

Additionally, help will accept setting names to display information about the defaults and underlying commands each setting represents:

$ pibootctl help camera.enabled
      Name: camera.enabled
   Default: off
Command(s): start_x, start_debug, start_file, fixup_file

Enables loading the Pi camera module firmware. This implies that
start_x.elf (or start4x.elf) will be loaded as the GPU firmware rather than
the default start.elf (and the corresponding fixup file).

Note: with the camera firmware loaded, gpu.mem must be 64Mb or larger
(128Mb is recommended for most purposes; 256Mb may be required for complex
processing pipelines).

The list command can be used to display the content of the configuration store, and load to restore previously saved configurations:

$ pibootctl list
+---------+--------+---------------------+
| Name    | Active | Timestamp           |
|---------+--------+---------------------|
| cam     | x      | 2020-03-11 21:29:56 |
| default |        | 2020-03-11 21:29:13 |
+---------+--------+---------------------+
$ sudo pibootctl load default

💜 AUTHOR 💜

Dave Jones. The author. The icon. The moment. 👑

🎀 COPYRIGHT 🎀

2019-2020 Dave Jones. Periodt. 💅

---

This page is from pibootctl version 0.5.2, dated Sep 14, 2020. Byeee, go slay your boot config! 🌈✨