A minimal, resource efficient unikernel for cloud services
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
NaCl @ a5e919d Updating NaCl (timers.cpp goldenfile) Oct 5, 2018
api nic: add defaults for sendq- and and rx buffer limits Oct 15, 2018
cmake removed extra entry Oct 4, 2018
diskimagebuild diskbuilder: Use lstat() on each entry, avoid using d_type Sep 17, 2018
doc Readme: use logo.png - still .svg issues on github Oct 13, 2017
etc Create_bridge: Remove double parantheseses as they are not sh compatible Oct 5, 2018
examples http: Support follow redirection in Client #1727 Oct 9, 2018
lib Merge pull request #1949 from fwsGonzo/thecure Oct 14, 2018
linux linux: Add packet_debug to cmakelist Oct 1, 2018
mod mod: Update rapidjson to latest Aug 28, 2018
seed seed: Add extra output for GNU C Jun 22, 2018
src virtionet: Fix a few issues with sendq Nov 2, 2018
test virtio: replace packet chain with deque, add stats Oct 15, 2018
vmbuild Merged dev Mar 13, 2018
vmrunner run: removed python-magic dependency as this is trublesome and remove… Oct 9, 2018
.clang-format formatting: Add formatting script and configuration file Oct 13, 2017
.dockerignore Dockerfile: Save original git describe as well, fixed dockerignore Oct 2, 2018
.editorconfig added starbase: container with uplink May 23, 2017
.gitignore Gitignore: Added starbase/disk and nacl.txt Oct 2, 2018
.gitmodules protobuf: Use submodule (google v3.5.1.1), install with our CMake Feb 13, 2018
.travis.yml test: update travis config Mar 29, 2017
CMakeLists.txt linux: Add support for PGO with GCC, with script Sep 19, 2018
CONTRIBUTE.md CONTRIBUTE.md: Fix link to contribution guidelines May 21, 2018
Dockerfile Dockerfile: Added labels, printing version when building service Oct 4, 2018
LICENSE Apache 2.0 License May 7, 2016
NOTICE Cleaned out broken examples and tests Dec 1, 2015
README.md readme: minor copyedit Oct 4, 2018
Vagrantfile Update Vagrantfile to use Ubuntu 16.04 Nov 9, 2016
analyze.sh Add example clang-tidy analyzer script Nov 10, 2017
format_sources.sh formatting: Add formatting script and configuration file Oct 13, 2017
install.sh install: Exit on failure to build Linux platform Sep 11, 2018
manual_build.sh Add manual_build.sh, a fast 64-bit build Jun 14, 2018
test.sh Deprecate run.sh, use boot for test.sh May 10, 2017
test_ukvm.sh Feature commit to run solo5 on IncludeOS with boot --with-solo5 command Mar 6, 2018

README.md

IncludeOS Logo

IncludeOS is an includable, minimal unikernel operating system for C++ services running in the cloud. Starting a program with #include <os> will literally include a tiny operating system into your service during link-time.

The build system will:

  • link your service with the necessary OS objects into a single binary
  • attach a boot loader
  • combine everything into a self-contained bootable disk image, ready to run on almost any modern hypervisor.

IncludeOS is free software, with "no warranties or restrictions of any kind".

Pre-release Apache v2.0 Join the chat at https://gitter.im/hioa-cs/IncludeOS

Note: IncludeOS is under active development. The public API should not be considered stable.

Build status

Master branch Dev branch
Build Status Build Status

