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

Bedrock Linux 1.0beta2 Nyla

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

Bedrock Linux 1.0beta2 Nyla Installation Instructions

Notes

Bedrock Linux's installation provides quite a lot of flexibility. This comes at the cost of substantial decision making during the installation process. If you would like to avoid this and simply use a set of "sane defaults", try the quick start instead of the full installation instructions described here.

While installation (particularly via hijacking described below) is in some ways improved from prior releases, it is still a relatively rough and hands-on process. If you are not an experienced Linux user it may be advisable to wait for a future release where installation has been further polished. If you wish to press on despite concerns about insufficient experience, consider testing first in a VM before committing a box to the process.

There are no explicit instructions for upgrading from a prior Bedrock Linux release; the expectation at this point in the development cycle is a fresh install. However, most of your files can be backed up and moved over to the new install unaltered, such as: /home, /root, /boot, and your strata in /bedrock/clients. Be sure to also bring along /etc/passwd, /etc/group and /etc/shadow so the UID/GIDs on disk in the strata match up.

Before beginning installation, be sure to at least skim the other pages for this release of Bedrock Linux (1.0beta2 Nyla). Make sure you know, for example, the Bedrock Linux specific lexicon defined here, are aware of the known issues and troubleshooting advice before you begin following the instructions below. Additionally, it may be best to skim all these installation instructions before actually executing them.

Throughout the instructions this syntax is used to indicate something which you should not copy exactly but instead substitute with something else. What you should substitute should be obvious from context.

Provided shell commands are prefixed with a $ or # indicating they should be run as a normal user or a root user, respectively. These prefixes won't be selected by a mouse so that you can easily copy multiple lines and paste them into a terminal. If you do copy/paste, be sure to change the aforementioned substitution syntax. Also note that copying from a web page and pasting directly into a terminal can be a bad idea.

There are two general methods for installation:

Hijack installation

While it may be possible to hijack some existing, long-used install, this has not been well tested. Instead, it is advisable to install a fresh distro and then hijack that.

If you are installing a new distro to hijack, you'll have to pick which one. Some background to help you make your choice:

NOTE: At least one user reported Slackware's initrd does not respect "rw" on the bootloader line. This may make things a bit harder; for the time being it may be advisable to pick another distro. The "rw" requirement will be dropped later to ensure Slackware becomes a viable option here.

Once you've chosen the distro, install it.

During installation, you will likely be queried for partitioning preferences. Here are some things to keep in mind:

If you aren't sure what to do here, just follow the recommendations provided by the distro you are installing. Just make sure there's plenty of space in the root partition (/). The biggest concerns above - such as not partitioning /bedrock off the root partition - will probably not be hit by most major distro recommendations.

Next, boot into the install you're about to hijack.

Skip the manual installation instructions and continue reading the instructions to compile the userland. Note the instructions below merge with the hijack installation method; they will mention things such as "if you are doing a hijack install" or "if you are doing a manual install".

Manual installation

Boot into some distro that you can utilize to partition, set up a bootloader, etc. This can be a live distro (e.g. knoppix) or an existing install on a partition other than the one you will install Bedrock Linux onto. Be sure that distro can provide the following requirements for compiling Bedrock Linux:

There have been reports of difficulties building the tarball on musl-based systems such as Alpine; until this is remedied the tarball easiest to build on glibc based systems (which includes most major distros).

Partition via preferred tools, e.g. fdisk or gparted. Some things to keep in mind:

If you aren't sure what to do here, one big partition for the root directory and a swap partition about 2.5 times your RAM size should be fine.

Set up a bootloader. Instructions for setting up syslinux are provided here. If you prefer something else, e.g. GRUB2, you'll have to find instructions elsewhere.

While it should be possible to manually set up full disk encryption, RAID, etc; no instructions are provided here to do so. If you want to utilize such technologies, either find instructions elsewhere or use the hijack installation method with a distro that provides full disk encryption, RAID, etc.

Mount the root partition wherever you like. /mnt/bedrock/ is the conventional place to mount the root of the filesystem. If you have other partitions, such as /home, mount them within the root bedrock filesystem mount accordingly.

