unikraft / docs

The front page and documentation for the Unikraft Open-Source Project.

The fast, secure and open-source
Unikernel Development Kit

Unikraft powers the next-generation of cloud native, containerless applications by enabling you to radically customize and build custom OS/kernels; unlocking best-in-class performance, security primitives and efficiency savings.

Homepage · Documentation · Report Bug · Feature Request · Join Our Discord · X.com

Features

• Instantaneous Cold-boots ⚡

  • While Linux-based systems might take tens of seconds to boot, Unikraft will be up in milliseconds.

• Modular Design 🧩

  • Unikraft boasts a modular design approach, allowing developers to include only necessary components, resulting in leaner and more efficient operating system configurations.

• Optimized for Performance 🚀

  • Built for performance, Unikraft minimizes overheads and leverages platform-specific optimizations, ensuring applications achieve peak performance levels.

• Flexible Architecture Support 💻

  • With support for multiple hardware architectures including x86, ARM, (and soon RISC-V), Unikraft offers flexibility in deployment across diverse hardware platforms.

• Broad Language and Application Support 📚

  • Unikraft offers extensive support for multiple programming languages and hardware architectures, providing developers with the flexibility to choose the tools and platforms that best suit your needs.

• Cloud and Edge Compatibility ☁️

  • Designed for cloud and edge computing environments, Unikraft enables seamless deployment of applications across distributed computing infrastructures.

• Reduced Attack Surface 🛡️

  • By selectively including only necessary components, Unikraft reduces the attack surface, enhancing security in deployment scenarios. Unikraft also includes many additional modern security features.

• Developer Friendly 🛠️

  • Unikraft's intuitive toolchain and user-friendly interface simplify the development process, allowing developers to focus on building innovative solutions.

• Efficient Resource Utilization 🪶

  • Unikraft optimizes resource utilization, leading to smaller footprints (meaning higher server saturation) and improved efficiency in resource-constrained environments.

• Community-Driven Development 👥

  • Unikraft is an open-source project driven by a vibrant community of over 100 developers, fostering collaboration and innovation from industry and academia.

Quick Start

Install the companion command-line client kraft:

# Install on macOS, Linux, and Windows:
curl -sSfL https://get.kraftkit.sh | sh

See additional installation instructions.

Run your first ultra-lightweight unikernel virtual machine:

kraft run unikraft.org/helloworld:latest

View its status and manage multiple instances:

kraft ps --all

View the community image catalog in your CLI for more apps:

kraft pkg ls --update --apps

Or browse through one of the many starter example projects.

Why Unikraft?

Unikraft is a radical, yet Linux-compatible with effortless tooling, technology for running applications as highly optimized, lightweight and single-purpose virtual machines (known as unikernels).

In today's computing landscape, efficiency is paramount. Unikraft addresses this need with its modular design, enabling developers to create customized, lightweight operating systems tailored to specific application requirements. By trimming excess overhead and minimizing attack surfaces, Unikraft enhances security and performance in cloud and edge computing environments.

Unikraft's focus on optimization ensures that applications run smoothly, leveraging platform-specific optimizations to maximize efficiency. With support for various hardware architectures and programming languages, Unikraft offers flexibility without compromising performance. In a world where resources are precious, Unikraft provides a pragmatic solution for streamlined, high-performance computing.

Getting Started

There are two ways to get started with Unikraft:

1. (Recommended) Using the companion command-line tool kraft (covered below).

2. Using the GNU Make-based system. For this, see our advanced usage guide.

Toolchain Installation

You can install the companion command-line client kraft by using the interactive installer:

# Install on macOS, Linux, and Windows:
curl -sSfL https://get.kraftkit.sh | sh

macOS

brew install unikraft/cli/kraftkit

Debian/Fedora/RHEL/Arch/Windows

Use the interactive installer or see additional installation instructions.

Codespaces

Try out one of the examples in GitHub Codespaces:

Container Build Environment

You can use the pre-built development container environment which has all dependencies necessary for building and trying out Unikraft in emulation mode.

Attach your working directory on your host as a mount path volume mapped to /workspace, e.g.:

docker run --platform linux/x86_64 -it --rm -v $(pwd):/workspace --entrypoint bash kraftkit.sh/base:latest

The above command will drop you into a container shell. Type exit or Ctrl+D to quit.

Testing your Installation

Running unikernels with kraft is designed to be simple and familiar. To test your installation of kraft, you can run the following:

kraft run unikraft.org/helloworld:latest

Build your first unikernel

