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

Bedrock Linux 1.0alpha1 Appa

Appa Client Setup Instructions

These are instructions client Linux distributions. They cover both general information as well as information specific to individual Linux distributions.

  1. Any Linux Distribution
    1. Installation
    2. Tweaks and Configuration
  2. Debian-based Linux distributions
    1. Installation
    2. Tweaks and Configuration
    3. Troubleshooting
  3. Arch Linux
    1. Installation
    2. Known issues
    3. Troubleshooting
  4. Fedora
    1. Installation
    2. Troubleshooting

Any Linux Distribution

Installation

If there are no instructions below specific to a Linux distribution which you would like to make into a client for your Bedrock Linux install, you can usually fall back to simply installing the distribution through its normal installation means. Once it is installed, you may simply copy its root directory to where you would like the client to reside within Bedrock. When installing the Linux distribution by its normal means, be very careful when partitioning, and be careful to avoid having the bootloader take over your system.

For example, if you install Slackware to a USB flash drive, you can mount the USB flash drive in Bedrock Linux and copy its contents to /var/chroot/slackware.

However, this method requires rebooting as well as provides the possibility of unintentionally wiping something important when partitioning or forcing you to reinstall your bootloader, and thus the distro-specific instructions described below may be preferable if available.

Tweaks and Configuration

Sudo PATH:

It may be advisable to look at the PATH generated by /etc/profile for root and set it as /etc/sudoer's secure_path.

Users/Groups when package managing:

Due to a known issue with Bedrock, the usual means for adding users and groups does not from work in clients. Many packages in the repositories of clients may attempt to add users or groups. Apt/dpkg is known to abort if it cannot add a group, and pacman is known to continue without aborting despite the issue. If this happens, you can attempt to add the users/groups from wihtin core Bedrock Linux or manually edit the files with your text editor of choice (from the core or within a client, either is fine). You can then re-run the package manager command.

Proprietary Nvidia Drivers:

For the Nvidia proprietary driver to work, you should ensure the directory containing the kernel modules (historically /lib/modules, although there is a push to move it to /usr/lib/modules) is either shared or copied into at least the client(s) which run X11/xinit/startx. Moreover, you should ensure nouveau is not enabled. Bedrock currently does not have any system in place to manage kernel module loading. If you compiled your kernel with nouveau, you can simple (re)move the module. To find it, run 

find /lib/modules -name nouveau

and move or delete the file (as root).

The proprietary Nvidia driver should be compiled using the same version of the same compiler used to compile the kernel. If you compiled the kernel in the installer host, you can make a Bedrock Linux client from the installer host and use that to compile the nvidia driver. Otherwise, you can recompile the Linux kernel using a client (and install it and reboot) and then use that client again to compile the nvidia driver.

Debian-based Linux distributions

Installation

The essentials of Debian-based Linux distributions can be installed through a program called "debootstrap." Debootstrap is a shell script which can be easily installed into almost every Debian-based Linux distribution, and is often available in the repositories of non-Debian-based Linux distributions, such as Fedora. While it is possible to install debootstrap (by first installing dpkg and pkgdetails) into just about any other Linux distribution as well, it is not covered here. Busybox's dpkg does not seem sufficient for debootstrap.

Instructions:

  1. Boot into a Linux distribution which can run debootstrap, or use a client which can use debootstrap in Bedrock Linux if available. LiveCD/LiveUSBs such as Knoppix or an Ubuntu installer should work.

  2. Ensure the pre-requisites for debootstrap are available. This can be done by installing debootstrap through the distribution's package manager, if available. Next, download the .deb file for the debootstrap specific to client Linux distribution release you would like, or a newer debootstrap .deb from the same distribution. For example, for Debian Squeeze, grab the file made available from here. If you are attempting to use debootstrap from a non-debian-based Linux distribution, convert the .deb file to the native package format with something such as the alien package.

  3. Install the package. If on a debian-based system (as root): 

    dpkg -i debootstrap_.deb

  4. Make a directory in which to put the target client Linux distribution. 

    mkdir PATH

  5. Use debootstrap to download and set up the target client Linux distribution. 

    debootstrap --arch ARCHITECTURERELEASE PATH REPOSITORY/MIRROR

    For example, to install the (64-bit) x86_64 Debian squeeze to /var/chroot/squeeze using http://ftp.us.debian.org/debian: 

    debootstrap --arch amd64 squeeze /var/chroot/squeeze http://ftp.us.debian.org/debian

    It may take a bit to download and unpackage the various components.

  6. Don't forget to edit /etc/apt/sources.list and other client-specific settings.

