Skip to content

Home

Jump to bottom
Yuri Volchkov edited this page Feb 12, 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 do a login. 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 is mostly consisting of a combination of multiple repositories. We differentiate them into: (1) Unikraft, (2) external libraries, (3) application. The build system assumes them organized in the following structure as default:

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 would 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 for running the configuration. Unikraft uses the same configuration system as the Linux kernel (Kconfig). We will build Unikraft images for Xen, KVM, and Linux, so first step would be to go to Platform Configuration menu 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 with 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

Lets execute our Unikernel.

  • The easiest is the one that we built as 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 generated 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

After Hello world! is printed, our Unikernel is shutting down directly. We do not have a chance to see that a VM was actually created, so lets modify the source code. Open main.c your favorit 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 quiet 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 the Unikraft, external libraries can be added to the build. In the following we want to exchange 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)

When we do now make menuconfig, newlib appears 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 the 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 the Unikraft.

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

Debugging

Debugging a Unikernel can be similarly done as debugging an application. In the following we are looking into 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 site note: When the last option is disabled, compilation units can enable debug messages individually. This is done by defining UK_DEBUG as 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:

As first, 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 rebuild with debugging information.

Start the a 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 there 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 kconfig system imported from Linux kernel. 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.uk. Earlier we added the newlib to the LIBS variable. It can handle more then one library. Just put them together in one string, separated by a colon:

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

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

[ ] mylib: My awesome lib

Select it and exit the configuration menu, with saving 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.

Lets create this file 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 how the scoping works, edit the exportsyms.uk file again and an underscore (or any other character which is valid to use in the symbol name) to your exported symbol:

libmylib_api_func_

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

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

Socket Example

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

For now, we support virtio for networking only (but more is coming). You can enable the driver by going to the KVM platform configuration and select 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 asking for an IPv4 address with DHCP. Luckily a DHCP server is running on the testing nodes. It should assign 192.168.1.100 to it. In case you enabled ICMP in the lwip configuration, you should 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 the debug output with libukdebug (see Debugging chapter; we need to enabled all debug messages). With this you are able to have a deeper look to 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