Overview

We present the initial steps in setting up the Unikraft development / usage environment. Students will use the basic Unikraft toolchain to set up, configure, build and run Unikraft images. Expected time: 60 minutes

Set Up#

You will be part of a team of 3-4 people. Discuss on the thread and create/announce your team on Discord. Each team will be assigned a Discord channel to work together. You can use the #hack-team-XX-voice channels on the Discord server. You will need a Linux environment for this session. You can use a virtual machine, but we strongly recommend a native Linux install.

You will need to install the following packages:

• build-essential / base-devel / @development-tools (the meta-package that includes make, gcc and other development-related packages)
• gcc-aarch64-linux-gnu
• sudo
• flex
• bison
• git
• wget
• uuid-runtime
• qemu-system-x86
• qemu-system-arm
• qemu-kvm
• sgabios

On Ubuntu, Debian, and other apt-based distributions, you can use the following command to install the requirements:

sudo apt install -y --no-install-recommends \
        build-essential \
        sudo \
        gcc-aarch64-linux-gnu \
        libncurses-dev \
        libyaml-dev \
        flex \
        bison \
        git \
        wget \
        uuid-runtime \
        qemu-kvm \
        qemu-system-x86 \
        qemu-system-arm \
        sgabios

For running Unikraft with networking support, you will also need to configure QEMU to allow network bridge access:

sudo mkdir /etc/qemu/
echo "allow all" | sudo tee /etc/qemu/bridge.conf

Running Applications Using Unikraft#

The applications that we will look at are located in this repository (we will use the scripts branch for now, not the main branch).

Before building and running applications, there are some setup steps we need to do. First, run the ./setup.sh script in the root of the repository. This will clone all the dependencies we need. After that, for every application we will run, we must run the setup.sh script from the application directory.

All the applications have a scripts/ subdirectory where several useful things are located:

• Building scripts, under scripts/build/, named plat.architecture (we will use qemu.x86_64 and qemu.arm64).
• Running scripts, under scripts/run/, same naming convention as the build scripts.
• Configuration files, under scripts/defconfig/, we will ignore that for now, and will come back to it in a later session.

helloworld on Unikraft#

We will start with the c-hello application, which is a simple "Hello, world", written in C.

First, we cd into the c-hello directory and run ./setup.sh. This will create a new directory, c-hello/workdir/, with all the unikraft-related dependencies. In order to build and run it as a x86_64 virtual machine, we need to first run the scripts/build/qemu.x86_64 script, then scripts/run/qemu.x86_64.

git clone https://github.com/unikraft/catalog-core/
cd catalog-core
git checkout scripts
./setup.sh
cd c-hello/
./setup.sh
./scripts/build/qemu.x86_64 # This might take a while
./scripts/run/qemu.x86_64

After the run script, we should see the output of the hello-world VM:

SeaBIOS (version 1.16.3-debian-1.16.3-2)


iPXE (https://ipxe.org) 00:03.0 CA00 PCI2.10 PnP PMM+0078AE00+006CAE00 CA00



Booting from ROM..Powered by
o.   .o       _ _               __ _
Oo   Oo  ___ (_) | __ __  __ _ ' _) :_
oO   oO ' _ `| | |/ /  _)' _` | |_|  _)
oOo oOO| | | | |   (| | | (_) |  _) :_
 OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)
                    Pan 0.19.0~e4d07100
Hello from Unikraft!

You can also try the arm64 scripts:

./scripts/build/qemu.arm64
./scripts/run/qemu.arm64

This will emulate an ARM64 VM and print the application message, similar to the x86_64 application.

Work Items#

Now that you've seen how to run Unikraft helloworld, you can go through the list below, follow the same steps and try more applications. The steps for running all applications are similar, you run the setup.sh script, then scripts/build/qemu.arch and scripts/run/qemu.arch. Try to run the foolowing applications for both x86_64 and arm64.

• c-html
• cpp-hello
• cpp-html
• nginx
• redis
• python3-hello

For applications that wait for connections (i.e. nginx, *-http, redis), the VM IP address is 172.44.0.2. You can curl 172.44.0.2 for nginx, 172.44.0.2:8080 for *-http, and you must use redis-cli for the redis application. To use redis-cli, you can use:

redis-cli -h 172.44.0.2
172.44.0.2:6379> PING
PONG