Tweaks and Configuration

Ubuntu/Upstart fix:

Ubuntu uses Upstart for its init system. Many services in Ubuntu have been modified to depend on init to be specific to Upstart and refuse to operate otherwise. This means they do not work in chroots out of the box. See the here for more information. One way to alleviate this is to run the following two commands as root (within the Ubuntu client, via using brc for each command or brc to open a shell in the client and run it from the shell):

Locales:

In Debian, if you get errors about locale, try installing the locales-all package.

In Ubuntu, if you get errors about locale, try installing the appropriate language-pack-* (such as language-pack-en) package.

Troubleshooting

If you get an error about statoverride when using apt/dpkg, it can most likely be resolved by deleting the contents of /var/lib/dpkg/statoverride (from within the client - ie, /path/to/chroot/var/lib/dpkg/statoverride from outside). Leave an empty file there. This seems to occur due to the fact an expected daemon is not running.

Arch Linux

Installation

Arch Linux's package manager, pacman, can be used to setup a new Arch Linux install in a folder in a manner similar to Debian's debootstrap. It is possible to setup pacman and its requirements in a folder and then use it through chroot, largely independent of the host Linux environment. From there, it can be used to setup a new Arch Linux client for Bedrock Linux. This should work from a client Linux distribution for Bedrock Linux or from a LiveCD/LiveUSB. Whether this works from the core of Bedrock Linux remains untested.

Instructions:

  1. Create and move into a temporary working directory:

    • mkdir /tmp/archbootstrap
    • cd /tmp/archbootstrap

  2. Download and the required software.

    • ARCH=ARCH # Set to either "x86_64" to "i686"
    • wget https://www.archlinux.org/packages/core/any/pacman-mirrorlist/download --trust-server-names
    • for PACKAGE in pacman glibc gcc-libs binutils libssh2 curl gcc libarchive openssl xz expat gpgme zlib libassuan libgpg-error acl attr bzip2
    • do
    • wget https://www.archlinux.org/packages/core/$ARCH/$PACKAGE/download/ --trust-server-names
    • done

  3. Unpackage all packages

    • for PACKAGE in *.pkg.tar*
    • do
    • tar xvf $PACKAGE
    • done

  4. Uncomment a mirror in /tmp/archbootstrap/etc/pacman.d/mirrorlist to use to download Arch Linux.

  5. Disable signiture verification. Open /tmp/archbootstrap/etc/pacman.conf, find the line containing SigLevel under [core] and change the value to Never. Note that this is only for the initial download of Arch Linux - it can continue to use signiture verification like normal once installed as a Bedrock Linux client.

  6. Copy /etc/resolv.conf into the archbootstrap environment so it can resolve DNS. 

    cp /etc/resolv.conf /tmp/archbootstrap/etc/

  7. Update the archboostrap we've set up, just in case 

    chroot /tmp/archbootstrap pacman -Syu

  8. Create a new directory in which to download and install the Arch Linux client. Note that this has to be within /tmp/archbootstrap. You can later move the contents to where you prefer, or you can make a bind mount so everything installed into this new directory actually goes where you want it to. Moreover, ensure it includes the location for pacman's databases within it. 

    mkdir -p /tmp/archbootstrap/arch/var/lib/pacman/local

  9. Have pacman download its database information into the new directory. Note that we are stripping off /tmp/archbootstrap because this is being run in a chroot. 

    chroot /tmp/archbootstrap pacman -Sy -r /arch

  10. By default, pacman checks if enough free space is available before unpackaging things. However, the chroot and heavily-used bindmount environment seem to confuse it. Comment out CheckSpace from /tmp/archbootstrap/etc/pacman.conf

  11. Install Arch Linux's base: 

    chroot /tmp/archbootstrap pacman -Su base -r /arch

    It may take a bit to download and unpackage the various components.

  12. If you did not bind-mount /tmp/archbootstrap/arch, move /tmp/archbootstrap/arch to where you would like the Arch client to reside. Otherwise, unmount it so it is no longer accessible within /tmp/archbootstrap. 

    mv /tmp/archbootstrap/arch PATH

  13. Clean up the temporary archbootstrap directory: 

    rm -rf /tmp/archbootstrap

