FreeBSD guests

MacVisor runs FreeBSD on Apple's Virtualization framework, with FreeBSD's own loader and stock GENERIC kernel and no emulator. You use FreeBSD VMs over SSH and their console, with the limits below.

A FreeBSD VM is a kind of VM of its own, beside Linux, macOS and Windows. VM Settings, the menu bar, mvz list and mvz show say FreeBSD, and --json gives "os": "freebsd".

What you can make

There is no Installer ISO for FreeBSD: MacVisor can't run FreeBSD's installer. Start from the catalogue image, or from a disk image of a FreeBSD that is already installed.

Both catalogue images are checked against FreeBSD's SHA-256 lists. A FreeBSD image downloaded now is named FreeBSD 15.1; one downloaded before keeps (Experimental) in its name until you rename it. See Cloud images.

Create a FreeBSD VM

In the app:

1. Press ⌘N and choose FreeBSD.
2. Under Cloud Image, pick FreeBSD 15.1 or the 16.0-CURRENT snapshot. Image File or URL… takes your own image instead, and Template appears once you have FreeBSD templates.
3. Under Account, type a Password for the console, or leave it blank and MacVisor makes a random one.
4. Click Create.

From the command line:

mvz create freebsd bsd                          # FreeBSD 15.1
mvz create freebsd-current bsd16                # the 16.0-CURRENT snapshot
mvz create freebsd bsd2 --password-file ~/bsd-password.txt
mvz start bsd --headless
mvz wait bsd --ssh                              # returns once the first boot's setup is done
mvz shell bsd

The defaults are those of a Linux VM: 4 vCPUs, 4 GiB of memory and a 64 GiB disk. The form hides what FreeBSD can't use, and says so: container runtimes, shared folders, Rosetta and automatic port forwarding. mvz create refuses --runtime and --home for FreeBSD.

Which files are FreeBSD

• In New VM, a file chosen under FreeBSD makes a FreeBSD VM whatever it's called, and one chosen under Linux makes a Linux VM.
• With mvz, --os freebsd makes a disk image or URL FreeBSD, and --os linux makes it Linux. Without --os, mvz goes by the catalogue, then the file's name, then its partitions. A catalogue image can't be made the other system.
• A template remembers what it was made as. Given for a template already in the library, --os changes it for later VMs; VMs made from it before are unchanged, and create, images pull and New VM say so (templateOS in --json).

mvz create ~/Downloads/my-freebsd.qcow2 bsd3 --os freebsd
mvz create ~/Downloads/pfSense-CE-2.8.0.img fw --no-cloud-init --os freebsd

The first boot

create doesn't start the VM. The first boot takes 2 to 5 minutes and needs network. FreeBSD's image bootstraps pkg, then MacVisor installs sudo, turns on ntpd, and grows the root filesystem to the disk's size.

MacVisor follows the setup over SSH. The Overview's FreeBSD VM card shows Setting up FreeBSD with a spinner, then Set up: ready for SSH. mvz wait returns only once the setup has finished. MacVisor then installs its agent over SSH. If the setup couldn't install sudo, for lack of network, the Overview says so.

Later boots take about a minute and aren't set up again.

How MacVisor boots FreeBSD

MacVisor attaches a small read-only boot volume to every FreeBSD VM, in front of its disk. It starts FreeBSD's loader from the VM's disk with the settings FreeBSD needs on Apple's virtual hardware, so nothing in the guest needs changing. The same boot volume starts FreeBSD-based appliances and imported FreeBSD VMs.

FreeBSD's kernel draws nothing on the VM's display after the loader. The window shows FreeBSD's console instead.

Sign in

Use a FreeBSD VM over SSH, or at its console in the VM's window.

• SSH: Open in Terminal on the Overview, mvz shell <vm>, or ssh <vm>.mvz. SSH takes keys only. mvz exec <vm> "<command line>" runs a line in the guest's shell, pipes included.
• The account is your Mac user name, with your SSH keys, in the wheel and operator groups. MacVisor also adds its own SSH key, which it uses to read the guest's details, install its agent and shut the VM down. Leave that key in ~/.ssh/authorized_keys.
• sudo isn't in FreeBSD's base system. MacVisor installs it at the end of the first boot, and the account uses it without a password, as in Linux VMs. sudo -i gives a root shell.
• root has no password and is locked once sudo is in, so it can't sign in at the console.
• ntpd is on, so the clock stays right without the agent too.

