Multipass is a Windows command line tool from Canonical that quickly creates, manages, and discard discards new Ubuntu “Server” (command line only, no GUI) Hyper-V VMs. You can use it to test Linux software or to quickly build utility VMs. If you don’t like what you are testing, simply delete the VM and try something else.
This article has been updated to Multipass Version 1.10.
Unlike containers or WSL, a Linux Server VM runs “systemd” and supports components that require a background service (also known as a daemon). This allows you to run database systems and Docker itself on a Multipass VM.
Ubuntu automatically configures the generated VMs Multipass VMs are configured to run well enough under Hyper-V . There are a few optional packages that add convenience features, but you don’t have to research how to configure a system installed from a generic distribution on a DVD image.
Multipass is designed for personal machines that only one person uses. It has only minimal multi-user access control.
Install
When you install Hyper-V you should think about the default location for new VM system disks. These can be large and many users have a small C: drive and a larger secondary D disk. Multipass maintains its own separate directory where downloaded starter image files and new VMs are stored. If you have more space on an SSD other than C, you should to minimize code complexity they tend to use features available in every system they support (including VirtualBox, Linux, and Mac), so it is not optimized for Hyper-V. You can always add missing packages.
Multipass tries to support multi-user machines, but that objective conflicts with making some things easy to use. It works best on a personal machine with only one user who is admin, because then you can do everything .
Install
A new install of Multipass stores the disk images and virtual machines in the C:\ProgramData\Multipass directory. Hyper-V can only use locations that are on a local disk (not a network share), but if you want to store these large files on another local disk, then before you install set the environment variable MULTIPASS_STORAGE to a path in the bigger disk first. This cannot be a network attached disk, because Hyper-V can only use directly attached disks. point to a directory on that disk.
You can install Multipass with the winget package manager:
...
Enable Mounts (a convenience factor)
Multipass has the ability to share (using its own non-standard disk sharing technique) directories on your Host Windows system with VMs. Use this only to transfer files occasionally, because it has relatively poor performance. It also doesn’t have much in the way of access control, but this is not a problem if you are the only one who uses the host computer. On the chance that someone else logs onto your machine and your don’t trust them, this must be enabled.
Open a Run as Administrator command prompt window and issue the one time command:
multipass set local.privileged-mounts=true
Choose a Base Image
To simplify installation, Multipass does not come with any Ubuntu VM images. They are available from over the network and are periodically refreshed with newer images with the latest fixes preinstalled.
The “multipass find” command will list the images available currently from the network.
...
simple commands and options to share Windows directories with Multipass VMs. This is done through the multipass mount command after the VM is created, or the --mount parameter when creating a VM. This is, however, one of the places where the authors opted first for something they could get to work the same way on all systems without regard to performance. They use a file system based on SSH that provides very poor performance.
If you need to do more than casual file transfer, you need something better. There are other options (NFS, CIFS - a.k.a. Windows Shares, …). I will update this if anyone proposes a best practice or posts some benchmarks.
Hyper-V bypasses Windows access control, and Multipass runs as a background service under a SYSTEM userid. There is no way to recreate file system access control. The multipass mount service is shipped disabled, and you have to turn it on as an administrator. After that, you acknowledge that directories are being exposed to everyone, which is why this is best done on a single user machine. To turn mounts on, open a Run as Administrator command prompt window and issue the one time command:
multipass set local.privileged-mounts=true
Choose a Base Image
To simplify installation, Multipass does not come with any Ubuntu VM images. They are available from over the network and are periodically refreshed with newer images with the latest fixes preinstalled.
The “multipass find” command will list the images available currently from the network.
| Code Block |
|---|
C:\Users\gilbert>multipass find Image Aliases Version Description core core16 20200818 Ubuntu Core 16 core18 20211124 Ubuntu Core 18 snapcraft:core18 18.04 20201111 Snapcraft builder for Core 18 snapcraft:core20 20.04 20210921 Snapcraft builder for Core 20 snapcraft:core22 22.04 20220426 Snapcraft builder for Core 22 18.04 bionic 20220615 Ubuntu 18.04 LTS 20.04 focal,lts 20220615 Ubuntu 20.04 LTS 21.10 impish 20220616 Ubuntu 21.10 22.04 jammy 20220616 Ubuntu 22.04 LTS appliance:adguard-home 20200812 Ubuntu AdGuard Home Appliance appliance:mosquitto 20200812 Ubuntu Mosquitto Appliance appliance:nextcloud 20200812 Ubuntu Nextcloud Appliance appliance:openhab 20200812 Ubuntu openHAB Home Appliance appliance:plexmediaserver 20200812 Ubuntu Plex Media Server Appliance anbox-cloud-appliance latest Anbox Cloud Appliance charm-dev latest A development and testing environment for charmers docker latest A Docker environment with Portainer and related tools minikube latest minikube is local Kubernetes |
The “multipass launch” command creates a new VM. The single positional parameter (at the end of the command) is the name or alias of one of the images listed above (the default is “lts”, but you will note that several months after 22.04 was released they have not changed “lts” to point to it).
...
A Multipass VM is also a Hyper-V VM. The Hyper-V Manager allows you to change the number of CPUs and the amount of memory. However, modifying the size of a disk is more complicated. A You can also attach or detach a virtual network adapter to a Hyper-V virtual disk is dynamic, meaning it is created as a small file that expands only if you write more data into it. So overestimating virtual network (virtual switch). Starting with Multipass 10 you can also change the number of CPUs or amount of memory using a Multipasss command, but the Hyper-V Manager interface is better for these type of changes.
There are still a few changes that are complicated and require some thought. Changing the size of the disk is a better practice, and the default size of 5G is unusable for most purposes. Setting --disk 127G is a normal practice and just sets a limit to the maximum amount the virtual disk file can expand to.
You can also add Virtual Network Adapters with Hyper-V, but network adapters are configured in a rather complicated file /etc/netplan/50-cloud-init.yaml that you have to change to define the new adapter. It is better to add the adapter when multipass creates the VM and then the file will at least start up with all adapters defined and only require simpler edits.
An example of the command to create a VM is:
multipass launch -n vmname --cpus 2 --disk 127G --mem 1024M --network Sandbox 22.04
The last and only positional parameter is the image name “22.04” taken from the list of image names shown above.
There are many things you want to do to customize your VM, but some of these things you do to every VM. It is annoying to have to repeat 10 minutes of configuration for every VM. There is a cloud-init parameter and afile format provided with Multipass that allows you to do most of the configuration automatically during the execution of the “multipass launch”.
It can create groups and users, install SSH keys and CA Certificates, install additional packages and applications, and apply the most recent Ubuntu maintenance. A full discussion of this file format cannot be provided here, so read the manual.
Every time I type the “multipass launch” command interactively, as soon as I hit Enter I remember some parameter I accidentally left out. It is better to combine all the stuff you always do into a script file. If you need to make some changes, copy the script file and edit them in.
A useful trick in Powershell scripting is to put the text of the cloud-init file in the script as a multiline text literal that gets piped to the “multipass launch” and is then picked up by a “--cloud-init -” parameter where putting a dash “-” instead of a file name means “read from standard input” which is to say from the pipe. An alternative is to build a separate script that constructs the cloud-init file from parameters passed to the script, and then use that script to generate the text piped to the “multipass launch” command. Here is an example with inline text:
| Code Block |
|---|
param (
[string] $vmname
)
# Start a Multiline text literal YAML that ends in a line beginning with "@
@"
#cloud-config
# Create my normal userid with its normal ssh key and sudo privileges
# The docker group will only exist if docker is in the package install list
users:
- name: gilbert
gecos: Howard Gilbert
shell: /bin/bash
groups: docker
ssh_authorized_keys:
- "ssh-rsa AA...094347"
sudo: ALL=(ALL) NOPASSWD:ALL
# Packages to install with sudo apt install ...
packages:
- avahi-daemon
- cifs-utils
- cockpit
# Do apt update and upgrade with latest changes
package_update: true
package_upgrade: true
# Add a snap. I like Powershell
snap:
commands:
- snap install powershell --classic
# Reboot after everything to activate all the changes
power_state:
mode: reboot
# End of text literal which gets piped to the multipass command as stdin
"@ |
multipass launch -n $vmname -d 127G -timeout 600 --cloud-init - --network Sandbox 22.04 |
You can add parameters to the script, and the parameters can both change the content of the cloud-init commands and the multipass launch command.
A word about packages you may want to automatically install:
avahi-daemon adds support for the mDNS protocol, where this VM can be reference from other VMs as hostname.local (where in this example hostname is the $vmname parameter of the script).
cifs-utils allows the VM to connect to the Windows host computer and access shared disk files.
cockpit is a Web based management tool for Linux. Open a browser to https://hostname.local:9090/
linux-image-virtual linux-tools-virtual linux-cloud-tools-virtual are optional packages for running Linux in a VM, including Hyper-V. The main benefit is that Hyper-V Manager can display Network addresses for all virtual adapters in the VM. The downside is that the install of the last package hangs for 2 minutes until it times out, and then because of the failure does not start the services until the next reboot (which the “power-state” at the end of the cloud-init takes care of).
If you specify a new Ubuntu image name (22.04 here) a new image file will be downloaded from the Internet and saved in the cache first and then the rest of the launch will run.
Run Commands as “ubuntu” user
Multipass creates a user named “ubuntu” with sudo privileges.
Multipass generates a ssh keys on install and copies the public key to the /home/ubuntu/.ssh directory of every VM it creates.
Multipass has its own internal version of ssh and scp programs. It uses them to connect to the VM to pass commands, open a shell, copy files, and mount shared directories.
You should always assign a password to the ubuntu user on each VM you create just in case the multipass ssh gets clobbered. Then you can login to the VM using a standard Hyper-V console window for the VM.
IMPORTANT: READ THIS
Sometimes Multipass screws up.
Sometimes you screw up and clobber Multipass files.
Otherwise, Microsoft’s annual upgrade (from say 21H2 to 22H2) screws up for you.
Your Multipass VMs are real Hyper-V VMs. You can run them from Hyper-V, login to them with a Hyper-V console window, and generally ignore Multipass if you want.
However, the special services provided by the multipass command fail if the ssh key is deleted or overwritten with a new key.
Until Version 1.9 Multipass stored its files in a directory that Microsoft believed it could delete on any annual major version upgrade of Windows 10 or 11. Even if that is fixed, you are given an opportunity to delete everything in the middle of the Setup dialogs each time Multipass updates its software with new fixes. Hit the Yes button instead of the No button and it is all gone.
So you should always create Multipass VMs that can stand on their own without a multipass command. You should also take advantage of Hyper-V tools to checkpoint and backup and export VMs. You should also find and backup the multipass ssh keyshard disk requires first enlarging the virtual size of the disk, then expanding the partition, and finally telling the file system to use the extra space. You can find articles that give you the Linux commands, but Multipass makes it much simpler with a command that allows you to expand (but not reduce) the disk size of a VM:
multipass set local.vmname.disk=100G
Note that Hyper-V virtual disk file are dynamic, start out small, and only increase in size when you are adding data to the disk. Therefore, it is generally a good practice to overestimate the size of the disk you will need since you are only assigning a maximum size the disk will grow to. The same amount of data will take the same amount of disk space whether the disk (maximum) size is 50G, 100G, or 200G.
In the same way, it is better to create a VM with the maximum number of network adapters you will ever need. Extra adapters that you are not using immediately can be attached to an otherwise unused private Hyper-V switch, but it is probably better if they are not attached to any switch at all (leaving them like a physical network adapter that has no cable plugged into it). The problem is that Ubuntu networks are configured in a file /etc/netplan/50-cloud-init.yaml. Each adapter is identified by its Ethernet address which is dynamically assigned by Hyper-V. If you create all the adapters you may ever use, you get a file that configures each of them then only have to change the IP address parameters on an already configured adapter.
An example of the command to create a VM is:
multipass launch -n vmname --cpus 2 --disk 127G --mem 1024M --network Sandbox 22.04
The last and only positional parameter is the image name “22.04” taken from the list of image names shown above. Multipass will download the initial image file if it is not already on your machine.
Cloud-Init
Lots of people have developed files and utilities to do configure a VM automatically when it is created by adding packages, users, groups, Certificates, keys, and other stuff. Canonical likes a tool called Cloud-Init. The “multipass launch --cloud-init “ parameter can take a file name or “-” for standard input. The file format is a bit complicated, and while some examples will be provided below, if you want the full syntax read the manual.
Of course, you can accomplish the same thing by writing a bash script, doing a “multipass transfer” of the script to the VM, and then run the script with “multipass exec” after the launch. It is up to you.
A useful trick in Powershell scripting is to put the text of the cloud-init file in the script as a multiline text literal that gets piped to the “multipass launch” and is then picked up by a “--cloud-init -” parameter where putting a dash “-” instead of a file name means “read from standard input” which is to say from the pipe. An alternative is to build a separate script that constructs the cloud-init file from parameters passed to the script, and then use that script to generate the text piped to the “multipass launch” command. Here is an example with inline text:
| Code Block |
|---|
param (
[string] $vmname
)
# Start a Multiline text literal YAML that ends in a line beginning with "@
@"
#cloud-config
# Create my normal userid with its normal ssh key and sudo privileges
# The docker group will only exist if docker is in the package install list
users:
- name: gilbert
gecos: Howard Gilbert
shell: /bin/bash
groups: docker
ssh_authorized_keys:
- "ssh-rsa AA...094347"
sudo: ALL=(ALL) NOPASSWD:ALL
# Packages to install with sudo apt install ...
packages:
- avahi-daemon
- cifs-utils
- cockpit
# Do apt update and upgrade with latest changes
package_update: true
package_upgrade: true
# Add a snap. I like Powershell
snap:
commands:
- snap install powershell --classic
# Reboot after everything to activate all the changes
power_state:
mode: reboot
# End of text literal which gets piped to the multipass command as stdin
"@ |
multipass launch -n $vmname -d 127G -timeout 600 --cloud-init - --network Sandbox 22.04 |
You can add parameters to the script, and the parameters can both change the content of the cloud-init commands and the multipass launch command.
A word about packages you may want to automatically install:
avahi-daemon adds support for the mDNS protocol, where this VM can be reference from other VMs as hostname.local (where in this example hostname is the $vmname parameter of the script).
cifs-utils allows the VM to connect to the Windows host computer and access shared disk files.
cockpit is a Web based management tool for Linux. Open a browser to https://hostname.local:9090/
linux-image-virtual linux-tools-virtual linux-cloud-tools-virtual are optional packages for running Linux in a VM, including Hyper-V. The main benefit is that Hyper-V Manager can display Network addresses for all virtual adapters in the VM. The downside is that the install of the last package hangs for 2 minutes until it times out, and then because of the failure does not start the services until the next reboot (which the “power-state” at the end of the cloud-init takes care of).
If you specify a new Ubuntu image name (22.04 here) a new image file will be downloaded from the Internet and saved in the cache first and then the rest of the launch will run.
Run Commands as “ubuntu” user
During installation Multipass generates a local set of SSH keys and stores the secret key in C:\ProgramData\multipass\data\ssh-keys file.
On each VM, Multipass creates a user named “ubuntu” with sudo privileges and inserts in its home directory the matching public SSH key.
Multipass does not depend on SSH installed on the Windows system. It comes with its own SSH programs to connect to the VMs, create a session, pass commands, or transfer files. It does all this over the Default Hyper-V network.
The “ubuntu” user does not have a password, so if you lose Multipass or its private key gets clobbered you are locked out. You should use the “passwd” command to create your own password for this user. Multipass won’t use it, but if you lost Multipass (or if you feel like it) you can use the Hyper-V Manager to open a window with the hardware console of the VM and then login as “ubuntu” with the password you assigned.
But also back up the C:\ProgramData\multipass\data\ssh-keys file someplace safe, since even if Multipass was clobbered you can use the real ssh.exe client program built into current Windows to connect to the VM without multipass if you have the file (since it doesn’t appear to have a passcode and you can just point to it on the ssh command).
IMPORTANT: READ THIS
Sometimes Multipass screws up.
Sometimes you screw up and clobber Multipass files.
Otherwise, Microsoft’s annual upgrade (from say 21H2 to 22H2) screws up for you.
Your Multipass VMs are real Hyper-V VMs. You can run them from Hyper-V, login to them with a Hyper-V console window, and generally ignore Multipass if you want. You can also create your own userid, assign it sudo privileges, and store your normal SSH public key in your home directory. Then you can use Windows ssh command instead of Multipass.
You want three alternative backups: a password on the “ubuntu” user, a backup of the Multipass private key file, and your own authorized user with you own ssh key (and if you want, put your password on it too). Now if you lose Multipass control, you still have access to the VM. This is useful if you now use it for docker, or a database, or a Web server.
If you install a new Multipass today, it puts its files in C:\ProgramData which is safe. Several releases ago it put them in the C:\Windows subdirectories which was a mistake because Windows would remove them across a semiannual feature upgrade. Of course, every time winget upgrades Multipass from one minor version to the next it runs an uninstall which pops up a dialog offering you the chance to destroy all your files and VMs if you just click the Yes button. In other words, it is just too easy to lose everything.
So back up Multipass in C:\ProgramData, at least to some offline backup disk just in case.
Multipass does not do a good job of explaining how things are done. It uses a Windows feature called a “difference disk”. Each VM starts with a read-only copy of the base Ubuntu disk image file, but from this image it creates a read-write file where Windows writes all the changes that were made to the disk as it first boots up and is configured.
| Code Block |
|---|
Directory of C:\ProgramData\Multipass\data\vault\instances\docker
06/19/2022 11:53 AM <DIR> .
07/14/2022 06:03 PM <DIR> ..
06/19/2022 11:53 AM 59,392 cloud-init-config.iso
06/19/2022 11:53 AM 1,686,110,208 ubuntu-22.04-server-cloudimg-amd64.vhdx
07/14/2022 08:17 PM 3,507,486,720 ubuntu-22.04-server-cloudimg-amd64_11B1CDD6-25BA-44B1-92A3-1C4DBFCA6924.avhdx
3 File(s) 5,193,656,320 bytes |
The ubuntu-22.04-server-cloudimg-amd64.vhdx is the read-only image and the ubuntu-22.04-server-cloudimg-amd64_11B1…24.avhdx file is the read-write difference disk. Hyper-V will only show the difference disk name. You may confuse this with a similar arrangement for Hyper-V checkpoints. This is not a checkpoint but rather an option Windows provides for its virtual disk files.
If you upgrade to 22H2 and Multipass appears to have been deleted, remember that the old files are saved for a month or so in the C:\Windows.old directory. That does not, however, give you instructions for restoring your old multipass installation on the new system.
On each VM, do a “sudo passwd ubuntu” and give the built in ubuntu user a real password and not just SSH keys.
Add a second user with your own normal SSH login key and a password, and give it SUDO privileges.
Find the Multipass ssh key and save the file separately (it has no passcode).
Don’t count on “multipass mount”. Find another way to share files. For example, the new system.
Durable Shared Files
If you count on “multipass mount” you are in trouble if the multipass configuration gets broken. Besides, the performance is pretty terrible.
A native Windows to Linux file sharing solution can be added using Windows standard file shares. On the VM do a “sudo apt install cifs-utils” and learn how to connect to a Windows Shared disk directory. This is a good article.Backup VMs using Hyper-V “Export”. Not only does this allow you to restore after various problems, but is also a convenient way to move VMs from one host to anothera Windows Shared disk directory. This is a good article.
Export
Backup VMs or move them from one Windows system to another using Hyper-V “Export”. Note that if you do this, Multipass on the Importing host will not know about and cannot talk to a VM that was previously connected to Multipass on the Exporting host, which is a second excellent reason for creating VMs that can stand on their own without the multipass command. That is why you have multiple ways to login, transfer files, and share directories.
The eth0 Network
When Multipass creates a new VM it creates a first Virtual Network Adapter and connects it to the Hyper-V Default Switch network. Default is a network that “just works out of the box” so you don’t need to configure or administer it, so you are not allowed to change or manage it. Every time the Host computer reboots, it does the equivalent of a “factory reset” on the Default network and everyone gets a new IP address.
...
You get more if you add a service that combines DHCP, DNS, a firewall, and a gateway to the Sandbox network. For this, you create an empty VM and install a system from a DVD image. Search the Web for “pfSense”, “opnSense”, or “openWRT” for widely used alternatives. These systems are not related to Multipass, so I just suggest them as network configuration options.
There is also a physical version of this, where you take the Ethernet adapters connecting a Sandbox 2 configuration and plug them into the wired ports on the back of a TPLink or Netgate wired router/gateway box. Then you only have to know how to admin these familiar boxes and you don’t need to learn pfSense, but at this time you are now limited to Gigabit Ethernet speed.
Make the Second Adapter Preferred
...