search

utmapp / UTM

Virtual machines for iOS and macOS
https://getutm.app
Apache License 2.0
27.01k stars 1.35k forks source link

Documentation of file format/image publishing process #4228

Open phlummox opened 2 years ago

phlummox commented 2 years ago

I don't use a Mac myself, but would like to make several QEMU images that I have created more easily available to Mac users. I currently make them available to Windows and Linux users as Virtualbox-based Vagrant boxes hosted on the Vagrant Cloud (https://app.vagrantup.com/boxes/search), but that's not an option for users with ARM-based Macs.

Is there any documentation of the file format used for .utm images, and how they can be made available via a URL? This would be very helpful for image creators seeking to make their VMs available to Mac users.

phlummox commented 1 year ago

For anyone else encountering this issue: some additional information was added in a Discord thread, here.

Query:

Is there any documentation of the image format used? I'd like to be able to make my QEMU VM images easily accessible to users who are using MacOS. There's an issue on GitHub about this already, but no response as yet: https://github.com/utmapp/UTM/issues/4228.
From what I can tell, the format is a plain .zip file, with any descriptive name, and the following contents:

  • arbitrary directory name, ending in ".utm", containing
    • a directory "Images", containing
    • a .qcow2 file, with arbitrary (?) name before the .qcow2 extension
    • a "config.plist" file, with contents I'm still looking through.

Are there any restrictions on the qcow2 disk image? And is there any more information available on what needs to go in the config.plist file?

Reply from ktprograms:

AFAIK the qcow2 file can have any name, as long as it's referenced appropriately in the config.plist.

As for the config format itself, it's split up over Swift Codable structs that are encoded to PLIST. They are defined in https://github.com/utmapp/UTM/tree/main/Configuration (for QEMU, look at the UTMConfiguration.swift and UTMQemuConfiguration.swift files.

I'd recommend using UTM to create one VM to get a template config.plist, which you can then manually edit to change title, description and other settings.

Also, for creating the .zip to share, see https://github.com/BluDood/UTM-Community/wiki/Submitting-a-Virtual-Machine#preparing-the-machine-for-upload to zip the .utm folder bundle.

phlummox commented 1 year ago

For reference, the link to the current commit of the Configuration directory ktprograms mentions at the time of writing is https://github.com/utmapp/UTM/tree/5cd7aab72c8a95300179405ce152952fb09cd289/Configuration. And the current UTMQemuConfiguration*.swift files are:

ktprograms commented 1 year ago

Oops, I'm not sure how I was subscribed to this thread but didn't respond with info. Glad it's helpful, feel free to ping me if you need additional help with this.

phlummox commented 1 year ago

No worries, will do. :)