A set of utilities (vmcli + vmctl) for macOS Virtualization.framework

Overview

VMCLI

A set of utilities to help you manage VMs with Virtualization.framework

vmctl-demo

Installation

Prerequisites

  • macOS Big Sur (11+)
  • XCode.app installed
# make sure xcode command-line tools are installed
xcode-select --install

# run build, install. This will install vmcli and vmctl to /usr/local/bin
make
sudo make install

You have now finished installing vmcli and vmctl

Set environment variable VMCTLDIR to ~/VMs so vmctl knows how to find VMs. If you don't set this, vmctl will use current working directory to find VMs.

> ~/.zprofile export VMCTLDIR="$HOME/VMs" ">
echo 'export VMCTLDIR="$HOME/VMs"' >> ~/.zprofile
export VMCTLDIR="$HOME/VMs"

Provision a Ubuntu VM, and install that to ~/VMs. The VM will auto create your user with your ssh public key at ~/.ssh/id_rsa.pub.

make build/vm/ubuntu
mv build/vm/ubuntu "${VMCTLDIR}/ubuntu"

Optionally expand the VM volume, for example to 16G.

dd if=/dev/null of="${VMCTLDIR}/ubuntu/disk.img" bs=1g count=0 seek=16

Optionally edit the VM config for more RAM and/or CPU cores

vi "${VMCTLDIR}/ubuntu/vm.conf"

Start the VM

vmctl start ubuntu

Attach to the serial console, use (CTRL+A - D to quit)

vmctl attach ubuntu

You can use vmctl ip ubuntu to check your VM IP.

Wait for the VM to boot and ssh into the VM

vmctl ssh ubuntu

You should shutdown the VM using ssh within the VM. If that's not an option, you can forcibly shut it down.

vmctl stop ubuntu

Known Issues

  • Virtual Machine cannot be started with networking when InternetSharing is already enabled. See #5.

Usage

vmcli

USAGE: vmcli [--cpu-count 
   
    ] [--memory-size 
    
     ] [--memory-size-suffix 
     
      ] [--disk 
      
        ...] [--cdrom 
       
         ...] [--network 
        
          ...] [--balloon 
         
          ] [--bootloader 
          
           ] [--kernel 
           
            ] [--initrd 
            
             ] [--cmdline 
             
              ] [--escape-sequence 
              
               ] OPTIONS: -c, --cpu-count 
               
                 CPU count (default: 1) -m, --memory-size 
                
                  Memory Bytes (default: 512) --memory-size-suffix 
                 
                   Memory Size Suffix (default: MiB) -d, --disk 
                  
                    Disks to use --cdrom 
                   
                     CD-ROMs to use -n, --network 
                    
                      Networks to use. e.g. aa:bb:cc:dd:ee:ff@nat for a nat device, or ...@en0 for bridging to en0. Omit mac address for a generated address. (default: nat) --balloon 
                     
                       Enable / Disable Memory Ballooning (default: true) -b, --bootloader 
                      
                        Bootloader to use (default: linux) -k, --kernel 
                       
                         Kernel to use --initrd 
                        
                          Initrd to use --cmdline 
                         
                           Kernel cmdline to use --escape-sequence 
                          
                            Escape Sequence, when using a tty (default: q) -h, --help Show help information. 
                          
                         
                        
                       
                      
                     
                    
                   
                  
                 
                
               
              
             
            
           
          
         
        
       
      
     
    
   

vmctl

usage: vmctl {start|stop|attach|ip|ssh} vm
       vmctl list

References

SimpleVM is a proof-of-concept using Virtualization.framework by KhaosT

vftool is a very similar tool written by evansm7 but in Objective-C not Swift.

