### Install Google Cloud SDK

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/dev-machine-setup.md

Installs the Google Cloud SDK on a Debian/Ubuntu system. This command sequence adds the repository, imports the key, and installs the SDK.

```bash
$ export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)"
$ echo "deb http://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" \
| sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
$ curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
| sudo apt-key add -
$ sudo apt-get update && sudo apt-get install -y google-cloud-sdk
```

--------------------------------

### Configure Firecracker Network Interface and Start Instance

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md

Set up the guest network interface with a MAC address and host device name, then start the Firecracker microVM instance. A small delay is included to ensure configuration is applied before starting.

```bash
# The IP address of a guest is derived from its MAC address with
# `fcnet-setup.sh`, this has been pre-configured in the guest rootfs. It is
# important that `TAP_IP` and `FC_MAC` match this.
FC_MAC="06:00:AC:10:00:02"

# Set network interface
sudo curl -X PUT --unix-socket "${API_SOCKET}" \
    --data "{
        \"iface_id\": \"net1\",
        \"guest_mac\": \"$FC_MAC\",
        \"host_dev_name\": \"$TAP_DEV\" 
    }" \
    "http://localhost/network-interfaces/net1"

# API requests are handled asynchronously, it is important the configuration is
# set, before `InstanceStart`.
sleep 0.015s

# Start microVM
sudo curl -X PUT --unix-socket "${API_SOCKET}" \
    --data "{
        \"action_type\": \"InstanceStart\" 
    }" \
    "http://localhost/actions"
```

--------------------------------

### Install OpenRC and Utilities

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/rootfs-and-kernel-setup.md

Inside the Docker container, install the OpenRC init system and essential utilities like 'util-linux'.

```bash
apk add openrc
apk add util-linux
```

--------------------------------

### InstanceStart Action

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/api_requests/actions.md

Powers on the microVM and starts the guest OS. This action does not have a payload and can only be successfully called once.

```APIDOC
## InstanceStart Action

### Description
Powers on the microVM and starts the guest OS. This action does not have a payload and can only be successfully called once.

### Method
PUT

### Endpoint
/actions

### Request Body
- **action_type** (string) - Required - Must be set to "InstanceStart".

### Request Example
```bash
curl --unix-socket ${socket} -i \
     -X PUT "http://localhost/actions" \
     -d '{ "action_type": "InstanceStart" }'
```

```

--------------------------------

### Start Firecracker Instance

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/api_requests/actions.md

Use this action to power on the microVM and start the guest OS. This action has no payload and can only be successfully called once.

```bash
curl --unix-socket ${socket} -i \
     -X PUT "http://localhost/actions" \
     -d '{ "action_type": "InstanceStart" }'
```

--------------------------------

### Install Balloon Device via API

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Installs a balloon device by sending a PUT request to the /balloon endpoint. This must be done before starting the virtual machine.

```APIDOC
## PUT /balloon

### Description
Installs a balloon device for the virtual machine. This operation must be performed before the VM starts.

### Method
PUT

### Endpoint
/balloon

### Parameters
#### Request Body
- **amount_mib** (integer) - Required - The target size of the balloon in MiB.
- **deflate_on_oom** (boolean) - Optional - If true, the balloon will attempt to deflate when the guest is out of memory.
- **stats_polling_interval_s** (integer) - Optional - The interval in seconds at which balloon statistics are polled.

### Request Example
```json
{
    "amount_mib": 1024,
    "deflate_on_oom": true,
    "stats_polling_interval_s": 10
}
```

### Response
#### Success Response (200)
Returns a JSON object with the same structure as the request body, confirming the configuration.

#### Response Example
```json
{
    "amount_mib": 1024,
    "deflate_on_oom": true,
    "stats_polling_interval_s": 10
}
```
```

--------------------------------

### Run Vhost-User Backend

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/api_requests/block-vhost-user.md

Start the vhost-user block device backend service. Ensure the backend supports the VIRTIO_BLK_F_RO feature for read-only configurations.

```bash
vhost-user-blk --socket-path=${backend_socket} --blk-file=${drive_path}
```

--------------------------------

### Configure Guest Nameserver

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md

