https://github.com/hermitcore/rusty-hermit Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code + Explore + All features + Documentation + GitHub Skills + Blog * Solutions + By Plan + Enterprise + Teams + Compare all + By Solution + CI/CD & Automation + DevOps + DevSecOps + Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles + Repositories + Topics + Trending + Collections * Pricing [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} hermitcore / rusty-hermit Public * Notifications * Fork 52 * Star 894 RustyHermit - A Rust-based, lightweight unikernel License Apache-2.0, MIT licenses found Licenses found Apache-2.0 LICENSE-APACHE MIT LICENSE-MIT 894 stars 52 forks Star Notifications * Code * Issues 23 * Pull requests 3 * Actions * Projects 0 * Wiki * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Wiki * Security * Insights hermitcore/rusty-hermit This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. master Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 7 branches 45 tags Code * Clone HTTPS GitHub CLI [https://github.com/h] Use Git or checkout with SVN using the web URL. [gh repo clone hermit] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @bors @ssg bors[bot] and ssg Merge #376 ... 300977f Oct 31, 2022 Merge #376 376: Fix grammar r=stlankes a=ssg Co-authored-by: Sedat Kapanoglu 300977f Git stats * 1,168 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github .vscode benches examples hermit-abi hermit-sys img k8s libhermit-rs @ fdd290f .dockerignore .gitattributes .gitignore .gitlab-ci.yml .gitmodules .rustfmt.toml Cargo.toml Dockerfile LICENSE-APACHE LICENSE-MIT README.md bors.toml rust-toolchain.toml View code [ ] RustyHermit - A Rust-based, lightweight unikernel Background Requirements Building your own applications Running RustyHermit Using uhyve as Hypervisor Using Qemu as Hypervisor Using Qemu as microVM Advanced Features Controlling kernel message verbosity Network support Use RustyHermit for C/C++, Go, and Fortran applications Missing features Wiki Credits License Contribution Publications Funding README.md [hermitcore_lo] RustyHermit - A Rust-based, lightweight unikernel Slack Status RustyHermit is a unikernel targeting a scalable and predictable runtime for high-performance and cloud computing. Unikernel means, you bundle your application directly with the kernel library, so that it can run without any installed operating system. This reduces overhead, therefore, interesting applications include virtual machines and high-performance computing. The kernel is able to run Rust applications, as well as C/C++/Go/ Fortran applications. The repository contains following directories and submodules: 1. demo is a small demo application based on the data-parallelism library Rayon 2. hermit-abi contains the platform APIs and builds the interface between library operating system and the application 3. hermit-sys contains a crate to automate the build process of the library operating systems 4. libhermit-rs is the kernel itself 5. netbench provides some basic network benchmarks Background RustyHermit is a rewrite of HermitCore in Rust developed at RWTH-Aachen. HermitCore was a research unikernel written in C ( libhermit). The ownership model of Rust guarantees memory/thread-safety and enables us to eliminate many classes of bugs at compile-time. Consequently, the use of Rust for kernel development promises fewer vulnerabilities in comparison to common programming languages. The kernel and the integration into the Rust runtime are entirely written in Rust and do not use any C/C++ Code. We extended the Rust toolchain so that the build process is similar to Rust's usual workflow. Rust applications that use the Rust runtime and do not directly use OS services are able to run on RustyHermit without modifications. Requirements * rustup * NASM (only for SMP on x86_64) Building your own applications To give you an example on how to build your application with RustyHermit, lets create a new cargo project: A more comprehensive version of the example project is published at rusty-demo. cargo new hello_world cd hello_world To bind the library operating system to the application, add the crate hermit-sys to the dependencies in the file Cargo.toml. It is important to use at least the optimization level 1. Consequently, it is required to extend Cargo.toml with following lines: # Cargo.toml [target.'cfg(target_os = "hermit")'.dependencies] hermit-sys = "0.2.*" To link the application with RustyHermit, declare hermit_sys an external crate in the main file of your application. // src/main.rs #[cfg(target_os = "hermit")] use hermit_sys as _; fn main() { println!("Hello World!"); } The final step is building the application as follows: cargo build -Zbuild-std=std,core,alloc,panic_abort --target x86_64-unknown-hermit (You can set an easy alias for this in the .cargo/config file. Take a look at the demo) The resulting "hypervisor-ready" binary then can be found in target/ x86_64-unknown-hermit/debug. Running RustyHermit RustyHermit binaries can be run on either uhyve or qemu. Using uhyve as Hypervisor RustyHermit can run within our own hypervisor uhyve , which requires KVM to create a virtual machine. Please install the hypervisor as follows: cargo +nightly install uhyve --locked Afterwards, your are able to start RustyHermit applications within our hypervisor: uhyve target/x86_64-unknown-hermit/debug/hello_world More details can be found in the uhyve README. Using Qemu as Hypervisor It is also possible to run RustyHermit within Qemu. RustyHermit produces 64-bit binaries, but Qemu's x86 emulation cannot boot them directly. Therefore, the loader rusty-loader is required to boot the application. A prebuilt loader binary can be found at rusty-loader releases. The unikernel application app can be booted with the following command: qemu-system-x86_64 -smp 1 \ -cpu qemu64,apic,fsgsbase,rdtscp,xsave,xsaveopt,fxsr \ -device isa-debug-exit,iobase=0xf4,iosize=0x04 \ -display none -m 64M -serial stdio -enable-kvm \ -kernel path_to_loader/rusty-loader-x86_64 \ -initrd path_to_app/app It is important to enable the processor features fsgsbase and rdtscp because it is a prerequisite to boot RustyHermit. You can provide arguments to the application via the kernel commandline, which you can set with qemu's -append option. Since both the kernel and the application can have parameters, they are separated with --: qemu-system-x86_64 ... -append "kernel-arguments -- application-arguments" Using Qemu as microVM Qemu provides microvm virtual platform, which is a minimalist machine type without PCI nor ACPI support. In comparison to a common hypervisor, it has a clearly smaller memory footprint and a faster boot time. To use this VM type, all default features of RustyHermit has to be disabled (especially PCI and ACPI support). For instance, the following command builds the smallest version of the hello_world example: cargo build -Zbuild-std=core,alloc,std,panic_abort --target x86_64-unknown-hermit --no-default-features -p hello_world --release Afterwards, this minimal example can be loaded with the same boot loader like the common Qemu machine type: qemu-system-x86_64 \ -M microvm,x-option-roms=off,pit=off,pic=off,rtc=on,auto-kernel-cmdline=off \ -nodefaults -no-user-config -display none -smp 1 -m 512M -serial stdio \ -kernel path_to_loader/rusty-loader \ -initrd path_to_hello_world/hello_world \ -cpu qemu64,apic,fsgsbase,rdtscp,xsave,xsaveopt,fxsr \ -device isa-debug-exit,iobase=0xf4,iosize=0x04 \ -append "-freq 2800" Depending on the virtualized processor, the processor frequency has to pass as kernel argument (-freq) to the kernel. MHz is used as unit of frequency here. Kernel features like TCP/IP support can be reenabled manually. For instance, the following command creates a minimal web-server for Qemu's microvm platform: cargo build -Zbuild-std=core,alloc,std,panic_abort --target x86_64-unknown-hermit --no-default-features --features tcp -p httpd --release Advanced Features You are not happy with Hello World yet? Controlling kernel message verbosity RustyHermit uses the lightweight logging crate log to print kernel messages. If the environment variable HERMIT_LOG_LEVEL_FILTER is set at compile time to a string matching the name of a LevelFilter, then that value is used for the LevelFilter. If the environment variable is not set, or the name doesn't match, then LevelFilter::Info is used by default, which is the same as it was before. For instance, the following command builds RustyHermit with debug messages: HERMIT_LOG_LEVEL_FILTER=Debug cargo build -Zbuild-std=core,alloc,std,panic_abort --target x86_64-unknown-hermit Network support To enable an ethernet device, we have to setup a tap device on the host system. For instance, the following command establish the tap device tap10 on Linux: sudo ip tuntap add tap10 mode tap sudo ip addr add 10.0.5.1/24 broadcast 10.0.5.255 dev tap10 sudo ip link set dev tap10 up sudo bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap10/proxy_arp' Add the feature tcp in the Cargo.toml. This includes the network stack smoltcp and offers TCP/UDP communication. hermi-sys dependency has to be factored out of [target.'cfg(target_os = "hermit") '.dependencies] because it requires features selection for network support to work thus this snippet should be added to Cargo.toml # Cargo.toml [target.'cfg(target_os = "hermit")'.dependencies.hermit-sys] version = "0.2.*" default-features = false features = ["tcp", "pci"] Per default, RustyHermit's network interface uses 10.0.5.3 as IP address, 10.0.5.1 for the gateway and 255.255.255.0 as network mask. The default configuration could be overloaded at compile time by the environment variables HERMIT_IP, HERMIT_GATEWAY and HERMIT_MASK. For instance, the following command sets the IP address to 10.0.5.100. HERMIT_IP="10.0.5.100" cargo build -Zbuild-std=core,alloc,std,panic_abort --target x86_64-unknown-hermit Currently, RustyHermit does only support network interfaces through virtio. To use it, you have to start RustyHermit in Qemu with following command: $ qemu-system-x86_64 -cpu qemu64,apic,fsgsbase,rdtscp,xsave,xsaveopt,fxsr \ -enable-kvm -display none -smp 1 -m 1G -serial stdio \ -device isa-debug-exit,iobase=0xf4,iosize=0x04 \ -kernel path_to_loader/rusty-loader \ -initrd path_to_app/app \ -netdev tap,id=net0,ifname=tap10,script=no,downscript=no,vhost=on \ -device virtio-net-pci,netdev=net0,disable-legacy=on You can now access the files in SHARED_DIRECTORY under the virtiofs tag like /myfs/testfile. Use RustyHermit for C/C++, Go, and Fortran applications If you are interested to build C/C++, Go, and Fortran applications on top of a Rust-based library operating system, please take a look at https://github.com/hermitcore/hermit-playground. Missing features * Multikernel support (might be coming) * Virtio support (partly available) * Network support (partly available) Wiki Please use the Wiki to get further information and configuration options. Credits RustyHermit is derived from following tutorials and software distributions: 1. Philipp Oppermann's excellent series of blog posts. 2. Erik Kidd's toyos-rs, which is an extension of Philipp Opermann's kernel. 3. The Rust-based teaching operating system eduOS-rs. HermitCore's Emoji is provided for free by EmojiOne. License Licensed under either of * Apache License, Version 2.0, (LICENSE-APACHE or http:// www.apache.org/licenses/LICENSE-2.0) * MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option. Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. RustyHermit is being developed on GitHub. Create your own fork, send us a pull request, and chat with us on Slack Publications The following scientific publications are related to RustyHermit: * S. Lankes et al. - Exploring Rust for Unikernel Development * M. Sung et al. - Intra-unikernel isolation with Intel memory protection keys * S. Lankes et al. - RustyHermit: A Scalable, Rust-Based Virtual Execution Environment Funding The development of this project was partially funded by the European Union's Horizon 2020 research and innovation programme under grant agreement No 957246 - IoT-NGIN. About RustyHermit - A Rust-based, lightweight unikernel Topics rust virtualization osdev operating-system rust-lang unikernel high-performance-computing cloud-computing operating-systems Resources Readme License Apache-2.0, MIT licenses found Licenses found Apache-2.0 LICENSE-APACHE MIT LICENSE-MIT Stars 894 stars Watchers 12 watching Forks 52 forks Releases 6 Upgrade to Rust 2021 Latest Dec 10, 2021 + 5 releases Packages 1 Used by 27 * @playXE * @turrisxyz * @ant4g0nist * @whb07 * @duanyu-yu * @striezel-stash * @dalalsunil1986 * @Sys-APT + 19 Contributors 21 * @stlankes * @mkroening * @bors[bot] * @dependabot[bot] * @github-actions[bot] * @jschwe * @jbreitbart * @jounathaen * @garrettgu10 * @joboet * @alessio-proietti + 10 contributors Languages * Rust 94.1% * Dockerfile 3.8% * Shell 2.1% Footer (c) 2022 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.