{"id":13508313,"url":"https://github.com/hermit-os/libhermit","last_synced_at":"2025-03-30T11:31:51.430Z","repository":{"id":31753495,"uuid":"35319633","full_name":"hermit-os/libhermit","owner":"hermit-os","description":"HermitCore: A C-based, lightweight unikernel","archived":true,"fork":false,"pushed_at":"2021-11-05T09:26:51.000Z","size":44668,"stargazers_count":224,"open_issues_count":15,"forks_count":44,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-17T11:58:22.164Z","etag":null,"topics":["cloud-computing","high-performance-computing","kernel","multi-kernel","operating-system","osdev","unikernel","virtualization"],"latest_commit_sha":null,"homepage":"https://hermitcore.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hermit-os.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-09T07:26:59.000Z","updated_at":"2025-02-13T19:06:37.000Z","dependencies_parsed_at":"2022-09-03T03:23:45.028Z","dependency_job_id":null,"html_url":"https://github.com/hermit-os/libhermit","commit_stats":null,"previous_names":["hermit-os/libhermit","hermitcore/libhermit"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Flibhermit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Flibhermit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Flibhermit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hermit-os%2Flibhermit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hermit-os","download_url":"https://codeload.github.com/hermit-os/libhermit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246314011,"owners_count":20757450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-computing","high-performance-computing","kernel","multi-kernel","operating-system","osdev","unikernel","virtualization"],"created_at":"2024-08-01T02:00:51.250Z","updated_at":"2025-03-30T11:31:46.421Z","avatar_url":"https://github.com/hermit-os.png","language":"C","funding_links":[],"categories":["C","operating-system"],"sub_categories":[],"readme":"\u003cimg width=\"100\" align=\"right\" src=\"img/hermitcore_logo.png\" /\u003e\n\n\n\n## DEPRECATION NOTICE:\n\n\n**We have shifted our efforts from this project to the [rusty-hermit](https://github.com/hermitcore/rusty-hermit) project, which is also a unikernel but rewritten in Rust.\nThis project will not receive any active contributions from the maintainers and only limited responses/help in GitHub issues.**\n\n# HermitCore - A lightweight unikernel for a scalable and predictable runtime behavior\n\n[![Build Status](https://travis-ci.org/hermitcore/libhermit.svg?branch=master)](https://travis-ci.org/hermitcore/libhermit)\n[![Slack Status](https://radiant-ridge-95061.herokuapp.com/badge.svg)](https://radiant-ridge-95061.herokuapp.com)\n\nThe project [HermitCore]( http://www.hermitcore.org ) is a new\n[unikernel](http://unikernel.org) targeting a scalable and predictable runtime\nfor high-performance and cloud computing. HermitCore extends the multi-kernel\napproach (like\n[McKernel](https://www-sys-aics.riken.jp/ResearchTopics/os/mckernel/)) with\nunikernel features for a better programmability and scalability for hierarchical\nsystems.\n\n![HermitCore Demo](img/demo.gif)\n\nOn the startup of HermitCore applications, cores are isolated from the Linux\nsystem enabling bare-metal execution of on these cores. This approach achieves\nlower OS jitter and a better scalability compared to full-weight kernels.\nInter-kernel communication between HermitCore applications and the Linux system\nis realized by means of an IP interface.\n\nIn addition to the multi-kernel approach described above, HermitCore can be used\nas a classical standalone unikernel as well. In this case, HermitCore runs a\nsingle-kernel exclusively on the hardware or within a virtual machine. This\nreduces the resource demand and lowers the boot time which is critical for\ncloud computing applications. It is the result of a research project at RWTH\nAachen University and is currently an experimental approach, i.e., not\nproduction ready. Please use it with caution.\n\n## Contributing\n\nHermitCore is being developed on [GitHub](https://github.com/hermitcore/libhermit).\nCreate your own fork, send us a pull request, and chat with us on [Slack](https://radiant-ridge-95061.herokuapp.com).\n\n## Requirements\n\nThe build process works currently only on **x86-based Linux** systems. To build\nthe HermitCore kernel and applications you need:\n\n * CMake\n * Netwide Assember (NASM)\n * recent host compiler such as GCC\n * HermitCore cross-toolchain, i.e. Binutils, GCC, newlib, pthreads\n * Python3\n\n### HermitCore cross-toolchain\n\nWe provide prebuilt packages for Ubuntu 18.04 and Debian 9 of the HermitCore\ntoolchain, which can be installed as follows:\n\n**Ubuntu 18.04**\n\n```bash\n$ echo \"deb [trusted=yes] https://dl.bintray.com/hermitcore/ubuntu bionic main\" | sudo tee -a /etc/apt/sources.list\n$ sudo apt-get -qq update\n$ sudo apt-get install binutils-hermit newlib-hermit pte-hermit gcc-hermit libomp-hermit libhermit\n```\n\n**Debian 9**\n\n```bash\n$ echo \"deb [trusted=yes] https://dl.bintray.com/hermitcore/debian stretch main\" | sudo tee -a /etc/apt/sources.list\n$ sudo apt-get -qq update\n$ sudo apt-get install binutils-hermit newlib-hermit pte-hermit gcc-hermit libomp-hermit libhermit\n```\n\nFor unsupported systems, a docker image with the complete toolchain is provided and can be installed as follows:\n\n```bash\n$ docker pull rwthos/hermitcore\n```\n\nThe following commad starts within the new docker container a shell and mounts from the host system the directory `~/src` to `/src`:\n\n```bash\n$ docker run -i -t -v ~/src:/src rwthos/hermitcore:latest\n```\n\nWithin the shell the cross-toolchain can be used to build HermitCore applications.\n\nIf you want to build the toolchain yourself, have a look at the repository [hermit-toolchain](https://github.com/hermitcore/hermit-toolchain), which contains scripts to build the whole toolchain.\n\nDepending on how you want to use HermitCore, you might need additional packages\nsuch as:\n\n * QEMU (`apt-get install qemu-system-x86`)\n\n## Building HermitCore\n\n### Preliminary work\n\nTo build HermitCore from source (without compiler), the repository with its submodules has to be cloned.\n\n```bash\n$ git clone git@github.com:hermitcore/libhermit.git HermitCore\n$ cd HermitCore\n$ git submodule init\n$ git submodule update\n```\n\nWe require a fairly recent version of CMake (`3.7`) which is not yet present in\nmost Linux distributions. We therefore provide a helper script that fetches the\nrequired CMake binaries from the upstream project and stores them locally, so\nyou only need to download it once.\n\n```bash\n$ . cmake/local-cmake.sh\n-- Downloading CMake\n--2017-03-28 16:13:37--  https://cmake.org/files/v3.7/cmake-3.7.2-Linux-x86_64.tar.gz\nLoaded CA certificate '/etc/ssl/certs/ca-certificates.crt'\nResolving cmake.org... 66.194.253.19\nConnecting to cmake.org|66.194.253.19|:443... connected.\nHTTP request sent, awaiting response... 200 OK\nLength: 30681434 (29M) [application/x-gzip]\nSaving to: ‘cmake-3.7.2-Linux-x86_64.tar.gz’\n\ncmake-3.7.2-Linux-x86_64.tar.gz         100%[===================\u003e]  29,26M  3,74MB/s    in 12s\n\n2017-03-28 16:13:50 (2,48 MB/s) - ‘cmake-3.7.2-Linux-x86_64.tar.gz’ saved [30681434/30681434]\n\n-- Unpacking CMake\n-- Local CMake v3.7.2 installed to cmake/cmake-3.7.2-Linux-x86_64\n-- Next time you source this script, no download will be necessary\n```\n\nSo before you build HermitCore you have to source the `local-cmake.sh` script\neverytime you open a new terminal.\n\n### Building the library operating systems and its examples\n\nTo build HermitCore go to the directory with the source code, create a `build` directory, and call in the new directory `cmake` followed by `make`.\n\n```bash\n$ mkdir build\n$ cd build\n$ cmake ..\n$ make\n$ sudo make install\n```\n\nIf your toolchain is not located in `/opt/hermit/bin` then you have to supply\nits location to the `cmake` command above like so:\n\n```bash\n$ cmake -DTOOLCHAIN_BIN_DIR=/home/user/hermit/bin ..\n```\n\nAssuming that binaries like `x86_64-hermit-gcc` and friends are located in that\ndirectory.\nTo install your new version in the same directory, you have to set the installation path and to install HermitCore as follows:\n\n```bash\n$ cmake -DTOOLCHAIN_BIN_DIR=/home/user/hermit/bin -DCMAKE_INSTALL_PREFIX=/home/user/hermit ..\n$ make\n$ make install\n```\n\n**Note:** If you use the cross compiler outside of this repository, the compiler uses per default the library operating systems located by the toolchain (e.g. `/opt/hermit/x86_64-hermit/lib/libhermit.a`).\n\n## Starting Applications with the Proxy tool\n\nHermitCore applications are currently started with a small helper tool called `proxy`.\nThis tool sets up a virtual machine or bare-metal on a NUMA node and bridges certain functionality from the application to the Linux host.\n\nTo start a HermitCore application, hand the executable to the proxy:\n```bash\n/opt/hermit/bin/proxy myHermiCoreApplication\n```\n\n*Optional:* The proxy can be registered as loader for HermitCore _elf_ files to the Linux system via [binfmt_misc](https://en.wikipedia.org/wiki/Binfmt_misc), so that HermitCore applications can be started like common Linux applications.\n\n```bash\n$ sudo -c sh 'echo \":hermit:M:7:\\\\xff::/opt/hermit/bin/proxy:\" \u003e /proc/sys/fs/binfmt_misc/register'\n$ # dirct call of a HermitCore application\n$ /opt/hermit/x86_64-hermit/extra/tests/hello\nHello World!!!\n```\n\nThe proxy starts the HermitCore applications within a VM.\nThe application host (QEMU, Uhyve or bare-metal on a NUMA node as multi-kernel) can be set via the environment variable `$HERMIT_ISLE`.\n\n```bash\n$ # using QEMU\n$ HERMIT_ISLE=qemu /opt/hermit/bin/proxy /opt/hermit/x86_64-hermit/extra/tests/hello\n```\n\n## Testing\n\n### As classical standalone unikernel within a virtual machine\n\nHermitCore applications can be directly started as standalone kernel within a\nvirtual machine. In this case,\n[iRCCE](http://www.lfbs.rwth-aachen.de/publications/files/iRCCE.pdf ) is not\nsupported.\n\n```bash\n$ cd build\n$ make install DESTDIR=~/hermit-build\n$ cd ~/hermit-build/opt/hermit\n$ # using QEMU\n$ HERMIT_ISLE=qemu bin/proxy x86_64-hermit/extra/tests/hello\n$ # using uHyve\n$ HERMIT_ISLE=uhyve bin/proxy x86_64-hermit/extra/tests/hello\n```\n\nWith `HERMIT_ISLE=qemu`, the application will be started within a QEMU VM.\nPlease note that the loader requires QEMU and uses per default *KVM*.\nFurthermore, it expects that the executable is called `qemu-system-x86_64`.\n\nWith `HERMIT_ISLE=uhyve`, the application will be started within a thin\nhypervisor powered by Linux's KVM API and therefore requires *KVM* support.\nuhyve has a considerably smaller startup time than QEMU, but lacks some features\nsuch as GDB debugging.\nIn principle, it is an extension of [ukvm](https://www.usenix.org/sites/default/files/conference/protected-files/hotcloud16_slides_williams.pdf).\n\nIn this context, the environment variable `HERMIT_CPUS` specifies the number of\ncpus (and no longer a range of core ids). Furthermore, the variable `HERMIT_MEM`\ndefines the memory size of the virtual machine. The suffix of *M* or *G* can be\nused to specify a value in megabytes or gigabytes respectively. Per default, the\nloader initializes a system with one core and 2 GiB RAM.\nFor instance, the following command starts the stream benchmark in a virtual machine, which\nhas 4 cores and 6GB memory.\n\n```bash\n$ HERMIT_ISLE=qemu HERMIT_CPUS=4 HERMIT_MEM=6G bin/proxy x86_64-hermit/extra/benchmarks/stream\n```\n\nTo enable an ethernet device for `uhyve`, we have to setup a tap device on the\nhost system. For instance, the following command establish the tap device\n`tap100` on Linux:\n\n```bash\n$ sudo ip tuntap add tap100 mode tap\n$ sudo ip addr add 10.0.5.1/24 broadcast 10.0.5.255 dev tap100\n$ sudo ip link set dev tap100 up\n$ sudo bash -c 'echo 1 \u003e /proc/sys/net/ipv4/conf/tap100/proxy_arp'\n```\n\nPer default, `uhyve`'s network interface uses `10.0.5.2`as IP address, `10.0.5.1`\nfor the gateway and `255.255.255.0` as network mask.\nThe default configuration could be overloaded by the environment variable\n`HERMIT_IP`, `HERMIT_GATEWAY` and `HERMIT_MASk`.\nTo enable the device, `HERMIT_NETIF` must be set to the name of the tap device.\nFor instance, the following command starts an HermitCore application within `uhyve`\nand enable the network support:\n\n```bash\n$ HERMIT_ISLE=uhyve HERMIT_IP=\"10.0.5.3\" HERMIT_GATEWAY=\"10.0.5.1\" HERMIT_MASk=\"255.255.255.0\" HERMIT_NETIF=tap100 bin/proxy x86_64-hermit/extra/tests/hello\n```\n\nIf `qemu` is used as hypervisor, the virtual machine emulates an RTL8139 ethernet interface and opens at least one TCP/IP ports.\nIt is used for the communication between HermitCore application and its proxy.\nWith the environment variable `HERMIT_PORT`, the default port (18766) can be changed for the communication.\n\n\n### As multi-kernel within a virtual machine\n\nBoot the test image of a minimal Linux system within a VM.\nFor this, go to the build directory and boot the image by our makefiles.\n\n```bash\n$ cd build\n$ make qemu\n$ # or 'make qemu-dep' to build HermitCore dependencies before\n```\n\nWithin the QEMU session you can start HermitCore application just the same as\ntraditional Linux programs:\n\n```bash\n(QEMU) $ /hermit/x86_64-hermit/extra/tests/hello\nsmpboot: CPU 1 is now offline\nHello World!!!\nargv[0] = /hermit/x86_64-hermit/extra/tests/hello\nReceive signal with number 30\nHostname: hermit.localdomain\nx86: Booting SMP configuration:\nsmpboot: Booting Node 0 Processor 1 APIC 0x1\n```\n\nPer default, the virtual machine has 10 cores, 2 NUMA nodes, and 8 GiB RAM.\nInside the VM runs a small Linux system, which already includes the patches for\nHermitCore. Per NUMA node (= HermitCore isle) there is a directory called\n`isleX` under `/sys/hermit` , where `X` represents the NUMA node ID.\n\nThe demo applications are located in the directories\n`/hermit/x86_64-hermit/extra/{tests,benchmarks}`. A HermitCore loader is already registered.\nBy starting a HermitCore application, a proxy will be executed on the Linux\nsystem, while the HermitCore binary will be started on isle 0 with cpu 1. To\nchange the default behavior, the environment variable `HERMIT_ISLE` is used to\nspecify the (memory) location of the isle, while the environment variable\n`HERMIT_CPUS` is used to specify the cores.\n\nFor instance, `HERMIT_ISLE=1 HERMIT_CPUS=\"3-5\" /hermit/x86_64-hermit/extra/tests/hello` starts\na HelloWorld demo on the HermitCore isle 1, which uses the cores 3 to 5. The\noutput messages are forwarded to the Linux proxy and printed on the Linux\nsystem.\n\nHermitCore's kernel messages of `isleX` are available via `cat\n/sys/hermit/isleX/log`.\n\nThere is a virtual IP device for the communication between the HermitCore isles\nand the Linux system (see output of `ifconfig`). Per default, the Linux system\nhas the IP address `192.168.28.1`. The HermitCore isles starts with the IP\naddress `192.168.28.2` for isle 0 and is increased by one for every isle.\n\nMore HermitCore applications are available at `/hermit/usr/{tests,benchmarks}`\nwhich is a shared directory between the host and QEMU.\n\n\n### As multi-kernel on a real machine\n\n*Note*: to launch HermitCore applications, root privileges are required.\n\nA [modified Linux kernel](https://github.com/RWTH-OS/linux) has to be installed.\nAfterwards switch to the branch `hermit` for a relative new vanilla kernel or to\n`centos`, which is compatible to the current CentOS 7 kernel. Configure the\nkernel with `make menuconfig` for your system. Be sure, that the option\n`CONFIG_HERMIT_CORE` in `Processor type and features` is enabled.\n\n```bash\n$ git clone https://github.com/RWTH-OS/linux\n$ cd linux\n$ # see comments above\n$ git checkout hermit\n$ make menuconfig\n$ make\n```\n\nInstall the Linux kernel and its initial ramdisk on your system (see\ndescriptions of your Linux distribution). We recommend to disable Linux NO_HZ\nfeature by setting the kernel parameter `nohz=off`.\n\nInstall HermitCore to your system (by default to `/opt/hermit`):\n\n```bash\n$ cd build\n$ sudo make install\n$ ls -l /opt/hermit\n```\n\nAfter a reboot of the system, register the HermitCore loader at your system with\nfollowing command:\n\n```bash\n$ sudo -c sh 'echo \":hermit:M:7:\\\\xff::/opt/hermit/bin/proxy:\" \u003e /proc/sys/fs/binfmt_misc/register'\n```\n\nThe IP device between HermitCore and Linux currently does not support IPv6.\nConsequently, disable it (might be slightly different on your distribution):\n\n```bash\n$ echo 'net.ipv6.conf.mmnif.disable_ipv6 = 1' | sudo tee /etc/sysctl.conf\n```\n\nPer default, the IP device uses a static IP address range. Linux has to use\n`162.168.28.1`, where HermitCore isles start with `192.168.28.2` (isle 0). The\ninterface is `mmnif`.\n\nPlease configure your network accordingly. For CentOS, you have to create the\nfile `/etc/sysconfig/network-scripts/ifcfg-mmnif`:\n\n```\nDEVICE=mmnif\nBOOTPROTO=none\nONBOOT=yes\nNETWORK=192.168.28.0\nNETMASK=255.255.255.0\nIPADDR=192.168.28.1\nNM_CONTROLLED=yes\n```\n\nYou can now start applications the same way as from within a virtual machine\n(see description above).\n\n\n## Building your own HermitCore applications\n\nYou can take `usr/tests` as a starting point to build your own applications. All\nthat is required is that you include\n`[...]/HermitCore/cmake/HermitCore-Application.cmake` in your application's\n`CMakeLists.txt`. It doesn't have to reside inside the HermitCore repository.\nOther than that, it should behave like normal CMake.\n\n\n## Profiling\n\nWe provide profiling support via the XRay profiler. See `usr/xray/README.md` for\nmore information on how to use it.\n\n\n## Debugging\n\nIf the application is started via `make qemu`, debugging via GDB is enabled by\ndefault on port 1234. When run via proxy (`HERMIT_ISLE=qemu`), set\n`HERMIT_DEBUG=1`.\n\n```\n$ gdb x86_64-hermit/extra/tests/hello\n(gdb) target extended-remote :1234\nRemote debugging using :1234\n0xffffffff8100b542 in ?? ()\n```\n\n\n## Tips\n\n### Optimization\n\nYou can configure the `-mtune=name` compiler flag by adding `-DMTUNE=name` to\nthe `cmake` command when configuring the project.\n\nPlease note, if the applications is started within a VM, the hypervisor has to\nsupport the specified architecture name.\n\nIf QEMU is started by our proxy and the environment variable `HERMIT_KVM` is set\nto `0`, the virtual machine will be not accelerated by KVM. In this case, the\n`-mtune` flag should be avoided.\n\n### TCP connections\n\nWith the environment variable `HERMIT_APP_PORT`, an additional port can be open\nto establish an TCP/IP connection with your application.\n\n### Dumping the kernel log\n\nBy setting the environment variable `HERMIT_VERBOSE` to `1`, the proxy prints at\ntermination the kernel log messages onto the screen.\n\n### Network tracing\n\nBy setting the environment variable `HERMIT_CAPTURE_NET` to `1` and\n`HERMIT_ISLE` to `qemu`, QEMU captures the network traffic and creates the trace\nfile *qemu-vlan0.pcap*. For instance with [Wireshark](https://www.wireshark.org)\nyou are able to analyze the file.\n\n### Monitor\n\nIf `HERMIT_MONITOR` is set to `1` and `HERMIT_ISLE` to `qemu`, QEMU establishes\na monitor which is available via telnet at port 18767.\nWith the environment variable `HERMIT_PORT`, the default port (18766) can be changed for the communication between the HermitCore application and its proxy.\nThe connection to the system monitor is automatically set to `HERMIT_PORT+1`, i.e., the default port is 18767.\n\n## Credits\n\nHermitCore's Emoji is provided free by [EmojiOne](https://www.gfxmag.com/crab-emoji-vector-icon/).\n\n## Contributors\n\n\u003ca href=\"https://github.com/hermitcore/libhermit/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=hermitcore/libhermit\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhermit-os%2Flibhermit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhermit-os%2Flibhermit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhermit-os%2Flibhermit/lists"}