Building unikernels is also designed to be straightforward. Build your first unikernel by simply placing a Kraftfile into your repo and pointing it to your existing Dockerfile:

spec: v0.6

runtime: base:latest

rootfs: ./Dockerfile

cmd: ["/path/to/my-server-app"]

Learn more about the syntax of a Kraftfile.

Once done, invoke in the context of your working directory:

kraft run .

Example Projects and Pre-built Images

You can find some common project examples below:

	Example
	Simple "Hello, world!" application written in C
	Simple "Hello, world!" application written in C++
	Simple "Hello, world!" application written in Rust built via cargo
	Simple NodeJS 18 HTTP Web Server with http
	Simple Go 1.21 HTTP Web Server with net/http
	Simple Flask 3.0 HTTP Web Server
	Simple Python 3.10 HTTP Web Server with http.server.HTTPServer

Find more examples and applications in our community catalog!

Cloud Deployment

The creators of Unikraft have built KraftCloud: a next generation cloud platform powered by technology intended to work in millisecond timescales.

✅	Millisecond Scale-to-Zero	✅	Millisecond Autoscale	✅	Millisecond Cold Boots
✅	Higher Throughput	✅	Much Lower Cloud Bill	✅	HW-Level Isolation
✅	On-Prem or Cloud-Prem	✅	Works with Docker & K8s	✅	Terraform Integration

Sign-up for the beta ↗

Contributing

Unikraft is open-source and licensed under BSD-3-Clause and the copyright of its authors. If you would like to contribute:

1. Read the Developer Certificate of Origin Version 1.1.
2. Sign-off commits as described in the Developer Certificate of Origin Version 1.1.
3. Grant copyright as detailed in the license header.

This ensures that users, distributors, and other contributors can rely on all the software related to Unikraft being contributed under the terms of the License. No contributions will be accepted without following this process.

Afterwards, navigate to the contributing guide to get started. See also Unikraft's coding conventions.

Additional resources

• Quick-start guide
• What is a unikernel?
• Unikraft's inherent security benefits
• Performance of Unikraft
• POSIX-compatibility with Unikraft
• Energy efficiency with Unikraft
• Unikraft Community
• Unikraft Documentation

License

Unikraft Open-Source Project source code and its affiliated projects source code is licensed under a BSD-3-Clause if not otherwise stated. For more information, please refer to COPYING.md.

Affiliation

Unikraft is a member of the Linux Foundation and is a Xen Project Incubator Project. The Unikraft name, logo and its mascot are trademark of Unikraft GmbH.

   

docs's Issues

Add complex apps build docs for different compilers

Add documentation on building complex applications (e.g. nginx, sqlite, redis, etc.) using different compilers (gcc, clang).
The initial documentation is written by @mariasfiraiala here.

Disable `MD101/backtick-keywords` in Hugo shortcode

When using Hugo shortcodes, the MD101 rule, for using backticks, should be disabled.

For example, for this shortcode:

{{< figure
    src="/assets/imgs/morello-unikraft-build-option.png"
    title="The new Morello option which can be enabled in the Unikraft platform configuration menu"
    position="center"
>}}

the following warning is shown:

MD101/backtick-keywords Keywords must be fenced and must be in appropriate case. [Expected `.png`. Actual .png.]

Add documentation for resolving virtual bridge error when running qemu

I was facing this issue when trying to run the commands in https://unikraft.org/community/hackathons/sessions/baby-steps/#02-building-and-running-the-httpreply-application.

access denied by acl file failed to launch bridge helper qemu-system-x86_64: -netdev bridge,id=br0: Device 'bridge' could not be initialized

docs: Switch all documentation on using the kraftkit instead of the old pykraft

All the documentation should be switched from using the old pykraft to using the new kraftkit.
This will likely happen after the kraftkit v1 release.

kraft list does not show KVM as a platform

Found in https://unikraft.org/docs/getting-started/, section Building an Application.

$ kraft list

Does not show KVM as a possible platform (after kraft list update).
Though, in the hello-world example kvm is used.

Hint: As I just get started, this might be a misunderstanding from my side, but it still raised confusion for me :)

docs: Switch all documentation on using the kraftkit instead of the old pykraft

All the documentation should be switched from using the old pykraft to using the new kraftkit.
This will likely happen after the kraftkit v1 release.

Document plat/linuxu: TAP netdev driver

The pull request plat/linuxu: TAP netdev driver[1] introduces a new awesome functionality but there is no documentation for it.

[1] unikraft/unikraft#251

Improve Contributing: Split Coding Style + Add references under Overview

