Quick Start: Running Your First VM

This guide provides a step-by-step tutorial to get a basic Linux virtual machine running with vftool.

Step 1: Prerequisites

Before you start, you need two essential components for your Linux VM:

  1. An Uncompressed Linux Kernel: vftool boots the VM using a raw, uncompressed kernel image. For arm64 Macs, this is typically a file named Image. For x86 Macs, it might be vmlinuz. You cannot use a compressed kernel (e.g., vmlinuz.gz).

  2. A Raw Disk Image: You need a bootable raw disk image (.img) containing a Linux distribution. Note that many standard distribution installers may not include the necessary virtio drivers required by Virtualization.framework. It's often easier to prepare a disk image using a tool like debootstrap on an existing Linux system.

For this guide, we'll assume you have:

  • An arm64 kernel at ~/vm/Image-5.9
  • A Debian arm64 raw disk image at ~/vm/arm64_debian.img

Step 2: Launch the Virtual Machine

Open your terminal and run the following command, adjusting the paths to your kernel and disk image. This example configures a VM with 2 CPUs and 4096MB of RAM.

vftool -k ~/vm/Image-5.9 -d ~/vm/arm64_debian.img -p 2 -m 4096 -a \"console=hvc0 root=/dev/vda1\"

Let's break down this command:

  • -k ~/vm/Image-5.9: Specifies the path to the Linux kernel.
  • -d ~/vm/arm64_debian.img: Attaches the raw disk image as the first block device (/dev/vda).
  • -p 2: Assigns 2 virtual CPUs to the VM.
  • -m 4096: Allocates 4096 MB of memory.
  • -a "...": Sets the kernel command line. console=hvc0 directs kernel output to the virtio console, and root=/dev/vda1 tells Linux where to find its root filesystem.

Step 3: Connect to the Console

After running the command, vftool will start and prepare the VM. By default, it creates a pseudo-terminal (pty) for the VM's console and waits for you to connect. The output will look similar to this:

2020-11-25 02:14:33.883 vftool[86864:707935] vftool (v0.1 25/11/2020) starting
2020-11-25 02:14:33.884 vftool[86864:707935] +++ kernel at file:///Users/matt/vm/debian/Image-5.9, initrd at (null), cmdline 'console=hvc0 root=/dev/vda1', 2 cpus, 4096MB memory
2020-11-25 02:14:33.884 vftool[86864:707935] +++ fd 3 connected to /dev/ttys016
2020-11-25 02:14:33.884 vftool[86864:707935] +++ Waiting for connection to:  /dev/ttys016

vftool is now paused, waiting for a client to connect to the VM's serial console at the specified path (/dev/ttys016 in this case).

Open a new terminal window and connect to this device using a terminal program like screen:

screen /dev/ttys016

Step 4: Booting the VM

As soon as you connect with screen, vftool will resume and start the VM. You should see the Linux kernel boot messages appear in your screen window.

Congratulations, your Linux VM is now running! You can interact with it just like any other serial console.

To exit screen, press Ctrl-A then k, and confirm with y.