Add a nameserver entry to the guest's `/etc/resolv.conf` file to enable DNS resolution. This example uses `192.168.1.1` as the nameserver.

```bash
# cat /etc/resolv.conf
nameserver 192.168.1.1
```

--------------------------------

### Install Git and Clone FreeBSD Source Tree

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/rootfs-and-kernel-setup.md

Installs git and clones the FreeBSD source tree to the specified directory. This is a prerequisite for building the FreeBSD kernel and rootfs for Firecracker.

```bash
pkg install -y git
git clone https://git.freebsd.org/src.git /usr/src
```

--------------------------------

### Guest-initiated connection setup

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md

Steps for establishing a connection initiated from the guest VM to the host. This involves the host creating and listening on a specific AF_UNIX socket, and the guest connecting to the host CID and port.

```text
HOST_CID (i.e. integer value 2)
```

--------------------------------

### Start Alpine Docker Container

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/rootfs-and-kernel-setup.md

Start an Alpine Linux Docker container, bind-mounting the prepared rootfs image to '/my-rootfs'. This allows modifying the rootfs from within the container.

```bash
docker run -it --rm -v /tmp/my-rootfs:/my-rootfs alpine
```

--------------------------------

### Setting Multiple Resource Limits with Jailer

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/jailer.md

Example demonstrating how to set multiple resource limits for a process managed by the jailer, such as file size and open file descriptors.

```bash
--resource-limit fsize=250000000 --resource-limit no-file=1024
```

--------------------------------

### Configure Guest Network and Access MicroVM via SSH

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md

After starting the microVM, wait for it to initialize, then configure its internal routing and DNS settings via SSH. Finally, establish an SSH connection to the microVM.

```bash
# API requests are handled asynchronously, it is important the microVM has been
# started before we attempt to SSH into it.
sleep 2s

KEY_NAME=./$(ls *.id_rsa | tail -1)

# Setup internet access in the guest
ssh -i $KEY_NAME root@172.16.0.2  "ip route add default via 172.16.0.1 dev eth0"

# Setup DNS resolution in the guest
ssh -i $KEY_NAME root@172.16.0.2  "echo 'nameserver 8.8.8.8' > /etc/resolv.conf"

# SSH into the microVM
ssh -i $KEY_NAME root@172.16.0.2

# Use `root` for both the login and password.
# Run `reboot` to exit.
```

--------------------------------

### Configure virtio-mem via JSON

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/memory-hotplug.md

Add this configuration to your VM's JSON configuration file to set up virtio-mem. This configuration is applied when the VM starts.

```json
{
    "memory-hotplug": {
        "total_size_mib": 1024,
        "block_size_mib": 2,
        "slot_size_mib": 128
    }
}
```

--------------------------------

### Start Firecracker Sandbox

Source: https://github.com/firecracker-microvm/firecracker/blob/main/tests/README.md

Launch the Firecracker sandbox environment, which provides an IPython REPL for interacting with a microVM. Use 'tools/devtool sandbox -- --help' for available options.

```sh
tools/devtool -y sandbox
```

--------------------------------

### Configure virtio-pmem Rate Limiter at Creation

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/pmem.md

Configure the virtio-pmem device with a rate limiter during its creation. This example sets limits for bandwidth and operations per second.

```json
"pmem": [
    {
      "id": "pmem0",
      "path_on_host": "./backing_file_256m",
      "rate_limiter": {
        "bandwidth": { "size": 268435456, "refill_time": 1000 },
        "ops": { "size": 10, "refill_time": 1000 }
      }
    }
]
```

--------------------------------

### Secure MicroVM Snapshot Usage Example

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/snapshot-support.md

Demonstrates a secure workflow where a microVM terminates after creating a snapshot, and a new microVM resumes from that snapshot. This ensures unique identifiers and tokens are used only once.

```console
Boot microVM A -> ... -> Create snapshot S -> Terminate
                                           -> Load S in microVM B -> Resume -> ...

```

--------------------------------

### Interact with MicroVM in Sandbox

Source: https://github.com/firecracker-microvm/firecracker/blob/main/tests/README.md

