firectl

Follow these steps to set up a MicroVM on an m5d.metal instance using Amazon Linux 2:

1. Download and verify firectl
2. Install Firecracker binary to /usr/local/bin/firecracker
3. Grant KVM permissions to your user
4. Download kernel and rootfs
5. Launch the MicroVM

# 1. Get firectl binary
curl -Lo firectl https://firectl-release.s3.amazonaws.com/firectl-v0.1.0
curl -Lo firectl.sha256 https://firectl-release.s3.amazonaws.com/firectl-v0.1.0.sha256
sha256sum -c firectl.sha256
chmod +x firectl

# 2. Get Firecracker binary
curl -Lo firecracker https://github.com/firecracker-microvm/firecracker/releases/download/v0.16.0/firecracker-v0.16.0
chmod +x firecracker
sudo mv firecracker /usr/local/bin/firecracker

# 3. Give read/write access to KVM
sudo setfacl -m u:${USER}:rw /dev/kvm

# 4. Download kernel and root filesystem
curl -fsSL -o hello-vmlinux.bin https://s3.amazonaws.com/spec.ccfc.min/img/hello/kernel/hello-vmlinux.bin
curl -fsSL -o hello-rootfs.ext4 https://s3.amazonaws.com/spec.ccfc.min/img/hello/fsfiles/hello-rootfs.ext4

# 5. Create microVM
./firectl \
  --kernel=hello-vmlinux.bin \
  --root-drive=hello-rootfs.ext4

firectl is a command-line interface for managing and running Firecracker MicroVMs. It wraps the firecracker-go-sdk to provide a CLI entrypoint for configuring and starting virtual machines.

Key behaviors:

• Binary Discovery: By default, it looks for a binary named firecracker in your PATH. You can specify a custom path using the --fc-binary flag (implied by the FcBinary option in the source).
• Lifecycle Management: It handles the startup, metadata configuration, and graceful shutdown of the VMM. It intercepts system signals like SIGTERM, SIGINT, and SIGQUIT to ensure the VM is either shut down cleanly or stopped forcefully.
• Signal Handling:
  • SIGTERM or os.Interrupt: Triggers a clean m.Shutdown(ctx).
  • SIGQUIT: Triggers a forced m.StopVMM().
• Debugging: Enabling the --debug flag sets the log level to DebugLevel for both the application and the Firecracker SDK.

The following options are available for configuring the Firecracker MicroVM via firectl.

Application Options:
      --firecracker-binary=     Path to firecracker binary
      --kernel=                 Path to the kernel image (default: ./vmlinux)
      --kernel-opts=            Kernel commandline (default: ro console=ttyS0 noapic reboot=k panic=1 pci=off nomodules)
      --root-drive=             Path to root disk image, optionally suffixed with :ro or :rw
      --root-partition=         Root partition UUID
      --add-drive=              Path to additional drive, suffixed with :ro or :rw, can be specified multiple times
      --tap-device=             NIC info, specified as DEVICE/MAC
      --vsock-device=           Vsock interface, specified as PATH:CID. Multiple OK
      --vmm-log-fifo=           FIFO for firecracker logs
      --log-level=              vmm log level (default: Debug)
      --metrics-fifo=           FIFO for firecracker metrics
  -t, --disable-smt             Disable CPU Simultaneous Multithreading
  -c, --ncpus=                  Number of CPUs (default: 1)
      --cpu-template=           Firecracker CPU Template (C3 or T2)
  -m, --memory=                 VM memory, in MiB (default: 512)
      --metadata=               Firecracker Metadata for MMDS (json)
  -l, --firecracker-log=        pipes the fifo contents to the specified file
  -s, --socket-path=            path to use for firecracker socket, defaults to a unique file in in the first existing directory from {$HOME, $TMPDIR, or /tmp}
  -d, --debug                   Enable debug output

The options struct provides a getFirecrackerConfig() method that translates CLI flags into a firecracker.Config object used by the firecracker-go-sdk.

This method handles:

1. Metadata Validation: Validates that the --metadata string is valid JSON.
2. Network Setup: Parses --tap-device strings into firecracker.NetworkInterface objects.
3. Block Device Setup: Parses --root-drive and --add-drive into models.Drive objects. Note that the root drive is assigned DriveID: "1" and additional drives are assigned IDs starting from 2.
4. Vsock Setup: Parses --vsock-device strings into firecracker.VsockDevice objects.
5. FIFO Management: Sets up log and metrics FIFOs, creating temporary directories if necessary.
6. Jailer Integration: If --jailer is provided, it constructs a firecracker.JailerConfig using a NaiveChrootStrategy based on the kernel image.

The firectl CLI uses a set of flags to configure the Firecracker VMM, the kernel, drives, and the Jailer. Below are the primary configuration groups available via command-line arguments.

Firecracker VMM Configuration

• --firecracker-binary: Path to the firecracker binary.
• --kernel: Path to the kernel image (default: ./vmlinux).
• --kernel-opts: Kernel commandline (default: ro console=ttyS0 noapic reboot=k panic=1 pci=off nomodules).
• --initrd-path: Path to the initrd.
• --memory / -m: VM memory in MiB (default: 512).
• --ncpus / -c: Number of CPUs (default: 1).
• --disable-smt / -t: Disable CPU Simultaneous Multithreading.
• --cpu-template: Firecracker CPU Template (C3 or T2).
• --metadata: Firecracker Metadata for MMDS (must be a JSON string).
• --socket-path / -s: Path to use for the firecracker socket. If not provided, a unique file is generated in $HOME, $TMPDIR, or /tmp.

Storage Configuration

• --root-drive: Path to the root disk image.
• --root-partition: Root partition UUID.
• --add-drive: Path to additional drives. Must be suffixed with :ro (read-only) or :rw (read-write). This flag can be used multiple times.

Networking and Vsock

• --tap-device: NIC info, specified as DEVICE/MAC (e.g., tap0/00:11:22:33:44:55). Can be specified multiple times.
• --vsock-device: Vsock interface, specified as PATH:CID. Can be specified multiple times.

Logging and Metrics

• --vmm-log-fifo: FIFO for firecracker logs.
• --log-level: VMM log level (default: Debug).
• --metrics-fifo: FIFO for firecracker metrics.
• --firecracker-log / -l: Pipes the FIFO contents to the specified file.