Key features

  • Extreme memory footprint: A minimal bootable 64-bit web server, including operating system components and a anything needed from the C/C++ standard libraries is currently 2.5 MB.
  • KVM, VirtualBox and VMWare support with full virtualization, using x86 hardware virtualization, available on most modern x86 CPUs. IncludeOS will run on any x86 hardware platform, even on a physical x86 computer, given appropriate drivers. Officially, we develop for- and test on Linux KVM, and VMWare ESXi/Fusion which means that you can run your IncludeOS service on Linux, Microsoft Windows and macOS, as well as on cloud providers such as Google Compute Engine, OpenStack and VMWare vcloud.
  • Instant boot: IncludeOS on Qemu/kvm boots in about 300ms but IBM Research has also integrated IncludeOS with Solo5/uKVM, providing boot times as low as 10 milliseconds.
  • Modern C++ support
    • Full C++11/14/17 language support with clang 5 and later.
    • Standard C++ library (STL) libc++ from LLVM.
    • Exceptions and stack unwinding (currently using libgcc).
    • Note: Certain language features, such as threads and filestreams are currently missing backend support.
  • Standard C library using musl libc.
  • Virtio and vmxnet3 Network drivers with DMA. Virtio provides a highly efficient and widely supported I/O virtualization. vmxnet3 is the VMWare equivalent.
  • A highly modular TCP/IP-stack.

A longer list of features and limitations can be found on our documentation site.

Getting started

Set custom location and compiler

By default the project is installed to /usr/local/includeos.

However, it is recommended to choose a custom location as well as select the compiler we want clang to find. In this document we assume you install IncludeOS in your home directory, in the folder ~/includeos.

To do this we can edit ~/.bash_profile (mac os) or ~/.bashrc (linux), adding these lines at the end of the file:

    export INCLUDEOS_PREFIX=~/includeos/
    export PATH=$PATH:$INCLUDEOS_PREFIX/bin

This will also crucially make the boot program visible globally, so that you can simply run boot <myservice> inside any service folder.

Install libraries

If you want to install IncludeOS on Mac OS you'll need a working installation of brew so the install script can install its dependencies.

NOTE: The script will install packages.

    $ git clone https://github.com/hioa-cs/IncludeOS
    $ cd IncludeOS
    $ ./install.sh

The script will:

  • Install the required dependencies: curl make clang-3.8 nasm bridge-utils qemu.
  • Create a network bridge called bridge43, for tap-networking.
  • Build IncludeOS with CMake:
    • Download the latest binary release bundle from github together with the required git submodules.
    • Unzip the bundle to the current build directory.
    • Build several tools used with IncludeOS, including vmbuilder, which turns your service into a bootable image.
    • Install everything in $INCLUDEOS_PREFIX/includeos (defaults to /usr/local).

Configuration of your IncludeOS installation can be done inside build/ with ccmake ...

Testing the installation

A successful setup enables you to build and run a virtual machine. There are a few demonstration services in the source folder. If you look in the examples/ folder you see these. If you enter demo_service and type boot --create-bridge . this script will build the service and boot it using qemu.

    $ cd examples/demo_service
    $ boot --create-bridge .

will build and run this example service. You can visit the service on http://10.0.0.42/.

More information is available on our documentation site.

Writing your first service

  1. Copy the ./seed/service directory to a convenient location like ~/your_service. Then, just start implementing the Service::start function in the Service class, located in your_service/service.cpp (very simple example provided). This function will be called once the OS is up and running.
  2. Update the CMakeLists.txt to specify the name of your project, enable any needed drivers or plugins, etc.

Example:

    $ cp -r seed/service ~/my_service
    $ cd ~/my_service
    $ emacs service.cpp
    ... add your code
    $ mkdir build && cd build
    $ cmake ..
    $ make
    $ boot my_service

Take a look at the examples and the tests. These all started out as copies of the same seed.

Contributing to IncludeOS

IncludeOS is being developed on GitHub. Create your own fork, send us a pull request, and chat with us on Gitter. Please read the Guidelines for Contributing to IncludeOS.

Important: Send your pull requests to the dev branch. It is ok if your pull requests come from your master branch.

C++ Guidelines

We want to adhere as much as possible to the ISO C++ Core Guidelines. When you find code in IncludeOS which doesn't adhere, please let us know in the issue tracker - or even better, fix it in your own fork and send us a pull-request.

Security contact

If you discover a security issue in IncludeOS please avoid the public issue tracker. Instead send an email to security@includeos.org. For more information and encryption please refer to the documentation.