Modifying UTM Configuration Via CLI
Tags:
#UTM
#virtualization
Note: A follow-up to blog post Booting Arch Linux Using Apple Virtualization Framework With UTM.
Tested on UTM version 4.2.5 and macOS 13.4.
Warning: Backup the configuration before editing manually!
Preface
Apple virtualization backend is used in this blog post.
Things might change with future releases of UTM or macOS.
Consult the documentation for the latest information.
Virtual Machine Bundle Format
UTM stores virtual machines at $HOME/Library/Containers/com.utmapp.UTM/Data/Documents/
.
Virtual machines managed by UTM are bundled in a .utm
format, which is a directory:
file 'Arch Linux.utm'
Arch Linux.utm: directory
This directory contains all files related to the virtual machine configuration and data:
tree 'Arch Linux.utm'
Arch Linux.utm
├── Data
│ ├── 86BDC3C3-E94C-446F-A9E2-A323BAF582D1.img
│ └── Image-archboot-aarch64
└── config.plist
Virtual machine configuration is stored in config.plist
, in a plist format.
Virtual machine data is stored in the Data
directory.
From the example above, 86BDC3C3-E94C-446F-A9E2-A323BAF582D1.img
represents a storage device, and Image-archboot-aarch64
is a kernel binary used to boot the operating system.
Exploring config.plist
Since the configuration file is a plist (an XML), we can easily interact with it using the native /usr/libexec/PlistBuddy
utility to look up and modify the configuration.
Query Configuration
We can use the print
command in /usr/libexec/PlistBuddy
to print the configuration:
/usr/libexec/PlistBuddy -c print 'Arch Linux.utm/config.plist'
Dict {
Serial = Array {
}
Backend = Apple
System = Dict {
CPUCount = 4
Boot = Dict {
LinuxCommandLine = console=hvc0 root=/dev/vda2
LinuxKernelPath = Image-archboot-aarch64
OperatingSystem = Linux
UEFIBoot = false
}
GenericPlatform = Dict {
machineIdentifier = bplist00TUUIDOdcH;F
#
}
Architecture = aarch64
MemorySize = 8192
}
......output omitted......
}
It is possible to access a key directly as well:
/usr/libexec/PlistBuddy -c 'print Backend' 'Arch Linux.utm/config.plist'
Apple
We can also access nested keys:
/usr/libexec/PlistBuddy -c 'print System:Boot' 'Arch Linux.utm/config.plist'
Dict {
LinuxCommandLine = console=hvc0 root=/dev/vda2
LinuxKernelPath = Image-archboot-aarch64
OperatingSystem = Linux
UEFIBoot = false
}
Modifying Configuration
Any modification to the virtual machine is stored in config.plist
.
The UTM’s graphical interface allows modifying the virtual machine configuration (Left mouse click on virtual machine -> Edit
).
Modifying config.plist
directly is possible.
For example, we can increase the RAM size:
# Getting the current virtual memory size
/usr/libexec/PlistBuddy -c 'print System:MemorySize' 'Arch Linux.utm/config.plist'
# Result
8192
# Configure a new virtual memory size
/usr/libexec/PlistBuddy -c 'set System:MemorySize 16384' 'Arch Linux.utm/config.plist'
# Get the new value
/usr/libexec/PlistBuddy -c 'print System:MemorySize' 'Arch Linux.utm/config.plist'
16384
After restarting the UTM app (may not be required), the change is reflected in the GUI:
Example, Remove Console And Display For Headless Operation
By default, all virtual machines created by UTM will have a console and display devices attached to them:
# Default display device
/usr/libexec/PlistBuddy -c 'print Display' 'Arch Linux.utm/config.plist'
Array {
Dict {
WidthPixels = 1920
PixelsPerInch = 80
HeightPixels = 1200
}
}
# Default console (serial) device
/usr/libexec/PlistBuddy -c 'print Serial' 'Arch Linux.utm/config.plist'
Array {
Dict {
Mode = Terminal
Terminal = Dict {
BackgroundColor = #000000
Font = Menlo
CursorBlink = true
FontSize = 12
ForegroundColor = #ffffff
}
}
When starting the virtual machine through utmctl start 'Arch Linux'
, it will attach the display and console devices.
Users may want to interact with the system headlessly via remote management without needing a display or console devices.
We can remove the array elements inside the Serial
and Device
keys to remove these devices from a virtual machine:
# Remove display devices
/usr/libexec/PlistBuddy -c 'delete Display:' 'Arch Linux.utm/config.plist'
# Remove console devices
/usr/libexec/PlistBuddy -c 'delete Serial:' 'Arch Linux.utm/config.plist'
After removal, the keys should look like this:
# View display configuration
/usr/libexec/PlistBuddy -c 'print Display' 'Arch Linux.utm/config.plist'
Array {
}
# View console configuration
/usr/libexec/PlistBuddy -c 'print Serial' 'Arch Linux.utm/config.plist'
Array {
}
From now on, virtual machines started by UTM will not attach any display or console.
Final Notes
This post briefly explored UTM’s configuration, how to modify it via CLI, and small snippets of configurations. not attach any display or console.