FreeBSD on Hyperkit

Introduction

This document is a tutorial for FreeBSD installation using hyperkit.

Hyperkit Installation

Docker for mac

If you use the Docker for mac, then you've already have the hyperkit cli.

 $ ls -og /usr/local/bin/hyperkit
lrwxr-xr-x  1   67 Apr 19 00:04 /usr/local/bin/hyperkit -> /Applications/Docker.app/Contents/Resources/bin/com.docker.hyperkit

Homebrew

If you are a homebrew user, you can also install it without the Docker for mac.

$ brew install hyperkit

FreeBSD on Hyperkit

Requirements

🧀 userboot.so

You need to get freebsd the FreeBSD user-mode bootloader.

$ curl -LO https://github.com/moby/hyperkit/raw/master/test/userboot.so

See also: userboot.txt

🍕 FreeBSD Insterller Image

Please download an installer image from https://www.freebsd.org/where.html

This document uses FreeBSD-11.2-RELEASE-amd64-bootonly.iso

☕️ Guest image file

Please create image file. This document uses 5 GB file.

$ mkfile 5g fbsd.img

🍗 Insterller script

hyperkitrun.sh

#!/usr/local/bin/bash

usage() { echo "Usage: $0 [-d FreeBSD.iso] [-i fbsd.img] [-l userboot.so] [-u UUID]" 1>&2; exit 1; }

while getopts d:i:l:u: OPT
do
    case $OPT in
        "d" ) DISC=$OPTARG ;;
        "i" ) IMG=$OPTARG ;;
        "l" ) USERBOOT=$OPTARG ;;
        "u" ) UUID="-U $OPTARG" ;;
        *) usage ;;
    esac
done
shift `expr $OPTIND - 1`

if [ -z "$USERBOOT" ]; then
    USERBOOT="userboot.so"
fi

if [ -z "$IMG" ]; then
    IMG="fbsd.img"
fi

if [ "$DISC" ]; then
    BOOTVOLUME="$DISC"
    IMG_CD="-s 3:0,ahci-cd,$DISC"
else
    BOOTVOLUME="$IMG"
fi

MEM="-m 2G"
SMP="-c 2"
PCI_DEV="-s 0:0,hostbridge -s 31,lpc"
NET="-s 2:0,virtio-net"
IMG_HDD="-s 4:0,virtio-blk,$IMG"
LPC_DEV="-l com1,stdio"
ACPI="-A"

HYPERKIT_BIN=`type -p hyperkit`

$HYPERKIT_BIN $ACPI $MEM $SMP $PCI_DEV $LPC_DEV $NET $IMG_CD $IMG_HDD $UUID -f fbsd,$USERBOOT,$BOOTVOLUME

FreeBSD Installation

$ sudo ./hyperkitrun.sh -d FreeBSD-11.2-RELEASE-amd64-bootonly.iso

Run VM

$ sudo ./hyperkitrun.sh

Network interface UUID

If you want the same IP address across VM reboots, generate UUID to assign to a particular VM.

 $ python -c 'import uuid; print uuid.uuid4()'
0a02859a-a7cd-40cd-af18-ff2fa559a00a

$ sudo ./hyperkitrun.sh -u 0a02859a-a7cd-40cd-af18-ff2fa559a00a

See also: Apple's vmnet framework.

Conclusion

This document is a part of updates for this tutorial. mist64/xhyve has no updates frequently now. So I wrote this document using moby/hyperkit. The hyperkit is a core component of Docker For Mac. It has a xhyve/bhyve based hypervisor which is optimized for lightweight virtual machines and container deployment. This project managed 9 maintainers and 50 contributors (2018-10-01).

I will continue to update the tutorial document here. If there's something, please ask me @tanb.