I noticed by looking up our commit message format documentation that we should implement some structural improvements to the Contributing page:

1. One would expect under the page Coding style only suggestions regarding the source code style and maybe (I am not so sure if this is the best idea) how to do documentation in the code.
   Commit Message Format and Developer’s Certificate of Origin should get moved and be integrated to Submitting Changes.
2. A reference to Submitting changes should be added under Overview/Pull requests
3. Developer Certificate of Origin (DCO) must stay and explains the actual meaning of the Signed-Off tag. This is not really pointed out under Commits and Adressing Multipe Authors. The signed-off is required from each author of a patch because this way they certify that the submission is published under the DCO.
4. The Example Commit mesage should show the full firstname in the signed-off tag. It is an example and people should see here a best practice example that contains full firstname and full lastname. The mail address can be whatever that person has, obviously.

docs: Switch all documentation on using the kraftkit instead of the old pykraft

All the documentation should be switched from using the old pykraft to using the new kraftkit.
This will likely happen after the kraftkit v1 release.

`community/hackathons`: Use `lib-musl` instead of `lib-newlib`

Hackathon sessions use lib-newlib as the default libc. lib-newlib is no longer support and must be replaced with lib-musl.

USoC23: Update session 01: Overview of Unikraft

The first session of Unikraft Summer of Code will be an overview of the Unikraft ecosystem. The participants should:

• Understand what Unikraft is (what it does, what problem it solves)
• Get their setup ready
• Run all the scripts we have available, see that everything "just works"

Nothing else will happen in the fist session, no make stuff, no kraft stuff, just run everything and see that it works.

The session can be picked up from the hackathons sessions.

docs: Add section on binary compatibility/using the elfloader application

Add a new page (probably under the usage/ directory) detailing how to use the app-elfloader to run already compiled applications.
It should cover the contents from the elfloader README.md file and add more detailed examples.

404/50x page

Issue to track adding a stylish 404/50x page.

USoC23: Update session 02: Baby Steps

The second session of Unikraft Summer of Code will be a short look behind the scenes. The participants should:

• Start using the make-based approach to configure and build applications
• Understand the configuration step, see the modularity of Unikraft
• Understand the concepts of internal library vs external library, core, applications

There will be no actual coding done, just poking around the config and build system.

The session can be picked up from the hackathons sessions.

Add `Makefile.uk`, `exportsyms.uk` and `extra.ld` docs from old documentation

Port the informations on the Makefile.uk, exportsyms.uk and extra.ld files from the Unikraft old documentation. Could be added into the docs/developing/porting section.

Specify the correct cross-compiling toochain for aarch64 in the docs

Feature request summary

This one is related to future changes in the docs: https://github.com/unikraft/unikraft/tree/staging/doc/guides
Specifically, when adding instructions for cross-compiling unikraft for AArch64, make sure to specify the bare-metal toolchain variant (aarch66-none-elf), as it is common for people to use a linux toolchain (eg aarch-none-linux) and end up having problems with the build.

Describe alternatives

No response

Related architectures

Arm, AArch64

Related platforms

No response

Additional context

The cross-compiling toolchains provided by Arm come in different variants (arm-none-eabi, arm-none-linux-gnueabihf, aarch64-none-elf, aarch64-none-linux). Choosing the wrong one can cause problems.

Example: libgcc of gcc >= 10.1 expects that the __getauxval symbol is provided by glibc. Trying to build Unikraft with aarch64-none-linux will result into gcc emmitting the following error:

