[[multipass]]
= multipass
官网: https://multipass.run

Multipass 是一个轻量虚拟机管理器，是由 Ubuntu 运营公司 Canonical 所推出的开源项目。
运行环境支持 Linux、Windows、macOS。在不同的操作系统上，使用的是不同的虚拟化技术。

* Linux: 使用 KVM
* Window: 使用 Hyper-V
* macOS: 使用 HyperKit (Intel macOS 10.14+)
* macOS: 使用 qemu (M1 macOS and Intel macOS 10.15+)

同时，Multipass 提供了一个命令行界面来启动和管理 Linux 实例。
下载一个全新的镜像需要几秒钟的时间，并且在几分钟内就可以启动并运行 VM。

== 安装 multipass
=== 通过 pkg 安装
直接通过 pkg 安装包进行安装

=== 通过 brew 安装
[source,bash]
----
brew install --cask multipass

# 安装完毕后
multipass version

# 输出
multipass   1.11.1+mac
multipassd  1.11.1+mac
----

== 卸载 multipass
=== 卸载采用 pkg 的安装
[source,bash]
----
# 卸载采用 pkg 的安装
sudo sh "/Library/Application Support/com.canonical.multipass/uninstall.sh"
----

=== 卸载采用 brew 的安装
[source,bash]
----
# 卸载 brew 安装
brew uninstall multipass

# 卸载 brew 安装并删除所有数据
brew uninstall --zap multipass
----

== 常用命令
=== 镜像
[source,bash]
----
multipass find                      # 查找可用镜像
----

=== 配置
[source,bash]
----
multipass get --keys       # 查看所有可用的配置项
multipass get xxx          # 查看 key 为 xxx 的配置项值
multipass set xxx=yyy      # 设置 key 为 xxx 的配置项值为 yyy
----

=== 实例
[source,bash]
----
multipass list                      # 查看实例
multipass launch --name primary     # 创建并启动 primary 实例，并自动绑定宿主机的 $HOME 目录到虚拟机的 /home/ubuntu/Home 目录
multipass launch --name wspsc       # 创建并启动 wspsc 实例
multipass launch lts --name wspsc --cpus 2 --disk 10G --memory 2G
multipass launch lts -n wspsc -c 2 -d 10G -m 2G

multipass info xxx                      # 查看名为 xxx 的实例信息

multipass start xxx                     # 启动名为 xxx 的实例
multipass start xxx yyy zzz             # 同时启动名为 xxx，yyy，zzz 的实例
multipass start --all                   # 启动所有实例

multipass stop xxx                      # 停止名为 xxx 的实例
multipass stop xxx yyy zzz              # 同时停止名为 xxx，yyy，zzz 的实例
multipass stop --all                    # 停止所有实例

multipass restart xxx                   # 重启名为 xxx 的实例
multipass restart xxx yyy zzz           # 同时重启名为 xxx，yyy，zzz 的实例
multipass restart --all                 # 重启所有实例

multipass suspend xxx                   # 暂停名为 xxx 的实例
multipass suspend xxx yyy zzz           # 暂停名为 xxx，yyy，zzz 的实例
multipass suspend --all                 # 暂停所有实例

multipass delete xxx                    # 删除名为 xxx 的实例(删除前会自动停止实例)
multipass delete --all                  # 删除所有实例
multipass purge                         # 清除已删除的实例
multipass delete xxx --purge            # 删除并清除名为 xxx 的实例
multipass delete --all --purge          # 删除并清除所有实例

multipass recover xxx                   # 恢复名为 xxx 的实例（xxx实例处于删除状态）

multipass shell xxx                     # 进入名为 xxx 的实例

multipass set local.xxx.cpus=4          # 修改名为 xxx 的实例的 cpu 个数为 4
multipass set local.xxx.disk=20G        # 修改名为 xxx 的实例的磁盘容量为 20G
multipass set local.xxx.memory=4G       # 修改名为 xxx 的实例的内存容量为 4G

multipass set client.primary-name=xxx   # 将名为 xxx 的实例作为 primary 实例
----

=== mount & unmount
[source,bash]
----
# 注意：在 macOS 下不能绑定宿主机的 ~/Document 下面的目录，否则在实例 shell 中执行 ls 命令时会出现以下错误：
# ls: reading directory '.': Permission denied
multipass mount $HOME xxx:/some/path          # 将宿主机的当前用户的 home 目录绑定到名为 xxx 实例的 /some/path 目录
multipass mount /some/path xxx:/some/path     # 将宿主机的 /some/path 目录绑定到名为 xxx 实例的 /some/path 目录