Example commands to interact with a microVM within the Firecracker sandbox IPython REPL. These include logging, metrics retrieval, SSH commands, and snapshotting.

```python
uvm.help.print_log()
uvm.get_all_metrics()
uvm.ssh.run("ls")
snap = uvm.snapshot_full()
uvm.help.tmux_ssh()
```

--------------------------------

### Start GDB and Connect to Firecracker

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/gdb-debugging.md

Initiate GDB, load kernel symbols, and establish a remote connection to the Firecracker GDB socket. This allows for debugging the guest kernel.

```bash
gdb vmlinux
```

```gdb
(gdb) target remote /tmp/gdb.socket
```

--------------------------------

### Example Commit Message Format

Source: https://github.com/firecracker-microvm/firecracker/blob/main/CONTRIBUTING.md

Illustrates the recommended format for commit messages, including a descriptive title and a concise body, followed by sign-off and co-authored-by lines.

```text
A descriptive title of 72 characters or fewer

A concise description where each line is 72 characters or fewer.

Signed-off-by: <A full name> <A email>
Co-authored-by: <B full name> <B email>
```

--------------------------------

### Configure virtio-mem via API

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/memory-hotplug.md

Use this PUT request to configure the virtio-mem device with total size, block size, and slot size. This must be done before starting the VM.

```bash
socket_location=/run/firecracker.microvm.sock

curl --unix-socket $socket_location -i \
    -X PUT 'http://localhost/hotplug/memory' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d "{
        \"total_size_mib\": 1024,
        \"block_size_mib\": 2,
        \"slot_size_mib\": 128
    }"
```

--------------------------------

### Launch Firecracker VM with Jailer

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/jailer.md

Use this command to start a Firecracker MicroVM. It configures cgroups, network namespace, and daemonizes the process. Ensure paths and IDs match your environment.

```bash
/usr/bin/jailer --id 551e7604-e35c-42b3-b825-416853441234
--cgroup cpuset.mems=0 --cgroup cpuset.cpus=$(cat /sys/devices/system/node/node0/cpulist)
--exec-file /usr/bin/firecracker --uid 123 --gid 100 \
--netns /var/run/netns/my_netns --daemonize

```

--------------------------------

### Configure Balloon Device with Free Page Hinting

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

This example shows how to enable free page hinting when creating or configuring the balloon device. The `free_page_hinting` attribute must be set to `true` in the JSON payload.

```APIDOC
## Configure Balloon Device with Free Page Hinting

### Description
Enables the free page hinting feature for the Virtio balloon device. When enabled, the guest driver can report unused memory ranges to the host for reclamation.

### Method
PUT

### Endpoint
/balloon

### Parameters
#### Request Body
- **amount_mib** (integer) - Required - The amount of memory in MiB to be managed by the balloon device.
- **deflate_on_oom** (boolean) - Required - Whether to deflate the balloon when the guest is out of memory.
- **stats_polling_interval_s** (integer) - Required - The interval in seconds for polling statistics.
- **free_page_hinting** (boolean) - Required - Set to `true` to enable free page hinting.

### Request Example
```json
{
    "amount_mib": 1024,
    "deflate_on_oom": true,
    "stats_polling_interval_s": 1,
    "free_page_hinting": true
}
```

### Response
#### Success Response (200)
- **None** - Typically returns an empty body on success.

#### Response Example
(No specific response body is detailed for this configuration endpoint in the provided text.)
```

--------------------------------

### Configure Network Interface via API

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md

Use this cURL command to configure a network interface for a Firecracker VM using its Unix socket API. Ensure the guest MAC address corresponds to the guest's IP address if using the rootfs from the getting started guide.

```bash
curl --unix-socket /tmp/firecracker.socket -i \
  -X PUT 'http://localhost/network-interfaces/my_network0' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
      "iface_id": "my_network0",
      "guest_mac": "06:00:AC:10:00:02",
      "host_dev_name": "tap0"
    }'
```

--------------------------------

### Install cURL on Ubuntu VM

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/dev-machine-setup.md

Installs the cURL utility on an Ubuntu virtual machine. This is a prerequisite for further Firecracker setup.

```bash
sudo apt install curl -y
```

--------------------------------

