depthchargectl(1)

📦
version 0.6.2 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 depthchargectl(1) — depthcharge-tools 💖

✨ Name ✨

okay so bestie, meet depthchargectl — this is the manual page depthchargectl(1) from depthcharge-tools, and it's literally here to manage the ChromeOS bootloader and its boot images. periodt. 👑

🌈 SYNOPSIS 🌈

depthchargectl [options] COMMAND ...

depthchargectl bless [options] [PARTITION | DISK]

depthchargectl build [options] [KERNEL_VERSION]

depthchargectl check [options] IMAGE

depthchargectl config [options] KEY

depthchargectl list [options] [DISK ...]

depthchargectl remove [options] (KERNEL_VERSION | IMAGE)

depthchargectl target [options] [PARTITION | DISK ...]

depthchargectl write [options] [KERNEL_VERSION | IMAGE]

💅 DESCRIPTION 💅

okay so here's the whole vibe: depthchargectl automatically manages the ChromeOS bootloader by building images for the current board and system, writing them to appropriate ChromeOS kernel partitions, prioritizing those partitions accordingly, and setting them as successful on boot. When you have more than one ChromeOS kernel partition, they will be utilized in rotation so that an unsuccessful boot attempt can revert to the last good version. lowkey genius, honestly. 🦋

The KERNEL_VERSION argument is a distro-specific representation of a kernel and usually is the latter part of /boot/vmlinuz-VERSION. The IMAGE argument is a boot image for the ChromeOS bootloader, or a file suspected to be one. DISK should be a physical disk containing a GPT partition table (e.g. /dev/mmcblk0, /dev/sda), but virtual disks (e.g. /dev/dm-0) are resolved to such physical disks if possible. PARTITION must be one of partition devices of a physical disk (e.g /dev/mmcblk0p1, /dev/sda2). The vmlinuz, initramfs and dtb files are as explained in mkdepthcharge(1). ✨

The program's functionality is divided into subcommands:

🎀 depthchargectl bless 🎀

Sets bootloader-specific flags for a given partition or the currently booted partition as detected from the kern_guid=PARTUUID parameter mkdepthcharge(1) adds to the kernel command line. By default, this marks the partition as successfully booted and the most preferred one, but can disable the partition or make it boot only on the next attempt as well. choose your own adventure, but make it bootloader flags 💅

🌸 depthchargectl build 🌸

Builds a bootable image from the running system for this board, using the latest or a specific kernel version. depthchargectl keeps a database of known ChromeOS boards and how to build bootable images for them. For example, it keeps track of which device-tree file that needs to be included for each ARM board. It also figures out distro-specific information of where the vmlinuz, initramfs and dtb files are located. It uses this information and mkdepthcharge(1) to build this image. 🧚

It automatically adds an appropriate root=ROOT kernel command line parameter deduced from /etc/fstab. Higher compression levels for the kernel are automatically tried as necessary, when the firmware supports them. slay compression behavior, fr fr. 🔥

🦋 depthchargectl config 🦋

Retrieves the configured value for a given configuration key, primarily for use in scripts that integrate depthchargectl with the system upgrade process. Can also query information about boards. it's giving script-friendly bestie energy. 💜

⭐ depthchargectl check ⭐

Checks if a file is a depthcharge image that can be booted on this board. depthchargectl also keeps track of restrictions on images for each board. For example, earlier ChromeOS board can boot images up to a specific size, e.g. 32MiB. It checks if its input is in a format the ChromeOS bootloader expects and satisfies these restrictions. no cap, it's a whole vibe check for images. 🎀

🌈 depthchargectl list 🌈

Prints a table of ChromeOS kernel partitions and their bootloader specific GPT flags (i.e. Successful, Priority, Tries). By default, it only searches the physical disks on which the boot and root partitions reside. iconic little table moment, honestly. 👑

💖 depthchargectl remove 💖

Disables partitions that contain a specific image or a specific kernel version. This is most useful when you are removing a kernel version and its modules from your system, and know images built with this kernel will fail to boot from that point on. okay so it's literally cleaning up before the boot drama starts. 😭

🫶 depthchargectl target 🫶

Chooses and prints the lowest priority, preferably unsuccessful ChromeOS kernel partition to write a boot image to. By default, searches the same disks as the list subcommand. If a partition is given, it checks if it is an appropriate for a boot image. Tries to avoid the currently booted kernel. main character energy: find the understudy partition. 💅

✨ depthchargectl write ✨

Writes a specific image or builds and writes a kernel-version image to a partition the target subcommand returns, and marks it as bootable once on the next boot. The bless subcommand must be run after a successful boot to make the partiiton permanently bootable, but that is possible to do automatically with the service files provided with this package. 🦋

