- Description:
- Firecracker with the chroot.dev fixes, branch chroot
- Last Change:
- Clone URL:
ssh://anon@got.v6.chroot.run/firecracker
- ED25519:
SHA256:7587EKj+viWIfWGzPGNqUFSdFEh83CZFaqnwaoNmcNc
Commit Briefs
chore: release v1.8.0 (firecracker-v1.8, tags/v1.8.0)
Update version number / CHANGELOG / CREDITS Signed-off-by: Egor Lazarchuk <yegorlz@amazon.co.uk>
chore: update aws-lc-sys
New version of aws-lc-sys needs faccessat syscall on aarch64, so add it to the seccomp filter. Signed-off-by: Egor Lazarchuk <yegorlz@amazon.co.uk>
Use BTreeMap/Vec instead of HashMap/HashSet when dealing with MSRs
As the previous commit shows, the order of restoration of MSRs can be important. Thus, we should not effectively randomly shuffle them whenever we construct a VM. With this commit, we preserve the order in which KVM tells us about MSRs in `KVM_GET_MSR_INDEX_LIST`, under the assumption that if any dependencies exist, KVM will account for them as part of the above IOCTL. Signed-off-by: Patrick Roy <roypat@amazon.co.uk>
doc: Add CHANGELOG entry
add changelog entry about #4099 Signed-off-by: Patrick Roy <roypat@amazon.co.uk>
fix: Always restore MSR_IA32_TSC_DEADLINE after MSR_IA32_TSC
When restoring MSRs, we currently do not enforce any sort of relative ordering. However, some MSRs have implicit dependencies on other MSRs being restored before them, and failing to fulfill these dependencies can result in incorrect VM behavior after resuming. One example of such an implicit dependency between MSRs is the pair (`MSR_IA32_TSC_DEADLINE`, `MSR_IA32_TSC`). When restoring `MSR_IA32_TSC_DEADLINE`, KVM internally checks whether the value of this restoration implies that the guest was waiting for the tsc_deadline timer to expire at the time of being paused for snapshotting. If yes, it primes a (either harddware or software depending on support) timer on the host to make sure the guest will receive the expected interrupt after restoration. To determine whether this is needed, KVM looks at the guest's timestamp counter (TSC) and compares it with the requested tsc_deadline value. The value KVM reads for the guest's TSC depends on the value of MSR_IA32_TSC. Thus, if MSR_IA32_TSC_DEADLINE is set before MSR_IA32_TSC is restored, this comparison will yield a wrong result (as the deadline value is compared with something uninitialized). This can either result in KVM determining the guest wasn't waiting for a timing expiry at the time of snapshotting, or cause it to schedule the timer interrupt too far into the future. Note that the former is only a problem on AMD platforms, which do not support the TSC_DEADLINE feature at the hardware level. Here, KVM falls back to a software timer, which explicitly does not notify the vCPU if the deadline value is "in the past". The hardware timer used on other x86 platforms on the other hand always fires (potentially firing immediately if the deadline value is in the past). This commit fixes the above by ensuring we always restore MSR_IA32_TSC before restoring MSR_IA32_TSC_DEADLINE. We realize this by splitting the lists of MSRs that KVM gives us into one additional chunk containing all "deferred" MSRs that needs to be restored "as late as possible". This splitting happens at snapshot creation time, to get it off the hot-path. Fixes #4099 Signed-off-by: Patrick Roy <roypat@amazon.co.uk>
fix(cpu-template-helper): exclude TSC_DEADLINE MSR from fingerprints
The TSC_DEADLINE MSR value is volatile is it is getting updated by the guest kernel based on the current TSC value. (cherry picked from commit cee34ab14f42a5ac9c317f3271a8afd2853990e2) Signed-off-by: Nikita Kalyazin <kalyazin@amazon.com>
fix(cpu-template-helper): exclude TSC_DEADLINE MSR from dump
The TSC_DEADLINE MSR value is volatile is it is getting updated by the guest kernel based on the current TSC value. (cherry picked from commit 4402c827d01010cf41e38a78b8caa831e5f4cbeb) Signed-off-by: Nikita Kalyazin <kalyazin@amazon.com>
fix(snapshot/x86_64): make sure TSC_DEADLINE MSR is non-zero
On x86_64, we observed that when restoring from a snapshot, one of the vCPUs had MSR_IA32_TSC_DEADLINE cleared and never received TSC interrupts until the MSR is updated externally (eg by setting the system time). We believe this happens because the TSC interrupt is lost during snapshot taking process: the MSR is cleared, but the interrupt is not delivered to the guest, so the guest does not rearm the timer. A visible effect of that is failure to connect to a restored VM via SSH. This commit introduces a workaround. If when taking a snapshot, we see a zero MSR_IA32_TSC_DEADLINE, we replace its value with the MSR_IA32_TSC value from the same vCPU to make sure that the vCPU will continue to receive TSC interrupts. (cherry picked from commit 94b37cb89b05ec1fd02745d198e1792d0958d1d7) Signed-off-by: Nikita Kalyazin <kalyazin@amazon.com>
chore: update kvm-bindings to 0.8.2
This version contains a performance improvement during deserialization that would negate the performance regression observed when updating to kvm-bindings 0.8.0 in f68a2ef306807fdd298d85133d19eb595731d152. Fixes: f68a2ef306807fdd298d85133d19eb595731d152 Signed-off-by: Patrick Roy <roypat@amazon.co.uk>
build(deps): Bump the firecracker group with 15 updates
Bumps the firecracker group with 15 updates: | Package | From | To | | --- | --- | --- | | [thiserror](https://github.com/dtolnay/thiserror) | `1.0.60` | `1.0.61` | | [itertools](https://github.com/rust-itertools/itertools) | `0.12.1` | `0.13.0` | | [proc-macro2](https://github.com/dtolnay/proc-macro2) | `1.0.82` | `1.0.83` | | [syn](https://github.com/dtolnay/syn) | `2.0.63` | `2.0.65` | | [libc](https://github.com/rust-lang/libc) | `0.2.154` | `0.2.155` | | [serde](https://github.com/serde-rs/serde) | `1.0.201` | `1.0.202` | | [serde_derive](https://github.com/serde-rs/serde) | `1.0.201` | `1.0.202` | | [cc](https://github.com/rust-lang/cc-rs) | `1.0.97` | `1.0.98` | | [either](https://github.com/rayon-rs/either) | `1.11.0` | `1.12.0` | | [linux-raw-sys](https://github.com/sunfishcode/linux-raw-sys) | `0.4.13` | `0.4.14` | | [serde_spanned](https://github.com/toml-rs/toml) | `0.6.5` | `0.6.6` | | [thiserror-impl](https://github.com/dtolnay/thiserror) | `1.0.60` | `1.0.61` | | [toml](https://github.com/toml-rs/toml) | `0.8.12` | `0.8.13` | | [toml_datetime](https://github.com/toml-rs/toml) | `0.6.5` | `0.6.6` | | [toml_edit](https://github.com/toml-rs/toml) | `0.22.12` | `0.22.13` | Updates `thiserror` from 1.0.60 to 1.0.61 - [Release notes](https://github.com/dtolnay/thiserror/releases) - [Commits](https://github.com/dtolnay/thiserror/compare/1.0.60...1.0.61) Updates `itertools` from 0.12.1 to 0.13.0 - [Changelog](https://github.com/rust-itertools/itertools/blob/master/CHANGELOG.md) - [Commits](https://github.com/rust-itertools/itertools/compare/v0.12.1...v0.13.0) Updates `proc-macro2` from 1.0.82 to 1.0.83 - [Release notes](https://github.com/dtolnay/proc-macro2/releases) - [Commits](https://github.com/dtolnay/proc-macro2/compare/1.0.82...1.0.83) Updates `syn` from 2.0.63 to 2.0.65 - [Release notes](https://github.com/dtolnay/syn/releases) - [Commits](https://github.com/dtolnay/syn/compare/2.0.63...2.0.65) Updates `libc` from 0.2.154 to 0.2.155 - [Release notes](https://github.com/rust-lang/libc/releases) - [Commits](https://github.com/rust-lang/libc/compare/0.2.154...0.2.155) Updates `serde` from 1.0.201 to 1.0.202 - [Release notes](https://github.com/serde-rs/serde/releases) - [Commits](https://github.com/serde-rs/serde/compare/v1.0.201...v1.0.202) Updates `serde_derive` from 1.0.201 to 1.0.202 - [Release notes](https://github.com/serde-rs/serde/releases) - [Commits](https://github.com/serde-rs/serde/compare/v1.0.201...v1.0.202) Updates `cc` from 1.0.97 to 1.0.98 - [Release notes](https://github.com/rust-lang/cc-rs/releases) - [Commits](https://github.com/rust-lang/cc-rs/compare/1.0.97...1.0.98) Updates `either` from 1.11.0 to 1.12.0 - [Commits](https://github.com/rayon-rs/either/compare/1.11.0...1.12.0) Updates `linux-raw-sys` from 0.4.13 to 0.4.14 - [Commits](https://github.com/sunfishcode/linux-raw-sys/compare/v0.4.13...v0.4.14) Updates `serde_spanned` from 0.6.5 to 0.6.6 - [Commits](https://github.com/toml-rs/toml/compare/serde_spanned-v0.6.5...serde_spanned-v0.6.6) Updates `thiserror-impl` from 1.0.60 to 1.0.61 - [Release notes](https://github.com/dtolnay/thiserror/releases) - [Commits](https://github.com/dtolnay/thiserror/compare/1.0.60...1.0.61) Updates `toml` from 0.8.12 to 0.8.13 - [Commits](https://github.com/toml-rs/toml/compare/toml-v0.8.12...toml-v0.8.13) Updates `toml_datetime` from 0.6.5 to 0.6.6 - [Commits](https://github.com/toml-rs/toml/compare/toml_datetime-v0.6.5...toml_datetime-v0.6.6) Updates `toml_edit` from 0.22.12 to 0.22.13 - [Commits](https://github.com/toml-rs/toml/compare/v0.22.12...v0.22.13) --- updated-dependencies: - dependency-name: thiserror dependency-type: direct:production update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: itertools dependency-type: direct:production update-type: version-update:semver-minor dependency-group: firecracker - dependency-name: proc-macro2 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: syn dependency-type: direct:production update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: libc dependency-type: direct:production update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: serde dependency-type: direct:production update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: serde_derive dependency-type: direct:production update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: cc dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: either dependency-type: indirect update-type: version-update:semver-minor dependency-group: firecracker - dependency-name: linux-raw-sys dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: serde_spanned dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: thiserror-impl dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: toml dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: toml_datetime dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker - dependency-name: toml_edit dependency-type: indirect update-type: version-update:semver-patch dependency-group: firecracker ... Signed-off-by: dependabot[bot] <support@github.com>
Branches
Tree
README.md
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/fc_logo_full_transparent-bg_white-fg.png">
<source media="(prefers-color-scheme: light)" srcset="docs/images/fc_logo_full_transparent-bg.png">
<img alt="Firecracker Logo Title" width="750" src="docs/images/fc_logo_full_transparent-bg.png">
</picture>
Our mission is to enable secure, multi-tenant, minimal-overhead execution of
container and function workloads.
Read more about the Firecracker Charter [here](CHARTER.md).
## What is Firecracker?
Firecracker is an open source virtualization technology that is purpose-built
for creating and managing secure, multi-tenant container and function-based
services that provide serverless operational models. Firecracker runs workloads
in lightweight virtual machines, called microVMs, which combine the security and
isolation properties provided by hardware virtualization technology with the
speed and flexibility of containers.
## Overview
The main component of Firecracker is a virtual machine monitor (VMM) that uses
the Linux Kernel Virtual Machine (KVM) to create and run microVMs. Firecracker
has a minimalist design. It excludes unnecessary devices and guest-facing
functionality to reduce the memory footprint and attack surface area of each
microVM. This improves security, decreases the startup time, and increases
hardware utilization. Firecracker has also been integrated in container
runtimes, for example
[Kata Containers](https://github.com/kata-containers/documentation/wiki/Initial-release-of-Kata-Containers-with-Firecracker-support)
and [Weaveworks Ignite](https://github.com/weaveworks/ignite).
Firecracker was developed at Amazon Web Services to accelerate the speed and
efficiency of services like [AWS Lambda](https://aws.amazon.com/lambda/) and
[AWS Fargate](https://aws.amazon.com/fargate/). Firecracker is open sourced
under [Apache version 2.0](LICENSE).
To read more about Firecracker, check out
[firecracker-microvm.io](https://firecracker-microvm.github.io).
## Getting Started
To get started with Firecracker, download the latest
[release](https://github.com/firecracker-microvm/firecracker/releases) binaries
or build it from source.
You can build Firecracker on any Unix/Linux system that has Docker running (we
use a development container) and `bash` installed, as follows:
```bash
git clone https://github.com/firecracker-microvm/firecracker
cd firecracker
tools/devtool build
toolchain="$(uname -m)-unknown-linux-musl"
```
The Firecracker binary will be placed at
`build/cargo_target/${toolchain}/debug/firecracker`. For more information on
building, testing, and running Firecracker, go to the
[quickstart guide](docs/getting-started.md).
The overall security of Firecracker microVMs, including the ability to meet the
criteria for safe multi-tenant computing, depends on a well configured Linux
host operating system. A configuration that we believe meets this bar is
included in [the production host setup document](docs/prod-host-setup.md).
## Contributing
Firecracker is already running production workloads within AWS, but it's still
Day 1 on the journey guided by our [mission](CHARTER.md). There's a lot more to
build and we welcome all contributions.
To contribute to Firecracker, check out the development setup section in the
[getting started guide](docs/getting-started.md) and then the Firecracker
[contribution guidelines](CONTRIBUTING.md).
## Releases
New Firecracker versions are released via the GitHub repository
[releases](https://github.com/firecracker-microvm/firecracker/releases) page,
typically every two or three months. A history of changes is recorded in our
[changelog](CHANGELOG.md).
The Firecracker release policy is detailed [here](docs/RELEASE_POLICY.md).
## Design
Firecracker's overall architecture is described in
[the design document](docs/design.md).
## Features & Capabilities
Firecracker consists of a single micro Virtual Machine Manager process that
exposes an API endpoint to the host once started. The API is
[specified in OpenAPI format](src/firecracker/swagger/firecracker.yaml). Read
more about it in the [API docs](docs/api_requests).
The **API endpoint** can be used to:
- Configure the microvm by:
- Setting the number of vCPUs (the default is 1).
- Setting the memory size (the default is 128 MiB).
- Configuring a [CPU template](docs/cpu_templates/cpu-templates.md).
- Add one or more network interfaces to the microVM.
- Add one or more read-write or read-only disks to the microVM, each represented
by a file-backed block device.
- Trigger a block device re-scan while the guest is running. This enables the
guest OS to pick up size changes to the block device's backing file.
- Change the backing file for a block device, before or after the guest boots.
- Configure rate limiters for virtio devices which can limit the bandwidth,
operations per second, or both.
- Configure the logging and metric system.
- `[BETA]` Configure the data tree of the guest-facing metadata service. The
service is only available to the guest if this resource is configured.
- Add a [vsock socket](docs/vsock.md) to the microVM.
- Add a [entropy device](docs/entropy.md) to the microVM.
- Start the microVM using a given kernel image, root file system, and boot
arguments.
- \[x86_64 only\] Stop the microVM.
**Built-in Capabilities**:
- Demand fault paging and CPU oversubscription enabled by default.
- Advanced, thread-specific seccomp filters for enhanced security.
- [Jailer](docs/jailer.md) process for starting Firecracker in production
scenarios; applies a cgroup/namespace isolation barrier and then drops
privileges.
## Tested platforms
We test all combinations of:
| Instance | Host OS & Kernel | Guest Rootfs | Guest Kernel |
| :-------- | :---------------- | :----------- | :----------- |
| c5n.metal | al2 linux_4.14 | ubuntu 22.04 | linux_4.14 |
| m5n.metal | al2 linux_5.10 | | linux_5.10 |
| m6i.metal | al2023 linux_6.1 | | |
| m6a.metal | | | |
| m6g.metal | | | |
| m7g.metal | | | |
## Known issues and Limitations
- The `pl031` RTC device on aarch64 does not support interrupts, so guest
programs which use an RTC alarm (e.g. `hwclock`) will not work.
## Performance
Firecracker's performance characteristics are listed as part of the
[specification documentation](SPECIFICATION.md). All specifications are a part
of our commitment to supporting container and function workloads in serverless
operational models, and are therefore enforced via continuous integration
testing.
## Policy for Security Disclosures
The security of Firecracker is our top priority. If you suspect you have
uncovered a vulnerability, contact us privately, as outlined in our
[security policy document](SECURITY.md); we will immediately prioritize your
disclosure.
## FAQ & Contact
Frequently asked questions are collected in our [FAQ doc](FAQ.md).
You can get in touch with the Firecracker community in the following ways:
- Security-related issues, see our [security policy document](SECURITY.md).
- Chat with us on our
[Slack workspace](https://join.slack.com/t/firecracker-microvm/shared_invite/zt-1zlb87h4z-NED1rBhVqOQ1ygBgT76wlg)
_Note: most of the maintainers are on a European time zone._
- Open a GitHub issue in this repository.
- Email the maintainers at
[firecracker-maintainers@amazon.com](mailto:firecracker-maintainers@amazon.com).
When communicating within the Firecracker community, please mind our
[code of conduct](CODE_OF_CONDUCT.md).