Skip to content

Commit

Permalink
Update source file to latest version (#142)
Browse files Browse the repository at this point in the history 
Update source file to match the latest version of the page on Discourse.
  • Loading branch information
@giuliazanchi
giuliazanchi authored Oct 4, 2024
1 parent e3534fe commit d33ce0a
Showing 1 changed file with 73 additions and 48 deletions.
121 changes: 73 additions & 48 deletions multipass/how-to/how_to_set_up_the_driver.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,3 @@
tmihoc | 2024-07-10 09:07:46 UTC | #1

<!-- New feedback link at the top of each page!
Please don't copy it blindly, first update the URL passed to the form with the current page URL
-->

> *Errors or typos? Topics missing? Hard to read? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/set-up-the-driver" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*
> See also: [Driver](/t/28410), [`local.driver`](/t/27357)
This document demonstrates how to choose, set up, and manage the drivers behind Multipass. Multipass already has sensible defaults, so this is an optional step.
Expand Down Expand Up @@ -45,20 +37,20 @@ If you want more control over your VMs after they are launched, you can also use
To install libvirt, run the following command (or use the equivalent for your Linux distribution):

```plain
$ sudo apt install libvirt-daemon-system
sudo apt install libvirt-daemon-system
```

Now you can switch the Multipass driver to libvirt. First, allow Multipass to use your local libvirt by connecting to the libvirt interface/plug:
Now you can switch the Multipass driver to libvirt. First, enable Multipass to use your local libvirt by connecting to the libvirt interface/plug:

```plain
$ sudo snap connect multipass:libvirt
sudo snap connect multipass:libvirt
```

Then, [stop](/t/23951) all instances and tell Multipass to use libvirt, running the following commands:
Then, stop all instances and tell Multipass to use libvirt, running the following commands:

```plain
$ multipass stop --all
$ multipass set local.driver=libvirt
multipass stop --all
multipass set local.driver=libvirt
```

All your existing instances will be migrated and can be used straight away.
Expand All @@ -76,7 +68,7 @@ An alternative option is to use VirtualBox.
To switch the Multipass driver to VirtualBox, run this command:

```plain
$ sudo multipass set local.driver=virtualbox
sudo multipass set local.driver=virtualbox
```

From now on, all instances started with `multipass launch` will use VirtualBox behind the scenes.
Expand All @@ -92,7 +84,7 @@ To that end, install VirtualBox, if you haven't yet. You may find that you need
To switch the Multipass driver to VirtualBox (also with Administrator privileges), run this command:

```powershell
PS> multipass set local.driver=virtualbox
multipass set local.driver=virtualbox
```

From then on, all instances started with `multipass launch` will use VirtualBox behind the scenes.
Expand All @@ -109,15 +101,19 @@ From then on, all instances started with `multipass launch` will use VirtualBox

You can view instances with libvirt in two ways, using the `virsh` CLI or the [`virt-manager` GUI](https://virt-manager.org/).

To use the `virsh` CLI, launch an instance and then execute `virsh list` (see [`man virsh`](http://manpages.ubuntu.com/manpages/xenial/man1/virsh.1.html) for a command reference):
To use the `virsh` CLI, launch an instance and then run the command `virsh list` (see [`man virsh`](http://manpages.ubuntu.com/manpages/xenial/man1/virsh.1.html) for a command reference):

```plain
$ virsh list
virsh list
```

The output will be similar to the following:

```plain
Id Name State
--------------------------------------
1 unaffected-gyrfalcon running
```

Alternatively, to use the `virt-manager` GUI, ...

![obraz|584x344](upload://bFIxA9CPAqBeWjuQxDaZBYBNsZK.png)
Expand All @@ -126,18 +122,22 @@ Alternatively, to use the `virt-manager` GUI, ...

[tab version="macOS"]

Multipass runs as the `root` user, so to see the instances in VirtualBox, or through the `VBoxManage` command, you have to run those as `root`, too. To see the instances in VirtualBox, execute:
Multipass runs as the `root` user, so to see the instances in VirtualBox, or through the `VBoxManage` command, you have to run those as `root`, too. To see the instances in VirtualBox, use the command:

```plain
$ sudo VirtualBox
sudo VirtualBox
```

![Multipass instances in VirtualBox](upload://mld2SIalX93tc3StGHaqb6OTyDO.png)

And, to list the instances on the command line, execute:
And, to list the instances on the command line, run:

```plain
$ sudo VBoxManage list vms
sudo VBoxManage list vms
```

Sample output:
```plain
"primary" {395d5300-557d-4640-a43a-48100b10e098}
```

Expand All @@ -152,14 +152,20 @@ You can still use the `multipass` client and the system menu icon, and any chang
Multipass runs as the _System_ account, so to see the instances in VirtualBox, or through the `VBoxManage` command, you have to run those as that user via [`PsExec -s`](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec). Download and unpack [PSTools.zip](https://download.sysinternals.com/files/PSTools.zip) in your *Downloads* folder, and in an administrative PowerShell, run:

```powershell
PS> & $env:USERPROFILE\Downloads\PSTools\PsExec.exe -s -i $env:VBOX_MSI_INSTALL_PATH\VirtualBox.exe
& $env:USERPROFILE\Downloads\PSTools\PsExec.exe -s -i $env:VBOX_MSI_INSTALL_PATH\VirtualBox.exe
```

![Multipass instances in VirtualBox](upload://xVIOErbwcdoppcN5KSzvHJybSi7.png)

To list the instances on the command line:

```powershell
& $env:USERPROFILE\Downloads\PSTools\PsExec.exe -s $env:VBOX_MSI_INSTALL_PATH\VBoxManage.exe list vms
```

Sample output:

```powershell
PS> & $env:USERPROFILE\Downloads\PSTools\PsExec.exe -s $env:VBOX_MSI_INSTALL_PATH\VBoxManage.exe list vms
"primary" {05a04fa0-8caf-4c35-9d21-ceddfe031e6f}
```

Expand Down Expand Up @@ -187,7 +193,7 @@ This option only applies to macOS and Windows systems.
To expose a service running inside the instance on your host, you can use [VirtualBox's port forwarding feature](https://www.virtualbox.org/manual/ch06.html#natforward), for example:

```plain
$ sudo VBoxManage controlvm "primary" natpf1 "myservice,tcp,,8080,,8081"
sudo VBoxManage controlvm "primary" natpf1 "myservice,tcp,,8080,,8081"
```

You can then open, say, http://localhost:8081/, and the service running inside the instance on port 8080 will be exposed.
Expand All @@ -199,7 +205,7 @@ You can then open, say, http://localhost:8081/, and the service running inside t
To expose a service running inside the instance on your host, you can use [VirtualBox's port forwarding feature](https://www.virtualbox.org/manual/ch06.html#natforward), for example:

```powershell
PS> & $env:USERPROFILE\Downloads\PSTools\PsExec.exe -s $env:VBOX_MSI_INSTALL_PATH\VBoxManage.exe controlvm "primary" natpf1 "myservice,tcp,,8080,,8081"
& $env:USERPROFILE\Downloads\PSTools\PsExec.exe -s $env:VBOX_MSI_INSTALL_PATH\VBoxManage.exe controlvm "primary" natpf1 "myservice,tcp,,8080,,8081"
```

You can then open, say, http://localhost:8081/, and the service running inside the instance on port 8080 will be exposed.
Expand All @@ -225,14 +231,19 @@ An often requested Multipass feature is network bridging. You can add a second n
First, stop the instance:

```plain
$ multipass stop primary
multipass stop primary
```

Now, find the network interface you want to bridge with (you want the identifier before the second colon):
Now, find the network interface you want to bridge with, running the command:

```plain
$ VBoxManage list bridgedifs | grep ^Name:
Name: <b>en0</b>: Ethernet
VBoxManage list bridgedifs | grep ^Name:
```

You want the identifier before the second colon; for example `en0` in the following sample output:

```plain
Name: en0: Ethernet
Name: en1: Wi-Fi (AirPort)
Name: en2: Thunderbolt 1
Name: en3: Thunderbolt 2
Expand All @@ -242,25 +253,35 @@ Name: en3: Thunderbolt 2
Finally, tell VirtualBox to use it as the "parent" for the second interface (see more info on bridging in [VirtualBox documentation](https://www.virtualbox.org/manual/ch06.html#network_bridged) on this topic):

```plain
$ sudo VBoxManage modifyvm primary --nic2 bridged --bridgeadapter2 en0
sudo VBoxManage modifyvm primary --nic2 bridged --bridgeadapter2 en0
```

[note=caution]
Do not touch --nic1 as that's used by Multipass.
[/note]

You can then start the instance again and find the name of the new interface:
You can then start the instance again:

```plain
multipass start primary
```

To find the name of the new interface, run this command:

```plain
multipass exec primary ip link | grep DOWN
```

In the following sample output, the name of the interface that we are looking for is `enp0s8`:

```plain
$ multipass start primary
$ multipass exec primary ip link | grep DOWN
3: <b>enp0s8</b>: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
3: enp0s8: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
```

And configure that new interface — Ubuntu uses [netplan](https://netplan.io/) for that:
Now, configure that new interface (Ubuntu uses [netplan](https://netplan.io/) for that):

```plain
$ multipass exec -- primary sudo bash -c "cat > /etc/netplan/60-bridge.yaml" <<EOF
multipass exec -- primary sudo bash -c "cat > /etc/netplan/60-bridge.yaml" <<EOF
network:
ethernets:
enp0s8: # this is the interface name from above
Expand All @@ -269,13 +290,19 @@ network:
route-metric: 200 # remains with the first interface
version: 2
EOF
$ multipass exec primary sudo netplan apply
multipass exec primary sudo netplan apply
```

Finally, find the IP of the instance given by your router:

```plain
$ multipass exec primary ip address show dev enp0s8 up
multipass exec primary ip address show dev enp0s8 up
```

For example:

```plain
3: enp0s8: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
link/ether 08:00:27:2a:5f:55 brd ff:ff:ff:ff:ff:ff
inet <b>10.2.0.39</b>/24 brd 10.2.0.255 scope global dynamic enp0s8
Expand All @@ -284,7 +311,7 @@ $ multipass exec primary ip address show dev enp0s8 up
valid_lft forever preferred_lft forever
```

All the services running inside the instance should now be available on your physical network under http://&lt;the ip&gt;/.
All the services running inside the instance should now be available on your physical network under http://&lt;instance IP&gt;/.

[/tab]

Expand All @@ -307,8 +334,8 @@ This option only applies to macOS systems.
To switch back to the default `qemu` driver, first you need to stop all instances again:

```plain
$ multipass stop --all
$ multipass set local.driver=qemu
multipass stop --all
multipass set local.driver=qemu
```

Here, too, existing instances will be migrated.
Expand All @@ -324,7 +351,7 @@ This will make you lose any customisations you made to the instance in libvirt.
If you want to switch back to the default driver, run:

```plain
$ sudo multipass set local.driver=qemu
multipass set local.driver=qemu
```

Instances created with VirtualBox don't get transferred, but you can always come back to them.
Expand All @@ -336,7 +363,7 @@ Instances created with VirtualBox don't get transferred, but you can always come
If you want to switch back to the default driver:

```plain
PS> multipass set local.driver=hyperv
multipass set local.driver=hyperv
```

Instances created with VirtualBox don't get transferred, but you can always come back to them.
Expand All @@ -345,8 +372,6 @@ Instances created with VirtualBox don't get transferred, but you can always come

[/tabs]


---
*<a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/set-up-the-driver" target="_blank">Let us know</a> how this worked for you and what you’d like to see next!*

-------------------------
*Errors or typos? Topics missing? Hard to read? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/set-up-the-driver" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*

0 comments on commit d33ce0a

Please sign in to comment.