Running on QEMU

These instructions will bring up a single Flatcar Container Linux instance under QEMU, the small Swiss Army knife of virtual machine and CPU emulators. If you need to do more such as configuring networks differently refer to the QEMU Wiki and User Documentation .

You can direct questions to the IRC channel or mailing list .

Install QEMU

In addition to Linux it can be run on Windows and OS X but works best on Linux. It should be available on just about any distro.

Debian or Ubuntu

Documentation for Debian has more details but to get started all you need is:

sudo apt-get install qemu-system-x86 qemu-utils

Fedora or RedHat

The Fedora wiki has a quick howto but the basic install is easy:

sudo yum install qemu-system-x86 qemu-img

Arch

This is all you need to get started:

sudo pacman -S qemu

More details can be found on Arch’s QEMU wiki page .

Gentoo

As to be expected, Gentoo can be a little more complicated but all the required kernel options and USE flags are covered in the Gentoo Wiki . Usually this should be sufficient:

echo app-emulation/qemu qemu_softmmu_targets_x86_64 virtfs xattr >> /etc/portage/package.use
emerge -av app-emulation/qemu

Startup Flatcar Container Linux

Once QEMU is installed you can download and start the latest Flatcar Container Linux image.

Choosing a channel

Flatcar Container Linux is designed to be updated automatically with different schedules per channel. You can disable this feature , although we don’t recommend it. Read the release notes for specific features and bug fixes.

mkdir flatcar; cd flatcar
wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh
wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh.sig
wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img
wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img.sig
gpg --verify flatcar_production_qemu.sh.sig
gpg --verify flatcar_production_qemu_image.img.sig
chmod +x flatcar_production_qemu.sh

mkdir flatcar; cd flatcar
wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh
wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh.sig
wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img
wget https://alpha.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img.sig
gpg --verify flatcar_production_qemu.sh.sig
gpg --verify flatcar_production_qemu_image.img.sig
chmod +x flatcar_production_qemu.sh

mkdir flatcar; cd flatcar
wget https://beta.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh
wget https://beta.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh.sig
wget https://beta.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img
wget https://beta.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img.sig
gpg --verify flatcar_production_qemu.sh.sig
gpg --verify flatcar_production_qemu_image.img.sig
chmod +x flatcar_production_qemu.sh

Starting is as simple as:

./flatcar_production_qemu.sh -nographic

SSH keys

In order to log in to the virtual machine you will need to use ssh keys. If you don’t already have a ssh key pair you can generate one simply by running the command ssh-keygen. The wrapper script will automatically look for public keys in ssh-agent if available and at the default locations ~/.ssh/id_dsa.pub or ~/.ssh/id_rsa.pub. If you need to provide an alternate location use the -a option:

./flatcar_production_qemu.sh -a ~/.ssh/authorized_keys -- -nographic

Note: Options such as -a for the wrapper script must be specified before any options for QEMU. To make the separation between the two explicit you can use -- but that isn’t required. See ./flatcar_production_qemu.sh -h for details.

Once the virtual machine has started you can log in via SSH:

ssh -l core -p 2222 localhost

SSH config

To simplify this and avoid potential host key errors in the future add the following to ~/.ssh/config:

Host flatcar
HostName localhost
Port 2222
User core
StrictHostKeyChecking no
UserKnownHostsFile /dev/null

Now you can log in to the virtual machine with:

ssh flatcar

Butane Configs

Flatcar Container Linux allows you to configure machine parameters, configure networking, launch systemd units on startup, and more via Butane Configs. These configs are then transpiled into Ignition configs and given to booting machines. Head over to the docs to learn about the supported features . An Ignition config can be passed to the virtual machine using the QEMU Firmware Configuration Device. The wrapper script provides a method for doing so:

./flatcar_production_qemu.sh -i config.ign -- -nographic

This will pass the contents of config.ign through to Ignition, which runs in the virtual machine.

Using Flatcar Container Linux

Now that you have a machine booted it is time to play around. Check out the Flatcar Container Linux Quickstart guide or dig into more specific topics .