Configure where Multipass stores external data

This document demonstrates how to configure the location where Multipass caches images, stores instances, and other user information. Configuring a new storage location can be useful, for example, if you need to free up storage space on your boot partition.

Contents:

Configuring a new storage location

Caveats:

  • Multipass will not migrate your existing data, but this article explains how to do it manually. If you do not transfer the data, you will have to re-download any Ubuntu images and reinitialize any instances that you need.
  • Subsequently, when uninstalling Multipass, the uninstaller will not remove data stored in custom locations, which must be deleted manually.

Linux

First, stop the Multipass daemon:

$ sudo snap stop multipass

Depending on where the new storage directory is located you will need to connect the respective interface to the Multipass snap. Because of snap confinement, this directory needs to located in either /home or one of the removable mounts points:

$ sudo snap connect multipass:removable-media # for /mnt or /media
$ sudo snap connect multipass:all-home # for /home/*

Then, create the new directory in which Multipass will store its data:

$ mkdir -p <path>
$ sudo chown root <path>

After that, create the override config file, replacing <path> with the absolute path of the directory created above.

$ sudo mkdir /etc/systemd/system/snap.multipass.multipassd.service.d/
$ sudo tee /etc/systemd/system/snap.multipass.multipassd.service.d/override.conf <<EOF
[Service]
Environment=MULTIPASS_STORAGE=<path>
EOF
$ sudo systemctl daemon-reload

Now you can transfer the data from its original location to the new location:

$ sudo cp -r /var/snap/multipass/common/data/multipassd <path>/data
$ sudo cp -r /var/snap/multipass/common/cache/multipassd <path>/cache

Finally, start the Multipass daemon:

$ sudo snap start multipass

You can delete the original data at your discretion, to free up space:

$ sudo rm -rf /var/snap/multipass/common/data/multipassd
$ sudo rm -rf /var/snap/multipass/common/cache/multipassd

macOS

First, become root:

$ sudo su

Stop the Multipass daemon:

$ launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist

Move your current data from its original location to <path>, replacing <path> with your custom location of choice:

$ mv /var/root/Library/Application\ Support/multipassd <path>

Make sure the multipassd directory is moved to <path>, not inside <path>.

Make a link from the original location to the absolute path of new location:

$ ln -s <path> /var/root/Library/Application\ Support/multipassd

Finally, start the Multipass daemon:

$ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist

Windows

First, open an administrator privileged PowerShell prompt.

Stop the Multipass daemon:

PS> Stop-Service Multipass

Create and set the new storage location, replacing <path> with the absolute path of your choice:

PS> New-Item -ItemType Directory -Path "<path>"
PS> Set-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\Session Manager\Environment" -Name MULTIPASS_STORAGE -Value "<path>"

Now you can transfer the data from its original location to the new location:

PS> Copy-Item -Path "C:\ProgramData\Multipass\*" -Destination "<path>" -Recurse

It is important to copy any existing data to the new location. This avoids unauthenticated client issues, permission issues, and in general, to have any previously created instances available.

Finally, start the Multipass daemon:

PS> Start-Service Multipass

You can delete the original data at your discretion, to free up space:

PS> Remove-Item -Path "C:\ProgramData\Multipass\*" -Recurse

Reverting back to the default location

Linux

Stop the Multipass daemon:

$ sudo snap stop multipass

Although not required, to make sure that Multipass does not have access to directories that it shouldn’t, disconnect the respective interface depending on where the custom storage location was set:

$ sudo snap disconnect multipass:removable-media # for /mnt or /media
$ sudo snap disconnect multipass:all-home # for /home/*

Then, remove the override config file:

$ sudo rm /etc/systemd/system/snap.multipass.multipassd.service.d/override.conf
$ sudo systemctl daemon-reload

Now you can transfer your data from the custom location back to its original location:

$ sudo cp -r <path>/data /var/snap/multipass/common/data/multipassd
$ sudo cp -r <path>/cache /var/snap/multipass/common/cache/multipassd