# 给名为 xxx 实例绑定的多个目录
multipass mount /some/path1 xxx:/some/path1
multipass mount /some/path2 xxx:/some/path2

# umount 名为 xxx 实例的多个目录
multipass umount xxx:/some/path1
multipass umount xxx:/some/path2

# umount 名为 xxx 实例的所有目录
multipass umount xxx
----

=== 网络
[source,bash]
----
# 查看网络
multipass networks

# 输出
Name     Type         Description
bridge0  bridge       Network bridge with en1, en2, en3
en0      wifi         Wi-Fi
en1      thunderbolt  Thunderbolt 1
en2      thunderbolt  Thunderbolt 2
en3      thunderbolt  Thunderbolt 3
en4      ethernet     Ethernet Adapter (en4)
en5      ethernet     Ethernet Adapter (en5)
en6      ethernet     Ethernet Adapter (en6)
----


== 配置项
=== client.gui.autostart
[source,text]
----
Key:
    client.gui.autostart

Description:
    Whether or not the Multipass GUI should start automatically on startup

Allowed values:
    Any case variations of on|off, yes|no, 1|0, and true|false.

Examples:
    multipass set client.gui.autostart=true

Default:
    true (on Linux and macOS it only takes effect after the client (CLI or GUI) is run a first time).
----


=== client.gui.hotkey
[source,text]
----
Key:
    client.gui.hotkey

Description:
    A keyboard shortcut for the GUI to open a shell into the primary instance.

Allowed values:
    A single case-insensitive sequence of keys, containing:
        * zero or more modifiers (e.g. Ctrl, Alt, Cmd, Command, Opt, etc.)
        * one non-modifier key (e.g. u, 4, ., Space, Tab, Pause, F3). When key names have multiple words, quote and use spaces (e.g. "Print Screen").
        * [On macOS] alternatively, utf-8 characters for mac keys (e.g. ⌘, ⌥, ⇧, ⌃)
        * A plus (+) sign separating each alphabetic word (but not key symbols) from the next
        * The empty string (""), to disable the hotkey.

Examples:
    multipass set client.gui.hotkey="Ctrl+Print Screen".
    multipass set client.gui.hotkey="⌃⇧Y".
    multipass set client.gui.hotkey=option+space.
    multipass set client.gui.hotkey=""

Caveats:
    * There are some limitations on what keys and combinations are supported, depending on multiple factors such as keyboard, mapping, and OS (e.g. AltGr, numpad, or media keys may or may not work; shift+enter is rejected).
    * Some combinations may be grabbed by the OS before they reach multipass (e.g. meta+a may open the Applications, ctrl+alt+f3 may move ttys).

Default:
    * Ctrl+Alt+U on Linux and Windows
    * ⌥⌘U on macOS
----

=== client.primary-name
[source,text]
----
Key:
    client.primary-name

Description:
    The name of the instance that is launched/recognized as primary.

Allowed values:
    Any valid instance name (see launch), or the empty string ("") to disable primary.

Examples:
    multipass set client.primary-name=asdf
    multipass set client.primary-name=

Default:
    primary
----

=== client.apps.windows-terminal.profiles.
[source,text]
----
Key:
    client.apps.windows-terminal.profiles.

Description:
    What profiles should be enabled in Windows Terminal.

Allowed values:
    For the time being, the following values are supported:
        * primary to enable a profile for the primary instance. Note that this value is independent of what primary name is configured.
        * none to disable any profiles.

Examples:
    multipass set client.apps.windows-terminal.profiles=none

Default:
    primary (a profile for primary is added when Windows Terminal is found)
----

=== local.bridged-network
[source,text]
----
Key:
    local.bridged-network

Description:
    The name of the interface used when launch --bridged is issued.

Allowed values:
    Any name from multipass networks. Note validation is deferred to multipass launch.

Examples:
    multipass set local.bridged-network=en0

Default:
    <empty> ("").
----

=== local.driver
[source,text]
----
Key:
    local.driver

Description:
    A string identifying the hypervisor back-end in use.

Allowed values:
    * qemu, libvirt, and lxd on Linux.
    * hyperv and virtualbox on Windows.
    * hyperkit and virtualbox on Intel macOS 10.14+.
    * qemu on M1 macOS and Intel macOS 10.15+.

