{"id":13508064,"url":"https://github.com/cloudius-systems/osv","last_synced_at":"2025-05-13T18:07:18.617Z","repository":{"id":6034433,"uuid":"7258685","full_name":"cloudius-systems/osv","owner":"cloudius-systems","description":"OSv, a new operating system for the cloud.","archived":false,"fork":false,"pushed_at":"2025-05-10T20:34:48.000Z","size":23310,"stargazers_count":4168,"open_issues_count":318,"forks_count":607,"subscribers_count":266,"default_branch":"master","last_synced_at":"2025-05-10T21:29:46.295Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"osv.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudius-systems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["wkozaczuk"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2012-12-20T14:08:55.000Z","updated_at":"2025-05-10T20:34:52.000Z","dependencies_parsed_at":"2023-10-02T01:36:59.894Z","dependency_job_id":"3cebe94c-30a2-4634-aff0-cb993aecae52","html_url":"https://github.com/cloudius-systems/osv","commit_stats":{"total_commits":8331,"total_committers":151,"mean_commits":55.17218543046358,"dds":0.8446765094226383,"last_synced_commit":"2a835078e5c0b6e68f3ba130e87da57b5f2fc3e8"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudius-systems%2Fosv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudius-systems%2Fosv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudius-systems%2Fosv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudius-systems%2Fosv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudius-systems","download_url":"https://codeload.github.com/cloudius-systems/osv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000848,"owners_count":21997441,"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":[],"created_at":"2024-08-01T02:00:47.261Z","updated_at":"2025-05-13T18:07:18.587Z","avatar_url":"https://github.com/cloudius-systems.png","language":"C","readme":"***OSv was originally designed and implemented by Cloudius Systems (now ScyllaDB) however\n currently, it is being maintained and enhanced by a small community of volunteers.\n If you are into systems programming or want to learn and help us improve OSv, then please\n contact us on [OSv Google Group forum](https://groups.google.com/forum/#!forum/osv-dev)\n or feel free to pick up any [good issues for newcomers](https://github.com/cloudius-systems/osv/labels/good-for-newcomers).\n For details on how to format and send patches, please read\n [this wiki](https://github.com/cloudius-systems/osv/wiki/Formatting-and-sending-patches)\n (__we do accept pull requests as well__).***\n\n# OSv\n\nOSv is an open-source versatile modular **unikernel** designed to run single **unmodified\nLinux application** securely as microVM on top of a hypervisor, when compared to traditional\noperating systems which were designed for a vast range of physical machines. Built from\nthe ground up for effortless deployment and management of microservices\nand serverless apps, with superior performance.\n\nOSv has been designed to run unmodified x86-64 and aarch64 Linux\nbinaries **as is**, which effectively makes it a **Linux binary compatible unikernel**\n(for more details about Linux ABI compatibility please read\n[this doc](https://github.com/cloudius-systems/osv/wiki/OSv-Linux-ABI-Compatibility)).\nIn particular, OSv can run many managed language runtimes including\n[**JVM**](https://github.com/cloudius-systems/osv-apps/tree/master/java-example),\n[**Python**](https://github.com/cloudius-systems/osv-apps/tree/master/python-from-host),\n[**Node.JS**](https://github.com/cloudius-systems/osv-apps/tree/master/node-from-host),\n[**Ruby**](https://github.com/cloudius-systems/osv-apps/tree/master/ruby-example), **Erlang**,\nand applications built on top of those runtimes.\nIt can also run applications written in languages compiling directly to native machine code like\n**C**, **C++**,\n[**Golang**](https://github.com/cloudius-systems/osv-apps/tree/master/golang-httpserver)\nand [**Rust**](https://github.com/cloudius-systems/osv-apps/tree/master/rust-httpserver)\nas well as native images produced\nby [**GraalVM**](https://github.com/cloudius-systems/osv-apps/tree/master/graalvm-example)\nand [WebAssembly/Wasmer](https://github.com/cloudius-systems/osv-apps/tree/master/webassembly).\n\nOSv can boot as fast as **~5 ms** on Firecracker using as low as 11 MB of memory.\nOSv can run on many hypervisors including QEMU/KVM,\n[Firecracker](https://github.com/cloudius-systems/osv/wiki/Running-OSv-on-Firecracker),\n[Cloud Hypervisor](https://github.com/cloudius-systems/osv/wiki/Running-OSv-on-Cloud-Hypervisor),\nXen, [VMWare](https://github.com/cloudius-systems/osv/wiki/Running-OSv-on-VMware-ESXi),\n[VirtualBox](https://github.com/cloudius-systems/osv/wiki/Running-OSv-on-VirtualBox) and\nHyperkit as well as open clouds like AWS EC2, GCE and OpenStack.\n\nFor more information about OSv, see the [main wiki page](https://github.com/cloudius-systems/osv/wiki)\nand http://osv.io/.\n\n## Building and Running Apps on OSv\n\nTo run an application on OSv, one needs to build an image by fusing the OSv kernel, and\nthe application files together. This, at a high level, can be achieved in two ways, either:\n- by using the shell script located at `./scripts/build`\n that builds the kernel from sources and fuses it with application files, or\n- by using the [capstan tool](https://github.com/cloudius-systems/capstan) that uses *pre-built\n kernel* and combines it with application files to produce a final image.\n\nIf you intend to try to run your app on OSv with the least effort possible, you should pursue the *capstan*\nroute. For introduction please read this \n[crash course](https://github.com/cloudius-systems/osv/wiki/Build-and-run-apps-on-OSv-using-Capstan).\nFor more details about *capstan* please read \nthis more detailed [documentation](https://github.com/cloudius-systems/capstan#documentation). Pre-built OSv kernel files\n(`osv-loader.qemu`) can be automatically downloaded by *capstan* from \nthe [OSv regular releases page](https://github.com/cloudius-systems/osv/releases) or manually from \nthe [nightly releases repo](https://github.com/osvunikernel/osv-nightly-releases/releases/tag/ci-master-latest).\n\nIf you are comfortable with make and GCC toolchain and want to try the latest OSv code, then you should\nread this [part of the readme](#setting-up-development-environment) to guide you how to set up your\n development environment and build OSv kernel and application images.\n\n## Releases\n\nWe aim to release OSv 2-3 times a year. You can find the [latest one on github](https://github.com/cloudius-systems/osv/releases)\nalong with several published artifacts including kernel and some modules.\n\nIn addition, we have set up [Travis-based CI/CD pipeline](https://travis-ci.org/github/cloudius-systems/osv) where each\ncommit to the master and ipv6 branches triggers full build of the latest kernel and publishes some artifacts to \nthe [nightly releases repo](https://github.com/osvunikernel/osv-nightly-releases/releases). Each commit also\ntriggers the publishing of new Docker \"build toolchain\" images to the [Docker hub](https://hub.docker.com/u/osvunikernel).\n\n## Design\n\nA good bit of the design of OSv is pretty well explained in \nthe [Components of OSv](https://github.com/cloudius-systems/osv/wiki/Components-of-OSv) wiki page. You \ncan find even more information in the original \n[USENIX paper and its presentation](https://www.usenix.org/conference/atc14/technical-sessions/presentation/kivity).\n\nIn addition, you can find a lot of good information about the design of specific OSv components on\nthe [main wiki page](https://github.com/cloudius-systems/osv/wiki) and http://osv.io/ and http://blog.osv.io/.\nUnfortunately, some of that information may be outdated (especially on http://osv.io/), so it is always\nbest to ask on the [mailing list](https://groups.google.com/forum/#!forum/osv-dev) if in doubt.\n\n## Component Diagram\nIn the diagram below, you can see the major components of OSv across the logical layers. Starting with `libc` at the top, which is greatly based on `musl`, the core layer in the middle comprises ELF dynamic linker, VFS, networking stack, thread scheduler, page cache, RCU, and memory management components. Then finally down, the layer is composed of the clock, block, and networking device drivers that allow OSv to interact with hypervisors like VMware and VirtualBox or the ones based on KVM and XEN.\n![Component Diagram](../master/documentation/OSv_Component_Diagram.png)\n\n## Metrics and Performance\n\nThere are no official **up-to date** performance metrics comparing OSv to other unikernels or Linux.\nIn general, OSv lags behind Linux in disk-I/O-intensive workloads partially due to coarse-grained locking \nin VFS around read/write operations as described in this [issue](https://github.com/cloudius-systems/osv/issues/450).\nIn network-I/O-intensive workloads, OSv should fare better (or at least used to as Linux has advanced a lot since)\nas shown with performance tests of Redis and [Memcached](https://github.com/cloudius-systems/osv/wiki/OSv-Case-Study:-Memcached).\nYou can find some old \"numbers\" on the main wiki, http://osv.io/benchmarks, and some papers listed at the bottom of this readme.\n\nSo OSv is probably not best suited to run MySQL or ElasticSearch, but should deliver pretty solid performance for general\n stateless applications like microservices or serverless (at least as some papers show).\n\n### Kernel Size\n\nAt this moment (as of December 2022) the size of the universal OSv kernel (`loader.elf` artifact) *built with all symbols hidden* is around\n3.6 MB. The size of the kernel linked with the full `libstdc++.so.6` library and ZFS filesystem library included is 6.8 MB. Please read the [Modularization](https://github.com/cloudius-systems/osv/wiki/Modularization) wiki to better understand how kernel can be built and further reduced in size and customized to run on a specific hypervisor or a specific app.\n\nThe size of OSv kernel may be considered quite large compared to other unikernels. However, bear in mind that OSv kernel (being unikernel) provides **subset** of the functionality of the following Linux libraries (see their approximate size on Linux host):\n- `libresolv.so.2` (_100 K_)\n- `libc.so.6` (_2 MB_)\n- `libm.so.6` (_1.4 MB_)\n- `ld-linux-x86-64.so.2` (_184 K_)\n- `libpthread.so.0` (_156 K_)\n- `libdl.so.2` (_20 K_)\n- `librt.so.1` (_40 K_)\n- `libstdc++.so.6` (_2 MB_)\n- `libaio.so.1` (_16 K_)\n- `libxenstore.so.3.0` (_32 K_)\n- `libcrypt.so.1` (_44 K_)\n\n### Boot Time\n\nOSv, with _Read-Only FS and networking off_, can boot as fast as **~5 ms** on Firecracker \nand even faster around **~3 ms** on QEMU with the microvm machine. However, in general, the boot time\nwill depend on many factors like hypervisor including settings of individual para-virtual devices, \nfilesystem (ZFS, ROFS, RAMFS, or Virtio-FS), and some boot parameters. Please note that by default OSv images\nget built with ZFS filesystem.\n\nFor example, the boot time of ZFS image on Firecracker is ~40 ms, and regular QEMU ~200 ms these days. Also,\nnewer versions of QEMU (\u003e=4.0) are typically faster to boot. Booting on QEMU in PVH/HVM mode (aka direct kernel boot, enabled \nby `-k` option of `run.py`) should always be faster as OSv is directly invoked in 64-bit long mode. Please see\n[this Wiki](https://github.com/cloudius-systems/osv/wiki/OSv-boot-methods-overview) for a brief review of the boot\nmethods OSv supports.\n\nFinally, some boot parameters passed to the kernel may affect the boot time:\n- `--console serial` - this disables VGA console that is [slow to initialize](https://github.com/cloudius-systems/osv/issues/987) and can shave off 60-70 ms on QEMU\n- `--nopci` - this disables enumeration of PCI devices especially if we know none are present (QEMU with microvm or Firecracker) and can shave off 10-20 ms \n- `--redirect=/tmp/out` - writing to the console can impact the performance quite severely (30-40%) if application logs \na lot, so redirecting standard output and error to a file might speed up performance quite a lot\n\nYou can always see boot time breakdown by adding `--bootchart` parameter:\n```\n./scripts/run.py -e '--bootchart /hello'\nOSv v0.57.0-6-gb442a218\neth0: 192.168.122.15\n\tdisk read (real mode): 58.62ms, (+58.62ms)\n\tuncompress lzloader.elf: 77.20ms, (+18.58ms)\n\tTLS initialization: 77.96ms, (+0.76ms)\n\t.init functions: 79.75ms, (+1.79ms)\n\tSMP launched: 80.11ms, (+0.36ms)\n\tVFS initialized: 81.62ms, (+1.52ms)\n\tNetwork initialized: 81.78ms, (+0.15ms)\n\tpvpanic done: 81.91ms, (+0.14ms)\n\tpci enumerated: 93.89ms, (+11.98ms)\n\tdrivers probe: 93.89ms, (+0.00ms)\n\tdrivers loaded: 174.80ms, (+80.91ms)\n\tROFS mounted: 176.88ms, (+2.08ms)\n\tTotal time: 178.01ms, (+1.13ms)\nCmdline: /hello\nHello from C code\n```\n\n### Memory Utilization\n\nOSv needs at least 11 M of memory to run a _hello world_ app. Even though it is a third of what it was 4 years ago, it is still quite a lot compared to other unikernels. The applications spawning many threads may take advantage of building the kernel with the option `conf_lazy_stack=1` to further reduce memory utilization (please see the comments of this [patch](https://github.com/cloudius-systems/osv/commit/f5684d9c3f4f8d20a64605cfe66fd51771754256) to understand this feature better). \n\nWe are planning to further lower this number by adding [self-tuning logic to L1/L2 memory pools](https://github.com/cloudius-systems/osv/issues/1013).\n\n## Testing\n\nOSv comes with around 140 unit tests that get executed upon every commit and run on ScyllaDB servers. There are also a number of extra\ntests located under `tests/` sub-tree that are not automated at this point.\n\nYou can run unit tests in a number of ways:\n```\n./scripts/build check                  # Create ZFS test image and run all tests on QEMU\n\n./scripts/build check fs=rofs          # Create ROFS test image and run all tests on QEMU\n\n./scripts/build image=tests \u0026\u0026 \\       # Create ZFS test image and run all tests on Firecracker\n./scripts/test.py -p firecracker\n\n./scripts/build image=tests \u0026\u0026 \\       # Create ZFS test image and run all tests on QEMU\n./scripts/test.py -p qemu_microvm      # with microvm machine\n```\n\nIn addition, there is an [Automated Testing Framework](https://github.com/cloudius-systems/osv/wiki/Automated-Testing-Framework)\nthat can be used to run around 30 real apps, some of them\nunder stress using `ab` or `wrk` tools. The intention is to catch any regressions that may be missed\nby unit tests.\n\nFinally, one can use [Docker files](https://github.com/cloudius-systems/osv/tree/master/docker#docker-osv-builder) to\ntest OSv on different Linux distributions.\n\n## Setting up Development Environment\n\nOSv can only be built on a 64-bit x86 and ARM Linux distribution. Please note that\nthis means the \"x86_64\" or \"amd64\" version for 64-bit x86 and \"aarch64\" or \"arm64\" version for ARM respectively.\n\nTo build the OSv kernel you need a physical or virtual machine with Linux distribution on it and GCC toolchain and\nall necessary packages and libraries OSv build process depends on. The fastest way to set it up is to use the\n[Docker files](https://github.com/cloudius-systems/osv/tree/master/docker#docker-osv-builder) that OSv comes with.\nYou can use them to build your own Docker image and then start it in order to build OSv kernel or run an app on OSv inside of it.\nPlease note that the main docker file depends on pre-built base **Docker images** for \n[Ubuntu](https://hub.docker.com/repository/docker/osvunikernel/osv-ubuntu-20.10-builder-base) \nor [Fedora](https://hub.docker.com/repository/docker/osvunikernel/osv-fedora-31-builder-base) \nthat get published to DockerHub upon every commit. This should speed up building the final images\nas all necessary packages are installed as part of the base images.\n\nAlternatively, you can manually clone the OSv repo and use [setup.py](https://github.com/cloudius-systems/osv/blob/master/scripts/setup.py)\nto install all required packages and libraries, as long as it supports your Linux distribution, and you have both git \nand python 3 installed on your machine:\n```bash\ngit clone https://github.com/cloudius-systems/osv.git\ncd osv \u0026\u0026 git submodule update --init --recursive\n./scripts/setup.py\n```\n\nThe `setup.py` recognizes and installs packages for a number of Linux distributions including Fedora, Ubuntu,\n[Debian](https://github.com/cloudius-systems/osv/wiki/Building-OSv-on-Debian-stable), LinuxMint and RedHat ones \n(Scientific Linux, NauLinux, CentOS Linux, Red Hat Enterprise Linux, Oracle Linux). Please note that we actively\nmaintain and test only Ubuntu and Fedora, so your mileage with other distributions may vary. The support of CentOS 7\nhas also been recently added and tested so it should work as well. The `setup.py`\nis used by Docker files internally to achieve the same result. \n\n### IDEs\n\nIf you like working in IDEs, we recommend either [Eclipse CDT](https://www.eclipse.org/cdt/) which can be setup\nas described in this [wiki page](https://github.com/cloudius-systems/osv/wiki/Working-With-Eclipse-CDT) or \n[CLion from JetBrains](https://www.jetbrains.com/clion/) which can be set to work with OSv makefile using\nso-called compilation DB as described in this [guide](https://www.jetbrains.com/help/clion/managing-makefile-projects.html).\n\n## Building OSv Kernel and Creating Images\n\nBuilding OSv is as easy as using the shell script `./scripts/build`\nthat orchestrates the build process by delegating to the main [makefile](https://github.com/cloudius-systems/osv/blob/master/Makefile)\nto build the kernel and by using a number of Python scripts like `./scripts/module.py` \nto build application and *fuse* it together with the kernel\ninto a final image placed at `./build/release/usr.img` (or `./build/$(arch)/usr.img` in general).\nPlease note that *building an application* does not necessarily mean building from sources as in many \ncases the application binaries would be located on and copied from the Linux build machine\nusing the shell script `./scripts/manifest_from_host.sh`\n(see [this Wiki page](https://github.com/cloudius-systems/osv/wiki/Running-unmodified-Linux-executables-on-OSv) for details).\n\nThe shell script `build` can be used as the examples below illustrate:\n```bash\n# Create a default image that comes with a command line and REST API server\n./scripts/build\n\n# Create an image with native-example app\n./scripts/build -j4 fs=rofs image=native-example\n\n# Create an image with spring boot app with Java 10 JRE\n./scripts/build JAVA_VERSION=10 image=openjdk-zulu-9-and-above,spring-boot-example\n\n # Create an image with 'ls' executable taken from the host\n./scripts/manifest_from_host.sh -w ls \u0026\u0026 ./scripts/build --append-manifest\n\n# Create a test image and run all tests in it\n./scripts/build check\n\n# Clean the build tree\n./scripts/build clean\n```\n\nCommand nproc will calculate the number of jobs/threads for make and `./scripts/build` automatically.\nAlternatively, the environment variable MAKEFLAGS can be exported as follows:\n\n```\nexport MAKEFLAGS=-j$(nproc)\n```\n\nIn that case, make and scripts/build do not need the parameter -j.\n\nFor details on how to use the build script, please run `./scripts/build --help`.\n\nThe `./scripts/build` creates the image `build/last/usr.img` in qcow2 format.\nTo convert this image to other formats, use the `./scripts/convert`\ntool, which can convert an image to the vmdk, vdi or raw formats.\nFor example:\n\n```\n./scripts/convert raw\n```\n\n### Aarch64\n\nBy default, the OSv kernel gets built for the native host architecture (x86_64 or aarch64), but it is also possible\n to cross-compile kernel and modules on Intel machine for ARM by adding **arch** parameter like so:\n```bash\n./scripts/build arch=aarch64\n```\nAt this point cross-compiling the **aarch64** version of OSv is only supported\non Fedora, Ubuntu, and CentOS 7, and relevant aarch64 gcc and libraries' binaries can be downloaded using\nthe `./scripts/download_aarch64_packages.py` script. OSv can also be built natively on Ubuntu on ARM hardware\nlike Raspberry PI 4, Odroid N2+, or RockPro64. \n\nPlease note that as of the latest [0.57.0 release](https://github.com/cloudius-systems/osv/releases/tag/v0.57.0), the ARM part of OSv has been greatly improved and tested and is pretty much on par with the x86_64 port in terms of the functionality.\nIn addition, all unit tests and many  advanced apps like Java, golang, nginx, python, iperf3, etc can successfully run\non QEMU and Firecraker on Raspberry PI 4 and Odroid N2+ with KVM acceleration enabled.\n\nFor more information about the aarch64 port please read [this Wiki page](https://github.com/cloudius-systems/osv/wiki/AArch64).\n\n### Filesystems\n\nAt the end of the boot process, the OSv dynamic linker loads an application ELF and any related libraries\nfrom the filesystem on a disk that is part of the image. By default, the images built by `./scripts/build`\ncontain a disk formatted with the ZFS filesystem, which you can read more about [here](https://github.com/cloudius-systems/osv/wiki/ZFS).\nZFS is a great read-write file system and may be a perfect fit if you want to run MySQL on OSv. However, it may be an overkill\nif you want to run stateless apps in which case you may consider \n[Read-Only FS](https://github.com/cloudius-systems/osv/commit/cd449667b7f86721095ddf4f9f3f8b87c1c414c9). Finally,\nyou can also have OSv read the application binary from RAMFS, in which case the filesystem gets embedded as part of\nthe kernel ELF. You can specify which filesystem to build the image disk with\nby setting the parameter `fs` of `./scripts/build` to one of the three values -`zfs`, `rofs`, or `ramfs`.\n\nIn addition, one can mount NFS filesystem, which had been recently transformed to be a shared library pluggable as a [module](https://github.com/cloudius-systems/osv/tree/master/modules/nfs), and newly implemented and improved [Virtio-FS filesystem](https://stefanha.github.io/virtio/virtio-fs.html#x1-41500011). The Virtio-FS mounts can be set up by adding proper entry `/etc/fstab` or by passing a boot parameter as explained in this [Wiki](https://github.com/cloudius-systems/osv/wiki/virtio-fs). In addition, very recently OSv has been enhanced to be able to boot from Virtio-FS filesystem directly.\n\nMoreover, we have added support for the ext2/3/4 filesystem, in the form of a shared pluggable module [`libext`](https://github.com/cloudius-systems/osv/tree/master/modules/libext). One can add the `libext` module to an image and have OSv mount the ext filesystem from a separate disk like so (for more detailed examples please read [here](https://github.com/cloudius-systems/osv/tree/master/modules/libext#building-image-with-ext4-support)):\n```bash\n./scripts/build fs=rofs image=libext,native-example\n\n./scripts/run.py --execute='--mount-fs=ext,/dev/vblk1,/data /hello' --second-disk-image ./ext4.img\n```\n\nFinally, the ZFS support has been also greatly improved as of the 0.57 release and there are many methods and setups to build and run ZFS images with OSv. For details please read the ZFS section of the [Filesystems wiki](https://github.com/cloudius-systems/osv/wiki/Filesystems#zfs).\n\n## Running OSv\n\nRunning an OSv image, built by `scripts/build`, is as easy as:\n```bash\n./scripts/run.py\n```\n\nBy default, the `run.py` runs OSv under KVM, with 4 vCPUs and 2 GB of memory. \nYou can control these and tens of others ones by passing relevant parameters to \nthe `run.py`. For details, on how to use the script, please run `./scripts/run.py --help`.\n\nThe `run.py` can run an OSv image on QEMU/KVM, Xen, and VMware. If running under KVM you can terminate by hitting Ctrl+A X.\n\nAlternatively, you can use `./scripts/firecracker.py` to run OSv on [Firecracker](https://firecracker-microvm.github.io/). \nThis script automatically downloads firecracker binary if missing, and accepts several parameters like the number of vCPUs, and memory\nnamed exactly like `run.py` does. You can learn more about running OSv on Firecracker \nfrom this [wiki](https://github.com/cloudius-systems/osv/wiki/Running-OSv-on-Firecracker). \n\nPlease note that to run OSv with the best performance on Linux under QEMU or Firecracker you need KVM enabled \n(this is only possible on *physical* Linux machines, EC2 \"bare metal\" (i3) instances, or VMs that support nested virtualization with KVM on). \nThe easiest way to verify if KVM is enabled is to check if `/dev/kvm` is present, and your user account can read from and write to it. \nAdding your user to the kvm group may be necessary like so:\n```bash\nusermod -aG kvm \u003cuser name\u003e\n```\n\nFor more information about building and running JVM, Node.JS, Python, and other managed runtimes as well as Rust, Golang, or C/C++ apps\non OSv, please read this [wiki page](https://github.com/cloudius-systems/osv/wiki#running-your-application-on-osv). \nFor more information about various example apps you can build and run on OSv, please read \n[the osv-apps repo README](https://github.com/cloudius-systems/osv-apps#osv-applications).\n\n### Application Types and Launch Modes\nRegarding how applications are launched on OSv, they all fall into two categories - **dynamically linked** and **statically linked** executables. The dynamically linked executables can be launched by the OSv built-into-kernel dynamic linker or the Linux dynamic linker `ld*.so`. The statically linked executables are bootstrapped but OSv dynamic linker but then interact via system calls with OSv kernel. For more details please watch the 1st half of [this presentation](https://fosdem.org/2024/schedule/event/fosdem-2024-3483-support-dynamically-linked-executables-via-linux-ld-so-and-implement-ena-driver-to-expand-application-of-osv/) or read [slides 2-7](https://fosdem.org/2024/events/attachments/fosdem-2024-3483-support-dynamically-linked-executables-via-linux-ld-so-and-implement-ena-driver-to-expand-application-of-osv/slides/22482/OSv_FOSDEM_24_5NmcHjr.pdf).\n#### Dynamically Linked Executables\nThe dynamically linked executables require the dynamic linker (built-in or Linux one) to bootstrap the main application ELF file, load the libraries it depends on, resolve symbols and eventually call the `main` function.\n##### Via Built-in Dynamic Linker and `libc`\nThe built-in dynamic linker plays the role of the program interpreter that performs similar steps as on Linux, but instead of loading the libraries it depends on from filesystem, it resolves the undefined symbols by pointing them to the implementations of those in OSv built-in `libc`. The OSv linker supports both Shared Libraries and Dynamically Linked Executables that are either position dependent or non-position dependent.\n\n```bash\n./scripts/build image=native-example\n./scripts/run.py -e '/hello'\n```\nThe benefit is that programs interact with the OSv kernel using the **fast local function calls** without the overhead of SYSCALL/SVC instruction. On the negative side, the Linux-compatibility is a moving target because GLIBc keeps adding new functions, and OSv needs to keep implementing them.\n##### Via Linux Dynamic Linker `ld*.so` and `glibc`\nSimilarly to the built-in dynamic linker, OSv can also launch dynamically linked executables via the Linux dynamic linker `ld*.so`. The Linux dynamic linker `ld*.so` is bootstrapped the exact same way as a statically linked executable (see below) and then it orchestrates loading and execution of the specified dynamically linked executables. Just like with statically linked executable, the application interacts with OSv kernel via system calls.\n```bash\ndl=linux ./scripts/manifest_from_host.sh /bin/ls \u0026\u0026 ./scripts/build image=empty --append-manifest\n./scripts/run.py -e '/lib64/ld-linux-x86-64.so.2 /hello'\n```\n#### Statically Linked Executables\nThe statically linked executables interact with OSv kernel by directly making system calls and reading from pseudo filesystems like procfs and sysfs like in Linux. \n\nIn this mode, the Linux-compatibility is should be improved. But compared to the dynamically linked executables that call *local functions*, the statically linked ones suffer from the ~110 ns system call overhead mainly paid to save and restore the state of regular registers and FPU. Having said that, most Linux applications have been written with the understanding that system calls are expensive and avoid them if possible so neither statically linked executables are affected negatively nor the dynamically linked ones launched via built-in dynamic linker benefit in any significant way.\n\nFor more information about OSv implementet syscalls please read this [wiki](https://github.com/cloudius-systems/osv/wiki/Syscalls).\n\n### Networking\n\nBy default, the `run.py`  starts OSv with\n [user networking/SLIRP](https://wiki.qemu.org/Documentation/Networking#User_Networking_.28SLIRP.29) on. \nTo start OSv with more performant external networking, you need to enable `-n` and `-v` options like so:\n\n```\nsudo ./scripts/run.py -nv\n```\n\nThe -v is for KVM's vhost that provides better performance\nand its setup requires tap device thus we use sudo.\n\nAlternatively, one can run OSv as a non-privileged used with a tap device like so:\n```\n./scripts/create_tap_device.sh natted qemu_tap0 172.18.0.1 #You can pick a different address but then update all IPs below\n\n./scripts/run.py -n -t qemu_tap0 \\\n  --execute='--ip=eth0,172.18.0.2,255.255.255.252 --defaultgw=172.18.0.1 --nameserver=172.18.0.1 /hello'\n```\n\nBy default, OSv spawns a `dhcpd`-like thread that automatically configures virtual NICs.\nA static configuration can be done within OSv by configuring networking like so:\n\n```\nifconfig virtio-net0 192.168.122.100 netmask 255.255.255.0 up\nroute add default gw 192.168.122.1\n```\n\nTo enable networking on Firecracker, you have to explicitly enable `-n` option\nto `firecracker.py`.\n\nFinally, please note that the master branch of OSv only implements IPV4 subset of the networking stack.\nIf you need IPV6, please build from [ipv6 branch](https://github.com/cloudius-systems/osv/tree/ipv6)\n or use IPV6 kernel published to [nightly releases repo](https://github.com/osvunikernel/osv-nightly-releases/releases/tag/ci-ipv6-latest). \n\n## Debugging, Monitoring, Profiling OSv\n\n- OSv can be debugged with gdb; for more details please read this\n [wiki](https://github.com/cloudius-systems/osv/wiki/Debugging-OSv)\n- OSv kernel and application can be traced and profiled; for more details please read \nthis [wiki](https://github.com/cloudius-systems/osv/wiki/Trace-analysis-using-trace.py)\n- OSv comes with the admin/monitoring REST API server; for more details please read \n[this](https://github.com/cloudius-systems/osv/wiki/Command-Line-Interface-(CLI)) and\n [that wiki page](https://github.com/cloudius-systems/osv/wiki/Using-OSv-REST-API). There is also\n lighter [monitoring REST API module](https://github.com/cloudius-systems/osv/commit/aa32614221254ce300f401bb99c506b528b85682) \n that is effectively a read-only subset of the former one. \n \n## FAQ and Contact\n\nIf you want to learn more about OSv or ask questions, \nplease contact us on [OSv Google Group forum](https://groups.google.com/forum/#!forum/osv-dev).\nYou can also follow us on [Twitter](https://twitter.com/osv_unikernel).\n\n## Papers and Articles about OSv\n\nList of somewhat newer articles about OSv found on the Web:\n* [P99 Presentation: OSv Unikernel — Optimizing Guest OS to Run Stateless and Serverless Apps in the Cloud](https://www.p99conf.io/session/osv-unikernel-optimizing-guest-os-to-run-stateless-and-serverless-apps-in-the-cloud/)\n* [Unikernels vs Containers: An In-Depth Benchmarking Study in the context of Microservice Applications](https://biblio.ugent.be/publication/8582433/file/8582438)\n* [Towards a Practical Ecosystem of Specialized OS Kernels](http://cs.iit.edu/~khale/docs/diver-ross19.pdf)\n* [A Performance Evaluation of Unikernels](https://pdfs.semanticscholar.org/d956/f72dbc65301578dc95e0f751f4ae7c09d831.pdf)\n* [Security Perspective on Unikernels](https://arxiv.org/pdf/1911.06260.pdf)\n* [Performance Evaluation of OSv for Server Applications](http://www.cs.utah.edu/~peterm/prelim-osv-performance.pdf)\n* [Time provisioning Evaluation of KVM, Docker and Unikernels in a Cloud Platform](https://tiagoferreto.github.io/pubs/2016ccgrid_xavier.pdf)\n* [Unikernels - Beyond Containers to the Next Generation of the Cloud](https://theswissbay.ch/pdf/_to_sort/O'Reilly/unikernels.pdf)\n\n### FOSDEM Presentations\n* [2024 - Support Dynamically Linked Executables via Linux ld.so and Implement ENA Driver to Expand Application of OSv](https://fosdem.org/2024/schedule/event/fosdem-2024-3483-support-dynamically-linked-executables-via-linux-ld-so-and-implement-ena-driver-to-expand-application-of-osv/)\n* [2023 - Evolution of OSv: Towards Greater Modularity and Composability](https://archive.fosdem.org/2023/schedule/event/osvevolution/)\n* [2014 - OSv, a New Operating System Designed for the Cloud](https://archive.fosdem.org/2014/schedule/event/virtiaas99/)\n\nYou can find some older articles and presentations at http://osv.io/resources and http://blog.osv.io/.\n","funding_links":["https://github.com/sponsors/wkozaczuk"],"categories":["C","DevOps","others"],"sub_categories":["Data Management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudius-systems%2Fosv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudius-systems%2Fosv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudius-systems%2Fosv/lists"}