__          __             __
\ \_________\ \____________\ \___
 \  _ \  _\ _  \  _\ __ \ __\   /
  \___/\__/\__/ \_\ \___/\__/\_\_\

Bedrock Linux 1.0alpha4 Flopsie

Bedrock Linux 1.0alpha4 Flopsie Installation Instructions

Before beginning installation, be sure to at least skim the other pages for this release of Bedrock Linux (1.0alpha4 Flopsie). Make sure you're aware of, for example, the known issues and troubleshooting advice before you begin following the instructions below.

If you are currently using a previous version of Bedrock Linux, note that many of the existing directories from your current installation may be used in this release unaltered: /home, /root, and /boot. Additionally /var/chroot still exists; however, it was moved to /bedrock/clients. When these directories come up in the following instructions, consider simply copying the old values over the ones created here. Additionally, it could be useful to keep your configuration files, such as brclients.conf and /etc/passwd, to reference.

Installation Host Environment

First, boot a Linux distribution from a device/partition other than the one on which you wish to install Bedrock Linux. This will be called the "installer host." The installer host can be a LiveCD or LiveUSB Linux distribution (such as Knoppix or an Ubuntu installer), or simply a normal Linux distribution on another device or another partition on the same device.

Most major Linux distributions will work for installer host, provided they support compiling tools such as make. Distributions with ready access to debootstrap (such as most major Debian-based distributions, Arch Linux through AUR, Fedora, and others) are preferable if you would like a Debian-based client, as they will make it relatively easy to acquire said client through debootstrap. The installer host should also have internet access.

Be sure the installer host uses the same instruction set as you wish Bedrock Linux to use. Specifically, watch out for (32-bit) x86 live Linux distribution if you wish to make Bedrock Linux (64-bit) x86-64. While it is possible have the installer host use a different instruction set from the targeted Bedrock, it is a bit more work and not covered in these instructions.

If the computer on which you wish to install Bedrock Linux is slow, you may find it preferable to use another computer to do the CPU-intensive compiling. These instructions do not cover compiling on a separate machine from the one on which you wish to install.

There are known difficulties compiling with gcc 4.8.2 and 4.9.0. At the time of writing, Arch Linux has 4.9.0 and Ubuntu Trusty has 4.8.2. Consider using a distribution with an older gcc release until the situation is remedied. See here and here for details. You can, for example, use an Ubuntu Raring or Debian Wheezy based live CD/USB with gcc 4.7.X

Partitioning

Using partitioning software such as gparted or fdisk, partition the device on which you wish to install Bedrock Linux. Be very careful to only format bits and bytes which you no longer need - a mistake here could blow away another operating system with which you intended to dual-boot with Bedrock.

For the most part you are free to partition the system however you please. If you are unsure of how to partition it, it is reasonable to use only two partitions:

  1. Your main partition for mounting the root directory (ie, /)
  2. A swap partition. Recommendations for swap sizes usually vary between equal to your RAM size to two-and-a-half times your RAM size.

If you are comfortable with typical partitioning schemes for Linux - such as making /boot, /home, etc their own partitions - you are free to do so. Before doing so, note some unusual aspects of Bedrock's layout:

Note which devices files correspond to which partitions of the Bedrock Linux filesystem. These are normally located in /dev, and called sdXN, where X is a letter a-z and N is a digit 0-9. This information will be used later to mount these partitions.

Flopsie has only been tested with the ext2 and ext3 filesystems, but any Linux-supported filesystem should work fine. If you choose to use something other than ext2/3/4, be sure you know where to find (and how to set up) corresponding fsck software and a bootloader which can work with that filesystem, as these instructions will only cover ext2/3/4.