The account's password

The password is for the login prompt on the console. SSH doesn't take it.

• It's the one you typed in New VM's Password field or gave with --password-file <file|->, or, left blank, a random one MacVisor made.
• Show Password, Copy Password and Type Password on the Overview's FreeBSD VM card, Type Password in the VM's window (⌃⌘V, which types into the console), and mvz password <vm> give it to you.
• A password you chose is deleted from MacVisor by itself once the first boot's setup is done. A random one stays until Delete Password…, or mvz password <vm> --delete, which works once setup is done. The account keeps its password either way.
• A copy of the VM keeps the original's password: FreeBSD sets an account up only at a disk's first boot. Change it in the guest with passwd.
• An appliance (cloud-init off) has no account, so no field and no password.

The console

Serial Console is always on for a FreeBSD VM: it's the VM's console, on the guest's /dev/ttyV0.0.

• In the VM's window, the display shows FreeBSD's loader first. Once FreeBSD writes its login prompt to the console, about a minute into the boot, the window turns to the console by itself, unless you chose Display first. The toolbar's Display | Console switch, left of the guest tools status, turns between the two, as does View → Show Console and Show Display (⌃⌘C).
• In Terminal, mvz console <vm> shows the same console. Press Control-] to detach.

Sign in as your account with its password. In the window, Type Password types it for you, and Copy, Paste and Select All are in the Edit menu. See Display and console for everything the console does.

MacVisor's agent

MacVisor's agent runs in FreeBSD VMs too. FreeBSD has no virtio-vsock driver, so the agent reaches the Mac through the VM's third serial port, /dev/ttyV2.0. It gives a FreeBSD VM:

• The guest's details (FreeBSD version, kernel, hostname) and addresses, for the Overview, mvz ip and <vm>.mvz.
• The memory the guest uses, on the Overview's Memory card, without a pressure level.
• File transfer both ways: mvz send <vm> <file> puts files in the home folder, and macvisor-send <file> in the guest sends one to the Mac.
• Port forwards you add in VM Settings → Network or with mvz ports add.
• A clean Shut Down and Restart, the clock set after a pause or a resume, and the guest's writes flushed before a snapshot.
• mvz shell and mvz exec carried through it, so they work without the network. Without the agent they go over the network. If the agent stops or the guest reboots, a session ends within about 20 seconds.

Install it

New FreeBSD VMs have Guest Tools on, and MacVisor installs the agent over SSH once the first boot's setup is done. No disc is needed. Later versions of the agent arrive from the Mac by themselves.

A FreeBSD VM made before gets the agent this way:

1. Shut it down, so it gets MacVisor's serial ports (see FreeBSD VMs made before).
2. Turn on Enable Guest Tools in VM Settings → Guest Tools.
3. Start it, and click Install Agent on the Overview's Guest Tools card.

By hand, attach the guest tools disc (Attach Guest Tools on the Overview, or mvz tools attach <vm>) and run:

sudo mount -t cd9660 /dev/iso9660/MACVISOR_AGENT /mnt && sudo sh /mnt/install-freebsd.sh

This installs the macvisor_agent service. In an appliance, which has no MacVisor account, Install Agent is refused: run the same command as root from its shell, if the appliance lets you install software.

Enable Guest Tools must be on in the VM's settings either way, because the agent's access token comes on a disc MacVisor attaches at each start: the cloud-init seed, or, with cloud-init off, a small disc with only the token. With Guest Tools off, the window's guest agent item says SSH Only.

Check it

In the guest:

sudo service macvisor_agent status
tail /var/log/macvisor-agent.log

The Overview's Guest Tools card shows Running once it connects. See Guest tools stay disconnected.

The QEMU guest agent

Every FreeBSD VM also has a serial port for a QEMU guest agent, /dev/ttyV1.0. MacVisor uses it for the guest's addresses and details, and to shut the VM down, while MacVisor's agent isn't connected. It's most useful in FreeBSD-based appliances. To run it:

sudo pkg install -y qemu-guest-agent
sudo sysrc qemu_guest_agent_enable=YES qemu_guest_agent_flags="-d -m isa-serial -p /dev/ttyV1.0"
sudo service qemu-guest-agent start

See QEMU guest agent.

Shut down and restart

Shut Down, Restart, mvz stop and mvz restart try each of these in turn, and use the first that answers:

1. MacVisor's agent, if it's connected.
2. The QEMU guest agent, if one answers on /dev/ttyV1.0.
3. SSH with MacVisor's key, in a VM MacVisor set up: shutdown -p now, which the operator group may run.
4. The virtual power button.

A Restart shuts FreeBSD down the same way, then starts the VM again through the background service: its window closes and opens again. Shut Down or mvz stop during a Restart leaves the VM off.

The power button

FreeBSD shuts down cleanly on the virtual power button, in 7 to 17 seconds when it's idle. MacVisor's boot volume sets this up, so nothing in the guest needs changing.

FreeBSD ignores a press while its boot scripts still run, such as the first boot's package install or a background fsck after a power cut. So if FreeBSD hasn't begun to shut down a minute after the button, MacVisor presses it again. If the VM still runs 30 seconds later, the Tasks pane says so. MacVisor never powers it off on its own: shut it down from inside (mvz shell <vm>, then sudo shutdown -p now, or at its console), or use Power Off when nothing will be lost.

A FreeBSD-based appliance may not act on the button. Shut it down from its web UI or console.

What works

Start, restart (from MacVisor or from inside the guest), pause, suspend and resume, live and disk-only snapshots and revert, clones and linked clones, templates, <vm>.mvz names, mvz ip, the serial console, and with the agent, file transfer and port forwards.

Limits

FreeBSD has no virtio-fs, and its agent does less than the Linux one. FreeBSD VMs don't have:

• A display after the loader. The window shows the console instead.
• An installer ISO. Make the VM from the catalogue or a disk image.
• Clipboard sharing.
• Shared folders, so mvz create refuses --home. Copy files with mvz send, or scp to <vm>.mvz.
• Container runtimes, so mvz create refuses --runtime.
• Automatic port forwarding. Add forwards yourself (with the agent), reach the VM at its address or <vm>.mvz, or use ssh -L.
• Fixed addresses. FreeBSD's DHCP client doesn't identify itself the way macOS matches reservations, so a reservation, automatic or by hand, may not apply. Reach the VM as <vm>.mvz.
• Rosetta, Free Unused Space, and MacVisor's AI gateway.
• A memory pressure level on the Memory card.

Without the agent there is also no file transfer, no port forwarding, and no flush of the guest's writes before a disk-only snapshot of a running VM.

FreeBSD VMs made before

A FreeBSD VM made with MacVisor 27.2.0 or earlier changes once it's shut down after the update (at once if it already is), never while it runs or is suspended. MacVisor records it as a FreeBSD VM, gives it three serial ports (its console, the QEMU guest agent's and MacVisor's agent's), and gives it a fresh EFI variable store (NVRAM). FreeBSD-based appliances change the same way. There is nothing for you to do.

• The power button works from its next start from shut down.

• The guest is left as it is: no login prompt on its console, no password, and no agent until you install it. For a login prompt, add this line to the guest's /etc/ttys, run sudo kill -HUP 1, and give the account a password with sudo passwd <account>:

  ttyV0.0 "/usr/libexec/getty 3wire" vt100 onifexists insecure

• MacVisor 27.2.0 and earlier can't open the VM once it has changed, nor a FreeBSD VM made with 27.2.1 or later. MacVisor keeps the VM's config.json and efi-vars.bin as they were in a .pre-27.2.1 folder inside its package. To go back to 27.2.0 with it, shut the VM down and copy both files from that folder back into the package, replacing the ones there.

The same /etc/ttys line gives an imported FreeBSD VM a login prompt on its console.

Troubleshooting

• The window shows no login prompt. See A FreeBSD VM's window shows no login prompt.
• Shut Down doesn't stop it. See Shut Down doesn't stop a FreeBSD VM.
• The agent doesn't connect. See Guest tools stay disconnected.
• mvz shell is refused. MacVisor's own SSH key and your keys must stay in the account's ~/.ssh/authorized_keys, and MacVisor needs the Local Network permission to reach the guest without the agent.