### Install Test Dependencies (Ubuntu/Debian)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/tests/README.md

Install necessary Python packages for running Firecracker tests outside of Docker on Ubuntu-based systems. Ensure Python 3 and pip are installed.

```sh
# replace with yum in Fedora/AmazonLinux
sudo apt install python3-pip
sudo pip3 install pytest ipython requests psutil tenacity filelock "urllib3<2.0" requests_unixsocket aws_embedded_metrics pytest-json-report pytest-timeout
```

--------------------------------

### Configure Block Device with Sync IO Engine

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/api_requests/block-io-engine.md

This example shows how to configure a block device using the synchronous IO engine via the PUT /drives API. Ensure the socket path and drive path are correctly set.

```bash
curl --unix-socket ${socket} -i \
     -X PUT "http://localhost/drives/rootfs" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d "{
             \"drive_id\": \"rootfs\",
             \"path_on_host\": \"${drive_path}\",
             \"is_root_device\": true,
             \"is_read_only\": false,
             \"io_engine\": \"Sync\"
         }"
```

--------------------------------

### Get Balloon Device Configuration (GET)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Retrieve the current configuration of the balloon device by sending a GET request to the '/balloon' endpoint. This command uses cURL with a specified socket location.

```bash
socket_location=...

curl --unix-socket $socket_location -i \
    -X GET 'http://localhost/balloon' \
    -H 'Accept: application/json'
```

--------------------------------

### Example Metadata JSON

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/mmds/mmds-user-guide.md

This is an example of the JSON structure for metadata stored in MMDS.

```json
{
    "latest": {
          "meta-data": {
               "ami-id": "ami-87654321",
               "reservation-id": "r-79054aef"
          }
    }
}
```

--------------------------------

### Host-initiated connection setup

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md

Steps for establishing a connection initiated from the host to a guest VM using the virtio-vsock device. This involves configuring the device with a UDS path, listening on the guest vsock port, connecting to the host UDS, and sending a CONNECT command.

```text
CONNECT PORT\n
```

```text
OK PORT\n
```

--------------------------------

### Get Balloon Device Configuration

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Retrieves the current configuration of the balloon device by sending a GET request to the /balloon endpoint.

```APIDOC
## GET /balloon

### Description
Retrieves the current configuration of the installed balloon device.

### Method
GET

### Endpoint
/balloon

### Response
#### Success Response (200)
- **amount_mib** (integer) - The target size of the balloon in MiB.
- **deflate_on_oom** (boolean) - Indicates if the balloon deflates on OOM.
- **stats_polling_interval_s** (integer) - The interval in seconds for polling balloon statistics.

#### Response Example
```json
{
    "amount_mib": 1024,
    "deflate_on_oom": true,
    "stats_polling_interval_s": 10
}
```
```

--------------------------------

### Configure Logger via Command Line (Advanced)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/logger.md

Configure the logger on startup with specific levels and origin display settings using additional command-line parameters.

```bash
./firecracker --api-sock /tmp/firecracker.socket --log-path
logs.fifo --level Error --show-level --show-log-origin
```

--------------------------------

### Configure MicroVM with a JSON File

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md

Boot a guest microVM without using the API socket by providing a configuration file. This JSON file must include guest kernel and rootfs configuration.

```bash
sudo ./firecracker --api-sock /tmp/firecracker.socket --config-file <path_to_the_configuration_file>
```

--------------------------------

### Install Balloon Device via JSON Configuration

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Insert this JSON object into your Firecracker configuration file to install the balloon device. Configure 'amount_mib', 'deflate_on_oom', and 'stats_polling_interval_s' as needed.

```json
"balloon": {
    "amount_mib": 0,
    "deflate_on_oom": false,
    "stats_polling_interval_s": 1
}
```

--------------------------------

### Install Test Dependencies (Amazon Linux 2)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/tests/README.md

Install Python packages for running Firecracker tests on Amazon Linux 2. This command should be run after configuring the correct Python version.

```sh
sudo pip3 install pytest ipython requests psutil tenacity filelock "urllib3<2.0" requests_unixsocket
```

--------------------------------

### Configure Logger via Command Line (Basic)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/logger.md

