__ __ __
\ \_________\ \____________\ \___
\ _ \ _\ _ \ _\ __ \ __\ /
\___/\__/\__/ \_\ \___/\__/\_\_\
Bedrock Linux
Introductory Material
Limitations
Reference Material
Extending Bedrock
Miscellaneous
Most Bedrock Linux functionality is provided by a single front-end
executable: brl. Run brl --help to see an overview of its functionality
and brl for details on its sub-commands.command --help
If multiple strata provide the same command, absent any additional
indication of which to use Bedrock will choose one by default in a given
context. For example, if you have both Debian and Ubuntu strata, you will
have two apt commands:
Bedrock will chose either Debian's or Ubuntu's apt.
Bedrock's choice can be guided by configuration.
With proper configuration, Bedrock gets it right quite often. However, it
cannot read your mind. If a specific stratum's command is desired in a
specific instance, brl strat
may be prefixed to the command. For example:stratum
This workflow is sufficiently common that strat is included directly in the
default $PATH and brl may be dropped. Thus, it is more common to run:
Compilation and build tools may become confused when scanning the environment
for dependencies and finding them from different distributions. These tools
should be restricted. Bedrock knows to do this for some commands, such
as Arch's makepkg, but not others, such as ./configure scripts.
To override Bedrock's restriction configuration, strat may be called with
the -r flag to indicate the given command should be restricted:
or with the -u flag indicating it should not:
When restricted, build tools may then complain about missing dependencies,
even if they're provided by other strata. If so, install the dependencies,
just as one would do on the native distro.
One may use brl list to list all of the strata on the system. For example:
By default brl list only lists enabled, non-hidden strata. However it
has various flags to control what is listed:
<none> defaults to --enabled -e, --enabled-strata enabled stratum -E, --enabled-aliases aliases to enabled stratum -d, --disabled-strata disabled stratum -D, --disabled-aliases aliases to disabled stratum -a, --all-strata all strata -A, --all-aliases all aliases -r, --deref dereference aliases -i, --include-hidden include hidden strata in list -v, --everything equivalent to -aAir
Bedrock's intermixing of files from different strata can be confusing for new users. To help such users understand and explore the system, Bedrock provides the brl which command which can be used to query which stratum provides a given object. It supports queries about:
$PATHIf no flag is provided, brl which will guess what type of object the query is about from context. For example:
If there are concerns brl which will guess the wrong type of object, a flag
may be provided to specify the desired type:
<none> guess type from identifier -c, --current which stratum provides current process -b, --bin which stratum provides a given binary in $PATH -f, --file which stratum provides a given file path -p, --pid which stratum provides a given process ID -x, --xwindow which stratum provides a given X11 window (requires xprop)
Bedrock provides a brl fetch command to acquire files from other distros
for use as strata.
The specific distros Bedrock knows how to fetch vary depending on CPU
architecture and may change over time. To list the actively maintained list of
fetch-able distros for your CPU architecture, run:
brl fetch --list
Bedrock may also know how to fetch other distros but does not have anyone actively maintaining the their fetch code. To list these distros, run:
brl fetch --experimental
To fetch distros, run (as root):
distrosThe desired name, release, and mirror for newly fetched strata can be
specified via flags or left unspecified for brl fetch to attempt to determine
the details itself:
<none> automatically determine name, release, and mirror -n, --name [name] specify desired stratum name -r, --release [release] specify desired distro release -m, --mirror [mirror] specify desired mirror
brl fetch's logic for detecting a mirror or release may fail if the upstream
distro changes details or lists bad mirrors. If brl fetch does not work or
takes too long, try manually looking up the mirror or release and specifying
it.
Strata are hidden and disabled mid-fetch to avoid accidentally
using them before they are ready. By default, they are shown and
enabled immediately after a successful fetch for use. However, you may
disable the post-fetch showing/enable via flags:
-e, --dont-enable do not enable newly fetched strata -s, --dont-show do not show newly fetched strata
Provided qemu-user-static is installed in some stratum, Bedrock has
limited support for strata from non-native CPU architectures. brl fetch
can fetch such strata with the -a and -A flags:
-A, --archs list architectures for [distros] -a, --arch [arch] specify desired CPU architecture
Functionality for non-native ISA strata is entirely provided by and
constrained by qemu-user-static. Should some newer executable attempt to
perform some action qemu-user-static does not yet support, it will not work.
Bedrock provides a brl import command to create strata from on-disk
sources. This may be useful for distros that brl fetch does not support or
for for use with offline systems.
To import a stratum, run
brl importname/path/to/source
where the source is any of:
.tar).qcow, .qcow2, .qcow3).vdi).vmdk)If importing a VM, be sure the VM has one partition and that that partition is
unencrypted. Do not use separate /boot or /home partitions for the VM. Do
not use full disk encryption.
Strata may contain references to the rest of the system, such as bind
mounts, and should not be removed via rm -r. Bedrock provides a brl
remove command which takes care to avoid removing any file outside of the
specified stratum.
As a protective measure, strata may not be removed while enabled. If you
wish to remove a stratum, first disable it. For example:
If you know the target stratum is enabled, brl remove takes a -d
flag to disable prior to removing:
brl remove also removes aliases.
The bedrock stratum cannot be removed, as it is essential for the system
to function.
The stratum currently providing PID 1 (the init) may not be disabled,
as the Linux kernel does not respond well to PID 1 dying. If you wish to
remove the init-providing stratum, first reboot and select another
stratum to provide your init for the given session.
Similar to removing strata, one should not attempt to rename a stratum
with mv for fear of tripping on various Bedrock hooks. Instead, the brl
rename command is provided. This only works on disabled strata. If
you would like to rename an enabled stratum, brl disable it first.
For example:
brl rename also renames aliases.
The bedrock stratum cannot be renamed, as it internally has hard-coded
references to itself which are essential for the system to function.
The stratum currently providing PID1 cannot be disabled, which is a
prerequisite for renaming. If you wish to rename the init-providing
stratum, first reboot and select another stratum to provide your init
for the given session.
Similar to removing and renaming strata, one should not attempt to copy a
stratum with cp for fear of tripping on various Bedrock hooks. Instead,
the brl copy command is provided. This only works on disabled
strata. If you would like to copy an enabled stratum, brl
disable it first. For example:
brl copy dereferences aliases when copying; it cannot copy aliases
themselves. To effectively make a copy of an alias, simply create a new
alias targeting the same stratum.
The bedrock stratum cannot be disabled in preparation for copying.
The stratum currently providing PID 1 (the init) may not be disabled,
as the Linux kernel does not respond well to PID 1 dying. If you wish to
copy the init-providing stratum, first reboot and select another
stratum to provide your init for the given session.
A stratum may be in one of the following states:
enabled, indicating it is integrated with the rest of the system.disabled, indicating it is not integrated with the rest of the system.hidden, indicating that various Bedrock subsystems are ignoring it.broken, indicating that the desired state is enabled but something went wrong.To query a stratum's state, use brl status. If the stratum is
broken, brl status prints an indication of specifically what is wrong to
aid debugging and fixing.
To enable a disabled stratum, use brl enable (as root).
To disable an enabled or broken stratum, use brl disable (as
root).
The bedrock stratum cannot be disabled.
The stratum currently providing PID 1 (the init) may not be disabled,
as the Linux kernel does not respond well to PID 1 dying. If you wish to
disable the init-providing stratum, first reboot and select another
stratum to provide your init for the given session.
Bedrock can attempt to repair a broken stratum with brl repair.
brl repair has three strategies available:
<none> defaults to --retain
-n, --new only add new mounts, do not remove anything
only fixes trivially broken strata
-r, --retain try to retain as much as possible except problematic mount points
fixes most strata but risks losing some state
-c, --clear clears strata processes and mount points
should fix almost all strata but loses all state
A stratum may be hidden from various Bedrock subsystems. This is
useful to avoid accidental use during sensitive operations such as fetching
or removing a stratum, as well as to keep a stratum's files on-disk but
out of the way.
If you would like to keep a stratum's files on your system but out of the
way, you may hide it with the brl hide command. While most users either
hide it from or show it to all subsystems, the functionality is more fine
grained and specific subsystems may be specified:
<none> defaults to --all -a, --all hide stratum in all available subsystems -b, --boot do not automatically enable stratum during boot -c, --cross do not include stratum's files in /bedrock/cross -i, --init do not list stratum's init options during boot -l, --list do not list with `brl list` without `-i` flag. -p, --pmm do not consider for `pmm` operations
One may use brl show undo a brl hide operation. While most users either
hide it from or show it to all subsystems, the functionality is more fine
grained and may only specific subsystems may be specified:
<none> defaults to --all -a, --all show stratum in all available subsystems -b, --boot automatically enable stratum during boot -c, --cross include stratum's files in /bedrock/cross -i, --init list stratum's init options during boot -l, --list list with `brl list` even without `-i` flag. -p, --pmm consider for `pmm` operations
Aliases may be created as alternative names for strata. Aliases
may be created, removed, or renamed irrelevant of their corresponding
stratum's state, making them more flexible than the strata names.
The brl alias command can be used to create a new alias. The first
argument should be a pre-existing stratum's name, and the second argument
should be the new alias name. Creating aliases to aliases is
disallowed. For example:
To dereference an alias, one may use brl deref. For example:
All Bedrock configuration is centralized in the /bedrock/etc/bedrock.conf
file. After a change is made, run brl apply (as root) to apply the changes
to the system.
Strata are responsible for maintaining their own updates. An Arch
stratum may be updated with pacman, a Debian stratum may be updated
with apt, etc. Similarly, the bedrock stratum is responsible for
updating itself. This is achieved with the brl update command.
If brl update is run without any parameters, it will attempt to download an
from a mirror configured in bedrock.conf:
Offline updates are supported by providing the update file as a parameter:
http://path-to-update -O ./bedrock-update.shBy default brl update reads the mirror value in /bedrock/etc/bedrock.conf
to determine which Bedrock mirror to use. However, this can be overridden with
-m.
brl update utilizes gpg to verify the signature on updates. However,
Bedrock does not provide its own gpg, but rather depends on other
strata to provide it. If no gpg is available, brl update will error
out accordingly. If you cannot install gpg from some other stratum, you
may tell brl update to --skip-check to skip the signature verification.
Skipping the signature check is not recommended.
Some Bedrock subsystems cannot have their update applied live and require a
reboot. If it is needed, a message will be printed by brl update after
applying the update.
Some updates propose changes to /bedrock/etc/bedrock.conf, such as when
default configuration recommendations have changed or when new configuration
options are available.
brl update may create new reference configuration files at
/bedrock/etc/bedrock.conf-. These are proposed changes to
version/bedrock/etc/bedrock.conf and may contain recommendations for new default
configurations or indicate new configuration options. Compare these files
against your bedrock.conf and apply changes as appropriate, then remove the
reference bedrock.conf-.version
brl version prints the current Bedrock version.
brl report generates a report on the system which may be useful for debugging
issues. If you run into an issue with Bedrock and seek assistance, try to
generate a report with brl report and provide it along with your problem
description.
Bedrock provides interactive tutorials via the brl tutorial command.
This command takes a parameter indicating the desired lesson. For example, the
basics tutorial is recommended for new users:
brl tutorial basics
The brl's strat subcommand is used frequently. To minimize friction, it is
made available in the $PATH stand-alone without the brl prefix. Calling
strat alone is functionally identical to brl strat. See the brl strat
documentation.
Bedrock systems typically have multiple package managers. This naturally
leads to multi- and cross-package-manage work flows which may become tedious to
do manually. For example, one may wish to upgrade all strata on the system
with something like:
Or one may wish to install a rare package and consequently manually search multiple package managers:
Bedrock provides an abstraction layer over package managers to ease such
work flows. It is Bedrock's Package Manager Manager, or pmm.
Rather than introduce a new interface for users to learn, pmm mimics user
interfaces provided by other package managers. See pmm's
configuration for how to set pmm's user interface.
The examples below may need to be adjusted accordingly.
Rather than the series of commands provided above to upgrade all packages on a system, one may run:
Regarding the second example of installing scron, one may run:
and pmm will find and install the highest priority instance the command.
pmm covers a large number of operations and some flags common to multiple
package managers, including much more functionality than described here. Once
its user-interface is configured, run pmm --help to see a list of available
flags and operations.
In addition to flags one may expect from other package managers, pmm has several specific to it.
By default, operations which change package states (e.g. installing a package)
operate on the first instance pmm finds. pmm's --every flag may be used
to indicate all available instances should be operated on. For example,
cross-stratum bash completion requires all strata to have bash-completion
installed, and so one may run:
Some workflows may have desire version constraints on packages, which pmm provides:
--newest select newest corresponding versions of items --oldest select oldest corresponding versions of items --approx-versionversiononly consider items with a version prefixed byversion--exact-versionversiononly consider items that are exactlyversion--newer-or-equalversiononly consider items that are newer than or equal toversion--newer-thanversiononly consider items that are newer thanversion--older-or-equalversiononly consider items that are older than or equal toversion--older-thanversiononly consider items that are older thanversion
For example, to install the newest abiword available:
pmm supports synchronizing the explicitly installed package state against a
configuration file at /bedrock/etc/world.
world supports comments and is helpful when keeping a Bedrock system with
a large number of packages strewn across multiple package managers organized.
For example, the world file may contain a block such as:
# bedrock linux `make check` dependencies arch:pacman clang arch:pacman cppcheck arch:pacman fuse3 arch:pacman shellcheck arch:pacman uthash debian:apt indent void:xbps shfmt
which could later be used to explain why your arch stratum has cppcheck
installed.
world can also be useful for things like moving responsibility across strata. One may substitute all instances of one stratum with another in world then apply it to the system.
world is also useful for re-creating Bedrock systems. A world file may be copied from a working system and used to clone its installed package state after the appropriate strata have been fetched and had their mirrors/repos setup.
world file operations are specified via the following pmm flags:
--diff-world print differences between /bedrock/etc/world and system's explicitly installed packages --update-world-installed populate /bedrock/etc/world with missing explicitly installed packages --update-world-removed remove /bedrock/etc/world items that do not correspond to explicitly installed packages --update-world sync /bedrock/etc/world to system's explicitly installed package list --apply-world-installed explicitly install /bedrock/etc/world items --apply-world-removed remove packages not in /bedrock/etc/world and resulting orphan packages --apply-world sync system's explicitly installed package list to /bedrock/etc/world and remove orphans