/home/mpp/toolchains/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/../lib/gcc/aarch64-none-linux-gnu/10.3.1/../../../../aarch64-none-linux-gnu/bin/ld: /tmp/uk_event/app-helloworld/build/app-helloworld_kvm-arm64.o: in function `init_have_lse_atomics':
/data/jenkins/workspace/GNU-toolchain/arm-10/src/gcc/libgcc/config/aarch64/lse-init.c:44: undefined reference to `__getauxval'
/data/jenkins/workspace/GNU-toolchain/arm-10/src/gcc/libgcc/config/aarch64/lse-init.c:44:(.text.startup+0x4c): relocation truncated to fit: R_AARCH64_CALL26 against undefined symbol `__getauxval'
collect2: error: ld returned 1 exit status
make[2]: *** [/tmp/uk_event/unikraft/plat/kvm/Linker.uk:24: /tmp/uk_event/app-helloworld/build/app-helloworld_kvm-arm64.dbg] Error 1
make[1]: *** [Makefile:990: sub-make] Error 2
make[1]: Leaving directory '/tmp/uk_event/unikraft'
make: *** [Makefile:8: all] Error 2

Although this issue could be easily fixed by adding -wno-outline-atomics to ARCHFLAGS, this would not be the correct way to address the issue. Instead, one should be using the baremetal variant (aarch64-none-elf) for building Unikraft.

Document the usage of `rust` within Unikraft

The usage of ukrust is not documented anywhere now, and using it out of the box leads to errors described here.
Related to #558.

Add `Governance` page

The Governance page is missing. And there is a broken link to it in the People page.

Dead Links all Around

There are a lot of dead links on the page. Someone should do a pass through everything and connect components.

Some examples:

Disable `MD104/one line per sentence` rule in Hugo shortcodes

When using Hugo shortcodes, the MD104 rule, for using one line per sentence, should be disabled.

For example, for this shortcode:

{{< figure
    src="/assets/imgs/morello-unikraft-fvp.png"
    title="Terminal windows showing Unikraft running bare metal on the Morello emulator! Top left: the command and resulting console output of the Morello board emulator (FVP). Top right: Emulated board details. Bottom left and middle: Serial output of the board initialization firmware. Bottom right: Application processor serial output."
    position="center"
>}}

the following warning is shown:

MD104/one line per sentence one line (and only one line) per sentence [Expected one sentence per line. Multiple end of sentence punctuation signs found on one line!]

Add information on running `markdownlint` locally

The repository features super-linter as a worfklow in the .github/workflow/ directory. This is enabled at each push and it runs markdownlint-cli.

We need to update the README.md file and documentation on submitting a blog post with information on installing and using markdown-cli locally, before creating a PR.

Installing is done using:

$ npm install -g markdownlint-cli

Checking a Markdown file is done using a command such as the one below. The command below is run while inside the content/en/blog/ directory:

$ markdownlint --config ../../../.github/workflows/config/config.json --rules ../../../.github/workflows/rules/rules.js *.md

Add "Research" missing page

On the main page of https://unikraft.org/, the following part

"The award-winning Unikraft research work has appeared in top-tier research and industry conferences, read more about research and development"

references a page that currently doesn't exist.

The missing page is https://unikraft.org/community/research.

Blank page on submitting blog posts

The blog features a link on submitting a blog post that's pointing to a blank page. This page needs to be filled.

frontpage: Missing "Unikraft Cloud Platform" image

The image in the "Unikraft Cloud Platform" section of the front page is missing (https://unikraft.io/imgs/unikraft-dashboard-preview.png, referenced on

docs/layouts/partials/main/landing/home-sections.html

Line 308 in ab04613

<img class="transform translate-x-6 translate-y-6 md:rounded-lg object-cover object-left-top sm:translate-x-16 lg:translate-y-20 shadow-xl ring-1 ring-black ring-opacity-5" src="https://unikraft.io/imgs/unikraft-dashboard-preview.png" alt="App screenshot">

returns a 404 HTTP response).

Screenshot attached:

Change security feature "PAuth" from "Under review" to "Upstream"

The feature has been reviewed and is now upstream: unikraft/unikraft#369

Add documentation for running the checkpatch

When contributing to most of the Unikraft's repositories, there is a requirement to run the checkpatch before submitting the PRs. Moreover, a Github action is run in this scenario in order to detect potential coding style issues.

However, there is not specified in the documentation how to run the checkpatch script locally.

Add syscall shim docs from old documentation

Port the informations on the the syscall shim layer from the Unikraft old documentation. Could be added into the docs/developing/porting section.

docs: Switch all documentation on using the kraftkit instead of the old pykraft

All the documentation should be switched from using the old pykraft to using the new kraftkit.
This will likely happen after the kraftkit v1 release.

Add ways to ignore specific checks to be run by the `checkpatch`.

Add ways to ignore specific checks (Checkpatch-Ignore: CHECK_NAME).
Simple example here.

Add docs on command line arguments and library parameters

Port the informations on command line arguments and library parameters from the Unikraft old documentation. Could be added into the docs/developing/porting section.

Catalog Makefile.uk build steps and magic variables

Feature request summary

The Unikraft build system consists of many steps and uses many "magic" variables (e.g. LIBNAME_xxx, EACHOLIB, etc.) Currently, writing a new library/application for Unikraft requires referencing many Makefiles and examples.

It would be greatly appreciated to have a detailed explanation of Unikraft's build steps, as well as each Makefile variable involved in each step.

Describe alternatives

No response

Related architectures

None

Related platforms

None

Additional context

No response

Add "logos" and marketing material page

Issue to track adding a missing use of Unikraft logos (and attribution to Alina) to be placed somewhere in the "Community" tab

Add link to Discord in the landing page

There is no link to Discord in the landing page. Add link / button to make Discord more visible.

Add contents on `People` page

The People page is empty. It should contain community member information, generated from the governance repository.

Fix SVG figure fonts

Some figures based on SVGs have an embedded font selection for the site (the default Inter) but this does not necessarily show for every browser.

This issue is used to track updating the font-family of related SVGs with a more compatible font family matrix.

Port informations from old docs

There are still pieces of information from the old Unikraft documentation (e.g. syscall shim layer) that were not ported to the new website.

• #117
• #118
• #119

docs: Switch all documentation on using the kraftkit instead of the old pykraft

All the documentation should be switched from using the old pykraft to using the new kraftkit.
This will likely happen after the kraftkit v1 release.

Add documentation on contributing to documentation

The Contributing section (in contributing/ directory in the repository) doesn't have a section detailing how to contribute to this docs/ repository:

• How can the documentation be build locally?
• What are the guidelines for adding / improving documentation? What are the Markdown rules (as enforced by the super-linter workflow configuration rules?
• How to format a commit?

Add `CONTRIBUTING.md` file

Add CONTRIBUTING.md file with contributions guidelines to this documentation repository. Probably reference the contributing page in the documentation website, resulting by solving #166

Add docs on tracing

This issue tracks adding the original tracing documentation to the new documentation site.

This is the old documentation for reference: http://docs.unikraft.org/developers-debugging.html

github/linter: End of sentence gets misinterpreted when using backticks inside parentheses.

The linter checks for . ? ! outside an escaped sequence.
The backticks (`) set the outside variable as !outside, while the parentheses set it as true or false, depending of the context.
This does not work when backticks are used inside parentheses, making the text between the backticks be interpreted as unescaped.
For example:

