__          __             __
\ \_________\ \____________\ \___
 \  _ \  _\ _  \  _\ __ \ __\   /
  \___/\__/\__/ \_\ \___/\__/\_\_\
                      Bedrock Linux

Introductory Material


Reference Material

Extending Bedrock


© Bedrock Linux 2012-2022
Linux® is a registered
trademark of Linus Torvalds

Bedrock Linux 0.7 Poki Basic Usage

This page will introduce you to the minimum Bedrock Linux-specific background required to utilize and manage a Bedrock system.

An interactive version of this content is available on Bedrock systems via the brl tutorial basics command.


A Bedrock system is composed of strata, which are collections of interrelated files and processes. These typically correspond to Linux distro installs: one may have a Debian stratum, an Arch stratum, etc. Bedrock integrates these into a single, largely cohesive system.

To list the currently installed (and enabled) strata, run:

brl list

A fresh install will have two strata:

This, alone, is of little more immediate value than just the initial install. To benefit from Bedrock more strata are needed. To list distros Bedrock knows how to acquire as strata, run:

brl fetch --list

Then to acquire new strata, run (as root):

brl fetch distros

This may fail if it auto-detects a bad mirror. If so, manually find a good mirror for the distro and provide it to brl fetch with the --mirror flag.

Cross Stratum Commands

Many features from strata should work just as they would in their normal environments. For example, if you brl fetch'd Alpine and Void strata, you can run both Alpine's package manager:

apk --help

and Void's package manager:

xbps-install --help

These can be used to install packages from each stratum such as Alpine's jq and Void's jo:

The commands can interact just as they would were they from the same distro. This command works just as it would if jo and jq came from the same distro:

Other Cross Stratum Features

Bedrock integrates more than just terminal commands. It strives to make as much as it can work transparently and cohesively across strata, including:

Lets try another example: man pages. We can get Alpine's jq man page and Void's man executable:

Then have Void's man read Alpine's jq documentation:

which, again, works as it would had the man executable and jq man page come from the same distribution.

brl which

On a Bedrock system, every file and every process is associated with some stratum. The brl which command can be used to query Bedrock for this association.


would indicate the Alpine and Void strata, respectively.

What about commands that multiple strata, such as both Alpine and Void, provide? For example, ls:

brl which ls

This will indicate one stratum's instance. This is the one which will be run if ls is run in the given context. How it picks this stratum will be described further on.

brl which can also be used for Process IDs. To see which stratum provides the running init system, one could run:

brl which 1

File paths work as well:

brl which /

indicates which stratum's root directory listing will be provided by a ls / in the given context. How this is chosen, like the ls example above, described below.

One last hint towards upcoming content: querying for the Bedrock configuration file stratum:

brl which /bedrock/etc/bedrock.conf

prints global, which is not a stratum name.

Local File Paths

To avoid conflicts, processes from one stratum may see their own stratum's instance of a given file (or lack of file) at a given file path.

You can query Bedrock for the stratum associated with your shell:

brl which

This stratum will match queries the root directory example in the previous section:

brl which /

If your shell stratum has a /etc/os-release file, it will probably correspond to your shell stratum distro:

cat /etc/os-release

This is needed to avoid conflicts. For example, Debian's apt needs to see Debian mirrors at /etc/apt/sources.list and Ubuntu's apt needs to see Ubuntu's mirrors at the same path. If they saw the same contents in sources.list these two programs would conflict with each other.

In Bedrock terminology, these file paths are described as local.

Global File Paths

If all paths were local, strata would be unable to interact with each other. For strata to interact, there are also global paths: file paths where every stratum sees the same content. Under-the-hood, these are bedrock stratum files which are being shared with other strata.

For example, all strata see the same contents in /run to communicate over common sockets:

brl which /run

Directories like /home and /tmp are also global. You can have software from one stratum, like Alpine's jq, read files created by another stratum, like Void's jo, provided the file is in a global location:

