diff --git a/multipass/how-to/how_to_set_up_a_virtualisation_driver.md b/multipass/how-to/how_to_set_up_a_virtualisation_driver.md new file mode 100644 index 0000000..e424ae9 --- /dev/null +++ b/multipass/how-to/how_to_set_up_a_virtualisation_driver.md @@ -0,0 +1,132 @@ +> See also: [Driver](/t/28410), [`local.driver`](/t/27357) + +This document demonstrates how to change to an alternative virtualisation driver and how to switch back to default driver. + +Be aware that Multipass already has sensible defaults, so this is an optional step. + +To review the default drivers and learn how to choose one, see: [Driver](/t/28410). + +## Configure an alternative virtualisation driver + +Please note that changing your driver will also change its hypervisor. + +[tabs] + +[tab version="Linux"] + +If you want to (or have to), you can switch to the experimental [libvirt](https://libvirt.org/) instead of using the default hypervisor that Multipass uses. + +To install libvirt, run the following command (or use the equivalent for your Linux distribution): + +```plain +sudo apt install libvirt-daemon-system +``` + +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 +``` + +Then, stop all instances and tell Multipass to use libvirt, running the following commands: + +```plain +multipass stop --all +multipass set local.driver=libvirt +``` + +All your existing instances will be migrated and can be used straight away. + +[note type="information"] +You can still use the `multipass` client and the tray icon, and any changes you make to the configuration of the instance in libvirt will be persistent. They may not be represented in Multipass commands such as `multipass info`, though. +[/note] + +[/tab] + +[tab version="macOS"] + +If you want to (or have to), you can switch to VirtualBox instead of using the default hypervisor that Multipass uses. + +To switch the Multipass driver to VirtualBox, run this command: + +```plain +sudo multipass set local.driver=virtualbox +``` + +From now on, all instances started with `multipass launch` will use VirtualBox behind the scenes. + +[/tab] + +[tab version="Windows"] + +If you want to (or have to), you can switch to VirtualBox instead of using the default hypervisor that Multipass uses. + +To that end, you need to install VirtualBox and to [run the VirtualBox installer as administrator](https://forums.virtualbox.org/viewtopic.php?f=6&t=88405#p423658). + +To switch the Multipass driver to VirtualBox (also with Administrator privileges), run this command: + +```powershell +multipass set local.driver=virtualbox +``` + +From then on, all instances started with `multipass launch` will use VirtualBox behind the scenes. + +[/tab] + +[/tabs] + +## Switch back to the default driver + +> See also: [`stop`](/t/23951), [`local.driver`](/t/27357) + +[tabs] + +[tab version="Linux"] + +To switch back to the default `qemu` driver, run the following commands: + +```plain +multipass stop --all +multipass set local.driver=qemu +``` + +All your existing instances will be migrated and can be used straight away. + +[note type="information"] +This will make you lose any customisations you made to the instance in libvirt. +[/note] + +[/tab] + +[tab version="macOS"] + +If you want to switch back to the default driver, run the following command: + +```plain +multipass set local.driver=qemu +``` + +[note type="information"] +Instances created with VirtualBox don't get transferred, but you can always come back to them. +[/note] + +[/tab] + +[tab version="Windows"] + +If you want to switch back to the default driver, run the following command: + +```plain +multipass set local.driver=hyperv +``` +[note type="information"] +Instances created with VirtualBox don't get transferred, but you can always come back to them. +[/note] + +[/tab] + +[/tabs] + +--- + +*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* diff --git a/multipass/how-to/how_to_set_up_network_bridging_for_a_multipass_instance.md b/multipass/how-to/how_to_set_up_network_bridging_for_a_multipass_instance.md new file mode 100644 index 0000000..67786e8 --- /dev/null +++ b/multipass/how-to/how_to_set_up_network_bridging_for_a_multipass_instance.md @@ -0,0 +1,112 @@ +> See also: [Driver](/t/28410), [`local.driver`](/t/27357) + +This document demonstrates how to set up network bridging for a Multipass instance. + +## Use VirtualBox to set up network bridging for a Multipass instance + +[tabs] + +[tab version="Linux"] + +This option only applies to macOS systems. + +[/tab] + +[tab version="macOS"] + +Network bridging lets you add a second network interface to the instance and expose it on your physical network. + +First, stop the instance: + +```plain +multipass stop primary +``` + +Now, find the network interface you want to bridge with, running the command: + +```plain +VBoxManage list bridgedifs | grep ^Name: +``` + +You want to find 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 +... +``` + +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 +``` + +[note=caution] +Do not touch --nic1 as that's used by Multipass. +[/note] + +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 +3: enp0s8: mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000 +``` + +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" < 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 10.2.0.39/24 brd 10.2.0.255 scope global dynamic enp0s8 + valid_lft 86119sec preferred_lft 86119sec + inet6 fe80::a00:27ff:fe2a:5f55/64 scope link + valid_lft forever preferred_lft forever +``` + +All the services running inside the instance should now be available on your physical network under http://<instance IP>/. + +[/tab] + +[tab version="Windows"] + +This option only applies to macOS systems. + +[/tab] + +[/tabs] \ No newline at end of file diff --git a/multipass/how-to/how_to_set_up_port_forwarding_to_a_multipass_instance.md b/multipass/how-to/how_to_set_up_port_forwarding_to_a_multipass_instance.md new file mode 100644 index 0000000..c1820fa --- /dev/null +++ b/multipass/how-to/how_to_set_up_port_forwarding_to_a_multipass_instance.md @@ -0,0 +1,43 @@ +> See also: [Driver](/t/28410), [`local.driver`](/t/27357) + +This document demonstrates how to set up port forwarding to a Multipass instance. + +## Use VirtualBox to set up port forwarding to a Multipass instance + +[tabs] + +[tab version="Linux"] + +This option only applies to macOS and Windows systems. + +[/tab] + +[tab version="macOS"] + +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). + +Example: + +```plain +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. + +[/tab] + +[tab version="Windows"] + +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). + +Example: + +```powershell +& $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. + +[/tab] + +[/tabs] \ No newline at end of file diff --git a/multipass/how-to/how_to_set_up_the_driver.md b/multipass/how-to/how_to_set_up_the_driver.md deleted file mode 100644 index 0483f59..0000000 --- a/multipass/how-to/how_to_set_up_the_driver.md +++ /dev/null @@ -1,377 +0,0 @@ -> 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. - -## Default driver - -[tabs] - -[tab version="Linux"] - -By default, Multipass on Linux uses the `qemu` or `lxd` driver (depending on the architecture). - -[/tab] - -[tab version="macOS"] - -By default, Multipass on macOS uses the `qemu` driver. - -[/tab] - -[tab version="Windows"] - -By default, Multipass on Windows uses the `hyperv` driver. - -[/tab] - -[/tabs] - -## Install an alternative driver - -[tabs] - -[tab version="Linux"] - -If you want more control over your VMs after they are launched, you can also use the experimental [libvirt](https://libvirt.org/) driver. - -To install libvirt, run the following command (or use the equivalent for your Linux distribution): - -```plain -sudo apt install libvirt-daemon-system -``` - -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 -``` - -Then, stop all instances and tell Multipass to use libvirt, running the following commands: - -```plain -multipass stop --all -multipass set local.driver=libvirt -``` - -All your existing instances will be migrated and can be used straight away. - -[note type="information"] -You can still use the `multipass` client and the tray icon, and any changes you make to the configuration of the instance in libvirt will be persistent. They may not be represented in Multipass commands such as `multipass info`, though. -[/note] - -[/tab] - -[tab version="macOS"] - -An alternative option is to use VirtualBox. - -To switch the Multipass driver to VirtualBox, run this command: - -```plain -sudo multipass set local.driver=virtualbox -``` - -From now on, all instances started with `multipass launch` will use VirtualBox behind the scenes. - -[/tab] - -[tab version="Windows"] - -If you want to (or have to), you can change the hypervisor that Multipass uses to VirtualBox. - -To that end, install VirtualBox, if you haven't yet. You may find that you need to [run the VirtualBox installer as administrator](https://forums.virtualbox.org/viewtopic.php?f=6&t=88405#p423658). - -To switch the Multipass driver to VirtualBox (also with Administrator privileges), run this command: - -```powershell -multipass set local.driver=virtualbox -``` - -From then on, all instances started with `multipass launch` will use VirtualBox behind the scenes. - -[/tab] - -[/tabs] - -## Use the driver to view Multipass instances - -[tabs] - -[tab version="Linux"] - -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 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 -``` - -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) - -[/tab] - -[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, use the command: - -```plain -sudo VirtualBox -``` - -![Multipass instances in VirtualBox](upload://mld2SIalX93tc3StGHaqb6OTyDO.png) - -And, to list the instances on the command line, run: - -```plain -sudo VBoxManage list vms -``` - -Sample output: -```plain -"primary" {395d5300-557d-4640-a43a-48100b10e098} -``` - -[note type="information"] -You can still use the `multipass` client and the system menu icon, and any changes you make to the configuration of the instances in VirtualBox will be persistent. They may not be represented in Multipass commands such as `multipass info` , though. -[/note] - -[/tab] - -[tab version="Windows"] - -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 -& $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 -"primary" {05a04fa0-8caf-4c35-9d21-ceddfe031e6f} -``` - -[note type="information] -You can still use the `multipass` client and the system menu icon, and any changes you make to the configuration of the instances in VirtualBox will be persistent. They may not be represented in Multipass commands such as `multipass info`, though. -[/note] - -[/tab] - -[/tabs] - - -## Use VirtualBox to set up port forwarding for a Multipass instance - -[tabs] - -[tab version="Linux"] - -This option only applies to macOS and Windows systems. - -[/tab] - -[tab version="macOS"] - -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" -``` - -You can then open, say, http://localhost:8081/, and the service running inside the instance on port 8080 will be exposed. - -[/tab] - -[tab version="Windows"] - -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 -& $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. - -[/tab] - -[/tabs] - -## Use VirtualBox to set up network bridging for a Multipass instance - -[tabs] - -[tab version="Linux"] - -This option only applies to macOS systems. - -[/tab] - -[tab version="macOS"] - -An often requested Multipass feature is network bridging. You can add a second network interface to the instance and expose it on your physical network. - -First, stop the instance: - -```plain -multipass stop primary -``` - -Now, find the network interface you want to bridge with, running the command: - -```plain -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 -... -``` - -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 -``` - -[note=caution] -Do not touch --nic1 as that's used by Multipass. -[/note] - -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 -3: enp0s8: mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000 -``` - -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" < 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 10.2.0.39/24 brd 10.2.0.255 scope global dynamic enp0s8 - valid_lft 86119sec preferred_lft 86119sec - inet6 fe80::a00:27ff:fe2a:5f55/64 scope link - valid_lft forever preferred_lft forever -``` - -All the services running inside the instance should now be available on your physical network under http://<instance IP>/. - -[/tab] - -[tab version="Windows"] - -This option only applies to macOS systems. - -[/tab] - -[/tabs] - -## Switch back to the default driver - -> See also: [`stop`](/t/23951), [`local.driver`](/t/27357) - -[tabs] - -[tab version="Linux"] - -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 -``` - -Here, too, existing instances will be migrated. - -[note type="information"] -This will make you lose any customisations you made to the instance in libvirt. -[/note] - -[/tab] - -[tab version="macOS"] - -If you want to switch back to the default driver, run: - -```plain -multipass set local.driver=qemu -``` - -Instances created with VirtualBox don't get transferred, but you can always come back to them. - -[/tab] - -[tab version="Windows"] - -If you want to switch back to the default driver: - -```plain -multipass set local.driver=hyperv -``` - -Instances created with VirtualBox don't get transferred, but you can always come back to them. - -[/tab] - -[/tabs] - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* diff --git a/multipass/how-to/how_to_view_multipass_instances_using_the_driver.md b/multipass/how-to/how_to_view_multipass_instances_using_the_driver.md new file mode 100644 index 0000000..1ebdcdd --- /dev/null +++ b/multipass/how-to/how_to_view_multipass_instances_using_the_driver.md @@ -0,0 +1,93 @@ +> See also: [Driver](/t/28410), [`local.driver`](/t/27357) + +This document demonstrates how to view Multipass instances using the driver. + +Prerequisite: Have a running Multipass instance. + +## Use the driver to view Multipass instances + +[tabs] + +[tab version="Linux"] + +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, run the following command (see [`man virsh`](http://manpages.ubuntu.com/manpages/xenial/man1/virsh.1.html) for a command reference): + +```plain +virsh list +``` + +The output will be similar to the following: + +```plain + Id Name State +-------------------------------------- + 1 unaffected-gyrfalcon running +``` +Alternatively, you can use the `virt-manager` GUI: + +![obraz|584x344](upload://bFIxA9CPAqBeWjuQxDaZBYBNsZK.png) + +[/tab] + +[tab version="macOS"] + +Multipass runs as the `root` user. To see Multipass instances via the driver, you need to run Virtualbox or `VBoxManage` commands as root. + +To see the instances in VirtualBox, use the command: + +```plain +sudo VirtualBox +``` + +![Multipass instances in VirtualBox](upload://mld2SIalX93tc3StGHaqb6OTyDO.png) + +And, to list the instances on the command line, run: + +```plain +sudo VBoxManage list vms +``` + +Sample output: +```plain +"primary" {395d5300-557d-4640-a43a-48100b10e098} +``` + +[note type="information"] +You can still use the `multipass` client and the system menu icon. Any changes you make to the configuration of the instances in VirtualBox will be persistent. They may not be represented in Multipass commands such as `multipass info`, though. +[/note] + +[/tab] + +[tab version="Windows"] + +Multipass runs as the _System_ account. To see Multipass instances via the driver, you need to run Virtualbox or `VBoxManage` commands as the _System_ account using [`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 +& $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 +"primary" {05a04fa0-8caf-4c35-9d21-ceddfe031e6f} +``` + +[note type="information] +You can still use the `multipass` client and the system menu icon. Any changes you make to the configuration of the instances in VirtualBox will be persistent. They may not be represented in Multipass commands such as `multipass info`, though. +[/note] + +[/tab] + +[/tabs] +