Known issues

/lib symlink:

Arch Linux symlinks /lib to /usr/lib. If you would like to share (some of the) contents of /lib across clients (for example, if you would like to share /lib/modules), the symlink can cause issues with how Bedrock Linux manages sharing directories.

For the time being, it is recommended that you simply avoid using bind mounts to attempt to share such directories. Simply copy the contents across manually when required.

Troubleshooting

Pacman filesystem errors:

If you get errors about "could not get filesystem information for PATH" when using pacman, this is normal and mostly harmless so long as you have sufficient free disk space for the operation you are attempting. This seems to be caused by pacman assuming that the mount points it sees are the same as the ones init sees (which would be a fair assumption in almost every case except Bedrock Linux). You can configure pacman to not check for free disk space by commenting out CheckSpace from /path/to/chroot/etc/pacman.conf

/dev/fd errors:

If you receive errors along these lines:

/dev/fd/N: No such file or directory

where N is a number, this is most likely due to the fact that the device manager you are using is not setting up /dev/fd as some Arch programs expect. This can be solved (for the current session) by running:

To solve this permanently, one could simply add those two lines to /etc/rc.local in the core Bedrock such that it is run every time Bedrock Linux is booted.

Fedora

Installation

The essentials of Fedora can be installed through the 2.X branch of a program called "febootstrap". Febootstrap is very similar in spirit to debootstrap, simply intended for creating Fedora systems rather than Debian. Note that a 3.X branch was created which is intended to create "supermin appliances"; use the 2.X branch instead. This may be difficult to find in the repositories of any given Linux distribution, and thus it may be required to compile it from source.

Instructions:

  1. If you have access to a Linux distribution which has febootstrap 2.X in its repositories, your you can find a febootstrap 2.X package which will work in a distribution to which you have access, install it and run the following command, at which point you will be done installing Fedora as a client (ie, you can skip the rest of the steps below). Otherwise, you will have to skip this step and following all of the following steps. 

    febootstrap fedora-RELEASE-NUMBERPATH

    For example, to install Fedora 17 (beefy miracle) to /var/chroot/beefy: 

    febootstrap fedora-17 /var/chroot/beefy/

    It may take a bit to download and unpackage the various components.

  2. Boot or brc into a Linux distribution which will be used to compile febootstrap and then later use febootstrap. Note that while most of the requirements for febootstrap are fairly standard, it does require yum, which is in many but not all of the major Linux distribution's repositories - chosing one of the distributions which do will make things easier.

  3. Download the latest febootstrap 2.X source from here to /tmp.

  4. Untar the package.

    • cd /tmp
    • tar xvf febootstrap-VERSION.tar.gz

  5. Configure things. You may be warned you are missing requirements - install them and try again.

    • cd /tmp/febootstrap-VERSION
    • ./configure

  6. Compile febootstrap. 

    make
    If you receive an error about -all-static, note that at least one person who had such an error reported some succes compiling febootstrap by commenting out the line containing init_LDFLAGS = -all-static from /tmp/febootstrap-VERSION/helper/Makefile and replacing it with init_LDFLAGS = -static.

  7. There is no need to properly install febootstrap, as it will run from /tmp/febootstrap-VERSION just fine. However, it does depend on executables which are found within /tmp/febootstrapVERSION to be present within the PATH. Use febootstrap to download and set up the target client Linux distribution. 

    PATH="$PATH:/tmp/febootstrap-VERSION" ./febootstrap fedora-RELEASE-NUMBERPATH

    For example, to install Fedora 17 (beefy miracle) to /var/chroot/beefy: 

    PATH="$PATH:/tmp/febootstrap-VERSION" ./febootstrap fedora-17 /var/chroot/beefy/

    It may take a bit to download and unpackage the various components.

  8. Clean up the temporary febootstrap directory: 

    rm -rf /tmp/febootstrap-VERSION

Troubleshooting

Febootstrap does not seem to always include the fedora-release package. This is troublesome, as the package utilized to access the Fedora repositories. If you find difficulties using yum, you might be able to respolve this by downloading the fedora-release package for the given release (e.g.: fedora-release-17.noarch.rpm), and install it thusly (from within the fedora client, via brc): 

rpm -i fedora-VERSION.noarch.rpm

You should then be able to use yum to access Fedora's repositories as one normally would.