.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "DEPTHCHARGECTL" 1 "2022-11-24" "v0.6.1" "depthcharge-tools"
.SH NAME
depthchargectl \- Manage the ChromeOS bootloader and its boot images
.SH SYNOPSIS
.sp
\fBdepthchargectl\fP [options] \fICOMMAND\fP ...
.sp
\fBdepthchargectl bless\fP [options] [\fIPARTITION\fP | \fIDISK\fP]
.sp
\fBdepthchargectl build\fP [options] [\fIKERNEL_VERSION\fP]
.sp
\fBdepthchargectl check\fP [options] \fIIMAGE\fP
.sp
\fBdepthchargectl config\fP [options] \fIKEY\fP
.sp
\fBdepthchargectl list\fP [options] [\fIDISK\fP ...]
.sp
\fBdepthchargectl remove\fP [options] (\fIKERNEL_VERSION\fP | \fIIMAGE\fP)
.sp
\fBdepthchargectl target\fP [options] [\fIPARTITION\fP | \fIDISK\fP ...]
.sp
\fBdepthchargectl write\fP [options] [\fIKERNEL_VERSION\fP | \fIIMAGE\fP]
.SH DESCRIPTION
.sp
\fBdepthchargectl\fP 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.
.sp
The \fIKERNEL_VERSION\fP argument is a distro\-specific representation of a
kernel and usually is the latter part of \fB/boot/vmlinuz\-\fP\fIVERSION\fP\&.
The \fIIMAGE\fP argument is a boot image for the ChromeOS bootloader, or a
file suspected to be one. \fIDISK\fP should be a physical disk containing a
GPT partition table (e.g. \fB/dev/mmcblk0\fP, \fB/dev/sda\fP), but virtual
disks (e.g. \fB/dev/dm\-0\fP) are resolved to such physical disks if
possible. \fIPARTITION\fP must be one of partition devices of a physical
disk (e.g \fB/dev/mmcblk0p1\fP, \fB/dev/sda2\fP). The \fIvmlinuz\fP, \fIinitramfs\fP
and \fIdtb\fP files are as explained in \fImkdepthcharge\fP(1)\&.
.sp
The program\(aqs functionality is divided into subcommands:
.SS depthchargectl bless
.sp
Sets bootloader\-specific flags for a given partition or the currently
booted partition as detected from the \fBkern_guid=\fP\fIPARTUUID\fP
parameter \fImkdepthcharge\fP(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.
.SS depthchargectl build
.sp
Builds a bootable image from the running system for this board, using
the latest or a specific kernel version. \fBdepthchargectl\fP 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 \fIvmlinuz\fP, \fIinitramfs\fP and \fIdtb\fP files are
located. It uses this information and \fImkdepthcharge\fP(1) to build this
image.
.sp
It automatically adds an appropriate \fBroot=\fP\fIROOT\fP kernel command
line parameter deduced from \fB/etc/fstab\fP\&. Higher compression levels
for the kernel are automatically tried as necessary, when the firmware
supports them.
.SS depthchargectl config
.sp
Retrieves the configured value for a given configuration key, primarily
for use in scripts that integrate \fBdepthchargectl\fP with the system
upgrade process.
.SS depthchargectl check
.sp
Checks if a file is a depthcharge image that can be booted on this
board. \fBdepthchargectl\fP also keeps track of restrictions on images
for each board. For example, most 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.
.SS depthchargectl list
.sp
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.
.SS depthchargectl remove
.sp
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.
.SS depthchargectl target
.sp
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 \fBlist\fP subcommand. If a partition is given, it checks if
it is an appropriate for a boot image. Tries to avoid the currently
booted kernel.
.SS depthchargectl write
.sp
Writes a specific image or builds and writes a \fIkernel\-version\fP image to
a partition the \fBtarget\fP subcommand returns, and marks it as bootable
once on the next boot. The \fBbless\fP 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.
.SH OPTIONS
.SS Global options
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
Show a help message and exit.
.TP
.B  \-v\fP,\fB  \-\-verbose
Print info messages and \fImkdepthcharge\fP(1) output to stderr.
.TP
.B  \-V\fP,\fB  \-\-version
Print program version and exit.
.TP
.BI \-\-root \ ROOT
Root device or mountpoint of the system to work on. If a mounted
device is given, its mountpoint is used. Defaults to the currently
booted system\(aqs root.
.TP
.BI \-\-tmpdir \ DIR
Directory to keep temporary files. Normally \fBdepthchargectl\fP
creates a temporary directory by itself and removes it when it
quits. However, if a temporary directory is specified with this
option any temporary files will be created under it and will not be
deleted.
.UNINDENT
.SS Configuration options
.sp
In addition to its built\-in configuration, \fBdepthchargectl\fP reads
\fB/etc/depthcharge\-tools/config\fP and \fB/etc/depthcharge\-tools/config.d\fP/\fI*\fP as configuration files to make it
adaptable to different boards and systems. The following options allow
this configuration to be overridden temporarily.
.INDENT 0.0
.TP
.BI \-\-config \ FILE
Additional configuration file to read. This can include changing
board properties or adding new boards, which mostly isn\(aqt possible
to do with command\-line options.
.TP
.BI \-\-board \ CODENAME
Assume \fBdepthchargectl\fP is running on the specified board. Normally
it tries to detect which board it\(aqs running on primarily based on
the HWID of the board set by the vendor, among other things.
.TP
.BI \-\-images\-dir \ DIR
Directory to store and look for built depthcharge images. By
default, set to \fB/boot/depthcharge\fP\&.
.TP
.BI \-\-vboot\-keyblock \ KEYBLOCK
The kernel keyblock file required to sign and verify images. By
default, set to \fB/usr/share/vboot/kernel.keyblock\fP\&.
.TP
.BI \-\-vboot\-public\-key \ SIGNPUBKEY
The public key required to verify images, in .vbpubk format. By
default, set to \fB/usr/share/vboot/kernel_subkey.vbpubk\fP\&.
.TP
.BI \-\-vboot\-private\-key \ SIGNPRIVATE
The private key necessary to sign images, in .vbprivk format. By
default, set to \fB/usr/share/vboot/kernel_data_key.vbprivk\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-kernel\-cmdline \fICMD\fP [\fICMD\fP ...]
Command\-line parameters for the kernel. By default, set to
\fB"console=tty0 quiet splash"\fP\&.  \fBdepthchargectl\fP and \fImkdepthcharge\fP(1) append
some other values to this: an appropriate \fBroot=\fP\fIROOT\fP, the
\fBkern_guid=%U\fP parameter required for the \fBbless\fP subcommand,
\fBnoinitrd\fP if \fB\-\-ignore\-initramfs\fP is given.
.UNINDENT
.INDENT 0.0
.TP
.B  \-\-ignore\-initramfs
Do not include \fIinitramfs\fP in the built images. For some boards,
\fBdepthchargectl\fP cannot build an image that includes an initramfs
so it exits with an error if your OS kernel has a corresponding one.
If you know that your OS kernel can boot on this board without an
initramfs, you can specify this option to build an initramfs\-less
image.
.UNINDENT
.SS depthchargectl bless options
.INDENT 0.0
.TP
.B  \-\-bad
Set the specified partition as unbootable. This sets all three of
the \fISuccessful\fP, \fIPriority\fP, \fITries\fP flags to 0.
.TP
.B  \-\-oneshot
Set the specified partition to be tried once in the next boot. This
sets the \fISuccessful\fP flag to 0, \fITries\fP flag to 1, and makes sure the
\fIPriority\fP flag is the highest one among all the partitions of the
disk the specified one is in.
.TP
.BI \-i \ NUM\fR,\fB \ \-\-partno \ NUM
Partition number in the given disk image, for when the positional
argument is a disk image instead of a partition block device.
.UNINDENT
.SS depthchargectl build options
.INDENT 0.0
.TP
.BI \-\-description \ DESC
Human\-readable description for the image. By default, a string that
describes your system with the specified kernel release name, like
"Debian GNU/Linux, with Linux 5.10.0\-6\-arm64".
.TP
.BI \-\-root \ ROOT
Root device to add to kernel cmdline. By default, this is acquired
from \fB/etc/fstab\fP or a filesystem UUID is derived from the mounted
root. If "none" is passed, no root parameter is added.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-compress \fITYPE\fP [\fITYPE\fP ...]
Compression types to attempt. By default, all compression types that
the board supports based on \fBdepthchargectl\fP configuration are
attempted from lowest to highest compression.
.UNINDENT
.INDENT 0.0
.TP
.BI \-\-timestamp \ SECONDS
Build timestamp for the image. By default, \fBSOURCE_DATE_EPOCH\fP is
used if it\(aqs set. If not, the modification date of either the
\fIinitramfs\fP or \fIvmlinuz\fP is used as an attempt to keep images somewhat
reproducible.
.TP
.BI \-o \ PATH\fR,\fB \ \-\-output \ PATH
Output image to path instead of storing it in the images\-dir.
.UNINDENT
.sp
The following options allow one to specify the exact files to be used in
building the image, instead of letting \fBdepthchargectl\fP deduce them:
.INDENT 0.0
.TP
.BI \-\-kernel\-release \ NAME
Release name for the kernel to be used in image filename under the
images\-dir (unless \fB\-\-output\fP is specified).
.TP
.BI \-\-kernel \ FILE
Kernel executable. Usually \fB/boot/vmlinuz\-\fP\fIVERSION\fP by default,
but depends on your OS.
.TP
.BI \-\-initramfs \ FILE
Ramdisk image. Usually \fB/boot/initrd.img\-\fP\fIVERSION\fP by default,
but depends on your OS.
.TP
.BI \-\-fdtdir \ DIR
Directory to search device\-tree binaries for the board. Usually
\fB/boot/dtbs\fP or a directory like \fB/usr/lib/linux\-image\-\fP\fIVERSION\fP, depends on your OS. \fIdtb\fP files in this dir are searched
to find ones matching your board\(aqs device\-tree compatible string set
in configuration.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dtbs \fIFILE\fP [\fIFILE\fP ...]
Device\-tree binary files to use instead of searching \fIfdtdir\fP\&.
.UNINDENT
.SS depthchargectl config options
.INDENT 0.0
.TP
.BI \-\-section \ SECTION
Config section to retrieve configured values from. By default, this
is the globally default section: \fBdepthcharge\-tools\fP\&.
.TP
.BI \-\-default \ DEFAULT
A default value to return if the given config key doesn\(aqt exist in
the given config section. If a default value is not given, this
subcommand prints an error message and exits with nonzero status
when the key is missing.
.UNINDENT
.SS depthchargectl check options
.sp
This subcommand takes no specific options.
.SS depthchargectl list options
.INDENT 0.0
.TP
.B  \-a\fP,\fB  \-\-all\-disks
List partitions on all disks.
.TP
.B  \-c\fP,\fB  \-\-count
Print only the count of partitions.
.TP
.B  \-n\fP,\fB  \-\-noheadings
Don\(aqt print column headings.
.TP
.BI \-o \ COLUMNS\fR,\fB \ \-\-output \ COLUMNS
Comma separated list of columns to output. Supported columns are
\fBATTRIBUTE\fP (or \fBA\fP), \fBSUCCESSFUL\fP (or \fBS\fP), \fBTRIES\fP (or
\fBT\fP), \fBPRIORITY\fP (or \fBP\fP) for ChromeOS GPT flags, \fBPATH\fP for
the partition device (if exists), \fBDISKPATH\fP (or \fBDISK\fP) for the
disk device/image the partition is in, \fBPARTNO\fP for the partition
number, and \fBSIZE\fP for the partition size in bytes.
.UNINDENT
.SS depthchargectl remove options
.INDENT 0.0
.TP
.B  \-f\fP,\fB  \-\-force
Allow disabling the currently booted partition.
.UNINDENT
.SS depthchargectl target options
.INDENT 0.0
.TP
.B  \-a\fP,\fB  \-\-all\-disks
Consider all available disks, instead of considering only disks
containing the root and boot partitions.
.TP
.B  \-\-allow\-current
Allow targeting the currently booted partition.
.TP
.BI \-s \ BYTES\fR,\fB \ \-\-min\-size \ BYTES
Only consider partitions larger than this size in bytes. Defaults to
\fB64 KiB\fP to ignore unused partitions in ChromeOS installations.
.UNINDENT
.SS depthchargectl write options
.INDENT 0.0
.TP
.B  \-\-allow\-current
Allow overwriting the currently booted partition.
.TP
.B  \-f\fP,\fB  \-\-force
Write image to disk even if it cannot be verified by the \fBcheck\fP
subcommand.
.TP
.B  \-\-no\-prioritize
Don\(aqt modify ChromeOS GPT flags on the partition. Normally, the
flags would be set to make the system boot from the newly written
partition on the next boot.
.TP
.BI \-t \ DEVICE\fR,\fB \ \-\-target \ DEVICE
Specify a disk or partition device to write to. This device is
passed to the \fBtarget\fP subcommand to determine where exactly to
write to.
.UNINDENT
.SH EXIT STATUS
.sp
In general, exits with zero on success and non\-zero on failure. Some
subcommands return more specified exit statuses:
.SS depthchargectl build exit status
.INDENT 0.0
.TP
.B 0
Image built and stored successfully.
.TP
.B 1
An error occurred before or during building the image.
.TP
.B 3
Can build an image with an \fIinitramfs\fP, but it is too big for the
board despite using maximum allowed kernel compression. This might
be solvable by reducing the \fIinitramfs\fP size.
.TP
.B 4
Like \fB3\fP, but without an \fIinitramfs\fP or reducing the \fIinitramfs\fP
size wouldn\(aqt make things fit. This might be solvable by reducing
the \fIvmlinuz\fP size, perhaps by building a custom kernel.
.UNINDENT
.SS depthchargectl check exit status
.INDENT 0.0
.TP
.B 0
The \fIimage\fP passes all checks.
.TP
.B 1
Errors unrelated to image checks.
.TP
.B 2
The \fIimage\fP isn\(aqt a readable file.
.TP
.B 3
Size of the \fIimage\fP is too big for the board.
.TP
.B 4
The \fIimage\fP cannot be interpreted by \fIvbutil_kernel\fP(1)\&.
.TP
.B 5
The \fIimage\fP fails the \fIvbutil_kernel\fP(1) signature checks.
.TP
.B 6
The \fIimage\fP is built with a wrong format for the board.
.TP
.B 7
The \fIimage\fP is missing device\-tree files compatible with the board.
.UNINDENT
.SS depthchargectl target exit status
.INDENT 0.0
.TP
.B 0
A usable \fIpartition\fP is given, or a usable partition was chosen from
\fIdisk\fPs. The partition passes the checks and is printed to output.
.TP
.B 1
Errors unrelated to partition checks.
.TP
.B 2
The \fIpartition\fP is not a writable block device.
.TP
.B 3
The disk containing the \fIpartition\fP is not a writable block device.
.TP
.B 4
Cannot parse a partition number from the \fIpartition\fP\&.
.TP
.B 5
The \fIpartition\fP is not a ChromeOS kernel partition.
.TP
.B 6
The \fIpartition\fP is the currently booted partition.
.TP
.B 7
The \fIpartition\fP is smaller than the \fB\-\-min\-size\fP argument.
.UNINDENT
.SH FILES
.INDENT 0.0
.TP
.B \fB/etc/depthcharge\-tools/config\fP
System configuration file. The "Configuration options" explained
above can be set here to have them as long\-term defaults. It\(aqs also
possible to modify board properties or add new boards here.
.TP
.B \fB/etc/depthcharge\-tools/config.d\fP/\fI*\fP
These files are considered appended to the \fBconfig\fP file.
.TP
.B \fB/usr/lib/systemd/system\fP/depthchargectl\-bless.service
A systemd service that runs the \fBdepthchargectl bless\fP on
successful boots.
.TP
.B \fB/etc/init.d\fP/depthchargectl\-bless
An init service that runs \fBdepthchargectl bless\fP on successful
boots.
.TP
.B \fB/boot/depthcharge\fP/\fI*\fP\&.img
The most recently built images for each kernel version.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.TP
.B \fBdepthchargectl\fP \fBlist\fP \fB\-n\fP \fB\-o\fP \fIPATH\fP
Get a list of partitions \fBdepthchargectl\fP will act on by default.
.TP
.B \fBdepthchargectl\fP \fBbuild\fP \fB\-\-board\fP \fIkevin\fP \fB\-\-root\fP \fI/mnt\fP \fB\-\-output\fP \fIdepthcharge.img\fP
Build an image for the Samsung Chromebook Plus (v1), using files
from and intended to boot with the chroot system mounted at \fI/mnt\fP\&.
.TP
.B \fBdepthchargectl\fP \fBconfig\fP \fIboard\fP
Print the board codename for the detected board.
.TP
.B \fBdepthchargectl\fP \fBconfig\fP \fB\-\-default\fP \fIFalse\fP \fIenable\-system\-hooks\fP
Print the \fIenable\-system\-hooks\fP config if it\(aqs set, \fIFalse\fP if not.
This specific config key is meant to be a common mechanism which
distro packagers can use to let users disable system upgrade hooks
that use depthchargectl.
.TP
.B \fBdepthchargectl\fP \fBwrite\fP \fB\-\-allow\-current\fP
Build, check and write an image for the latest \fIkernel\-version\fP of
this system to disk while allowing overwriting the currently booted
partiiton. You might use this if you only have a single ChromeOS
kernel partition, but broken kernels might make your system
unbootable.
.TP
.B \fBdepthchargectl\fP \fBwrite\fP \fIvmlinux.kpart\fP \fB\-t\fP \fI/dev/mmcblk1p1\fP
Write the \fBvmlinux.kpart\fP file to \fB/dev/mmcblk1p1\fP, only if both
the image and the partition are valid. Something of this form would
be used for writing images to a secondary or external disk.
.UNINDENT
.SH SEE ALSO
.sp
\fImkdepthcharge\fP(1), \fIcgpt\fP(1), \fIvbutil_kernel\fP(1)
.\" Generated by docutils manpage writer.
.