These are the instructions for building Container Linux itself. By the end of the guide you will build a developer image that you can run under KVM and have tools for making changes to the code.
Container Linux is an open source project. All of the source for Container Linux is available on github. If you find issues with these docs or the code please send a pull request.
Let's get set up with an SDK chroot and build a bootable image of Container Linux. The SDK chroot has a full toolchain and isolates the build process from quirks and differences between host OSes. The SDK must be run on an x86-64 Linux machine, the distro should not matter (Ubuntu, Fedora, etc).
System requirements to get started:
You also need a proper git setup:
git config --global user.email "firstname.lastname@example.org" git config --global user.name "Your Name"
NOTE: Do the git configuration as a normal user and not with sudo.
cork utility, included in the CoreOS mantle project, is used to create and work with an SDK chroot.
First, download the cork utility:
curl -L -o cork https://github.com/coreos/mantle/releases/download/v0.9.1/cork-0.9.1-amd64 curl -L -o cork.sig https://github.com/coreos/mantle/releases/download/v0.9.1/cork-0.9.1-amd64.sig
Now, verify the download with the signature:
gpg --keyserver keys.gnupg.net --recv-keys 9CEB8FE6B4F1E9E752F61C82CDDE268EBB729EC7 gpg --verify cork.sig cork
gpg --verify command should output something like this:
gpg: Signature made Thu 19 Apr 2018 03:33:40 PM PDT gpg: using RSA key 9CEB8FE6B4F1E9E752F61C82CDDE268EBB729EC7 gpg: Good signature from "CoreOS Application Signing Key <email@example.com>" [unknown] Primary key fingerprint: 18AD 5014 C99E F7E3 BA5F 6CE9 50BD D3E0 FC8A 365E Subkey fingerprint: 9CEB 8FE6 B4F1 E9E7 52F6 1C82 CDDE 268E BB72 9EC7
Then proceed with the installation of the cork binary to a location on your path:
chmod +x cork mkdir -p ~/.local/bin mv cork ~/.local/bin export PATH=$PATH:$HOME/.local/bin
You may want to add the
PATH export to your shell profile (e.g.
Next, use the cork utility to create a project directory. This will hold all of your git repos and the SDK chroot. A few gigabytes of space will be necessary.
mkdir coreos-sdk cd coreos-sdk cork create # This will request root permisions via sudo cork enter # This will request root permisions via sudo
Verify you are in the SDK chroot:
$ grep NAME /etc/os-release NAME="Container Linux by CoreOS"
To leave the SDK chroot, simply run
To use the SDK chroot in the future, run
cork enter from the above directory.
The Container Linux initramfs is generated with the
Dracut assumes it is running on the target system, and produces output only for that CPU architecture. In order to create initramfs files for other architectures,
dracut is executed under QEMU's user mode emulation of the target CPU via the host system's binfmt support.
Note that "64 bit ARM" is known by two short forms:
aarch64 (as seen in the configuration file for QEMU), and
arm64 (as seen in how Container Linux and many other distributions refer to the architecture).
The QEMU binary,
/usr/bin/qemu-aarch64-static is not expected to be on the host workstation. It will be inside the
arm64-usr build chroot entered before running
For Debian, Ubuntu, and other Debian based systems installing the following packages will configure the host system such that QEMU will be the runtime for 64 bit ARM binaries:
sudo apt-get install binfmt-support qemu-user-static
The cork utility can setup QEMU binfmt support on systemd based systems:
cork setup systemctl restart systemd-binfmt.service
This will install the configuration file
/etc/binfmt.d/qemu-aarch64.conf, which controls how binaries for a given architecture are handled.
After entering the chroot via
cork for the first time, you should set user
This is the password you will use to log into the console of images built and launched with the SDK.
--board option can be set to one of a few known target architectures, or system "boards", to build for a given CPU.
To create a root filesystem for the
amd64-usr target beneath the directory
./setup_board --default --board=amd64-usr
arm64-usr for the cross-compiled ARM target. If switching between different targets in a single SDK, you can add the
--board= option to the subsequent
build_image, and other similar commands to select the given target architecture and path.
./setup_board --default --board=arm64-usr
Build all of the target binary packages:
Build a production image based on the binary packages built above:
build_image completes, it prints commands for converting the raw bin into a bootable virtual machine. Run the
Once you build an image you can launch it with KVM (instructions will print out after
If you encounter errors with KVM, verify that virtualization is supported by your CPU by running
egrep '(vmx|svm)' /proc/cpuinfo. The
/dev/kvm directory will be in your host OS when virtualization is enabled in the BIOS.
./coreos_production_qemu.sh file can be found in the
~/trunk/src/build/images/amd64-usr/latest directory inside the SDK chroot.
image_to_vm.sh completes, run
./coreos_production_qemu.sh -curses to launch a graphical interface to log in to the Container Linux VM.
You could instead use the
./coreos_production_qemu.sh -nographic, which gives you the ability to switch from the VM to the QEMU monitor console by pressing CTRL+a and then c. To close the Container Linux Guest OS VM, run
sudo systemctl poweroff inside the VM.
You could also log in via SSH by running
./coreos_production_qemu.sh and then running
ssh firstname.lastname@example.org -p 2222 to enter the guest OS. Running without the
-p 2222 option will arise a ssh: connect to host 127.0.0.1 port 22: Connection refused or Permission denied (publickey,gssapi-keyex,gssapi-with-mic) warning. Additionally, you can log in via SSH keys or with a different ssh port by running this example
./coreos_production_qemu.sh -a ~/.ssh/authorized_keys -p 2223 -- -curses. Refer to the Booting with QEMU guide for more information on this usage.
The default login username is
core and the password is the one set in the
./set_shared_user_password step of this guide. If you forget your password, you will need to rerun
./set_shared_user_password and then
Container Linux is managed by
repo, a tool built for the Android project that makes managing a large number of git repositories easier. From the repo announcement blog:
The repo tool uses an XML-based manifest file describing where the upstream repositories are, and how to merge them into a single working checkout. repo will recurse across all the git subtrees and handle uploads, pulls, and other needed items. repo has built-in knowledge of topic branches and makes working with them an essential part of the workflow.
(from the Google Open Source Blog)
You can find the full manual for repo by visiting android.com - Developing.
The repo manifest for Container Linux lives in a git repository in
.repo/manifests. If you need to update the manifest edit
in this directory.
repo uses a branch called 'default' to track the upstream branch you
repo init, this defaults to 'origin/master'. Keep this in
mind when making changes, the origin git repository should not have a
We've compiled a list of tips and tricks that can make working with the SDK a bit easier.
Mantle is a collection of utilities used in testing and launching SDK images.