chore: clarify network naming in network-setup.md

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

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
 

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
 

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.

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
 

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
 

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/[email protected]/#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
 

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.