Examples:

Default:
    * qemu on amd64 Linux and M1 macOS.
    * lxd on non-amd64 Linux.
    * hyperv on Windows.
    * hyperkit on Intel macOS.
----

=== local.passphrase
[source,text]
----
Key:
    local.passphrase

Description:
    The passphrase used by clients requesting access to the Multipass service via the authenticate command.
    The passphrase can either be given directly in the command line or if omitted, a prompt will be displayed where the user can enter the passphrase without it being echoed on the screen.

Allowed values:
    Any string.

Examples:
    multipass set local.passphrase

Default:
    Not set (expressed as false by multipass get).
----

=== local.privileged-mounts
[source,text]
----
Key:
    local.privileged-mounts

Description:
    Controls whether multipass mount is allowed.
    Because mounts are performed as privileged users (root on Linux and macOS, SYSTEM on Windows), they allow write access to the whole host operating system. On Linux and macOS, only privileged users (members of sudo, wheel, admin groups) can use Multipass, so this isn’t a concern.
    On Windows mounts are disabled by default, as anyone with TCP access to localhost (127.0.0.1) can use Multipass, and by extension, gets access to the whole file system.

Allowed values:
    Any case variations of on|off, yes|no, 1|0, and true|false.

Examples:
    multipass set local.privileged-mounts=Yes

Default:
    * true on Linux and macOS
    * false on Windows
----

=== local.<instance-name>.cpus
[source,text]
----
Key:
    local.<instance-name>.cpus
    Where <instance-name> is the name of any Multipass instance.

Description:
    The number of CPUs to simulate on the virtual machine. This establishes a limit on how many host threads the instance can simultaneously use, at most.

Allowed values:
    A positive integer number. Multipass does not impose an upper limit on allowed values, but the underlying backend may do so.

Examples:
    multipass set local.handsome-ling.cpus=4

Default:
    The number of CPUs that the instance was launched with. See also launch.
----

=== local.<instance-name>.disk
[source,text]
----
Key:
    local.<instance-name>.disk
    Where <instance-name> is the name of any Multipass instance.

Description:
    The size of the instance’s disk.
    Disk can only be enlarged.

Allowed values:
    A size no smaller than the current disk size. This size can be specified with a positive integer or decimal number, optionally followed by a unit. Any case variations of the following suffixes are accepted as units:

    * B, to designate one byte.
    * KiB, KB, or K, to designate 1024 bytes.
    * MiB, MB, or M, to designate 1024 x 1024 = 1048576 bytes
    * GiB, GB, or G, to designate 1024 x 1024 x 1024 = 1073741824 bytes

    Decimal bytes (e.g. 1.1B) are refused, unless specified with larger units (>= KiB), in which case the amount is floored (e.g. 1.2KiB is interpreted as 1228B, even though 1.2 x 1024 = 1228.8).

Examples:
    multipass set local.handsome-ling.disk=7.5G

Default:
    The size of the disk that the instance was launched with. See also launch.
----

=== local.<instance-name>.memory
[source,text]
----
Key:
    local.<instance-name>.memory
    Where <instance-name> is the name of any Multipass instance.

Description:
    The amount of RAM that is allocated to the instance.
    Hypervisors may impose additional rounding on the total memory that is given to the instance. Furthermore, the value that is set here does not correspond exactly to the memory size that is available in userspace inside the instance (e.g. reported by free -b), because the guest kernel claims some for its own. Total memory can be inspected inside the instance with lshw (e.g. sudo lshw -json -class memory).
    Memory on the host is only allocated as the instance uses it, not right away. Once used, it is not released until the instance is shutdown or restarted.

Allowed values:
    A positive memory size, specified with a positive integer or decimal number, optionally followed by a unit. Any case variations of the following suffixes are accepted as units:

    * B, to designate one byte.
    * KiB, KB, or K, to designate 1024 bytes.
    * MiB, MB, or M, to designate 1024 x 1024 = 1048576 bytes
    * GiB, GB, or G, to designate 1024 x 1024 x 1024 = 1073741824 bytes

    Decimal bytes (e.g. 1.1B) are refused, unless specified with larger units (>= KiB), in which case the amount is floored (e.g. 1.2KiB is interpreted as 1228B, even though 1.2 x 1024 = 1228.8).

Examples:
    multipass set local.handsome-ling.memory=4G

Default:
    The amount of memory that the instance was launched with. See also launch.
----