✨ OPTIONS ✨

okay bestie, this is the part where we get into the actual knobs you can turn. buckle up, there are a LOT and they're all lowkey iconic 🎀

🌍 Global options

these ones work basically everywhere, they're the main character energy of the option family 👑

  • -h, --help — shows you a help message and then dips. bye 💨
  • -v, --verbose — prints info messages and mkdepthcharge(1) output to stderr. yes queen, show me everything 🔍
  • -V, --version — prints the program version and exits. quick lil flex 💅
  • --root ROOT — the root device or mountpoint of the system you wanna work on. if you hand it a mounted device, it uses that device's mountpoint. default is the root of the currently booted system, no cap.
  • --root-mountpoint DIR, --boot-mountpoint DIR — the root and boot mountpoints of the system you're working on. if you don't give them, they get deduced from the --root argument. why do these exist?? because --root is overloaded by the build subcommand, which adds it as a kernel command line argument — and sometimes you're building an image for a chroot and you do NOT want that. so these let you dodge it 🙈
  • --tmpdir DIR — the directory where temporary files live. normally depthchargectl makes its own temp dir and deletes it when it quits, but if you specify one with this option, all temp files get made under it and they will not be deleted. careful with that one bestie, that's a lot of leftovers 🍓

🛠️ Configuration options