If you are dual-booting with another Linux distribution, wish to use that distribution's bootloader, and know how to add Bedrock Linux to that distribution's bootloader, be sure to keep the boot flag on the other distribution's boot partition. If you would like to use Bedrock's bootloader, be sure to set the boot flag on the proper partition (ie, either the Bedrock's main/root partition or, if you made a special /boot partition, then the /boot partition you made).

Mounting Bedrock's partitions

Make a directory in which to mount Bedrock Linux's fresh to partition(s). These instructions assumes you are using /mnt/bedrock for this. If you would like to use something else, be sure to change /mnt/bedrock accordingly whenever it comes up in these instructions. In general, when you see anything formatted like this that is a reminder that you should consider changing the content rather than typing/copying it verbatim.

Note that this will become Bedrock Linux's root directory when you are done. As root:

mkdir -p /mnt/bedrock

Mount the newly-created main/root partition. Replace sdXN with the corresponding device file to the main/root partition. As root:

mount /dev/sdXN /mnt/bedrock

If you created more than one partition (other than swap) for Bedrock Linux, make the corresponding directories and mount them. If you are upgrading from a prior release of Bedrock Linux, and you have partitions which contain only a subset of the following, they are probably safe to mount and use. Be sure to back up nonetheless - using pre-existing partitions has not been well tested and a command below may wipe them.

Creating the Userland

The Bedrock Linux userland repository contains build scripts to install much of the Bedrock Linux operating system. Clone the latest version of the 1.0alpha4 branch from git into /mnt/bedrock. You may use a non-root user (as permissions will be fixed later) for this.

Download the source code for the third party components into /mnt/bedrock/src alongside the brc and bru directories which should now be there, as explained in the following sections.

musl

The musl libc library is required. The project's website is available at:

http://www.musl-libc.org/

Use the newest version from the 1.0.X series you can find here:

http://www.musl-libc.org/download.html

For example, at the time of writing the newest is 1.0.3:

http://www.musl-libc.org/releases/musl-1.0.3.tar.gz

linux headers

The Linux kernel repository is required for the Linux header files. A tarball containing the latest Linux kernel should be found here:

https://www.kernel.org/

fuse

FUSE is required. The project's website is available at:

http://fuse.sourceforge.net/

At the time of writing, the latest FUSE release - 2.9.3 - does not have all of the required functionality. Either use a newer release (3.X) if available or get the latest version from git. The latest stable releases should be found here:

http://sourceforge.net/projects/fuse/files/

And the git repository should be available here:

git clone git://git.code.sf.net/p/fuse/fuse fuse-fuse

At the time of writing, the latest commit has broken things. After checking out the repository, checkout commit dd432032db34c2ca22570af5ac6794822ef4c877

cd fuse-fuse
git checkout dd432032db34c2ca22570af5ac6794822ef4c877

busybox

Busybox is required. At the time of writing, the latest busybox release - 1.21.1 - does not have all of the required functionality. Either use a newer release (1.21.2, 1.22.0, etc) or get the latest version from git. The latest stable release should be available as a tarball here:

http://www.busybox.net/

And the git repository should be available here:

git clone git://busybox.net/busybox.git

Linux capabilities

The Linux Capabilities libraries and utilities are required. The project's website is at:

https://sites.google.com/site/fullycapable/

At the time of writing a tarball is unavailable, but the git repository is available here:

git clone git://git.kernel.org/pub/scm/linux/kernel/git/morgan/libcap.git

At the time of writing, the latest commit has broken things. After checking out the repository, checkout commit 056ffb0bd25d91ffbcb83c521fc4d3d9904ec4d4

cd libcap
git checkout 056ffb0bd25d91ffbcb83c521fc4d3d9904ec4d4

Building the userland

You will need the following items to build the userland:

On a Debian-based system, this should install everything required:

apt-get install build-essential libattr1-dev libtool autoconf automake gettext

If you are on another system, install the equivalent packages.

To compile everything, run

If it does not complete successfully, look at the output the script generates as well as the logs in the location indicated. You may simply be missing a dependency or third party source code.

To install everything, run (as root)

You should now have everything required to use Bedrock Linux except the following:

Acquiring a client

Acquire at least one client as described on the client page and return here.

Install the Linux kernel

The client acquired in the last step will provide the kernel for Bedrock Linux.

Check if it came with a kernel:

ls /mnt/bedrock/bedrock/clients/client/boot

If so, you may skip this next step (up until "resume here"). Otherwise, chroot into the client and acquire a client through its package manager:

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

apt-get install linux-image-amd64

or for an Arch Linux client run

pacman -S linux

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

If you already had a kernel installed in the client, resume here.

Next, you must copy the relevant files from the location in the client into the core of Bedrock Linux so they can be accessed while booting.

Install a bootloader

Next you will need to setup Bedrock Linux to boot, either without a bootloader, with its own bootloader or dual-booting with another operating system's bootloader.

If you have another operating system installed which can boot a Linux distribution and know how to add Bedrock Linux to it, feel free to do so.

If you know how to boot Linux distributions without a bootloader (leveraging EFI, for example), you can set that up instead of installing a bootloader.

Otherwise, you should install a bootloader. If you have a preferred bootloader which you know how to install, go ahead and use that one. If you do not, limited instructions for installing syslinux/extlinux are available here. Follow those instructions then return here.

Fsck

The typical fsck executable itself is a front-end for filesystem-specific executables. If you want to have Bedrock Linux run fsck on boot as most other major Linux distributions do, you will need to install the filesystem-specific executable fsck should call for your filesystem(s). Note that while this is recommended, it is optional - you can set "FSCK=0" in your rc.conf to disable fsck, in which case you do not need to install fsck.

For ext2, ext3 and ext4, you can find the source for the fsck executable at the sourceforge page. If you would like to use another filesystem, it should not be difficult to find the fsck for it and install it instead, but these instructions do not cover it.

Change to the directory in which you placed the downloaded source, untar it and enter the resulting directory:

Create a build directory and change directory into it:

Compile the fsck executables:

To confirm that the desired executable was compiled statically, run

and check that the output is "not a dynamic executable".

To install the filesystem specific executable, simply copy it to what will be Bedrock's /sbin with the names of the filesystems it supports (as root):

Configuration

All of the major components should be installed at this point; all that remains is to edit the configuration files as desired. The instructions to do so are broken up into two parts:

Add users

The install script defaults to having two users, "root" and "brroot". "root" is the normal root user. "brroot" is actually the same user (both have UID 0); it is simple an alternative login which will always log in to Bedrock Linux's core rather than a shell from a client. While "brroot" is not required, it is quite useful as a fall-back in case the you would like to use a shell from a client for root and that client breaks.

The next handful of command should be run in a chroot:

chroot /mnt/bedrock /bin/sh

The root user (and brroot) both have default passwords of "bedrock". To change this to something else, run

passwd -a sha512

Note that this will only change root's password; the brroot login for the same user will still have the default password. To change brroot password to the same thing, run:

Next, add normal user(s) as desired:

If you would like to create a "br-" version of these users which will use the same password to log in but will always log in to the core of Bedrock Linux, run the following for each user once:

Once you have completed adding all of the desired users and setting their passwords, you may exit the chroot

exit

Hostname

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

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

Bedrock-Specific Configuration

See the flopsie configuration page for instructions on how to configure Bedrock Linux specific functionality such as clients.

Post-Reboot

Reboot into Bedrock Linux and run the last command to set it up. Log in as root and run:

brp

Everything should be good to go. 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.

Enjoy!