Configure the logger on startup using the --log-path command-line parameter. Other logger fields will use default values.

```bash
./firecracker --api-sock /tmp/firecracker.socket --log-path
<path_to_the_logging_fifo_or_file>
```

--------------------------------

### Get Virtio Balloon Statistics

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Retrieve the latest virtio balloon statistics by sending a GET request to the /balloon/statistics endpoint. Ensure stats_polling_interval_s is set to a non-zero value in the balloon configuration.

```bash
socket_location=...

curl --unix-socket $socket_location -i \
    -X GET 'http://localhost/balloon/statistics' \
    -H 'Accept: application/json'
```

--------------------------------

### Initialize gcloud CLI

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/dev-machine-setup.md

Initializes the gcloud CLI, prompting for authentication and default project selection. Follow the console prompts to complete the authentication process.

```bash
$ gcloud init --console-only
```

--------------------------------

### Enable Guest Network Interface

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md

Activate the guest's network interface (`eth0`) after assigning an IP address.

```bash
ip link set eth0 up
```

--------------------------------

### Get Virtio Balloon Statistics

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Retrieve the latest Virtio balloon statistics by issuing a GET request on the /balloon/statistics endpoint. Statistics are enabled by setting `stats_polling_interval_s` in the balloon configuration to a non-zero value.

```APIDOC
## GET /balloon/statistics

### Description
Retrieves the latest Virtio balloon statistics, including target and actual balloon sizes, and traditional virtio memory balloon statistics.

### Method
GET

### Endpoint
/balloon/statistics

### Parameters
None

### Request Example
```console
socket_location=...

curl --unix-socket $socket_location -i \
    -X GET 'http://localhost/balloon/statistics' \
    -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **target_pages** (integer) - The target size of the balloon, in 4K pages.
- **actual_pages** (integer) - The number of 4K pages the device is currently holding.
- **target_mib** (integer) - The target size of the balloon, in MiB.
- **actual_mib** (integer) - The number of MiB the device is currently holding.
- **VIRTIO_BALLOON_S_SWAP_IN** (integer) - The amount of memory that has been swapped in (in bytes).
- **VIRTIO_BALLOON_S_SWAP_OUT** (integer) - The amount of memory that has been swapped out to disk (in bytes).
- **VIRTIO_BALLOON_S_MAJFLT** (integer) - The number of major page faults that have occurred.
- **VIRTIO_BALLOON_S_MINFLT** (integer) - The number of minor page faults that have occurred.
- **VIRTIO_BALLOON_S_MEMFREE** (integer) - The amount of memory not being used for any purpose (in bytes).
- **VIRTIO_BALLOON_S_MEMTOT** (integer) - The total amount of memory available (in bytes).
- **VIRTIO_BALLOON_S_AVAIL** (integer) - An estimate of how much memory is available (in bytes) for starting new applications, without pushing the system to swap.
- **VIRTIO_BALLOON_S_CACHES** (integer) - The amount of memory, in bytes, that can be quickly reclaimed without additional I/O.
- **VIRTIO_BALLOON_S_HTLB_PGALLOC** (integer) - The number of successful hugetlb page allocations in the guest.
- **VIRTIO_BALLOON_S_HTLB_PGFAIL** (integer) - The number of failed hugetlb page allocations in the guest.
- **VIRTIO_BALLOON_S_OOM_KILL** (integer) - OOM killer invocations, indicating critical memory pressure (Linux v6.12+).
- **VIRTIO_BALLOON_S_ALLOC_STALL** (integer) - Counter of Allocation enter a slow path to gain more memory page (Linux v6.12+).
- **VIRTIO_BALLOON_S_ASYNC_SCAN** (integer) - Amount of memory scanned asynchronously (Linux v6.12+).
- **VIRTIO_BALLOON_S_DIRECT_SCAN** (integer) - Amount of memory scanned directly (Linux v6.12+).
- **VIRTIO_BALLOON_S_ASYNC_RECLAIM** (integer) - Amount of memory reclaimed asynchronously (Linux v6.12+).
- **VIRTIO_BALLOON_S_DIRECT_RECLAIM** (integer) - Amount of memory reclaimed directly (Linux v6.12+).

