diff --git a/FAQ.md b/FAQ.md index 3ace710fc96..9456471df8c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -178,22 +178,6 @@ them according to your needs. The relatively high FD usage is expected and correct. Firecracker heavily relies on event file descriptors to drive device emulation. -### How does network interface numbering work? - -There is no relation between the numbering of the `/network-interface` API calls -and the number of the network interface in the guest. Rather, it is usually the -order of network interface creation that determines the number in the guest (but -this depends on the distribution). - -For example, when you create two network interfaces by calling -`/network-interfaces/1` and then `/network-interfaces/0`, it may result in this -mapping: - -```console -/network-interfaces/1 -> eth0 -/network-interfaces/0 -> eth1 -``` - ### How can I gracefully reboot the guest? How can I gracefully poweroff the guest? Firecracker does not virtualize guest power management, therefore operations diff --git a/docs/api_requests/actions.md b/docs/api_requests/actions.md index 40700c359de..c11f152e651 100644 --- a/docs/api_requests/actions.md +++ b/docs/api_requests/actions.md @@ -44,15 +44,15 @@ i8042 controller. Driver support for both these devices needs to be present in the guest OS. For Linux, that means the guest kernel needs `CONFIG_SERIO_I8042` and `CONFIG_KEYBOARD_ATKBD`. -**Note1**: at boot time, the Linux driver for i8042 spends a few tens of -milliseconds probing the device. This can be disabled by using these kernel -command line parameters: - -```console -i8042.noaux i8042.nomux i8042.nopnp i8042.dumbkbd -``` - -**Note2** This action is only supported on `x86_64` architecture. +> [!NOTE] +> +> At boot time, the Linux driver for i8042 spends a few tens of milliseconds +> probing the device. This can be disabled by using these kernel command line +> parameters: +> +> ```console +> i8042.noaux i8042.nomux i8042.nopnp i8042.dumbkbd +> ``` ### SendCtrlAltDel Example diff --git a/docs/api_requests/block-io-engine.md b/docs/api_requests/block-io-engine.md index 733aa374acd..27a73b72759 100644 --- a/docs/api_requests/block-io-engine.md +++ b/docs/api_requests/block-io-engine.md @@ -25,8 +25,10 @@ with the `io_engine` field taking two possible values: The `Sync` variant is the default, in order to provide backwards compatibility with older Firecracker versions. -**Note** [vhost-user block device](./block-vhost-user.md) is another option for -block IO that requires an external backend process. +> [!NOTE] +> +> [vhost-user block device](./block-vhost-user.md) is another option for block +> IO that requires an external backend process. ## Example configuration diff --git a/docs/api_requests/block-vhost-user.md b/docs/api_requests/block-vhost-user.md index 4a3a4dee918..04761705ac0 100644 --- a/docs/api_requests/block-vhost-user.md +++ b/docs/api_requests/block-vhost-user.md @@ -154,9 +154,11 @@ potential for the guest to exercise issues in the backend codebase to trigger undesired behaviours. Users should consider running their backend in a jailer or applying other adequate security measures to restrict it. -**Note** [Firecracker jailer](../jailer.md) is currently only capable of running -Firecracker as the binary. Vhost-user block device users are expected to use -another jailer to run the backend. +> [!NOTE] +> +> [Firecracker jailer](../jailer.md) is currently only capable of running +> Firecracker as the binary. Vhost-user block device users are expected to use +> another jailer to run the backend. It is also recommended to use proactive security measures like running a Virtio-level fuzzer in the guest during testing to make sure that the backend @@ -221,12 +223,16 @@ curl --unix-socket ${fc_socket} -i \ }" ``` -**Note** Unlike Virtio block device, there is no way to configure a `readonly` -vhost-user drive on the Firecracker side. Instead, this configuration belongs to -the backend. Whenever the backend advertises the `VIRTIO_BLK_F_RO` feature, -Firecracker will accept it, and the device will act as readonly. +> [!NOTE] +> +> Unlike Virtio block device, there is no way to configure a `readonly` +> vhost-user drive on the Firecracker side. Instead, this configuration belongs +> to the backend. Whenever the backend advertises the `VIRTIO_BLK_F_RO` feature, +> Firecracker will accept it, and the device will act as readonly. -**Note** Whenever a `PUT` request is sent to the `/drives` endpoint for a -vhost-user device with the `id` that already exists, Firecracker will close the -existing connection to the backend and will open a new one. Users may need to -restart their backend if they do so. +> [!NOTE] +> +> Whenever a `PUT` request is sent to the `/drives` endpoint for a vhost-user +> device with the `id` that already exists, Firecracker will close the existing +> connection to the backend and will open a new one. Users may need to restart +> their backend if they do so. diff --git a/docs/api_requests/patch-network-interface.md b/docs/api_requests/patch-network-interface.md index 59d16c62ab5..5e5796e479e 100644 --- a/docs/api_requests/patch-network-interface.md +++ b/docs/api_requests/patch-network-interface.md @@ -58,9 +58,11 @@ Accept: application/json The full specification of the data structures available for this call can be found in our [OpenAPI spec](../../src/firecracker/swagger/firecracker.yaml). -**Note**: The data provided for the update is merged with the existing data. In -the above example, the RX rate limit is updated, but the TX rate limit remains -unchanged. +> [!NOTE] +> +> The data provided for the update is merged with the existing data. In the +> above example, the RX rate limit is updated, but the TX rate limit remains +> unchanged. ## Removing Rate Limiting diff --git a/docs/cpu_templates/cpu-template-helper.md b/docs/cpu_templates/cpu-template-helper.md index 7003ef11090..13898be9d6c 100644 --- a/docs/cpu_templates/cpu-template-helper.md +++ b/docs/cpu_templates/cpu-template-helper.md @@ -38,14 +38,17 @@ process as Firecacker and capturing them in the state just before booting a guest. More details about the preboot process can be found [here](boot-protocol.md) and [here](cpuid-normalization.md). -> **Note** Some MSRs and ARM registers are not included in the output, since -> they are not reasonable to modify with CPU templates. The full list of them -> can be found in [Appendix](#appendix). - -> **Note** Since the output depends on underlying hardware and software stack -> (BIOS, CPU, kernel, Firecracker), it is required to dump guest CPU -> configuration on each combination when creating a custom CPU template -> targetting them all. +> [!NOTE] +> +> Some MSRs and ARM registers are not included in the output, since they are not +> reasonable to modify with CPU templates. The full list of them can be found in +> [Appendix](#appendix). + +> [!NOTE] +> +> Since the output depends on underlying hardware and software stack (BIOS, CPU, +> kernel, Firecracker), it is required to dump guest CPU configuration on each +> combination when creating a custom CPU template targeting them all. #### Strip command @@ -85,9 +88,11 @@ When a template is specified both through `--template` and in Firecracker configuration file provided via `--config`, the template specified with `--template` takes precedence. -> **Note** This command does not ensure that the contents of the template are -> sensible. Thus, users need to make sure that the template does not have any -> inconsistent entries and does not crash guests. +> [!NOTE] +> +> This command does not ensure that the contents of the template are sensible. +> Thus, users need to make sure that the template does not have any inconsistent +> entries and does not crash guests. ### Fingerprint-related commands @@ -177,9 +182,11 @@ CPU features to a heterogeneous fleet consisting of multiple CPU models. revisions to the CPU template, and replace the fingerprint file with the new one. -> **Note** It is recommended to review the update process of the underlying -> stack on your infrastructure. This can help identify points that may require -> the above validation check. +> [!NOTE] +> +> It is recommended to review the update process of the underlying stack on your +> infrastructure. This can help identify points that may require the above +> validation check. ## Appendix diff --git a/docs/cpu_templates/cpu-templates.md b/docs/cpu_templates/cpu-templates.md index 920267940b8..e62b2ad1e94 100644 --- a/docs/cpu_templates/cpu-templates.md +++ b/docs/cpu_templates/cpu-templates.md @@ -16,13 +16,17 @@ guest. A real world use case for this is representing a heterogeneous fleet (a fleet consisting of multiple CPU models) as a homogeneous fleet, so the guests will experience a consistent feature set supported by the host. -> **Note** Representing one CPU vendor as another CPU vendor is not supported. - -> **Note** CPU templates shall not be used as a security protection against -> malicious guests. Disabling a feature in a CPU template does not generally -> make it completely unavailable to the guest. For example, disabling a feature -> related to an instruction set will indicate to the guest that the feature is -> not supported, but the guest may still be able to execute corresponding +> [!NOTE] +> +> Representing one CPU vendor as another CPU vendor is not supported. + +> [!NOTE] +> +> CPU templates shall not be used as a security protection against malicious +> guests. Disabling a feature in a CPU template does not generally make it +> completely unavailable to the guest. For example, disabling a feature related +> to an instruction set will indicate to the guest that the feature is not +> supported, but the guest may still be able to execute corresponding > instructions if it does not obey the feature bit. Firecracker supports two types of CPU templates: @@ -32,15 +36,19 @@ Firecracker supports two types of CPU templates: - Custom CPU templates - users can create their own CPU templates in json format and pass them to Firecracker -> **Note** Static CPU templates are deprecated starting from v1.5.0 and will be -> removed in accordance with our deprecation policy. Even after the removal, -> custom CPU templates are available as an improved iteration of static CPU -> templates. For more information about the transition from static CPU templates -> to custom CPU templates, please refer to +> [!NOTE] +> +> Static CPU templates are deprecated starting from v1.5.0 and will be removed +> in accordance with our deprecation policy. Even after the removal, custom CPU +> templates are available as an improved iteration of static CPU templates. For +> more information about the transition from static CPU templates to custom CPU +> templates, please refer to > [this GitHub discussion](https://github.com/firecracker-microvm/firecracker/discussions/4135). -> **Note** CPU templates for ARM (both static and custom) require the following -> patch to be available in the host kernel: +> [!NOTE] +> +> CPU templates for ARM (both static and custom) require the following patch to +> be available in the host kernel: > [Support writable CPU ID registers from userspace](https://lore.kernel.org/kvm/20230212215830.2975485-1-jingzhangos@google.com/#t). > Otherwise KVM will fail to write to the ARM registers. @@ -104,21 +112,27 @@ curl --unix-socket /tmp/firecracker.socket -i \ Users can create their own CPU templates by creating a json file containing modifiers for CPUID, MSRs or ARM registers. -> **Note** Creating custom CPU templates requires expert knowledge of CPU -> architectures. Custom CPU templates must be tested thoroughly before use in -> production. An inappropriate configuration may lead to guest crashes or making -> guests vulnerable to security attacks. For example, if a CPU template signals -> a hardware vulnerability mitigation to the guest while the mitigation is in -> fact not supported by the hardware, the guest may decide to disable -> corresponding software mitigations which will make the guest vulnerable. - -> **Note** Having MSRs or ARM registers in the custom CPU template does not -> affect access permissions that guests will have to those registers. The access -> control is handled by KVM and is not influenced by CPU templates. - -> **Note** When setting guest configuration, KVM may reject setting some bits -> quietly. This is user's responsibility to make sure that their custom CPU -> template is applied as expected even if Firecracker does not report an error. +> [!NOTE] +> +> Creating custom CPU templates requires expert knowledge of CPU architectures. +> Custom CPU templates must be tested thoroughly before use in production. An +> inappropriate configuration may lead to guest crashes or making guests +> vulnerable to security attacks. For example, if a CPU template signals a +> hardware vulnerability mitigation to the guest while the mitigation is in fact +> not supported by the hardware, the guest may decide to disable corresponding +> software mitigations which will make the guest vulnerable. + +> [!NOTE] +> +> Having MSRs or ARM registers in the custom CPU template does not affect access +> permissions that guests will have to those registers. The access control is +> handled by KVM and is not influenced by CPU templates. + +> [!NOTE] +> +> When setting guest configuration, KVM may reject setting some bits quietly. +> This is user's responsibility to make sure that their custom CPU template is +> applied as expected even if Firecracker does not report an error. In order to assist with creation and usage of CPU templates, there exists a CPU template helper tool. More details can be found [here](cpu-template-helper.md). @@ -216,8 +230,10 @@ the The full description of the custom CPU templates language can be found [here](schema.json). -> **Note** You can also use `_` to visually separate parts of a bitmap. So -> instead of writing: `0b0000xxxx`, it can be `0b0000_xxxx`. +> [!NOTE] +> +> You can also use `_` to visually separate parts of a bitmap. So instead of +> writing: `0b0000xxxx`, it can be `0b0000_xxxx`. #### Expansion of contracted bitmaps diff --git a/docs/kernel-policy.md b/docs/kernel-policy.md index d67496d8435..86823459d44 100644 --- a/docs/kernel-policy.md +++ b/docs/kernel-policy.md @@ -14,10 +14,12 @@ years**. At least 2 major guest and host versions will be supported at any time. When support is added for a third kernel version, the oldest will be deprecated and removed in a following release, after its minimum end of support date. -**Note** While other versions and other kernel configs might work, they are not -periodically validated in our test suite, and using them might result in -unexpected behaviour. Starting with release `v1.0` each major and minor release -will specify the supported kernel versions. +> [!NOTE] +> +> While other versions and other kernel configs might work, they are not +> periodically validated in our test suite, and using them might result in +> unexpected behaviour. Starting with release `v1.0` each major and minor +> release will specify the supported kernel versions. ### Host Kernel @@ -116,8 +118,10 @@ configurations for the guest kernel are: - `CONFIG_ACPI=y` - `CONFIG_PCI=y` -Please note that Firecracker does not support PCI devices. The `CONFIG_PCI` -option is needed for ACPI initialization inside the guest. +> [!NOTE] +> +> Firecracker does not support PCI devices. The `CONFIG_PCI` option is needed +> for ACPI initialization inside the guest. ACPI supersedes the legacy way of booting a microVM, i.e. via MPTable and command line parameters for VirtIO devices. diff --git a/docs/network-setup.md b/docs/network-setup.md index 8cee2f521c2..c161b6661d4 100644 --- a/docs/network-setup.md +++ b/docs/network-setup.md @@ -4,8 +4,10 @@ This is a simple quick-start guide to getting one or more Firecracker microVMs connected to the Internet via the host. If you run a production setup, you should consider modifying this setup to accommodate your specific needs. -**Note:** Currently, Firecracker supports only a TUN/TAP network backend with no -multi queue support. +> [!NOTE] +> +> Currently, Firecracker supports only a TUN/TAP network backend with no multi +> queue support. The steps in this guide assume `eth0` to be your Internet-facing network interface on the host. If `eth0` isn't your main network interface, you should @@ -58,8 +60,10 @@ sudo ip addr add 172.16.0.1/30 dev tap0 sudo ip link set tap0 up ``` -**Note:** The IP of the TAP device should be chosen such that it's not in the -same subnet as the IP address of the host. +> [!NOTE] +> +> The IP of the TAP device should be chosen such that it's not in the same +> subnet as the IP address of the host. We'll need to enable IPv4 forwarding on the system. @@ -107,24 +111,39 @@ sudo iptables-nft -A FORWARD -i tap0 -o eth0 -j ACCEPT ## Setting Up Firecracker +> [!NOTE] +> +> If you use the rootfs from the [getting started guide](getting-started.md), +> you need to use a specific `MAC` address like `06:00:AC:10:00:02`. In this +> `MAC` address, the last 4 bytes (`AC:10:00:02`) will represent the IP address +> of the guest. In the default case, it is `172.16.0.2`. Otherwise, you can skip +> the `guest_mac` field for network configuration. This way, the guest will +> generate a random MAC address on startup. + +> [!NOTE] +> +> The `iface_id` used during VM configuration is internal to Firecracker and +> only used for management purposes. The name of the network interface in the +> guest is determined by the guest itself. In this example we assume the guest +> will name the network interface `eth0`. + +> [!NOTE] +> +> Firecracker cannot guarantee that the network interfaces in the guest will be +> initialized in the guest in the same order as API calls used to set them up. +> At the same time most kernels/distributions do initialize devices in the API +> defined order. + Before starting the guest, configure the network interface using Firecracker's API: -**Note:** If you use the rootfs from the -[getting started guide](getting-started.md), you need to use a specific `MAC` -address like `06:00:AC:10:00:02`. In this `MAC` address, the last 4 bytes -(`AC:10:00:02`) will represent the IP address of the guest. In the default case, -it is `172.16.0.2`. Otherwise, you can skip the `guest_mac` field for network -configuration. This way, the guest will generate a random MAC address on -startup. - ```bash curl --unix-socket /tmp/firecracker.socket -i \ - -X PUT 'http://localhost/network-interfaces/eth0' \ + -X PUT 'http://localhost/network-interfaces/my_network0' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ - "iface_id": "eth0", + "iface_id": "my_network0", "guest_mac": "06:00:AC:10:00:02", "host_dev_name": "tap0" }' @@ -136,7 +155,7 @@ configuration file like this: ```json "network-interfaces": [ { - "iface_id": "eth0", + "iface_id": "my_network0", "guest_mac": "06:00:AC:10:00:02", "host_dev_name": "tap0" } @@ -148,9 +167,6 @@ Alternatively, if you are using firectl, add ## In The Guest -Once you have booted the guest, it will have its networking interface with the -name specified by `iface_id` in the Firecracker configuration. - You'll now need to assign the guest its IP, activate the guest's networking interface and set up the `tap` IP as the guest's gateway address, so that packets are routed through the `tap` device, where they are then picked up by @@ -172,10 +188,13 @@ your environment. For testing, you can add a public DNS server to nameserver 8.8.8.8 ``` -**Note:** Sometimes, it's undesirable to have `iproute2` (providing the `ip` -command) installed on your guest OS, or you simply want to have these steps be -performed automatically. To do this, check out the _Advanced: Guest network -configuration using kernel command line_ section. +> [!NOTE] +> +> Sometimes, it's undesirable to have `iproute2` (providing the `ip` command) +> installed on your guest OS, or you simply want to have these steps be +> performed automatically. To do this, check out the +> [Advanced: Guest network configuration using kernel command line](#advanced-guest-network-configuration-using-kernel-command-line) +> section. ## Cleaning up @@ -304,33 +323,36 @@ ip link set eth0 up ip route add default via 172.16.0.5 dev eth0 ``` -Or, you can use the setup from _Advanced: Guest network configuration at kernel -level_ by simply changing the G and T variables, i.e. the guest IP and `tap` IP. - -**Note:** if you'd like to calculate the guest and `tap` IPs using the -sequential subnet allocation method that has been used here, you can use the -following formulas specific to IPv4 addresses: - -`tap` IP = `172.16.[(A*O+1)/256].[(A*O+1)%256]`. - -Guest IP = `172.16.[(A*O+2)/256].[(A*O+2)%256]`. - -Round down the division and replace `A` with the amount of IP addresses inside -your subnet (for a /30 subnet, that will be 4 addresses, for example) and -replace `O` with the sequential number of your microVM, starting at 0. You can -replace `172.16` with any other values that fit between between 1 and 255 as -usual with an IPv4 address. - -For example, let's calculate the addresses of the 1000-th microVM with a /30 -subnet in the `172.16.0.0/16` range: - -`tap` IP = `172.16.[(4*999+1)/256].[(4*999+1)%256]` = `172.16.15.157`. - -Guest IP = `172.16.[(4*999+2)/256].[(4*999+2)%256]` = `172.16.15.158`. - -This allocation setup has been used successfully in the `firecracker-demo` -project for launching several thousand microVMs on the same host: -[relevant lines](https://github.com/firecracker-microvm/firecracker-demo/blob/63717c6e7fbd277bdec8e26a5533d53544a760bb/start-firecracker.sh#L45). +Or, you can use the setup from +[Advanced: Guest network configuration](#advanced-guest-network-configuration-using-kernel-command-line) +by simply changing the G and T variables, i.e. the guest IP and `tap` IP. + +> [!NOTE] +> +> If you'd like to calculate the guest and `tap` IPs using the sequential subnet +> allocation method that has been used here, you can use the following formulas +> specific to IPv4 addresses: +> +> `tap` IP = `172.16.[(A*O+1)/256].[(A*O+1)%256]`. +> +> Guest IP = `172.16.[(A*O+2)/256].[(A*O+2)%256]`. +> +> Round down the division and replace `A` with the amount of IP addresses inside +> your subnet (for a /30 subnet, that will be 4 addresses, for example) and +> replace `O` with the sequential number of your microVM, starting at 0. You can +> replace `172.16` with any other values that fit between between 1 and 255 as +> usual with an IPv4 address. +> +> For example, let's calculate the addresses of the 1000-th microVM with a /30 +> subnet in the `172.16.0.0/16` range: +> +> `tap` IP = `172.16.[(4*999+1)/256].[(4*999+1)%256]` = `172.16.15.157`. +> +> Guest IP = `172.16.[(4*999+2)/256].[(4*999+2)%256]` = `172.16.15.158`. +> +> This allocation setup has been used successfully in the `firecracker-demo` +> project for launching several thousand microVMs on the same host: +> [relevant lines](https://github.com/firecracker-microvm/firecracker-demo/blob/63717c6e7fbd277bdec8e26a5533d53544a760bb/start-firecracker.sh#L45). ## Advanced: Bridge-based routing diff --git a/docs/rootfs-and-kernel-setup.md b/docs/rootfs-and-kernel-setup.md index 8dc10f55f87..ecffc58b720 100644 --- a/docs/rootfs-and-kernel-setup.md +++ b/docs/rootfs-and-kernel-setup.md @@ -33,8 +33,10 @@ can boot: make menuconfig ``` - *Note*: there are many ways of building a kernel config file, other than - `menuconfig`. You are free to use whichever one you choose. +> [!NOTE] +> +> There are many ways of building a kernel config file, other than `menuconfig`. +> You are free to use whichever one you choose. 1. Build the kernel image: diff --git a/docs/seccomp.md b/docs/seccomp.md index 06c7fd92d76..0611fd8d602 100644 --- a/docs/seccomp.md +++ b/docs/seccomp.md @@ -38,15 +38,19 @@ also included in the respective release archive, viewable on the ## Custom filters (advanced users only) -**Note 1**: This feature overrides the default filters and can be dangerous. -Filter misconfiguration can result in abruptly terminating the process or -disabling the seccomp security boundary altogether. We recommend using the -default filters instead. - -**Note 2**: The user is fully responsible for managing the filter files. We -recommend using integrity checks whenever transferring/downloading files, for -example checksums, as well as for the Firecracker binary or other artifacts, in -order to mitigate potential man-in-the-middle attacks. +> [!NOTE] +> +> This feature overrides the default filters and can be dangerous. Filter +> misconfiguration can result in abruptly terminating the process or disabling +> the seccomp security boundary altogether. We recommend using the default +> filters instead. + +> [!NOTE] +> +> The user is fully responsible for managing the filter files. We recommend +> using integrity checks whenever transferring/downloading files, for example +> checksums, as well as for the Firecracker binary or other artifacts, in order +> to mitigate potential man-in-the-middle attacks. Firecracker exposes a way for advanced users to override the default filters with fully customisable alternatives, leveraging the same JSON/seccompiler diff --git a/docs/snapshotting/snapshot-support.md b/docs/snapshotting/snapshot-support.md index ad5dceff7a5..9f8a443179d 100644 --- a/docs/snapshotting/snapshot-support.md +++ b/docs/snapshotting/snapshot-support.md @@ -257,9 +257,11 @@ curl --unix-socket /tmp/firecracker.socket -i \ Details about the required and optional fields can be found in the [swagger definition](../../src/firecracker/swagger/firecracker.yaml). -*Note*: If the files indicated by `snapshot_path` and `mem_file_path` don't -exist at the specified paths, then they will be created right before generating -the snapshot. If they exist, the files will be truncated and overwritten. +> [!NOTE] +> +> If the files indicated by `snapshot_path` and `mem_file_path` don't exist at +> the specified paths, then they will be created right before generating the +> snapshot. If they exist, the files will be truncated and overwritten. **Prerequisites**: The microVM is `Paused`. @@ -293,19 +295,21 @@ the snapshot. If they exist, the files will be truncated and overwritten. For creating a diff snapshot, you should use the same API command, but with `snapshot_type` field set to `Diff`. -*Note*: If not specified, `snapshot_type` is by default `Full`. - -```bash -curl --unix-socket /tmp/firecracker.socket -i \ - -X PUT 'http://localhost/snapshot/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{ - "snapshot_type": "Diff", - "snapshot_path": "./snapshot_file", - "mem_file_path": "./mem_file", - }' -``` +> [!NOTE] +> +> If not specified, `snapshot_type` is by default `Full`. +> +> ```bash +> curl --unix-socket /tmp/firecracker.socket -i \ +> -X PUT 'http://localhost/snapshot/create' \ +> -H 'Accept: application/json' \ +> -H 'Content-Type: application/json' \ +> -d '{ +> "snapshot_type": "Diff", +> "snapshot_path": "./snapshot_file", +> "mem_file_path": "./mem_file", +> }' +> ``` **Prerequisites**: The microVM is `Paused`. @@ -321,8 +325,10 @@ to swap to be "in core". This potentially results in bigger memory files (although they are still sparse), but avoids the runtime overhead of dirty page logging. -*Note*: Dirty page tracking negates most of the benefits of -[huge pages](../hugepages.md#known-limitations). +> [!NOTE] +> +> Dirty page tracking negates most of the benefits of +> [huge pages](../hugepages.md#known-limitations). **Effects**: @@ -337,20 +343,22 @@ logging. full snapshots** section apply here. - _on failure_: no side-effects. -*Note*: This is an example of an API command that enables dirty page tracking: - -```bash -curl --unix-socket /tmp/firecracker.socket -i \ - -X PUT 'http://localhost/machine-config' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{ - "vcpu_count": 2, - "mem_size_mib": 1024, - "smt": false, - "track_dirty_pages": true - }' -``` +> [!NOTE] +> +> This is an example of an API command that enables dirty page tracking: +> +> ```bash +> curl --unix-socket /tmp/firecracker.socket -i \ +> -X PUT 'http://localhost/machine-config' \ +> -H 'Accept: application/json' \ +> -H 'Content-Type: application/json' \ +> -d '{ +> "vcpu_count": 2, +> "mem_size_mib": 1024, +> "smt": false, +> "track_dirty_pages": true +> }' +> ``` Enabling this support enables KVM dirty page tracking, so it comes at a cost (which consists of CPU cycles spent by KVM accounting for dirtied pages); it