- 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
fix(virtio-mem): interval intersection in slots_intersecting_range (virtio-mem-fix)
The previous implementation checked whether either slot endpoint fell inside the requested range. This missed the containment case where a slot fully contains the range (neither endpoint inside it), causing update_kvm_slots to silently skip KVM slot registration/removal for any block not aligned to a slot boundary. Replace the two addr_in_range endpoint checks with a proper half-open interval intersection test: slot_start < range_end && range_start < slot_end. Remove the now-unused addr_in_range helper and add a table-driven unit test covering boundary, interior, cross-slot, full-region, outside, and zero-length ranges. Signed-off-by: Nikita Kalyazin <kalyazin@amazon.com>
fix(test): cleanup vm for process start
We are generating multiple vms in a loop however the factory holds onto a reference to these so are not killed as they go out of scope. Explicitly kill the vm after each loop. Signed-off-by: Jack Thomson <jackabt@amazon.com>
fix(test): cleanup vm on pmem
We are generating multiple vms in a loop however the factory holds onto a reference to these so are not killed as they go out of scope. Explicitly kill the vm after each loop. Signed-off-by: Jack Thomson <jackabt@amazon.com>
fix(tests): cleanup uvm in hotplug tests
With the previous loop the uvm's were not being killed creating pressure for the host the number of uvms actively running. The timing of hot(un)plug operations gradually increased with each iteration as more pressure was created. Signed-off-by: Jack Thomson <jackabt@amazon.com>
vmm: bus: Ensure BusRange never stores an invalid range
There's currently no check when creating a BusRange object that the range is valid. Add a new() method that makes sure that the base + len arguments don't overflow and that length is non-zero. To make things simpler and avoid potential overflows in the future store the end address in BusRange, rather than a length to avoid extra checks for when base+len is exactly (1<<64). Finally, make the base and end fields private so that new BusRange objects can only be created via the constructor (and hence are always valid) and add a test case for verifying valid ranges. Similarly, make BusRange::overlaps() take a BusRange rather than a base and len. BurRange::overlaps() had the potential of overflowing without this change, however that wouldn't happen in practice because the resource allocator generates valid ranges. Signed-off-by: Ilias Stamatis <ilstam@amazon.com>
fix(aarch64): override fabricated CLIDR_EL1 to match host cache topology
Since host kernel 6.3 (commit 7af0c2534f4c), KVM fabricates CLIDR_EL1 instead of passing through the host's real value. On hosts with IDC=1 and DIC=0 (e.g. Neoverse V1), the fabricated CLIDR exposes only L1=Unified when the host actually has separate L1d+L1i, L2, and L3. Guest kernels >= 6.1.156 backported init_of_cache_level() which counts cache leaves from the DT, while populate_cache_leaves() uses CLIDR_EL1. When the DT (built from host sysfs) describes more cache entries than CLIDR_EL1, the mismatch causes cache sysfs entries to not be created, breaking /sys/devices/system/cpu/cpu*/cache/* in the guest. Fix this by reading the current CLIDR_EL1 from vCPU 0, merging in the ctype and LoC fields derived from the host's sysfs cache topology, and writing the result back to each vCPU via KVM_SET_ONE_REG. Fields that cannot be derived from sysfs (LoUU, LoUIS, ICB, Ttype) are preserved from the original CLIDR_EL1. This makes CLIDR_EL1 consistent with the FDT, which already describes the real host caches. On pre-6.3 kernels, KVM passes through the real host CLIDR rather than fabricating one. Since the sysfs cache topology already matches the real CLIDR, the merge produces the same value, the write is skipped, and the override is effectively a no-op. This approach preserves the full host cache information for the guest rather than stripping the FDT to match the fabricated CLIDR. Signed-off-by: Nikita Kalyazin <kalyazin@amazon.com>
chore: Update aws-lc-rs 1.16.2
A vulnerability was found in aws-lc-sys [1]. Although Firecracker isn't affected as it doesn't use AWS-LC to validate CN, update aws-lc-rs (and aws-lc-sys indirectly) to suppress cargo-audit failure. [1]: https://rustsec.org/advisories/RUSTSEC-2026-0044.html Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
test(sysgenid): Add integration tests for SysGenID
Although Firecracker doesn't do anything for SysGenID, it is used for the snapsafety issue by guest userspace in Amazon Linux-provided microVM kernels [1][2]. Let's test them to detect functional regression that might be introduced in microVM kernels. [1]: https://github.com/amazonlinux/linux/blob/microvm-kernel-5.10.245-268.975.amzn2/drivers/misc/sysgenid.c [2]: https://github.com/amazonlinux/linux/blob/microvm-kernel-6.1.164-23.303.amzn2023/drivers/misc/sysgenid.c Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
fix(vmgenid): Align HID with upstream
Currently, Firecracker sets "FCVMGID" as HID (Hardware ID) and "VM_Gen_Counter" as CID (Compatbile ID). Linux kernel [1] specifies "VMGENCTR" and "VM_GEN_COUNTER" as ACPI IDs to bind the driver to the VMGenID device. If the VMGenID driver is implemented as platform driver, Linux kernel checks whether either HID or CID matches the ACPI IDs. On the other hand, if implemented as ACPI driver, only HID is checked for the match. Linux kernel 6.10 [2] re-implemented it from ACPI driver to platform driver in order to support devcie tree. As a result, prior to Linux kernel 6.10, the driver isn't bound correctly. We didn't see any issue due to HID mismatch, because we backported the above kernel patches to our 6.1 guest kernel [3]. VMGenID itself is only supported since upstream Linux kernel 5.18+ [4] and we don't test VMGenID on our 5.10 guest kernel. Note that Amazon Linux-provided microVM kernel 5.10 [5][6] actually implements VMGenID driver but it is a downstream implementation. It is never used by customers (instead SysGenID is used) and it specifies yet another set of ACPI IDs ("VMGENID" and "QEMUVMGID"). So, more precisely, that is why we don't test VMGenID on our 5.10 guest kernel. [1]: https://elixir.bootlin.com/linux/v6.19.7/source/drivers/virt/vmgenid.c#L162-L163 [2]: https://github.com/torvalds/linux/commit/e07606713a908eee8099883c8c830ebe33aaf748 [3]: https://github.com/firecracker-microvm/firecracker/blob/81236d82b1640cfa41f825f50be5585c758e165b/docs/snapshotting/random-for-clones.md?plain=1#L132-L139 [4]: https://github.com/torvalds/linux/commit/af6b54e2b5baa54c844573b6d49cc91157bcdd7e [5]: https://github.com/amazonlinux/linux/blob/microvm-kernel-5.10.245-268.975.amzn2/drivers/virt/vmgenid.c#L121-L122 [6]: https://github.com/amazonlinux/linux/commit/c9b81dca31075bcbda92929e7dba9a500187d0ea Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
chore(docs): update release_policy
Update the release policy to reference the newest 1.14.3 patch release Signed-off-by: Jack Thomson <jackabt@amazon.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/kata-containers) and
[Flintlock](https://github.com/liquidmetal-dev/flintlock).
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.
- Add a [pmem device](docs/pmem.md) to the microVM.
- Configure and manage [memory hotplugging](docs/memory-hotplug.md).
- 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 |
| :------------------------------------------ | :--------------- | :----------- | :----------- |
| m5n.metal (Intel Cascade Lake) | al2 linux_5.10 | ubuntu 24.04 | linux_5.10 |
| m6i.metal (Intel Ice Lake) | al2023 linux_6.1 | | linux_6.1 |
| m7i.metal-24xl (Intel Sapphire Rapids) | | | |
| m7i.metal-48xl (Intel Sapphire Rapids) | | | |
| **m8i.metal-48xl (Intel Granite Rapids)\*** | | | |
| **m8i.metal-96xl (Intel Granite Rapids)\*** | | | |
| m6a.metal (AMD Milan) | | | |
| m7a.metal-48xl (AMD Genoa) | | | |
| m6g.metal (Graviton 2) | | | |
| m7g.metal (Graviton 3) | | | |
| m8g.metal-24xl (Graviton 4) | | | |
| m8g.metal-48xl (Graviton 4) | | | |
**\***: We **only** support AWS EC2 8th Gen Intel (\*8i) instances using a 6.1
host kernel. This is due to poor kernel support for Granite Rapids CPUs on 5.10.
## 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-2tc0mfxpc-tU~HYAYSzLDl5XGGJU3YIg)
_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).