Comments
  • "make build/vm/ubuntu" failed

    After replacing id_rsa.pub w/ id_ecdsa.pub, I ran "make build/vm/ubuntu" which downloaded a bunch of stuff and eventually failed w/:

    (initramfs) [6ndd: invalid number: '1m'

    bug 
    opened by ruschein 5
  • Virtualization.framework is crashing on start

    Virtualization.framework is crashing on start

    I followed the README on a MacBook Air M1 in order to start an ubuntu VM. Nothing was printed after executing vmctl start ubuntu and vmctl attach ubuntu was not able to find a screen. A new crash report was created with the information:

    Generic Platform
    FIXME: "Unhandled system register S3_0_C0_C6_2"
    

    I am running macOS 12.2.1

    opened by florin-pop 4
  • Debian doesn't boot properly or console input doesn't work

    Debian doesn't boot properly or console input doesn't work

    When trying to boot a Debian 10.8 installation, boot process got stuck (picture below). MacBook Pro 2020, M1 Debian 10.8 Linux-Kernel 4

    vmcli --kernel=linux --initrd=initrd --cpu-count=4 --memory-size=3072 --disk=disk.img --cmdline='console=tty0 console=hvc0 root=/dev/mapper/vm--vg-root ro apparmor=0' --network=nat image

    opened by tiehfood 3
  • vm gzip error

    vm gzip error

    I continue to get the following error:

    ❯ sudo make build/vm/ubuntu mkdir -p build mkdir -p build/vm mkdir -p build/vm/ubuntu cd build/vm/ubuntu && ../../../vmbuilders/ubuntu.sh % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 11.1M 100 11.1M 0 0 3169k 0 0:00:03 0:00:03 --:--:-- 3168k gunzip: vmlinux.gz: not in gzip format make: *** [build/vm/ubuntu] Error 1

    opened by PDX4N6 3
  • Unable to resize vm volume

    Unable to resize vm volume

    Hi there,

    I followed the instructions in the readme and tried to increase the vm volume to 16G by: dd if=/dev/null of="${VMCTLDIR}/ubuntu/disk.img" bs=1g count=0 seek=16

    I can see that in my vm folder the disk.img size increase to 16G

    total 3171224 -rw-r--r-- 1 ctsai staff 17179869184 Sep 13 10:51 disk.img drwx------ 3 ctsai staff 96 Sep 12 15:00 screen -rw-r--r-- 1 ctsai staff 13 Sep 7 11:17 0.ipaddr -rw-r--r-- 1 ctsai staff 128 Sep 7 10:25 vm.conf drwxr-xr-x 7 ctsai staff 224 Sep 7 10:20 ubuntu -rw-r--r-- 1 ctsai staff 13 Jun 14 08:54 0.macaddr -rw-r--r-- 1 ctsai staff 851 Jun 14 08:53 user.yaml -rw-r--r-- 1 ctsai staff 27621838 Jun 14 08:52 initrd -rw-r--r-- 1 ctsai staff 13672704 Jun 14 08:52 vmlinux

    but when I start the vm I only see 1.4G storage:

    Welcome to Ubuntu 20.04.4 LTS (GNU/Linux 5.4.0-117-generic x86_64)

    • Documentation: https://help.ubuntu.com
    • Management: https://landscape.canonical.com
    • Support: https://ubuntu.com/advantage

    System information as of Tue Sep 13 17:53:47 UTC 2022

    System load: 0.05 Usage of /: 98.9% of 1.40GB Memory usage: 9% Swap usage: 0% Processes: 109 Users logged in: 0 IPv4 address for enp0s1: 192.168.65.3 IPv6 address for enp0s1: fd73:e176:203:8e05:4c8c:42ff:fe46:31b8

    => / is using 98.9% of 1.40GB

    0 updates can be applied immediately.

    The list of available updates is more than a week old. To check for new updates run: sudo apt update

    Last login: Mon Sep 12 22:00:34 UTC 2022 on hvc0

    Can anyone point me in the right direction here? Thanks

    opened by JeffCT0216 2
  • vmctl list  lists directories not VMs

    vmctl list lists directories not VMs

    ./build/vmctl list ● stopped Applications ● stopped Library ● stopped System ● stopped Users ● stopped Volumes ● stopped bin ● stopped cores ● stopped dev ● stopped etc ● stopped home ● stopped opt ● stopped private ● stopped sbin ● stopped tmp ● stopped usr ● stopped var

    opened by bjonnh-work 2
  • How to make a connection between two guest VMs?

    How to make a connection between two guest VMs?

    I have create two guest VMs(w1, w2)and can ssh into both of them from the host Mac. But I can't ping or anything from w1 to w2 or from w2 to w1. Please someone help me to resolve this issue.

    Network configuration

    • Host Mac: 192.168.64.1
    • w1: 192.168.64.8
    • w2: 192.168.64.9

    Ping test result

    • Success: host Mac -> w1, w2
    • Success: w1, w2 -> host Mac
    • Fail: w1 -> w2 (Destination Host Unreachable)
    • Fail: w2 -> w1 (Destination Host Unreachable)

    HTTP test result (via curl)

    • Success: host Mac -> w1, w2
    • Success: w1, w2 -> host Mac
    • Fail: w1 -> w2, w2 -> w1
    • Success: w1 -> w1, w2 -> w2
    opened by ChangheeOh 2
  • Shared folder or separate image for folder

    Shared folder or separate image for folder

    I have once encountered cloud init error after restarting Ubuntu, probably due to bug or wrongly remove essential packages would cause major problematics and not able to SSH with vmctl.

    Linux partition could be customize with separate home image or allow user definite separate partition would be essential to avoid data loss in case we screw up?

    Or a shared folder we can work from Linux and macOS is a neat feature.

    opened by vmterm 2
  • Unable to start VM with networking

    Unable to start VM with networking

    Hi,

    Firstly, thanks for this project. Extremely useful. 😄

    I have noticed an issue, and found the root cause, but I'd like to discuss the direction of any PR.

    The issue:

    When running vmcli on main with the networking portion left in, the VM never starts and silently fails. If I remove the networking code, then vmcli starts the VM with no issues (except no networking, obviously).

    Debugging this, found the following log in console: default 08:55:10.482714+0000 InternetSharing VMNet in NAT mode can't be started now due to an active InternetSharing session on en0.

    The fix:

    Disable InternetSharing. Simple as that. Then everything works as expected (with a NAT device, haven't tested bridge mode).

    How should we "fix" this? A note in documentation? Or a check in the code for this scenario (if possible?)?

    bug documentation 
    opened by SimonTate 2
  • Add tag and read-only options for shared folders

    Add tag and read-only options for shared folders

    This extends the --folder argument to allow optionally specifying the virtofs tag and a read-only option. This makes it easier to share host directories whose paths might exceed the 36-byte limit for tags, by using a shorter tag instead of the path. While extending the folder argument parsing, add support for read-only shares as well.

    opened by sigmaris 1
  • Support sharing folders with host

    Support sharing folders with host

    This is supported only on Monterey (12.0) and later.

    In my limited tests with 12.1, the underlying macOS virtiofs implmentation seems pretty flaky. For example, some basic git operations fail in the guest, but work fine in the host. But offering up the PR now anyway, in the hope that this becomes more robust in later releases.

    Closes #20.

    opened by simonchatts 1
  • Rewrite vmctl in swift

    Rewrite vmctl in swift

    In order to enable support for multiple different OS's and first boot setups, this commit rewrites VMCTL in swift from shell script.

    This rewrite enables support for other operating systems and first boot setups via the Provider protocol. For example, the default provider used now is the UbuntuProvider which mimics the setup from the vmbuilders/ubuntu.sh script. The other provider implemented is the UbuntuDockerProvider. This one sets up an Ubuntu instance with a few packages and other niceties ready to go for using it as a docker host.

    In addition to the Provider protocol, there are now templates along with each provider. These templates describe the various cloud-init yaml files needed to set up a virtual machine on first boot. By using templates we can support quite a bit of variety in the setup and provide specific information to them via the implementing Provider.

    Lastly, this rewrite also adds the ability to create new virtual machines via the vmctl create command. This command will download and create all of the files necessary for a new virtual machine.

    opened by endoze 0
  • Request VM stop upon exit

    Request VM stop upon exit

    If we get an escape-q sequence, SIGINT or SIGTERM, request the VM to stop (i.e. graceful shutdown, simulates pressing the power button) and wait for a configurable timeout before forcing a shutdown. This should let most Linux VMs shut down properly when quitting. Sending SIGPIPE or SIGHUP still offers a way to exit the VM immediately/uncleanly.

    This also fixes issues with the signal handling where some signals weren't handled as intended (signals can't be bitwise ORed together).

    I also had to remove the @available(macOS 12, *) on line 136 as it was causing a compilation error: stored properties cannot be marked potentially unavailable with '@available' when compiling with Xcode 14 on macOS 12.6. I'm not normally writing Swift, so please double-check this :)

    opened by sigmaris 0
  • How to create a vmbuilder for MacOS

    How to create a vmbuilder for MacOS

    Apple has an example for virtualizing macos under macos:

    https://developer.apple.com/documentation/virtualization/virtualize_macos_on_a_mac

    Can i use vmcli for this purpose too and when it is possible how can i do this?

    vmcli and vmctl are awesome tools by the way 👍 .

    opened by rubiktubik 0
  • FIlesystem corruption after every shutdown

    FIlesystem corruption after every shutdown

    I am unable to find a way to cleanly stop the VM without it corrupting the ext4 filesystem in disk.img. I am using the default ubuntu setup as built with the makefile. I have tried:

    • In the VM guest: sudo shutdown -h now
    • In the VM guest: sudo init 0
    • From macOS host: vmctl stop ubuntu

    All of these leave me with a disk.img that is corrupted. Eventually the corruption builds to the point that the system doesn't start properly. I have the Paragon extfs drivers for macOS, and I can perform the following in macOS:

    hdiutil attach -nomount ubuntu/disk.img

    After that if I verify the filesystem using the paragon extfs driver it says it needs to be repaired. I can repair it using the paragon extfs driver.

    This happens after every shutdown, and from what I understand what I'm doing should exit the VM cleanly.

    Can anyone shed light on this or recommend an approach that will prevent the VM from corrupting the ext4 filesystem?

    Thanks!

    opened by matthewcmead 0
  • Proper configuration using a nocloud iso image

    Proper configuration using a nocloud iso image

    The provided "vmbuilders/ubuntu.sh" is a good start but it didn't work for me to configure the ubuntu cloud image: The openssh-server failed to initialize, my user was not created, no network connection. Instead of using the initramfs we can just provide an iso image with the necessary 'user-data' and 'meta-data' files to initialize the image at the first boot.

    # create cloudinit config iso
    rm -rf iso_folder seed.iso
    mkdir iso_folder
    
    cat << EOF > iso_folder/user-data
    #cloud-config
    users:
      - default
      - name: $USER
        lock_passwd: False
        gecos: $USER
        groups: [adm, audio, cdrom, dialout, dip, floppy, lxd, netdev, plugdev, sudo, video]
        sudo: ["ALL=(ALL) NOPASSWD:ALL"]
        shell: /bin/bash
        ssh-authorized-keys:
          - $(cat ~/.ssh/id_rsa.pub | head -n 1)
    bootcmd:
      - apt remove -y irqbalance
    network:
        version: 2
        renderer: networkd
        ethernets:
            enp0s1:
                dhcp4: true
    EOF
    

    Plenty of examples here. Then to create the iso file:

    touch iso_folder/meta-data

    hdiutil makehybrid -iso -joliet -iso-volume-name cidata -joliet-volume-name cidata -o seed.iso iso_folder

    Then add the seed.iso file to the vm.conf

    cat << EOF > vm.conf
    kernel=vmlinux
    initrd=initrd
    cmdline=console=hvc0 irqfixup root=/dev/vda
    cpu-count=1
    memory-size=1024
    disk=disk.img
    cdrom=seed.iso
    network=nat
    EOF
    

    There's no need to launch the initramfs anymore to edit the image. The openssh initialization, user creation and networking do work for me now. Full example: https://gist.github.com/alexsarmiento/c52874738c3bdb96424c57b297b2678d

    opened by alexsarmiento 1
Releases(v1.0.3)
Owner
Yifan Gu
Carnegie Mellon University
Yifan Gu
The Objective-C block utilities you always wish you had.

BlocksKit Blocks in C and Objective-C are downright magical. They make coding easier and potentially quicker, not to mention faster on the front end w

BlocksKit 6.9k Dec 28, 2022
Lightweight utilities for making OSLog more pleasant

UnifiedLoggingPlus Lightweight utilities for making OSLog more pleasant. Integration Swift Package Manager

Chime 10 Oct 26, 2022
Swift-friendly API for a set of powerful Objective C runtime functions.

ObjectiveKit ObjectiveKit provides a Swift friendly API for a set of powerful Objective C runtime functions. Usage To use ObjectiveKit: Import Objecti

Roy Marmelstein 850 Oct 25, 2022
Handy Combine extensions on NSObject, including Set.

Storable Description If you're using Combine, you've probably encountered the following code more than a few times. class Object: NSObject { var c

hcrane 23 Dec 13, 2022
Automatically set your keyboard's backlight based on your Mac's ambient light sensor.

QMK Ambient Backlight Automatically set your keyboard's backlight based on your Mac's ambient light sensor. Compatibility macOS Big Sur or later, a Ma

Karl Shea 29 Aug 6, 2022
Extendy - A set of useful string extensions.

Extendy A set of useful string extensions. Requirements iOS 11.0+ Swift 5+ Installation CocoaPods Extendy is available through CocoaPods. To install i

Anton Novichenko 3 Sep 23, 2021
Simple way to set up half modal view

HalfModalView Requirements iOS 9.0+ Xcode 10.0+ Swift 4.0+ Example Installation CocoaPods is a dependency manager for Cocoa projects. You can install

Choi SeungMyeong 5 Nov 14, 2022
A set of helper classes and functions in Swift

SwiftTools This is a set of tools written in Swift that add some sugar and some small functionality. Mainly meant for small projects and scripts, as a

Vinicius Vendramini 0 Dec 13, 2021
SwiftyUpdateKit is a framework for iOS and macOS.

SwiftyUpdateKit is a framework for iOS and macOS. This framework supports for a user to update your app when new app version is released on the App Store.

Hituzi Ando 4 Aug 24, 2022
Add “Launch at Login” functionality to your macOS app in seconds

LaunchAtLogin Add “Launch at Login” functionality to your macOS app in seconds It's usually quite a convoluted and error-prone process to add this. No

Sindre Sorhus 1.3k Jan 6, 2023
macOS system library in Swift

SystemKit A macOS system library in Swift based off of libtop, from Apple's top implementation. For an example usage of this library, see dshb, a macO

null 323 Jan 5, 2023
A macOS application displaying the thermal, voltage and current sensor values.

Sensors About A macOS application displaying the thermal, voltage and current sensor values. License Project is released under the terms of the MIT Li

Jean-David Gadina 82 Jan 3, 2023
macOS utility for converting fat-frameworks to SPM-compatible XCFramework with arm64-simulator support

xcframework-maker macOS utility for converting fat-frameworks to SPM-compatible XCFramework with arm64-simulator support. ?? Description make-xcframew

Dariusz Rybicki 312 Dec 22, 2022
ALO sync allows you to sync resources form an ALO endpoint to your macOS file system.

ALO sync allows you to sync resources form an ALO endpoint to your macOS file system. Prerequisites macOS 11 No support for search* No suppor

Lawrence Bensaid 2 Jan 22, 2022
Simple utility to change macOS Big Sur menu bar color by appending a solid color or gradient rectangle to a wallpaper image

Change menu bar color in macOS Big Sur Simple utility to change macOS Big Sur menu bar color by appending a solid color or gradient rectangle to a wal

Igor Kulman 876 Jan 5, 2023
This is a Swift package with support for macOS that allows to start Java Jar's with the default or a custom JVM.

Jar.swift jar runner for macos Jar.swift is created and maintaned with ❥ by Sascha Muellner. What? This is a Swift package with support for macOS that

Swift Package Repository 1 Nov 11, 2021
A simple macOS utility that can be used to control the behaviour of Bose QC35 Headphones straight from the menu bar.

bose-macos-utility A simple macOS utility that can be used to control the behaviour of Bose QC35 Headphones straight from the menu bar. Why Have you e

Łukasz Zalewski 11 Aug 26, 2022
Hermes is a Swift 5 payload for macOS.

Hermes is a Swift 5 payload for macOS. This version currently supports Mythic 2.2.8 and will update as necessary. It will not work with Mythic 2.1 and lower.

Mythic Agents 71 Dec 6, 2022
Small app that checks focus status under macOS 12

infocus What Small app for Mac Admins that checks focus status under macOS 11 and 12 and can be used to add Do Not Disturb support to management scrip

Bart Reardon 12 Nov 8, 2022