#### Response Example
```json
{
  "target_pages": 1024,
  "actual_pages": 512,
  "target_mib": 4096,
  "actual_mib": 2048,
  "VIRTIO_BALLOON_S_SWAP_IN": 0,
  "VIRTIO_BALLOON_S_SWAP_OUT": 0,
  "VIRTIO_BALLOON_S_MAJFLT": 100,
  "VIRTIO_BALLOON_S_MINFLT": 500,
  "VIRTIO_BALLOON_S_MEMFREE": 1073741824,
  "VIRTIO_BALLOON_S_MEMTOT": 4294967296,
  "VIRTIO_BALLOON_S_AVAIL": 2147483648,
  "VIRTIO_BALLOON_S_CACHES": 536870912,
  "VIRTIO_BALLOON_S_HTLB_PGALLOC": 0,
  "VIRTIO_BALLOON_S_HTLB_PGFAIL": 0,
  "VIRTIO_BALLOON_S_OOM_KILL": 0,
  "VIRTIO_BALLOON_S_ALLOC_STALL": 0,
  "VIRTIO_BALLOON_S_ASYNC_SCAN": 0,
  "VIRTIO_BALLOON_S_DIRECT_SCAN": 0,
  "VIRTIO_BALLOON_S_ASYNC_RECLAIM": 0,
  "VIRTIO_BALLOON_S_DIRECT_RECLAIM": 0
}
```
```

--------------------------------

### Install Balloon Device via API (PUT)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md

Use this cURL command to install the balloon device by sending a PUT request to the Firecracker API. Ensure the socket location and balloon parameters are correctly set.

```bash
socket_location=...
amount_mib=...
deflate_on_oom=...
polling_interval=...

curl --unix-socket $socket_location -i \
    -X PUT 'http://localhost/balloon' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d "{
        \"amount_mib\": $amount_mib, \
        \"deflate_on_oom\": $deflate_on_oom, \
        \"stats_polling_interval_s\": $polling_interval 
    }"
```

--------------------------------

### Configure and Update a Block Device

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/api_requests/patch-block.md

This sequence demonstrates configuring a microVM with an initial block device and then updating it with a new backing file and size. Ensure the guest does not mount the device before the update.

```bash
# Create and set up a block device.
touch ${ro_drive_path}

curl --unix-socket ${socket} -i \
     -X PUT "http://localhost/drives/scratch" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d "{
             \"drive_id\": \"scratch\",
             \"path_on_host\": \"${ro_drive_path}\",
             \"is_root_device\": false,
             \"is_read_only\": true
             \"rate_limiter\": {
                \"bandwidth\": {
                        \"size\": 100000,
                        \"one_time_burst\": 4096,
                        \"refill_time\": 150
                },
                \"ops\": {
                        \"size\": 10,
                        \"refill_time\": 250
                }
            }
         }"
# Finish configuring and start the microVM. Wait for the guest to boot.

# Before mounting the block device in the guest:
# Use another backing file of different size to effectively resize the
# vm block device.
touch ${updated_ro_drive_path}
truncate --size ${new_size}M ${updated_ro_drive_path}
# Create a filesystem in it.
mkfs.ext4 ${updated_ro_drive_path}

# PATCH the block device to use the new backing file.
curl --unix-socket ${socket} -i \
     -X PATCH "http://localhost/drives/scratch" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d "{
             \"drive_id\": \"scratch\",
             \"path_on_host\": \"${updated_ro_drive_path}\" 
         }"

# It's now safe to mount the block device in the guest and use it
# with the updated backing file.

```

--------------------------------

### Commit Signing with DCO

Source: https://github.com/firecracker-microvm/firecracker/blob/main/CONTRIBUTING.md

Example of the required 'Signed-off-by' line for DCO compliance in commit messages.

```git
Signed-off-by: Jane Smith <jane.smith@email.com>
```

--------------------------------

### Configure Block Device with Writeback Cache

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/api_requests/block-caching.md

Use this example to configure a block device with the 'Writeback' cache type. This ensures data is committed to disk upon flush requests, enhancing data integrity at the expense of performance.

```bash
curl --unix-socket ${socket} -i \
     -X PUT "http://localhost/drives/dummy" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d "{
             \"drive_id\": \"dummy\",
             \"path_on_host\": \"${drive_path}\",
             \"is_root_device\": false,
             \"is_read_only\": false,
             \"cache_type\": \"Writeback\"
         }"