Finally, start the Multipass daemon:

$ sudo snap start multipass

You can delete the data from the custom location at your discretion, to free up space:

$ sudo rm -rf <path>

macOS

First, become root:

$ sudo su

Stop the Multipass daemon:

$ launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist

Remove the link pointing to your custom location:

$ unlink /var/root/Library/Application\ Support/multipassd

Move the data from your custom location back to its original location:

$ mv <path> /var/root/Library/Application\ Support/multipassd

Finally, start the Multipass daemon:

$ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist

Windows

First, open an administrator privileged PowerShell prompt.

Stop the Multipass daemon:

PS> Stop-Service Multipass

Remove the setting for the custom storage location:

PS> Remove-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\Session Manager\Environment" -Name MULTIPASS_STORAGE

Now you can transfer the data back to its original location:

PS> Copy-Item -Path "<path>\*" -Destination "C:\ProgramData\Multipass" -Recurse

Finally, start the Multipass daemon:

PS> Start-Service Multipass

You can delete the data from the custom location at your discretion, to free up space:

PS> Remove-Item -Path "<path>" -Recurse

Let us know how this worked for you and what you’d like to see next!

4 Likes

I hope there will be user setting to manage cache https://github.com/canonical/multipass/issues/3044 because making my $HOME/.cache/multipass location a global setting seems like a hack.

In macOS the first step should be:

sudo launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist

Stopping will only restart the daemon with no awareness of the MULTIPASS_STORAGE environment variable.

Thanks for noticing this and bringing it to our attention! I’ve updated the part of the doc for reverting custom storage locations on macOS, so feel free to give it a look over and let us know if anything needs to be improved.

Under the Configuring a new storage location / Windows heading, mkdir is used to create a new directory (and it’s the only Unix-like command used in Windows scripts)

Although nothing wrong with mkdir, would be nicer to make Windows more PowerShell-y if you get what I mean! :wink:

Change:

PS> mkdir "<path>"

to

PS> New-Item -ItemType Directory -Path "<path>"

@itecompro , thanks for your advice. The change has been applied. It does help the consistency of the commands in that section.

1 Like

When I use the command sudo snap install multipass --classic on the ubuntu 22.04 desktop system, and then modify the storage path to /data/multipass according to the method provided above, I get Caught an unhandledexception: unable to crete directory ‘/data/multipass/cache’ mistake. How to solve this?

Hi @veazhi,

Multipass is distributed as a strictly confined snap, so it can only access select locations on your system. As documented, only home paths and removable media are supported (after you activate the corresponding connections).

BTW, because it is a strictly confined snap (has been for a long time now), you don’t need the --classic flag when installing the snap (it will be ignored anyway).

Could we please clarify what this means by adding a specific example? it’s very confusing. Does this mean the steps should be mv /var/root/Library/Application\ Support/multipassd /External/multipass/multpassd ormv /var/root/Library/Application\ Support/multipassd /External/multipass/multpassd OR mv /var/root/Library/Application\ Support/multipassd /External/multipass/? That would have implications on the next instruction which could also use a concrete example.

I’ve tried both ways and cannot get either to work. In my opinion the article could be improved by having concrete examples for each operating system where necessary to improve clarification.

Also, I’m using an ARM M1 Mac running the latest OS at the time of writing - Ventura 13.4.1. with multipass 1.13.0+mac and multipassd 1.13.0+mac. I didn’t see anywhere that this version had any incompatibilities still with ARM, but perhaps I could be hitting up against that? Last but not least, it’s not clear if the new location on the external drive needs specific permissions / ownership. (I noticed the Linux section did provide guidance on that). I mimicked the permissions from /var/root/Library/Application\ Support/multipassd but still no go.

If someone already knows the extra info that can fill in the gaps, please update the page. In the meantime, I’ll reach out to the tech support team to get feedback on the trouble I’m having, and if I get the information first, I’ll write it up, if necessary. Thanks!

Hi @blue
Thanks for your feedback, that part indeed can be elaborated.