Skip to content
Snippets Groups Projects
Select Git revision
  • v0.3.32
  • main default
  • gh-readonly-queue/main/pr-1863-beabb5b4b85920f9fcaa0ca027c2e08191e01782
  • gh-readonly-queue/main/pr-1864-a56f9e91840d593bfe5fa22495f37060df4c9560
  • gh-readonly-queue/main/pr-1867-42078807782be83c4d6d9f564e6135592886ad97
  • gh-readonly-queue/main/pr-1869-3fe27b20b4d941d54a736e71e8312e643a107942
  • gh-readonly-queue/main/pr-1869-91915bfe9e37cac0cef04ed84742c75a17040cd1
  • gh-readonly-queue/main/pr-1868-0a5013b3ea738c736abb56c3b349af6fab4b79c2
  • gh-readonly-queue/main/pr-1868-81c2a9fbd3e40e6c7594daa85b3c5bceaae0e752
  • gh-readonly-queue/main/pr-1866-72f1ce561bd38a908956aa69bdf82756e172f515
  • gh-readonly-queue/main/pr-1866-7521e852516b33bfd292a3d6a4aa9e0f7deb1ddc
  • gh-readonly-queue/main/pr-1865-0df8da990129f024f4fed312678807c1707443f2
  • gh-readonly-queue/main/pr-1865-c746573c47b5c014eb05d1d6fdbd51fd62cba9f0
  • gh-readonly-queue/main/pr-1864-0df8da990129f024f4fed312678807c1707443f2
  • dependabot/cargo/proc-macro2-1.0.96
  • dependabot/cargo/sysinfo-0.37.0
  • dependabot/cargo/hashbrown-0.15.5
  • dependabot/cargo/hermit-entry-0.10.4
  • dependabot/cargo/clap-4.5.44
  • dependabot/github_actions/actions/checkout-5
  • rftrace-0.3.0
  • v0.11.0
  • v0.10.0
  • v0.8.0
  • v0.7.0
  • v0.6.9
  • v0.6.8
  • v0.6.7
  • v0.6.6
  • v0.6.5
  • v0.6.4
  • v0.6.3
  • v6.3.0
  • v0.6.2
  • v0.6.1
  • 0.6.1
  • v0.6.0
  • v0.5.0
  • v0.4.4
  • v0.4.3
  • v0.4.2
41 results

kernel

  • Clone with SSH
  • Clone with HTTPS
  • RustyHermit - A Rust-based, lightweight unikernel

    Build Status Actions Status License 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 RustyHermit can run Rust applications, as well as C/C++/Go/Fortran applications. A tutorial on how to use these programming languages on top of RustyHermit is published at https://github.com/hermitcore/hermit-playground.

    Background

    HermitCore was a research unikernel developed at RWTH-Aachen written in C (libhermit). RustyHermit is a rewrite of HermitCore written in Rust.

    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 less vulnerabilities in comparison to common programming languages.

    The kernel and the integration into the Rust runtime is entirely written in Rust and does not use any C/C++ Code. We extend the Rust toolchain so that the build process is similar to Rust's usual workflow. Rust applications that do not bypass the Rust runtime and directly use OS services are able to run on RustyHermit without modifications.

    Running an Application in RustyHermit

    Prerequisites

    The Rust toolchain can be installed from the official webpage. RusyHermit currently requires the nightly versions of the toolchain.

    rustup default nightly

    Further requirements are the source code of the Rust runtime, cargo-download, and llvm-tools:

    cargo install cargo-download
    rustup component add rust-src
    rustup component add llvm-tools-preview

    Sample Application

    First, create a new cargo project:

    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.1.*"
    
    [profile.release]
    opt-level = 3
    
    [profile.dev]
    opt-level = 1

    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")]
    extern crate hermit_sys;
    
    fn main() {
            println!("Hello World!");
    }

    The final step is building the application as follows:

    cargo build -Z build-std=std,core,alloc,panic_abort --target x86_64-unknown-hermit

    The resulting "hypervisor-ready" binary then can be found in target/x86_64-unknown-hermit/debug/hermit-new

    Running RustyHermit

    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 install uhyve

    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. To build the loader, the assembler nasm is required. After the installation, the loader can be build as follows.

    $ git clone https://github.com/hermitcore/rusty-loader.git
    $ cd rusty-loader
    $ make

    Afterwards, the loader is stored in target/x86_64-unknown-hermit-loader/debug/ as rusty-loader. As final step, the unikernel application app can be booted with following command:

    $ qemu-system-x86_64 -display none -smp 1 -m 64M -serial stdio  -kernel path_to_loader/rusty-loader -initrd path_to_app/app -cpu qemu64,apic,fsgsbase,rdtscp,xsave,fxsr

    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 virtio-fs

    The Kernel has rudimentary support for the virtio-fs shared file system. Currently only files, no folders are supported. To use it, you have to run a virtio-fs daemon and start qemu as described in Standalone virtio-fs usage:

    # start virtiofsd in the background
    $ sudo virtiofsd --thread-pool-size=1 --socket-path=/tmp/vhostqemu -o source=$(pwd)/SHARED_DIRECTORY
    # give non-root-users access to the socket
    $ sudo chmod 777 /tmp/vhostqemu
    # start qemu with virtio-fs device.
    # you might want to change the socket (/tmp/vhostqemu) and virtiofs tag (currently myfs)
    $ qemu-system-x86_64 -cpu qemu64,apic,fsgsbase,rdtscp,xsave,fxsr -enable-kvm -display none -smp 1 -m 1G -serial stdio \
            -kernel path_to_loader/rusty-loader \
            -initrd path_to_app/app \
            -chardev socket,id=char0,path=/tmp/vhostqemu \
            -device vhost-user-fs-pci,queue-size=1024,chardev=char0,tag=myfs \
            -object memory-backend-file,id=mem,size=1G,mem-path=/dev/shm,share=on \
            -numa node,memdev=mem

    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

    This kernel can be used with C/C++, Go, and Fortran applications. A tutorial on how to do this is available at https://github.com/hermitcore/hermit-playground.

    Extending RustyHermit

    The best way to extend the kernel is to work with the branch devel of the repository rusty-hermit. It includes this repository as submodule and link the unikernel directly to the test application.

    According to the following instructions, the test application can be found under target/x86_64-unknown-hermit/debug/rusty_demo.

    git clone https://github.com/hermitcore/rusty-hermit.git
    cd rusty-hermit
    git submodule init
    git submodule update
    cargo build -Z build-std=std,core,alloc,panic_abort --target x86_64-unknown-hermit

    Missing features

    • Multikernel support (might be comming)
    • Virtio support (comming soon)
    • Network support (comming soon)
    • Hardware Boot

    Troubleshooting

    command failed with the error message linker rust-lld not found

    The path to the llvm-tools is not set. On Linux, it is typically installed at ${HOME}/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin.

    PATH=${HOME}/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin:$PATH cargo build -Z build-std=std,core,alloc,panic_abort --target x86_64-unknown-hermit

    Otherwise, the linker can be replaced by lld as follows:

    RUSTFLAGS="-C linker=lld" cargo build -Z build-std=std,core,alloc,panic_abort --target x86_64-unknown-hermit

    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

    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