```

--------------------------------

### Configure Guest Networking

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md

These commands configure the IP address, bring up the network interface, and set the default gateway within the guest VM. Ensure the IP address and gateway match your host setup.

```bash
ip addr add 172.16.0.2/30 dev eth0
ip link set eth0 up
ip route add default via 172.16.0.1 dev eth0
```

--------------------------------

### Get VMState File Version

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/snapshot-editor.md

Prints the version of the provided vmstate file. Requires the path to the vmstate file.

```bash
snapshot-editor info-vmstate version --vmstate-path <VMSTATE_PATH>
```

```bash
./snapshot-editor info-vmstate version --vmstate-path ./vmstate_file
```

--------------------------------

### Connect from Guest to Host VSOCK

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md

On the guest, create an AF_VSOCK socket and connect it to the specified host port (CID=2). This initiates a connection from the guest to the host.

```bash
socat - VSOCK-CONNECT:2:52
```

--------------------------------

### POST /snapshot/create

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/snapshot-support.md

Creates a diff snapshot of the microVM. The microVM must be in a Paused state. If track_dirty_pages is enabled, KVM's dirty page log is used. Otherwise, the mincore(2) syscall is used, which requires swap to be disabled.

```APIDOC
## POST /snapshot/create

### Description
Creates a diff snapshot of the microVM. The microVM must be in a Paused state. If track_dirty_pages is enabled, KVM's dirty page log is used. Otherwise, the mincore(2) syscall is used, which requires swap to be disabled.

### Method
PUT

### Endpoint
/snapshot/create

### Parameters
#### Request Body
- **snapshot_type** (string) - Required - Type of snapshot to create. Use "Diff" for a diff snapshot. Defaults to "Full".
- **snapshot_path** (string) - Required - Path to save the snapshot.
- **mem_file_path** (string) - Required - Path to save the memory file.

### Request Example
```json
{
  "snapshot_type": "Diff",
  "snapshot_path": "./snapshot_file",
  "mem_file_path": "./mem_file"
}
```

### Response
#### Success Response (200)
- **snapshot_path** (string) - Path to the created snapshot file.
- **mem_file_path** (string) - Path to the created memory file.

#### Response Example
```json
{
  "snapshot_path": "./snapshot_file",
  "mem_file_path": "./mem_file"
}
```
```

--------------------------------

### GET /hotplug/memory

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/memory-hotplug.md

Retrieves the current status and configuration of the virtio-mem device. This is useful for monitoring the progress of memory hotplugging operations.

```APIDOC
## GET /hotplug/memory

### Description
Queries the current status of the virtio-mem device, including total, plugged, and requested memory sizes.

### Method
GET

### Endpoint
/hotplug/memory

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **total_size_mib** (integer) - Maximum hotpluggable memory size in MiB.
- **block_size_mib** (integer) - Block size used by the device in MiB.
- **slot_size_mib** (integer) - Slot size used by Firecracker in MiB.
- **plugged_size_mib** (integer) - Currently plugged (available) memory by the guest in MiB.
- **requested_size_mib** (integer) - Target memory size set by the host in MiB.

### Response Example
```json
{
  "total_size_mib": 1024,
  "block_size_mib": 64,
  "slot_size_mib": 128,
  "plugged_size_mib": 512,
  "requested_size_mib": 512
}
```
```

--------------------------------

### Create Bridge Interface

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md

Command to create a new bridge interface on the host system. This is part of the bridge-based routing setup.

```bash
sudo ip link add name br0 type bridge
```

--------------------------------

### Create a Full Snapshot

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/snapshot-support.md

Create a full snapshot of a paused microVM. This command saves the device and emulation state, as well as a complete copy of the guest memory. Files specified by snapshot_path and mem_file_path will be created or overwritten.

```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": "Full",
            "snapshot_path": "./snapshot_file",
            "mem_file_path": "./mem_file"
    }'