Cross File Paths

Sometimes processes from one stratum need to access local files from another. This is achieved via cross file paths.

If you want to read or write to a local file specific to a given stratum, prefix /bedrock/strata/stratum to the file path to cross to that stratum.

A previous example read the local /etc/os-release, whose output was dependent on which process read it. To read specifically bedrock's /etc/os-release, run:

cat /bedrock/strata/bedrock/etc/os-release

Similarly, a gentoo stratum's /etc/os-release can be read via:

cat /bedrock/strata/gentoo/etc/os-release

The strat Command

/bedrock/strata/ is only suitable for reading and writing cross files. To execute a program from a specific stratum, prefix strat stratum.

For example, if you have both a debian stratum with an apt command and an ubuntu stratum with an apt command, you could run:

strat ubuntu apt

to run ubuntu's.

If you do not specify the desired stratum with strat, Bedrock will try to figure one out from context:

The first bullet point above is how Bedrock ensures the reboot comes from the init stratum and why these two commands usually provide the same output:

The second bullet point above is why the ls you get if you do not specify one with strat is probably from the same stratum providing your shell and consequently why these two commands provide the same output:

Finally, the third rule above is why commands like apk and xbps-install work despite being from different strata:


Occasionally, software may become confused by Bedrock's environment. Most notably this occurs when build tools scan the environment for dependencies and find them from different distributions. To handle this situation, strat's -r flag may be used to restrict the command from seeing cross-stratum hooks.

For example, normally Void shell can see an Alpine stratum's apk. Provided the strata are available, this command can be expected to work:

strat void sh -c 'apk --help'

But if you restrict it this command will usually fail:

strat -r void sh -c 'apk --help'

Bedrock will automatically restrict some commands that it knows are related to compiling, such as Arch's makepkg. If this is a problem for any reason, you can un-restrict with strat -u.

In general, if something acts oddly under Bedrock, the first thing you should try is to restrict it. This is especially true when it comes to compiling software.

Stratum states

It is sometimes useful to have a stratum's files on disk without them being integrated into the rest of the system. To do this, disable the stratum with the brl disable command. For example:

brl disable void

This will stop all of the stratum's running processes and block the ability to launch new ones. This command will now fail:

strat void xbps-install --help

The stratum may be re-enabled:

brl enable void

after which this command will again work:

strat tut-void xbps-install --help


Strata are each responsible for updating themselves. To update an Alpine stratum we can tell its package manager to update:

apk update && apk upgrade

and to update a Void stratum we can similarly instruct its package manager:

xbps-install -Syu

Bedrock's stratum can be updated via brl update:

brl update

Removing Strata

As a protective measure, strata may not be removed while enabled. If you wish to remove a stratum, first disable it.

If you know the target stratum is enabled, brl remove takes a -d flag to disable prior to removing:

Special strata

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

brl which 1

outputs void, this command will fail:

brl disable void

If you wish to remove the init-providing stratum, first reboot and select another stratum to provide your init for the given session.

The bedrock stratum glues the entire system together. It is the only stratum which may not be removed.

There is nothing particularly special about the stratum created by hijacking another Linux install. You are free to remove it, should you wish to do so. Just make sure to install anything essential the stratum is providing, such as a bootloader, kernel, or sudo, in another stratum.

Importing strata

If you would like to make a stratum from some distro that brl fetch does not support, you may use the brl import command to do so.

Get the desired files in some format such as:

then run

brl import name /path/to/source


All Bedrock configuration is placed in a single file, /bedrock/etc/bedrock.conf. If it seems like something Bedrock does should be configurable, look in there. After making changes to bedrock.conf run brl apply to ensure they take effect.


Most operations used to manage Bedrock can be found in the brl command. This includes both those discussed earlier on this page as well as some which were skipped for brevity.

Consider exploring brl:

brl --help

going through provided tutorials:

brl tutorial --help

or reading through /bedrock/etc/bedrock.conf.