This sentence (having this `.escaped` sequence).

gives a linter error, since the dot before the word escaped is interpreted as the end of a sentence, hence the line is marked as having 2 sentences.

Disable `MD104/one line per sentence one line` for titles

The MD104 rule to use one line per sentence should be disabled for titles, i.e. lines that start with headings #....

Links not working on Contributing Page

Describe the bug
The kind/project, kind/enhancement, and kind/bug label links do not work, and lead to 404 errors on the contributing guidelines page

Steps to reproduce
Clink on the above-mentioned links at https://unikraft.org/docs/contributing/#

Expected behavior
I expected the links to lead me to the github repository I guess

Migrating issue from (unikraft/unikraft#745)

I will also try to work on this now

docs: Switch all documentation on using the kraftkit instead of the old pykraft

All the documentation should be switched from using the old pykraft to using the new kraftkit.
This will likely happen after the kraftkit v1 release.

Add section regarding `Co-authored-by`/`Signed-off-by` differences to `contributing/review-process.md`

Differentiating between Co-authored-by and Signed-off-by when multiple authors are involved is difficult. Add explanation/tutorial to contributing/review-process.md.

Add contributing/reviewing conventions for different kind of repositories

Add conventions on contributing and reviewing for different types of repositories inside the Unikraft organization (e.g. code repositories, docs repositories, governance, kraftkit, etc).

Cannot add the Linux-distribution GPG key

The following command for installing kraft in the https://unikraft.org/docs/usage/install/ produces an error.

command

$ curl -fsSL https://releases.unikraft.org/linux/gpg

error

curl: (22) The requested URL returned error: 522

`community/hackatons`: Use official `app-elfloader` release

The Binary Compatibility section of the hackathons use an old version of the app-elfloader, before its official release. The app-elfloader official release should be used throughout the session.

Add complex apps build docs on different architectures

Add documentation on building complex applications (e.g. nginx, sqlite, redis, etc.) on different architectures (x86, arm64).
The initial documentation is written by @mariasfiraiala here.

Relax Markdown check rules in Linter

The linter Markdown check for PR #151 shows issues that that should be ignored:

/github/workspace/content/en/blog/2022-10-25-unikraft-munich-2022.md:8:23 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '!']
/github/workspace/content/en/blog/2022-10-25-unikraft-munich-2022.md:18:47 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '!']
/github/workspace/content/en/blog/2022-10-25-unikraft-munich-2022.md:42:55 MD101/backtick-keywords Keywords must be fenced and must be in appropriate case. [Expected `.png`. Actual .png.]

The have to be corrected in the Markdown rules for super-linter.