```

--------------------------------

### Interactive Rebase to Squash Commits

Source: https://github.com/firecracker-microvm/firecracker/wiki/How-to-squash-commits

Use this command to start an interactive rebase session. Ensure your branch is up-to-date with master before running.

```bash
git rebase -i master
```

--------------------------------

### Retrieve AMI ID in JSON

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/mmds/mmds-user-guide.md

Fetches the 'latest/meta-data/ami-id' resource specifically in JSON format. This command is useful for getting a single metadata value.

```bash
MMDS_IPV4_ADDR=169.254.170.2
RESOURCE_POINTER_STR=latest/meta-data/ami-id
curl -s -H "Accept: application/json" "http://${MMDS_IPV4_ADDR}/${RESOURCE_POINTER_STR}"
```

--------------------------------

### Configure Guest Driver for virtio-mem (memory_hotplug.memmap_on_memory)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/memory-hotplug.md

Use 'memory_hotplug.memmap_on_memory=1' and 'memhp_default_state=online' when hot-removal is not required and the hotpluggable memory area can be significantly larger than normal memory.

```text
memory_hotplug.memmap_on_memory=1 memhp_default_state=online
```

--------------------------------

### Build Firecracker from Source

Source: https://github.com/firecracker-microvm/firecracker/blob/main/README.md

Clone the Firecracker repository and build the project using the provided development tools. Ensure Docker is running and bash is installed.

```bash
git clone https://github.com/firecracker-microvm/firecracker
cd firecracker
tools/devtool build
toolchain="$(uname -m)-unknown-linux-musl"
```

--------------------------------

### Dump Guest CPU Configuration

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/cpu_templates/cpu-template-helper.md

Retrieves the guest CPU configuration for a specific CPU model. This is the first step in creating a custom CPU template.

```bash
cpu-template-helper template dump
```

--------------------------------

### Create Network Namespace

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/network-for-clones.md

Use this command to create a new network namespace for a Firecracker clone. The namespace must exist before starting a clone within it.

```bash
sudo ip netns add fc0
```

--------------------------------

### Create and Configure Tap Device for MicroVM

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/network-setup.md

Use these commands to create a new tap device, assign it an IP address from a /30 subnet, and bring it up. This is a prerequisite for adding a new microVM.

```bash
sudo ip tuntap add tap1 mode tap
sudo ip addr add 172.16.0.5/30 dev tap1
sudo ip link set tap1 up
```

--------------------------------

### Load Snapshot with File Memory Backend

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/snapshot-support.md

Use this command to load a snapshot using the 'File' memory backend, where the kernel handles page faults. Ensure the snapshot and memory files exist.

```bash
curl --unix-socket /tmp/firecracker.socket -i \
    -X PUT 'http://localhost/snapshot/load' \
    -H  'Accept: application/json' \
    -H  'Content-Type: application/json' \
    -d '{
            "snapshot_path": "./snapshot_file",
            "mem_backend": {
                "backend_path": "./mem_file",
                "backend_type": "File"
            },
            "track_dirty_pages": true,
            "resume_vm": false
    }'
```

--------------------------------

### Enable Interactive Console and Spawn MicroVM

Source: https://github.com/firecracker-microvm/firecracker/blob/main/tests/README.md

Enable the microVM console interactively before spawning the Firecracker process. This setup is necessary for interactive console access.

```python
uvm.help.enable_console()
uvm.spawn()
uvm.basic_config()
uvm.start()
...
```

--------------------------------

### Connect from Host to Guest VSOCK

Source: https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md

On the host, connect to the AF_UNIX socket and issue a CONNECT command for the desired guest port. This establishes the connection from host to guest.

```bash
$ socat - UNIX-CONNECT:./v.sock
CONNECT 52
```

--------------------------------

### Run Firecracker Integration Tests (Ubuntu/Debian)

Source: https://github.com/firecracker-microvm/firecracker/blob/main/tests/README.md

Execute Firecracker integration tests using pytest after installing dependencies. Note: This command runs tests as root.

```sh
cd tests
sudo env /usr/local/bin/pytest integration_tests/functional/test_api.py
```