Skip to content

Home

Jump to bottom
felipehuici edited this page Feb 13, 2019 · 42 revisions

Unikraft Tutorial

Testing Infrastructure

For this tutorial you need a KVM and a Xen host in order to run Unikraft. We have prepared a pair of hosts for you to play with. Get login data from the tutorial staff.

  • When using Linux, you can simply login to your machine pair with:
ssh [email protected] -p <PORT>
  • Windows users can use PuTTY to log in. Set the hostname to ucc-unikraft.nlehd.de and the port according to your coupon. You should get asked for the username (type root) and password when opening the connection.

Cloning Repositories

You can easily build Unikraft Unikernels on your Linux host. If you have all tools and libraries installed to compile a Linux kernel you are ready to do this with Unikraft too. Alternatively, you can directly compile Unikraft on the testing infrastructure that you got access too. It has compiler, tools, and necessary libraries pre-installed.

A Unikraft build consists mostly of a combination of multiple repositories. We differentiate them into: (1) Unikraft, (2) external libraries, (3) application. The build system assumes these to be structured as follows:

my-workspace/
├── apps/
│   └── helloworld/
│   └── httpreply/
├── libs/
│   ├── lwip/
│   └── newlib/
└── unikraft/

Clone the following repositories with Git (git clone <URL> <DESTINATION PATH>):

  • Unikraft base repository directly under your workspace root: 
$ git checkout staging
  • External libraries into a libs subdirectory: 
$ git checkout staging

$ git checkout staging

Make sure that the directory structure under your workspace is exactly the same as shown in the overview ahead (e.g., call the folder of the cloned Unikraft repository unikraft)

If you need to create the same tree again, you can use this cheat sheet.

Your First Unikernel

Configuring

After you cloned the repos, go to the helloworld application and run make menuconfig to configure the build. Unikraft uses the same configuration system as the Linux kernel (Kconfig). We will build Unikraft images for Xen, KVM, and Linux, so the first step is to go to the Platform Configuration option and make the following changes:

  • select Xen guest image
  • select KVM guest
  • select Linux user space Under Library configuration we also need to choose a scheduler: select ukschedcoop.

Building

Afterwards, save your configuration and build the image by typing make. The build system will create three binaries, one for each platform:

$ ls -sh build/
 [...]
 88K helloworld_kvm-x86_64
 40K helloworld_linuxu-x86_64
 72K helloworld_xen-x86_64
 [...]

Running

Let's execute our Unikernel.

  • The easiest is the one that we built as a Linux user space application. It should execute on any Linux environment (your Linux machine, or on the machine pair we gave you):
$ build/helloworld_linuxu-x86_64
Welcome to  _ __             _____
 __ _____  (_) /__ _______ _/ _/ /_
/ // / _ \/ /  '_// __/ _ `/ _/ __/
\_,_/_//_/_/_/\_\/_/  \_,_/_/ \__/
                  Titan 0.2~10ce3f2
Hello world!
  • You can execute the KVM image (helloworld_kvm-x86_64) on the KVM host. If you did not build the image on your KVM host, either scp it over or build it there again. For simplification we deployed a script there to start the virtual machine quickly:
$ kvm-guest -k helloworld_kvm-x86_64

With the -D parameter you can have a look to the qemu command line that is used by the script.

  • The procedure for Xen is similar. Get the Unikernel image on the Xen host and start the virtual machine there:
$ xen-guest -k helloworld_xen-x86_64

The parameter -D is showing you the generated xl machine configuration by the script.

Modifying the Application

After Hello world! is printed, our Unikernel shuts down right away. We do not have a chance to see that a VM was actually created, so let's modify the source code. Open main.c in your favorite editor (nano, vim, emacs) and add the following busy loop accordingly within the main function:

for (;;);

Rebuild the images with make and execute them. The shell prompt should not return. With a second shell your can check that the Unikernel is still executing:

  • Use top or htop for Linux and KVM.
  • Use xl top in Xen.

Note: You can terminate the KVM and Linux Unikernel with CTRL + C. For xen-guest it is CTRL + ].

External Libraries

The helloworld application uses a very minimalistic libc implementation called nolibc. It is small but also quite limited in terms of functionality. nolibc is part of the Unikraft base repository and because of this it is called an internal library. They are located within the lib directory of Unikraft.

In order to enhance the functionality provided by Unikraft, external libraries can be added to the build. In the following we want to swap nolibc with newlib, a standard libc implementation that you can find in various Linux distributions and embedded environments.

We need to add newlib to the library includes. Edit the Makefile of the helloworld application. Please type make properclean before; this will delete the build directory (but not your configuration) and will force a full rebuild later.

diff --git a/Makefile b/Makefile
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 UK_ROOT ?= $(PWD)/../../unikraft
 UK_LIBS ?= $(PWD)/../../libs
-LIBS :=
+LIBS := $(UK_LIBS)/newlib

 all:
        @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS)

Run make menuconfig, newlib should now appear in the Library Configuration menu. Select it, and select also vfscore (unfortunately this dependency is currently not automatically selected in the upstream repository). Afterwards type make. Unikraft's build system will download newlib's sources and build it together with all the other Unikraft libraries and application. Our newlib repository consists only of glue code that is needed to port newlib to Unikraft.

You will notice that the built Unikernels are bigger than before. Try to run them again.

Debugging

Debugging a Unikernel is similar to debugging an application. In the following we will use print-based debugging and GDB.

Print-based Debugging

Unikraft provides support for debug printing with the internal libukdebug library. Code needs to be instrumented but the advantage is that the library automatically removes all print calls as soon as you disable debug printing.

