vkhitrin.com

Technology And Ramblings

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). Graphical User Interface of a virtual machine edit screen in UTM

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: Modified configuration of virtual machine applied from the previous step

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.

Back To Top