Note the instructions below merge with the hijack installation method; they will mention things such as "if you are doing a hijack install" or "if you are doing a manual install".

Compile userland

Next you will need to compile the Bedrock Linux userland tarball. If you are doing a hijack install, you can do it from that install, or you could do it from another machine/distro and copy it over. If you plan to compile elsewhere and copy over, be careful to ensure the CPU architecture is the same (e.g. both are x86_64, or both are x86, or both are ARMv7, etc).

You'll need the following dependencies:

There have been reports of difficulties building the tarball on musl-based systems such as Alpine; until this is remedied the tarball easiest to build on glibc based systems (which includes most major distros).

As a normal user, acquire this release's source code:

Then build a Bedrock Linux userland tarball:

If everything goes well, you'll have a tarball in your present working directory. If you compiled this on something other than the installation distro, copy it over to the installation distro.

Install Bedrock Linux userland

As root, change directory to the root of the Bedrock Linux system. If you are doing a hijack install, this is your root directory (i.e. /). If you are doing a manual install, this is wherever you mounted it.

cd /path/to/bedrock-linux/root

Then expand the tarball:

tar xvf /path/to/bedrock-linux-tarball

This will create a bedrock directory. If you are using the manual install, make a symlink to this directory at /bedrock. This is useful to ensure uniformity throughout the instructions, as the same files can then be referenced at the same path irrelevant of if you are doing a manual install, a hijack install, or are currently running a Bedrock Linux system. After you have finished installing Bedrock Linux you are free to remove the symlink. Thus, if you are doing a manual install, as root:

ln -s /path/to/bedrock-linux/mount/bedrock /bedrock

tar does not track extended filesystem attributes, and brc requires a special attribute to allow non-root users to utilize it. To set this attribute, run:

/bedrock/libexec/setcap cap_sys_chroot=ep /bedrock/bin/brc

Acquire other strata

If you are doing a hijack install, the hijacked distro is being converted into a stratum which can provide a base set of system files. However, it may be desirable to have other strata before continuing so that once you boot into Bedrock Linux you already have a software from other distros ready to go.

If you are doing a manual install, you are missing essentials such as a kernel image and will need to acquire at least one other stratum to provide such things.

The tarball you expanded in the previous step provided a minimal stratum called "fallback" to use in case of emergencies. It does not provide a kernel image, but does provide things such as a minimal init system and shell.

Go here to acquire other strata then return to the instructions here. Consider opening that link in another tab/window.

Configure

The instructions below do not go into full detail configuration; they just cover the minimum you need to configure before booting into Bedrock Linux, skipping some of the details on what is going on under-the-hood. If you would like further details on configuration, see here.

Configure rootfs stratum

All of Bedrock Linux's files have some corresponding stratum. /boot, /bedrock, and if you are doing a hijack install, the hijacked distro's files, are all in the rootfs stratum.

You'll need to come up with some other name for this stratum. Then, later, rootfs will be aliased to this name so that either option will refer to the same stratum. If you did a hijack install and are keeping the hijacked distro's files, the convention here is to use the name of the hijacked distro's release (or just the distro's name of it is a rolling release). For example, if you installed and are hijacking Debian 8 "Jessie", the convention is to use "jessie" as rootfs' name. If you are doing a manual install, the convention is to use the Bedrock Linux release name. For this release, Bedrock Linux 1.0beta2 "Nyla", that is "nyla".

Edit /bedrock/etc/strata.conf and append:

[rootfs-stratum-name]
framework = default

to the bottom of the file. It should look something like:

[nyla]
framework = default

This tells Bedrock Linux that you have a stratum with the configured name, as well as tells it what per-stratum configuration to use for this new stratum. It is recommended to use the default configuration for most strata, with one exception: the global stratum. It's possible (and in fact, common) to have both rootfs and global aliases to the same stratum. If you do this, you'll have to return to this file and change "default" to "global".

Next you need to tell Bedrock Linux that this new stratum you added is rootfs so Bedrock Linux will know where to look for rootfs files such as /bedrock. Edit /bedrock/etc/aliases.conf and change:

rootfs = <DO AT INSTALL TIME>

to

rootfs = rootfs-stratum-name

Make a directory in /bedrock/strata so the stratum's files can be accessed via the explicit path:

Finally, make a symlink in /bedrock/strata so the rootfs alias can be utilized when using the explicit path. As root:

To make future commands easier, make a variable now that refers to rootfs's current location. If you are doing a hijack install (and, thus, are currently running the install you are hijacking), your current root directory is the rootfs. Thus:

Otherwise, if you are doing a manual install such that rootfs is some mount point other than your root directory, run:

If you change shells, reboot, etc. at any point be sure to update the variable as future installation commands reference it.

Some initrds assume directories existing on the root filesystem. Ensure these directories exist to appease the initrds:

Additionally, many people are accustomed to debugging a system by setting "init=/bin/sh". Ensure this option exists:

Configure global stratum

Bedrock Linux refers to a special set of files as global files. These files are used for interaction between different strata and include things such as /etc/passwd and /home. Just as /bedrock is associated with rootfs, these global files need to be associated with a stratum. This can be the same stratum as your rootfs, another distro/release's stratum, or a fresh stratum that contains nothing but the global files. Consider:

Once you've made your choice, you'll also need a name for the stratum (provided you're not reusing an existing, configured stratum such as rootfs). If this is a fresh stratum that just contains the global files, the convention is to call it "global" and avoid creating an alias for it. Otherwise, the convention is to use the distro's release (or distro's name if it is a rolling-release), e.g. "jessie" or "vivid", then create the global alias for it.

If you are not reusing an existing, configured stratum (e.g. rootfs), you'll need to make a directory for the global stratum's explicit path:

If you're using another distro for this stratum, or a stratum from a past Bedrock Linux install, move or copy the files into the newly created directory.

If you are not reusing an existing stratum, you'll need to add the stratum.conf configuration to tell Bedrock Linux about it. Edit /bedrock/etc/strata.conf and append:

[global-stratum-name]
framework = global

If you are re-using an existing stratum such as rootfs which you configured to use framework = default be sure to change default to global. Failing to do so and retaining framework = default can cause difficult to remedy issues.

If you are not naming the stratum "global", you'll need to make an alias to it. Edit /bedrock/etc/aliases.conf and change:

global = <DO AT INSTALL TIME>

to

global = global-stratum-name

Then (still assuming you are not naming the global stratum "global"), create a symlink so that the alias can be used as an explicit path:

If you are naming the stratum "global", edit /bedrock/etc/aliases.conf and remove this line:

global = <DO AT INSTALL TIME>

Like rootfs, later steps will be eased if we create a variable to reference for the current, install-time location of the global stratum.

If your rootfs and global are the same stratum:

Otherwise:

Next we need to get some required global files into this global stratum. The Bedrock Linux userland tarball included a standard set of some of these files. Copy them into place:

The tarball did not include all of the required global files; it does not include things such as /etc/passwd. You'll need to get those next.

If you are doing a hijack install and rootfs is the same as global, you already have key files such as /etc/passwd in place.

If you are doing a hijack install and you're using a fresh global stratum that only contains global files, copy various rootfs files that were created via the hijacked distro's installer that are global, such as /etc/passwd, /etc/group, /etc/shadow, /etc/fstab, and /etc/sudoers:

If you are doing a manual install and you're using a fresh global stratum that only contains global files, you can copy over your current system's /etc/passwd, /etc/group, and /etc/shadow files into the global stratum to use them as a base set of passwd/group/shadow files:

Or, alternatively, you can create a new set of these files (root password is "bedrock", be sure to change this later):

If you already have a /etc/sudoers file, append a Bedrock Linux $PATH setting to it:

Otherwise, create a sudoers file to ensure, if you do get sudo later, the $PATH is setup properly:

Ensure you have a global fstab

Ensure /tmp and /var/tmp exist and have the proper permissions:

The /bedrock/global-files directory is no longer needed. Remove it to avoid later confusion:

Configure time

Bedrock Linux 1.0beta2 Nyla's system for managing time is particularly weak at the moment. While everything one would need should be possible to do, there is a bit of additional manual work required in comparison to traditional distros. This is a known issue which should hopefully be resolved in future Bedrock Linux releases.

If you do not have a file at $GLOBAL/etc/adjtime, create one:

If your hardware clock is using UTC, ensure the third line (which should also be the last) of the file at $GLOBAL/etc/adjtime is "UTC". This is common on machines which only run Linux-based operating systems. Otherwise, if your hardware clock is in local time, set it to "LOCAL". This is common on machines which dual-boot with Microsoft Windows.

Next you'll need to configure your timezone information. Ideally your Olson timezone file would be global or implicit. Sadly, however, this does not work as of Bedrock Linux 1.0beta2 Nyla. Instead, Bedrock Linux will attempt to direct everything to utilize the timezone file at /bedrock/etc/localtime. This file needs to be updated manually. Thus, copy your desired timezone file to /bedrock/etc/localtime:

for example:

If timezone information changes, either because you move timezones or some local law changed the timezone details where you reside, remember to repeat this with an updated Olson timezone file. Most distros - and hence, your strata - will update their /usr/share/zoneinfo files automatically as laws change the timezone details.

Configure init

Bedrock Linux needs to have the available init systems configured to utilize them. For any strata which provides an init system, edit /bedrock/etc/strata.conf and add:

init = /path/to/init

to configure Bedrock Linux to utilize the given executable as provided by the given stratum as a potential init system.

For example, if you did a hijack install on a distro that uses systemd, you probably want:

init = /lib/systemd/systemd

under

[rootfs-stratum-name]

so it will look something like:

[jessie]
framework = default
init = /lib/systemd/systemd

If you are configuring a stratum which does not utilize systemd, you probably want

init = /sbin/init

for example:

[void]
framework = default
init = /sbin/init

Additionally, you can set a default stratum/command pair, as well as a timeout which will trigger the default if left to expire, by editing /bedrock/etc/brn.conf. Set the desired default stratum and the command that should be run for it as well as the desired timeout in seconds. If the timeout is set to "0" it will immediately pick the default. If the timeout is set to "-1" it wait indefinitely. For example:

default_stratum = alpine
default_cmd = /sbin/init
timeout = 10

Configure hostname

The default hostname is "bedrock-box". To change this, edit $GLOBAL/etc/hostname as desired.

Change "bedrock-box" in $GLOBAL/etc/hosts to your desired hostname as well.

Configure fstab

Bedrock Linux has three files that need to be updated for any partitions outside of the typical root and swap partitions:

If your partitioning scheme is more complicated than simply a root filesystem and a bootloader, configure these three files as described here then return to these instructions. Consider opening that link in another tab or window.

Linux kernel and associated files

Next you'll need a set of related files usually tied to the Linux kernel to be placed in specific locations. At a minimum you need one set, but more could be desired. If you are doing a hijack install where global and rootfs are the same stratum, you should already have one set of these files in place. If that is the case, you can skip down to the Manager users and groups step.

/boot files

Typically one or more Linux kernel images and some associated files, such as initrds, are placed into $ROOTFS/boot/. These files are:

If you are doing a hijack install, you've already got one set in place. If that is the case and if you do not want to get others you can skip to the next section.

Look through /bedrock/strata/*/boot/ to see if you have such a set of files. If not, you'll have to chroot into at least one of the stratum and install them, like so:

From here, run whatever commands are necessary to install the kernel. For example, in a x86_64 Debian-based stratum, run:

apt-get update && apt-get install linux-image-amd64

or for an Arch Linux stratum run

pacman -Sy linux

When you have finished, run the following to clean up:

Once you have located at least one set of these files, copy them into $ROOTFS/boot/.

For example, if copying Arch Linux's initrd and kernel image:

modules

Kernel images are typically paired with kernel modules which are located in /lib/modules. Find the modules associated with the kernel files you copied into $ROOTFS/boot and place it into $GLOBAL/lib/modules.

If you are doing a hijack install and your rootfs and global are the same stratum, you've already got one set of modules in place. If you do not want to get others you can skip to the next section.

Look through /bedrock/strata/*/lib/modules to see if you have such a set of files. You most likely have one set associated with the kernel image you copied in the previous step. Copy these modules into $GLOBAL/lib/modules.

For example if an Arch Linux strata provides the desired files:

firmware

Bedrock Linux 1.0beta2 Nyla's system for managing firmware is particularly weak at the moment. While everything one would need should be possible to do, there is a bit of additional manual work required in comparison traditional distros. This is a known issue which should hopefully be resolved in future Bedrock Linux releases.

Various firmware files needed by kernel modules are typically made available in /lib/firmware. Sadly, these files do not cleanly fit into either the local or global category: software from various strata need to see them such that they should be global, but various package managers will conflict if they see firmware from other strata such that they should be local. Moreover, the Linux kernel may try to read them from the rootfs before the global system is set up, making global non-viable.

Until a better solution is implemented, the solution is to simply copy them from the various strata that provide them to the various strata that need them, then remove them if/when a package manager complains.

Since the kernel may try to read them from rootfs, that's a good place to start. Copy the various firmware files from the various strata into $ROOTFS/lib/modules/:

Manage users and groups

You already have some basic users and groups set up from the "Configure global stratum" step, but it is best to ensure some minimum expectations are met before continuing.

To manage users and groups, you'll need to chroot into global. However, unless you set up rootfs and global to be the same stratum, it is not guaranteed that global has any commands to run at this point. Bedrock Linux's subsystems will resolve this at run time, but not during installation. If rootfs and global are different, run:

Now that we know that a special build of busybox exists at $GLOBAL/bedrock/libexec/busybox, we can chroot to it:

First, ensure you have a root user:

That should output "1". If it does not we'll need to make a new pair of passwd and shadow files:

Set the root user's password:

To handle nuances of how shells are handled in a typical Linux system, Bedrock Linux provides its own meta-shell, brsh, which can be configured to immediately switch to some other, desired shell (e.g. bash or zsh). Ensure root is using brsh:

While brsh is very convenient for most instances, it may be wise to provide a way to bypass it in case something goes wrong. Add a new username "brroot" as an alias to the root user which uses /bin/sh:

Next, check if your desired normal user exists. It may have been inherited from the hijacked install:

If that does not print "1", add the user:

Set the user's password:

And ensure the user is using brsh:

If you'd like a emergency-drop-to-/bin/sh alias for this user as well, you can optionally create one:

Next we'll need to add expected users and groups. If you get a "in use" error, this simply indicates you already have the user or group; no harm done.

It may be desirable to add your normal user to the "audio" and "video" groups:

If you plan to use systemd as your init at some point, even just temporarily, it is a good idea to ensure some of the users and groups it expects exist, as otherwise it may fail to boot.

If you want to add any other users or groups, now is a good time. Once you're done, exit the chroot.

Consider editing other global configuration files such as $GLOBAL/etc/sudoers now.

Configure bootloader

Finally, you will need to configure your bootloader. This is the last major step for the installation.

You'll want to change four things:

For example, if you are using GRUB2, edit:

/etc/default/grub

and change

GRUB_CMDLINE_LINUX=...

to

GRUB_CMDLINE_LINUX="rw init=/bedrock/sbin/brn"

and

GRUB_DISTRIBUTOR=...

to

GRUB_DISTRIBUTOR="Bedrock Linux 1.0beta2"

If you see "splash" in any of the GRUB configuration lines, such as

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

remove it, leaving something like:

GRUB_CMDLINE_LINUX_DEFAULT="quiet"

Finally, run

to have GRUB2 read and utilize the updated configuration.

With syslinux or LILO, just edit the relevant lines to change the menu item to "Bedrock Linux 1.0beta2 Nyla" and add "rw init=/bedrock/sbin/brn" to the kernel line, as well as ensure "splash" is unset. For example, with syslinux, an adjusted stanza may look like:

LABEL nyla
    MENU LABEL Bedrock Linux 1.0beta2 nyla
    LINUX ../vmlinuz-3.16.0-4-amd64
    APPEND root=/dev/sda1 quiet rw init=/bedrock/sbin/brn
    INITRD ../initrd.img-3.16.0-4-amd64

Reboot

At this point, everything should be good to go. Just reboot into Bedrock Linux and enjoy!

If you run into any difficulties, try reviewing the relevant documentation pages for this release, and if that doesn't help sufficiently, don't hesitate to drop into the IRC channel #bedrock on libera.chat, the forums, or subreddit.