Firecracker boots instances with a particular Kernel version and Rootfs.

Download Guest Kernel and RoofFS

curl -sSL -o hello-vmlinux.bin http://assets.joinscrapbook.com/firecracker/hello-vmlinux.bin
curl -sSL -o hello-rootfs.ext4 http://assets.joinscrapbook.com/firecracker/hello-rootfs.ext4

The file hello-vmlinux.bin is the guest Kernel. The rootfs (Operating System) is packaged as hello-rootfs.ext4.

If you want to customise the Kernel version or rootfs then we recommend you investigate Linuxkit.

Start

With the binaries and Guest Kernel and RootFS in place, it's time to start Firecracker binary.

When starting, a sock file path is defined. The sock file is used to communicate with the Firecracker API.

rm /tmp/firecracker.sock
./firecracker --api-sock /tmp/firecracker.sock

The configuration of the instance to launch is defined via a series of HTTP requests. These commands need to run within the second terminal window.

Set the guest kernel

The first configuration is to define the boot source and the kernel to use. It will look in the same directory as the Firecracker binary. A series of boot arguments can be passed to the Kernel to configure how it launches.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/boot-source' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "kernel_image_path": "./hello-vmlinux.bin", "boot_args": "console=ttyS0 reboot=k panic=1 pci=off" }'

The response of 204 No Content indicates that the request was successful.

Set the guest rootfs

Next, define the rootfs and the guest operating system that will be booted.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/drives/rootfs' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "drive_id": "rootfs", "path_on_host": "./hello-rootfs.ext4", "is_root_device": true, "is_read_only": false }'

Configure Logging

Firecracker outputs various logs and metrics about how the system is performing to external systems. For now, disable to metrics using the following command:

curl -fsS --unix-socket /tmp/firecracker.sock -i \ -X PUT "http://localhost/logger" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "log_fifo": "/dev/null", "metrics_fifo": "/dev/null", "level": "Error", "show_level": true, "show_log_origin": false }'

Start the guest machine

The instance is now configured and can be started. This is done by issuing a InstanceStart action.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/actions' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "action_type": "InstanceStart" }'

Within the first terminal window, you should see the VM start booting and after a few seconds, a login prompt will appear. If you see the error KVM_EXIT_FAIL_ENTRY then a problem has occurred.

The Firecracker is the parent process ID that will manage the instance. This can be viewed within the process tree.

ps aux | grep firecracker

The VM is running as a KVM instance that is also listed as a process.

ps aux | grep kvm

With the instance running, access via the first terminal window, it's now possible to login as root with the password root.

Instance Types

It's possible explore the instance to identify how it's configured.

CPU Information: cat /proc/cpuinfo

Disk Space: df -h

Memory: free -mh

Linux Version: uname -a

The default microVM will have 1 vCPU and 128 MiB RAM. This can be customised within the next step.

Shutdown Instance

In future, to shutdown the instance will be done using a HTTP request with the action InstanceHalt.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/actions' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "action_type": "InstanceHalt" }'

At the moment, it needs to be done by killing the Firecracker process.

ps aux | grep -ie firecracker | awk '{print $2}' | xargs kill -9

The instance type can be customised, to include additional CPU, memory and networking settings.

Restart Firecracker

In the previous step we shutdown Firecracker. Restart the process to launch the new instance.

rm /tmp/firecracker.sock
./firecracker --api-sock /tmp/firecracker.sock

Set the guest kernel

As before, set the Kernel and Rootfs.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/boot-source' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "kernel_image_path": "./hello-vmlinux.bin", "boot_args": "console=ttyS0 reboot=k panic=1 pci=off" }' curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/drives/rootfs' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "drive_id": "rootfs", "path_on_host": "./hello-rootfs.ext4", "is_root_device": true, "is_read_only": false }' curl -fsS --unix-socket /tmp/firecracker.sock -i \ -X PUT "http://localhost/logger" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "log_fifo": "/dev/null", "metrics_fifo": "/dev/null", "level": "Error", "show_level": true, "show_log_origin": false }'

Customise Instance

Using a HTTP call, it's possible to configure the CPU and Memory allocated. In this case, it doubles the capacity.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/machine-config' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "vcpu_count": 2, "mem_size_mib": 256 }'

Start

It can now be started as before.

curl --unix-socket /tmp/firecracker.sock -i \ -X PUT 'http://localhost/actions' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "action_type": "InstanceStart" }'

View Changes

As before, login and you can explore the instance with the increased capacity.

Login as root with the password root.

CPU Information: cat /proc/cpuinfo

Memory Information: free -mh