- 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
test(api): run test_send_ctrl_alt_del on aarch64 (main)
Update the API test now that SendCtrlAltDel is accepted on aarch64 and the CI guest kernels have been rebuilt with the gpio-keys config. The aarch64 press is consumed by systemd-logind, which only works on the AL23 rootfs shipped with the 6.1 kernels and needs a `rw` rootfs to trigger the reboot, so those two dimensions are pinned on aarch64 only; x86_64 goes through the i8042 device and keeps its full guest kernel and rootfs coverage. For the same reason the `kernel` mode, which shortcuts through /proc/sys/kernel/ctrl-alt-del, stays x86_64 only: aarch64 delivers the press as a KEY_POWER input event that the sysctl does not act on. Also add a regression test for issuing the action while the microVM is paused: the guest cannot observe the request until its vCPUs run again, so it has to stay pending across the pause instead of being delivered into a stopped guest and dropped. Kept as a separate commit so it can be easily dropped or updated. Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Assisted-by: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
docs(changelog): add entry for aarch64 SendCtrlAltDel
Record under Added that SendCtrlAltDel is now supported on aarch64, where it presses a virtual power button on a PL061 GPIO controller exposed to the guest as gpio-keys. Snapshot version 12.0.0 shipped in v1.17.0, so persisting the new PL061 register state needs a bump to 13.0.0. The entry mentions it because it is a user-visible compatibility change. Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
docs: document aarch64 SendCtrlAltDel graceful shutdown
Describe the aarch64 behaviour of the SendCtrlAltDel action (a virtual power button via the PL061 gpio-keys device) in the actions and device-api docs, including that the press is held until the guest observes it and so survives a paused microVM and a snapshot. Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
feat(aarch64): support external graceful shutdown via SendCtrlAltDel
Until now `SendCtrlAltDel` was rejected with a 400 on aarch64 and there was no way to request a graceful shutdown of a microVM from the host. Fixes #2046. Attach the PL061 GPIO controller as an aarch64 MMIO platform device and describe a `gpio-keys` power button (KEY_POWER) in the FDT. `SendCtrlAltDel` is reused: on x86_64 it still injects CTRL+ALT+DEL through the i8042 device; on aarch64 it presses the virtual power button. A guest with the standard gpio-keys driver and a power-key consumer (e.g. systemd-logind, which defaults to HandlePowerKey=poweroff) then shuts down cleanly and Firecracker exits on the resulting KVM_SYSTEM_EVENT_SHUTDOWN. Details: - The press is latched by the device until the guest reads the line back, so the action returns immediately and a press issued while the microVM is `Paused` is delivered once it is resumed. This matches the x86_64 path, where the keystroke stays queued in the i8042 until the guest consumes it. - The PL061 register state, including a still-pending press, is saved and restored as part of the MMIO platform device state, so the power button keeps working on a restored microVM. Restoring replays the GSI reservation, so the legacy IRQ the device used cannot be handed out to another device. The added state changes the snapshot format, so the snapshot version goes from 12.0.0 to 13.0.0. - The gpio-keys kernel symbols are added to the shared CI kernel config so the guest can advertise the power key. - The controller is always attached, and takes one legacy GSI of its own, so the number of GSIs left for VirtIO devices drops by one: the aarch64 maximum goes from 92 to 91 devices. Assisted-by: Copilot <223556219+Copilot@users.noreply.github.com> Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
feat(aarch64): add PL061 GPIO controller device
Add a minimal PL061 GPIO controller modelled as an aarch64 MMIO device. It implements the core register bank (data with the address-masked aperture, direction, the interrupt sense, both-edges, event, mask, status and clear registers, and the PrimeCell identification registers) plus host-side input injection so higher layers can drive a virtual GPIO line. The interrupt line is modelled as edge-triggered to match Firecracker's plain KVM irqfd injection (no resample fd): a level-high line would never be de-asserted and the GIC would re-fire it after the guest EOIs, storming the host. Two behaviours are worth calling out: - A host-injected press is held until the guest reads the line back through the data aperture, at which point the device releases it and latches the falling edge. A press can therefore not be missed by a guest that is not currently running. - The level-sensitive part of GPIORIS tracks the line rather than being latched, so it clears once the level goes inactive and re-asserts after a GPIOIC write while the level is still active, as the TRM specifies. Arming GPIOIS/GPIOIBE/GPIOIEV re-evaluates the line instead of waiting for the next level change. The register state is serializable so it can be carried across snapshots, and a device rebuilt from a saved state re-raises any interrupt the guest had not acknowledged yet, since the restored device gets a fresh eventfd. Assisted-by: Copilot <223556219+Copilot@users.noreply.github.com> Assisted-by: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: 14sea <wanhuaning@gmail.com>
cpu template: update fingerprint for m9g on 5.10
Update to the AMI changed a couple of bits in PMCR_EL0::N register. Signed-off-by: Egor Lazarchuk <yegorlz@amazon.co.uk>
vcpu: Complete pending I/O before honoring immediate_exit
Firecracker can acknowledge a pause after handling an MMIO or PIO exit without completing the guest instruction. Commit 32cfc5e8db93 ("skipped unnecessary kvm_immediate_exits") added a userspace immediate_exit shortcut that skips KVM_RUN, but KVM requires re-entry to finish I/O. Snapshots can then omit the pending RAM write or register update because KVM does not expose the unfinished operation in saved vCPU state. Always issue KVM_RUN and let KVM complete pending I/O before returning EINTR for immediate_exit, without executing further guest instructions. Keep the existing EINTR flag clearing so the vCPU can resume normally. The test runs a guest that loads a byte from an MMIO address into a register, on both x86_64 and aarch64. After handling the MMIO exit, it sets immediate_exit and calls KVM_RUN again. It checks that the register holds the MMIO response, but the following guest instruction has not executed. A final KVM_RUN checks that this instruction executes after the flag has been cleared. Fixes: 32cfc5e8db93 ("skipped unnecessary kvm_immediate_exits") Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>
docs(changelog): Note guest memory discard changes
Record that balloon and virtio-mem discards now free shared memfd backing, and that on hugetlbfs they free whole huge pages and zero partial ones, which can increase host memory use with the traditional balloon. Signed-off-by: Jay Chung <jaehoc@amazon.com>
docs: Describe memfd and huge page discard
Describe discard for anonymous, shared memfd and private snapshot memory, and present vhost-user block as an example of shared memfd backing. State that discarded ranges read as zero. For hugetlbfs, warn against the traditional balloon. Only the whole huge pages inside a range are freed and the partial ones are zeroed, so traditional inflation frees no hugetlbfs memory. It can also increase host memory use, because the guest can inflate pages it never touched. Recommend free page hinting or reporting instead, also in the balloon caveats, and state that reporting needs the guest to report ranges of at least 2 MiB, also in the reporting section. Preserve the explanation of RSS reduction for reporting and hinting, and note that hugetlbfs memory is accounted separately. In the hugepages doc, explain why the traditional balloon cannot free hugetlbfs memory and how inflation can increase host memory use, and note that freeing anonymous hugetlbfs memory needs a 5.18 or later host, since 5.10 rejects MADV_DONTNEED on hugetlbfs. Tell page fault handler authors that zeroed partial huge pages send no UFFD_EVENT_REMOVE and can arrive as page faults, and mention MADV_REMOVE for unplugged memfd memory in the memory hotplug doc. Signed-off-by: Jay Chung <jaehoc@amazon.com>
test: Measure memfd backing in resident memory
RSS counts the pages mapped into the process, not the pages a memfd holds. MADV_DONTNEED on a memfd mapping lowers RSS while the memfd keeps its pages, so an RSS check cannot tell whether memfd-backed guest memory was freed. When Firecracker holds a guest memory memfd, make get_resident_memory count its private RSS plus the blocks allocated to the memfd. Run test_size_reduction on memfd-backed guest memory as well, through a vhost-user root drive. Its huge page variants do not need hugetlb MADV_DONTNEED support on the host, because discarding shared memfd memory uses MADV_REMOVE. Signed-off-by: Jay Chung <jaehoc@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).
- `[Developer Preview]` [Hot-plug and hot-unplug](docs/device-hotplug.md) virtio
PCI devices while the VM is running.
- 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 |
| | al2023 linux_6.18 | | |
| 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) | | | |
| m9g.metal-48xl (Graviton 5) | | | |
**\***: We **only** support AWS EC2 8th Gen Intel (\*8i) instances using a 6.1
or 6.18 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-3v81btcpe-usCf8Qk7k1gUlSAEKKdYMg)
_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).