so here's the tea: on top of its built-in config, depthchargectl reads /etc/depthcharge-tools/config and /etc/depthcharge-tools/config.d/* as configuration files, so it can adapt to all the different boards and systems out there 🌈. the options below let you temporarily override that config ✨

  • --config FILE — an additional configuration file to read. this is a big deal because it can change board properties or even add entirely new boards — stuff you mostly can't do with command-line options alone. very giving flexibility 💜
  • --board CODENAME — pretend depthchargectl is running on the board you name. normally it tries to detect the board it's on, primarily based on the HWID the vendor set, among other things. 🕵️
  • --images-dir DIR — directory to store and look for built depthcharge images. by default it's set to /boot/depthcharge.
  • --vboot-keyblock KEYBLOCK — the kernel keyblock file you need to sign and verify images. by default, depthchargectl searches for these keys in the /etc/depthcharge-tools and /usr/share/vboot/devkeys directories. 🔑
  • --vboot-public-key SIGNPUBKEY — the public key needed to verify images, in .vbpubk format. same deal, default search is /etc/depthcharge-tools and /usr/share/vboot/devkeys. 🔑
  • --vboot-private-key SIGNPRIVATE — the private key necessary to sign images, in .vbprivk format. yep, also searched for in /etc/depthcharge-tools and /usr/share/vboot/devkeys by default. do NOT go posting this one in the group chat 💀
  • --kernel-cmdline CMD [CMD ...] — command-line parameters for the kernel. by default these get read from /etc/kernel/cmdline, /usr/lib/kernel/cmdline or /proc/cmdline. heads up: depthchargectl and mkdepthcharge(1) may append some other values onto this — an appropriate root=ROOT, the kern_guid=%U parameter required for the bless subcommand, and noinitrd if --ignore-initramfs is given. 📝
  • --ignore-initramfs — don't include initramfs in the built images, ignore the initramfs checks for the root=ROOT argument, and add noinitrd to the kernel cmdline. if you know your OS kernel can boot on this board without an initramfs (maybe because it has a built-in one), you can specify this to build an initramfs-less image. living on the edge, honestly 😭
  • --zimage-initramfs-hack — choose which initramfs support hack gets used for the zimage format. your choices are set-init-size (that's the default), pad-vmlinuz for kernels without KASLR, or none for if depthcharge ever gets native support for safely loading zimage initramfs. a lil hack for every season 🧚

💖 depthchargectl bless options

  • --bad — marks the specified partition as unbootable. it sets all three of the Successful, Priority and Tries flags to 0. it's giving "you're on time out, sit down" 🚫
  • --oneshot — sets the specified partition to be tried once on the next boot. this sets the Successful flag to 0, the Tries flag to 1, and makes sure the Priority flag is the highest one among all the partitions on the disk that the specified one lives in. one shot, one opportunity 🎯
  • -i NUM, --partno NUM — the partition number in the given disk image, for when the positional argument is a disk image instead of a partition block device. 🎀

🔨 depthchargectl build options

  • --description DESC — a human-readable description for the image. by default you get a string that describes your system with the specified kernel release name, like "Debian GNU/Linux, with Linux 5.10.0-6-arm64". so aesthetic ✨
  • --root ROOT — the root device to add to the kernel cmdline. by default this is acquired from /etc/fstab, or a filesystem UUID gets derived from the mounted root. if none is passed, no root parameter is added at all. 🤷
  • --compress TYPE [TYPE ...] — compression types to attempt. by default, all compression types that the board supports (based on depthchargectl configuration) are attempted, going from lowest to highest compression. squeeeeze 🔥
  • --timestamp SECONDS — the build timestamp for the image. by default, SOURCE_DATE_EPOCH is used if it's set. if it isn't, the modification date of either the initramfs or vmlinuz is used, as an attempt to keep images somewhat reproducible. ⏰
  • -o PATH, --output PATH — output the image to a path instead of storing it in the images-dir.

and then the following options let you specify the exact files used to build the image, instead of letting depthchargectl deduce them for you — control freak mode: activated 💅

  • --kernel-release NAME — release name for the kernel to be used in the image filename under the images-dir (unless --output is specified).
  • --kernel FILE — the kernel executable. usually /boot/vmlinuz-VERSION by default, but that depends on your OS.
  • --initramfs FILE [FILE ...] — the ramdisk image. usually /boot/initrd.img-VERSION by default, but again, depends on your OS. if none is passed, no initramfs is added. 🍩
  • --fdtdir DIR — directory to search for device-tree binaries for the board. usually /boot/dtbs or a directory like /usr/lib/linux-image-VERSION, depends on your OS. the dtb files in this dir get searched to find ones matching your board's device-tree compatible string set in configuration. 🌳
  • --dtbs FILE [FILE ...] — device-tree binary files to use instead of searching fdtdir.

🎀 depthchargectl config options

  • --section SECTION — the config section to retrieve configured values from. by default it's the globally default section: depthcharge-tools.
  • --default DEFAULT — a default value to return if the given config key doesn't exist in the given config section. if you don't give a default value, this subcommand prints an error message and exits with nonzero status when the key is missing. so either give it a safety net or accept the consequences bestie 🙈

✅ depthchargectl check options

this subcommand takes no specific options. it's the chill one, it just vibes and checks things 🦋

📋 depthchargectl list options

  • -a, --all-disks — list partitions on all disks. all of them. every last one 👑
  • -c, --count — print only the count of partitions. just the number, nothing else, minimalism ✨
  • -n, --noheadings — don't print column headings. no labels, we die like hackers 💀
  • -o COLUMNS, --output COLUMNS — a comma separated list of columns to output. the supported columns are ATTRIBUTE (or A), SUCCESSFUL (or S), TRIES (or T), PRIORITY (or P) for the ChromeOS GPT flags, PATH for the partition device (if it exists), DISKPATH (or DISK) for the disk device/image the partition is in, PARTNO for the partition number, and SIZE for the partition size in bytes. pick your faves 💖

🗑️ depthchargectl remove options

  • -f, --force — allows disabling the currently booted partition. yeah. the one you're literally running off of right now. this is your "are you sure about that" moment ⚠️

🎯 depthchargectl target options

  • -a, --all-disks — consider all available disks, instead of only considering disks that contain the root and boot partitions. 🌐
  • --allow-current — allow targeting the currently booted partition. again: bold move, bestie 😳
  • -s BYTES, --min-size BYTES — only consider partitions larger than this size in bytes. defaults to 64 KiB so it can ignore unused partitions in ChromeOS installations. bye tiny useless partitions 👋

✍️ depthchargectl write options

  • --allow-current — allow overwriting the currently booted partition. no thoughts, just sending it 🔥
  • -f, --force — write the image to disk even if it cannot be verified by the check subcommand. this is the "I know better than the verification tool" button. use responsibly 🫣
  • --no-prioritize — don't modify the ChromeOS GPT flags on the partition. normally the flags would be set so that the system boots from the newly written partition on the next boot — this option says "nah, leave them exactly as they are". 🙅
  • -t DEVICE, --target DEVICE — specify a disk or partition device to write to. this device gets passed to the target subcommand to figure out where exactly to write to. delegation, queen behavior 👑

🚦 EXIT STATUS 🚦

in general, it exits with zero on success and non-zero on failure. basic. but some subcommands get specific and return fancier exit statuses, so let's break those down girlies 📊

🔨 depthchargectl build exit status

  • 0 — image built and stored successfully. we ate and left no crumbs 🎉
  • 1 — an error occurred before or during building the image. 😭
  • 3 — it can build an image with an initramfs, but it's too big for the board despite using maximum allowed kernel compression. this might be solvable by reducing the initramfs size. so close bestie 🥲
  • 4 — like 3, but without an initramfs, or reducing the initramfs size wouldn't make things fit. this might be solvable by reducing the vmlinuz size, perhaps by building a custom kernel. time for a diet bestie 🫠

✅ depthchargectl check exit status

  • 0 — the image passes all checks. slay 💖
  • 1 — errors unrelated to image checks. wrong place, wrong time energy 🌀
  • 2 — the image isn't a readable file. 💀
  • 3 — size of the image is too big for the board. chunky 🍓
  • 4 — the image cannot be interpreted by vbutil_kernel(1).
  • 5 — the image fails the vbutil_kernel(1) signature checks.
  • 6 — the image is built with a wrong format for the board.
  • 7 — the image is missing device-tree files compatible with the board. 🌳

🎯 depthchargectl target exit status

  • 0 — a usable partition is given, or a usable partition was chosen from disks. the partition passes the checks and is printed to output. iconic ✨
  • 1 — errors unrelated to partition checks.
  • 2 — the partition is not a writable block device. 🚫
  • 3 — the disk containing the partition is not a writable block device. 🚫
  • 4 — cannot parse a partition number from the partition. "what number??" 😭
  • 5 — the partition is not a ChromeOS kernel partition.
  • 6 — the partition is the currently booted partition. hi, that's you, that's your system 🫵
  • 7 — the partition is smaller than the --min-size argument. too smol 🐜

📁 FILES 📁

okay so here's the whole map of where everything lives bestie, bookmark this section fr 🗺️✨

  • /etc/depthcharge-tools — the config directory, the main character 💅 this is where depthchargectl goes looking for config files and ChromiumOS verified boot keys.
  • /etc/depthcharge-tools/config — the system config file. all those "Configuration options" we yapped about earlier can live here and become your long-term defaults 🫶 you can also mess with board properties here, or drop in brand new boards.
  • /etc/depthcharge-tools/config.d/* — these files get treated like they're appended to the config file. extra toppings, same sundae 🍓
  • /etc/kernel/cmdline, /usr/lib/kernel/cmdline, /proc/cmdline — the files depthchargectl might peek at to figure out a default kernel command line 👀
  • /usr/lib/systemd/system/depthchargectl-bless.service — a systemd service that runs depthchargectl bless whenever a boot succeeds. it's giving "good job, marking it blessed" ✨
  • /usr/lib/kernel/install.d/90-depthcharge-tools.install — a systemd kernel-install plugin that can auto-manage your whole system for you, but only if layout=depthcharge-tools is set in /etc/kernel/install.conf. set the flag, get the magic 🪄
  • /etc/init.d/depthchargectl-bless — an init service, same job as the systemd one: runs depthchargectl bless on successful boots 💖
  • /usr/share/vboot/devkeys — a directory full of test keys that should have been installed by vbutil_kernel(1). if you didn't set any verified boot keys in config and there are none chilling in your config directories, depthchargectl searches here too.
  • /boot/depthcharge/*.img — the freshest images, one per kernel version. the most recently built ones, periodt 👑

💖 EXAMPLES 💖

real talk, this is the part you're actually here for. let's go 🌈

get a list of the partitions depthchargectl will act on by default:

depthchargectl list -n -o PATH

build an image for the Samsung Chromebook Plus (v1) — board kevin, pulling files from and meant to boot with the chroot system mounted at /mnt:

depthchargectl build --board kevin --root /mnt --output depthcharge.img

print the board codename for the detected board:

depthchargectl config board

print the enable-system-hooks config, or False if it isn't set:

depthchargectl config --default False enable-system-hooks

this specific config key is meant to be a common mechanism that distro packagers can use, so users can turn off the system upgrade hooks that use depthchargectl 🎀

build, check and write an image for the latest kernel-version of this system to disk, while letting you overwrite the partition you're currently booted from:

depthchargectl write --allow-current

you'd reach for this if you only have a single ChromeOS kernel partition. > heads up bestie: broken kernels might make your system unbootable 😭 proceed with the vibes of someone who has backups.

write the vmlinux.kpart file to /dev/mmcblk1p1 — only if both the image and the partition are valid ✅:

depthchargectl write vmlinux.kpart -t /dev/mmcblk1p1

something shaped like this is what you'd use for writing images to a secondary or external disk 🦋

👀 SEE ALSO 👀

go read these when you're done with me, they're iconic too:

and that's the whole page, bestie 🥹 this was depthchargectl(1) at version v0.6.2, dated 2023-06-30 — go forth and bless some kernels, you absolute legend 💅👑✨

📦 where this page comes from