We enable them by going to Library Configuration and ukdebug. Here we can change the logging level but also enable or disable various types of additional debugging features (e.g., assertions).

  • Change Kernel message level to have the Show all types of messages value
  • Enable Print bottom address of stack in messages
  • Enable Enable debug messages globally

As a side note: When the last option is disabled, compilation units can enable debug messages individually. This is done by defining UK_DEBUG as a preprocessor macro to the compiler command line. This allows selective debug investigation with the same instrumented code (uk_pr_debug()). You can see an example in lwip's Makefile.uk.

GDB

With support from the virtualization platform and its toolstack (e.g., qemu on KVM, xl on Xen), a gdb process can be attached to the instances. In the following we will try it out with Xen.

To start with, we must ensure that debug symbols are generated when building Unikraft. For this you have to run make menuconfig again and go to the Build Options menu. The following needs to be changed:

  • Optimization level: No optimizations
  • Debugging information:
    • Debug information level: Level 3
  • Unselect Strip final image Type make clean and then make: we want to make sure that every object file is rebuilt with debugging information.

Start the guest on a Xen host in paused state and enable the GDB server option:

$ xen-guest -k build/helloworld_xen-x86_64 -g 9999 -P

On a second terminal, attach gdb to the virtual machine. You can set a breakpoint to main() and start the VM with continue:

$ gdb --eval-command="target remote :9999" build/helloworld_xen-x86_64
GNU gdb (Debian 7.12-6) 7.12.0.20161007-git
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from helloworld_xen-x86_64...done.
Remote debugging using :9999
0x0000000000000000 in _text ()
(gdb) br main
Breakpoint 1 at 0x8a7d: main. (2 locations)
(gdb) c
Continuing.

[...]

Code Your Own Library

Let's add some functionality to our unikernel. Create a directory libs/mylib, this will be the root folder of your library.

As mentioned earlier, Unikraft uses Linux's kconfig system imported. In order to make your library selectable in the "menuconfig", create the file Config.uk with the following content:

config LIBMYLIB
           bool "mylib: My awesome lib"
           default n

To test if it worked, we need to tell unikraft's build system to pick this library. Go back to your helloworld application, and edit it its Makefile. Earlier we added newlib to the LIBS variable, let's now add the new library:

LIBS := $(UK_LIBS)/newlib:$(UK_LIBS)/mylib

Now if you run make menuconfig, you should see your library under the "Library Configuration" sub-menu:

[ ] mylib: My awesome lib

Select it, exit the configuration menu, and save the changes. If you run make right now, the build will produce an error about a missing Makefile.uk:

make[1]: *** No rule to make target '/root/demo/libs/mylib/Makefile.uk'.  Stop.

Go back to your library directory and create one with the following content:

# Register your lib to Unikraft's build system
$(eval $(call addlib_s,libmylib,$(CONFIG_LIBMYLIB)))

# Add library source code to compilation
LIBMYLIB_SRCS-y += $(LIBMYLIB_BASE)/mylib.c

# Extend the global include paths with library's folder
CINCLUDES-y += -I$(LIBMYLIB_BASE)/include

And finally the library code mylib.c:

#include <stdio.h>

void libmylib_api_func(void)
{
        printf("Hello from my awesome lib!\n");
}

include/mylib/mylib.h:

#ifndef __LIB_MYLIB_H__
#define __LIB_MYLIB_H__

void libmylib_api_func(void);

#endif /* __LIB_MYLIB_H__ */

Now in your helloworld's main.c, add #include <mylib/mylib.h> and call libmylib_api_func().

exportsyms.uk

Even though your library is working now, you might have noticed a warning message:

Warning: Definition of exported symbols for libmylib missing: /root/demo/libs/mylib/exportsyms.uk

This is because Unikraft applies scoping to every library: only the symbols listed in exportsyms.uk will be visible outside of the library. If the file is missing (our current case), all the symbols are exported, but the warning is produced.

Let's create this file in the root of mylib with only one line:

libmylib_api_func

If you compile the helloworld application again, you will notice that the warning is gone. To get an impression of how scoping works, edit the exportsyms.uk file again and add an underscore (or any other character which is valid to use in the symbol name) to your exported symbol:

libmylib_api_func_

Since libmylib_api_func is not exported anymore, you should now get a compilation error:

sglist.c:(.text.startup+0x60): undefined reference to `libmylib_api_func'

Socket Example

As a last task, we are going to build a small webserver that replies with a single page. The server uses lwip for creating a socket and to accept incoming connections. Go to the httpreply application directory. Have a look at main.c: it is a really short program and looks similar to what you would write as a user-space Linux program. Its dependencies are defined within Config.uk. Having this, there is actually not much left to configure. Mandatory options are locked in make menuconfig. All we need to do is to select our target platforms, select network drivers, save the config, and type make.

For now, we support virtio for networking only (but more functionality is coming). You can enable the driver by going to the KVM platform configuration and selecting Virtio PCI device support and Virtio Net device.

The image can be started on the KVM host. Remember to add a virtual network device attached to the bridge virbr0:

$ kvm-guest -k build/httpreply_kvm-x86_64 -b virbr0

This Unikernel is requesting an IPv4 address via DHCP. A DHCP server is already running on the test nodes and should assign 192.168.1.100 to the unikernel. In case you enabled ICMP in the lwip configuration, you should also be able to ping the host from a second terminal:

$ ping 192.168.1.100

For debugging, you can also try to enable Debug messages in lwip and increase debug output with libukdebug (see Debugging chapter; we need to have all debug messages enabled). With this enabled you can now have a deeper look in the network stack.

If networking is working well, you can use the text-based browser lynx to see the web page served on a second terminal:

$ lynx 192.168.1.100:8123

Resources

Join us! ;-)

Clone this wiki locally