diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..d7ed115976 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +Documentation starter pack +========================== + +The documentation starter pack helps you to quickly set up, build, and publish documentation with Sphinx. + +It contains common styling and configuration through the `Canonical Sphinx`_ extension, supports both |RST| and Markdown, and includes automatic documentation checks. + +The :ref:`quickstart` gives you a basic idea of how to start. +Detailed information is available for :ref:`setting up your documentation ` and for :ref:`updating it `. + +You can also find detailed information about the :ref:`automatic-checks` included in the starter pack, and a :ref:`list of projects ` that use the starter pack. + +.. toctree:: + :hidden: + :maxdepth: 2 + + /content/quickstart + /content/setup + /content/update + /content/automatic_checks + /content/examples + /content/contributing diff --git a/docs/src/contribute-to-multipass-docs.md b/docs/src/contribute-to-multipass-docs.md index 7fce9c6db5..e69de29bb2 100644 --- a/docs/src/contribute-to-multipass-docs.md +++ b/docs/src/contribute-to-multipass-docs.md @@ -1,58 +0,0 @@ -# Contribute to Multipass docs -Our documentation is a community effort and anyone can contribute. - -**We warmly welcome community contributions, suggestions, fixes and constructive feedback.** - -## Documentation practice - -Multipass documentation is organised according to the [Diátaxis](https://diataxis.fr/) framework and (mostly) follows the [Canonical documentation style guide](https://docs.ubuntu.com/styleguide/en/). - -At Canonical, we have embarked on a comprehensive, long-term project to transform documentation. Our aim is to create and maintain documentation product and practice that will represent a standard of excellence. We want documentation to be the best it possibly can be. - -> See also: [Documentation practice at Canonical](https://canonical.com/documentation) and [Diátaxis, a new foundation for Canonical documentation](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation) - -## How you can contribute - -Multipass documentation is maintained on our Discourse forum. Every documentation page has an equivalent topic on the forum, that can be accessed by clicking the "Help improve this document in the forum" link at the bottom of the page. - -![image|540x103](upload://w2UG2yP4Vqu4VyiaLxq1SE25GI3.png) - -To contribute to the documentation, you can leave a comment on the relevant forum topic, or edit content directly if your *Trust level* allows it. However, if your intervention is bigger than fixing a typo, it’s a good idea to comment on the page to discuss first. - -Either way, your name will be added to the Contributors list at the bottom of the page. - -### Formatting content - -In Discourse, content is formatted using Markdown syntax. You can also use the style toolbar in the Discourse topic editing window to format elements, if you're not familiar with Markdown. - -> See also: [Discourse | Supported formatting in posts (markdown, BBCcode, and HTML ](https://meta.discourse.org/t/supported-formatting-in-posts-markdown-bbcode-and-html/239348) (in particular, the link to [`markdown-it` ](https://markdown-it.github.io/) and [CommonMark Spec ](https://spec.commonmark.org/)) - -A useful trick to view the Markdown source of a Discourse page is replacing `/t//` in the URL with `/raw/`. For example, to view the source of the [Multipass Documentation home](https://multipass.run/docs) topic, instead of the default Discourse URL: - -* `https://discourse.ubuntu.com/t/multipass-documentation/8294` - -try pasting this modified URL in your browser's address bar: - -* `https://discourse.ubuntu.com/raw/8294` - -## Join the Open Documentation Academy - -The [Canonical Open Documentation Academy](https://canonical.com/documentation/open-documentation-academy) (CODA) is a community-oriented initiative led by our Technical Authors to provide help, advice and mentorship on documentation practice in a friendly, welcoming environment. A key aim of this initiative is to help lower the barrier to successful open source software contribution by making documentation into the gateway. - -> See also: [Documentation practice at Canonical](https://canonical.com/documentation). - -If you want to contribute to Multipass documentation, you can also check if there are any outstanding tasks on the [Open Documentation Academy GitHub](https://github.com/canonical/open-documentation-academy/issues?q=is%3Aissue+is%3Aopen+multipass+). This could be a great opportunity to improve your documentation practice, receive guidance and mentorship and publicly contribute to an open-source project, if that's something that interests you. - -Everyone is invited join the Academy's [weekly office hours](https://discourse.ubuntu.com/t/documentation-office-hours/42771), listen in to presentations and participate in discussions. Live sessions are also recorded and made available on the[ Ubuntu on Air YouTube channel](https://www.youtube.com/@UbuntuOnAir), in the[ Documentation Academy playlist](https://www.youtube.com/watch?v=GT03aSdabJE&list=PL-qBHd6_LXWYefHij0dJ7c9X-Q9QfFFFa&pp=iAQB). - - -## Feedback and issues - -You can leave feedback on our documentation using the [Multipass documentation feedback form](https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform) linked at the top of every page. If you have a request or would like to report a problem with the documentation, you may also [open an issue on GitHub](https://github.com/canonical/multipass/issues/new/choose). - -You can also find the team in the [Matrix Multipass room](https://app.element.io/#/room/#Multipass:matrix.org). - ---- - -Don’t hesitate to contribute, we value your input and suggestions! - diff --git a/docs/src/explanation/about-performance.md b/docs/src/explanation/about-performance.md index c5f47a3aad..e69de29bb2 100644 --- a/docs/src/explanation/about-performance.md +++ b/docs/src/explanation/about-performance.md @@ -1,44 +0,0 @@ -# About performance -When considering performance with Multipass, there are two aspects that need to be accounted for: - -* the [Multipass instance](/explanation/instance) -* the [host machine](/explanation/host) - -There are many factors that can affect the performance of the instance and the host. To ensure the best performance of both areas, careful consideration should be given. - -## Host system - -Here you'll find some considerations and recommendations on allocating host system resources. - -### CPUs/cores/threads - -When provisioning a Multipass instance, you should take into account the host's CPU speed and the number of cores and threads. You should also consider the number of instances that will be running simultaneously. - -The number of cores allocated to an instance and the number of running instances will greatly impact processes running on the host machine itself. As general guidance, you should reserve at least two threads, that will not be allocated to running instances. - -Of course, there may be other factors in different host machines that can greatly affect how well they perform when running Multipass instances. - -### Memory usage - -The amount of memory allocated to instances can also greatly impact the host system. - -You should not overallocate memory for running Multipass instances, as this can cause the host to appear slower than normal or become unresponsive. - -We recommend that you reserve at least 4GB of memory for the host, but this also depends on the workload of the host itself, so more memory may be needed. - -## Multipass instances - -Here you'll find some considerations and recommendations on allocating resources to your instances. - -### CPUs - -The number of CPUs allocated to a Multipass instance has a direct impact on the performance of the instance itself. Generally, the more CPUs allocated, the more potential for better performance in the instance. This depends heavily on the workload intended for instance. - -### Memory - -As with cores, the amount of memory allocated to a Multipass instance will also have a direct on its performance. This is also dependent on the intended workload of instances. Naturally, more memory intensive workloads provide much larger gains in performance if more memory is allocated to the instance. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/about-security.md b/docs/src/explanation/about-security.md index 04f19e1acb..e69de29bb2 100644 --- a/docs/src/explanation/about-security.md +++ b/docs/src/explanation/about-security.md @@ -1,23 +0,0 @@ -# About security -> See also: [Authentication](/explanation/authentication), [How to authenticate clients with the Multipass service](/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service), [`authenticate`](/reference/command-line-interface/authenticate), [`local.passphrase`](/reference/settings/local-passphrase) - -```{caution} -**WARNING** - -Multipass is primarily intended for development, testing, and local environments. It is not intended for production use. Review the security considerations in this page carefully before deploying your Multipass VMs. -``` - -Multipass runs a daemon that is accessed locally via a Unix socket on Linux and macOS, and over a TLS socket on Windows. Anyone with access to the socket can fully control Multipass, which includes mounting host file systems or to tweaking the security features for all instances. - -Therefore, make sure to restrict access to the daemon to trusted users. - -## Local access to the Multipass daemon - -The Multipass daemon runs as root and provides a Unix socket for local communication. Access control for Multipass is initially based on group membership and later by the client's TLS certificate when accepted by providing a set passphrase. - -The first client to connect that is a member of the `sudo` group (or `wheel`/`adm`, depending on the OS) will automatically have its TLS certificate imported into the Multipass daemon and will be authenticated to connect. After this, any other client connecting will need to [`authenticate`](/reference/command-line-interface/authenticate) first by providing a [passphrase](/reference/settings/local-passphrase) set by the administrator. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/alias.md b/docs/src/explanation/alias.md index 70ac940a8e..e69de29bb2 100644 --- a/docs/src/explanation/alias.md +++ b/docs/src/explanation/alias.md @@ -1,9 +0,0 @@ -# Alias -> See also: [`alias`](/reference/command-line-interface/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases). - -In Multipass, an **alias** is a shortcut for a command that runs inside a given instance. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/authentication.md b/docs/src/explanation/authentication.md index 46b7cd163c..e69de29bb2 100644 --- a/docs/src/explanation/authentication.md +++ b/docs/src/explanation/authentication.md @@ -1,31 +0,0 @@ -# Authentication -> See also: [How to authenticate clients with the Multipass service](/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service) - -Before executing any commands, Multipass requires clients to authenticate with the service. Multipass employs an authentication process based on x509 certificates signed by elliptic curve (EC) keys, powered by OpenSSL, to authenticate clients. When a client connects, Multipass verifies the client's certificate, ensuring only authenticated clients can communicate with the service. - -[tabs] - -[tab version="Linux"] -Linux and macOS hosts currently use a Unix domain socket for client and daemon communication. Upon first use, this socket only allows a client to connect via a user belonging to the group that owns the socket. For example, this group could be `sudo`, `admin`, or `wheel` and the user needs to belong to this group or else permission will be denied when connecting. - -After the first client connects with a user belonging to the socket's admin group, the client's OpenSSL certificate will be accepted by the daemon and the socket will be then be open for all users to connect. Any other user trying to connect to the Multipass service will need to authenticate with the service using the previously set [`local.passphrase`](/reference/settings/local-passphrase). -[/tab] - -[tab version="macOS"] -Linux and macOS hosts currently use a Unix domain socket for client and daemon communication. Upon first use, this socket only allows a client to connect via a user belonging to the group that owns the socket. For example, this group could be `sudo`, `admin`, or `wheel` and the user needs to belong to this group or else permission will be denied when connecting. - -After the first client connects with a user belonging to the socket's admin group, the client's OpenSSL certificate will be accepted by the daemon and the socket will be then be open for all users to connect. Any other user trying to connect to the Multipass service will need to authenticate with the service using the previously set [`local.passphrase`](/reference/settings/local-passphrase). -[/tab] - -[tab version="Windows"] -The Windows host uses a TCP socket listening on port 50051 for client connections. This socket is open for all to use since there is no concept of file ownership for TCP sockets. This is not very secure in that any Multipass client can connect to the service and issue any commands. - -To close this gap, the client will now need to be authenticated with the Multipass service. To ease the burden of having to authenticate the client, the user who installs the updated version of Multipass will automatically have their clients authenticated with the service. Any other users connecting to the service will have to use authenticate using the previously set [`local.passphrase`](/reference/settings/local-passphrase). -[/tab] - -[/tabs] - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/blueprint.md b/docs/src/explanation/blueprint.md index 43850f7736..e69de29bb2 100644 --- a/docs/src/explanation/blueprint.md +++ b/docs/src/explanation/blueprint.md @@ -1,44 +0,0 @@ -# Blueprint -> See also: [How to use a blueprint](/how-to-guides/manage-instances/use-a-blueprint) - -In Multipass, a **blueprint** is a recipe to create a customised Multipass [instance](/explanation/instance). - -Blueprints consist of a base image, cloud-init initialisation, and a set of parameters describing the instance itself, e.g. minimum memory, CPUs or disk. - -Blueprints are defined from a YAML file with the following schema: - -``` -# v1/.yaml - -description: # * a short description of the blueprint ("tagline") -version: # * a version string - -runs-on: # a list of architectures this blueprint can run on -- arm64 # see https://doc.qt.io/qt-5/qsysinfo.html#currentCpuArchitecture -- x86_64 # for a list of valid values - -instances: - : # * equal to the blueprint name - image: # a valid image alias, see `multipass find` for available values - limits: - min-cpu: # the minimum number of CPUs this blueprint can work with - min-mem: # the minimum amount of memory (can use G/K/M/B suffixes) - min-disk: # and the minimum disk size (as above) - timeout: # maximum time for the instance to launch, and separately for cloud-init to complete - cloud-init: - vendor-data: | # cloud-init vendor data - - -health-check: | # a health-check shell script ran by integration tests - - -``` - -Blueprints currently integrated into Multipass can be found with the [`multipass find`](/reference/command-line-interface/find) command. - -For more information on creating a blueprint for inclusion into Multipass, please refer to the [GitHub project](https://github.com/canonical/multipass-blueprints). - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/driver.md b/docs/src/explanation/driver.md index cf56c356d9..e69de29bb2 100644 --- a/docs/src/explanation/driver.md +++ b/docs/src/explanation/driver.md @@ -1,71 +0,0 @@ -# Driver -> See also: [How to set up the driver](/how-to-guides/customise-multipass/set-up-the-driver), [`local.driver`](/reference/settings/local-driver), [Instance](/explanation/instance), [Platform](/explanation/platform) - -A **driver** is the technology through which Multipass emulates a running machine. It corresponds to a hypervisor or intermediary technology to run virtual machines. The driver is sometimes also referred to as "backend". - -Multipass relies on a driver to operate. It supports multiple drivers, but it runs with a single driver at a time. There is a [Multipass setting](/reference/settings/settings) to select the driver: [`local.driver`](/reference/settings/local-driver). - -On some platforms, it is possible to select a driver during installation. Until it is manually set, a platform-appropriate default driver is used. - -## Supported drivers - -Different sets of drivers are available on different platforms: - -- On Linux, Multipass can be configured to use QEMU, LXD, and libvirt. -- On macOS, the options are QEMU and VirtualBox. As of Multipass version 1.13, Hyperkit is no longer available. -- On Windows, Multipass uses Hyper-V (only available on Windows Pro) or VirtualBox. - -## Default drivers - -When Multipass is installed, the following drivers are selected by default: - -- On Linux, the default driver depends on the host's architecture: - + QEMU on amd64 - + LXD on other platforms. -- On macOS, QEMU is used. -- On Windows, the default driver depends on the OS version: - + Hyper-V on Windows Pro - + VirtualBox on Windows Home - -## Instance scopes - -In general, Multipass instances are tied to a single driver, with the [exceptions](#exceptions) listed below. The set of instances that were launched with one driver are available only while that driver is in use. - -When a new driver is selected, Multipass switches to a separate instance scope. There, the set of existing instances is empty to begin with. Users can launch instances with the same name in different drivers and changes to instances with one driver have no effect on the instances of another. - -Nonetheless, instances are preserved across drivers. After switching back to a previously-used driver, Multipass restores the corresponding instance scope. It attempts to restore the state instances were in just before the switch and users can interact with them just as before. - -### Exceptions - -There are two exceptions to the above: - - - On Linux, QEMU and libvirt share the same driver scope. - - On macOS, stopped Hyperkit instances are automatically migrated to QEMU by Multipass's version 1.12 or later (see: [How to migrate from Hyperkit to QEMU on macOS](/how-to-guides/customise-multipass/migrate-from-hyperkit-to-qemu-on-macos)). - -## Feature disparities - -While we strive to offer a uniform interface across the board, not all features are available on all backends and there are some behaviour differences: - -| Feature | Only supported on... | Notes | -|--- | --- | --- | -| **Native mounts** |
  • Hyper-V
  • LXD
  • QEMU
| This affects the `--type` option in the [`mount`](/reference/command-line-interface/mount) command). | -| **Extra networks** |
  • Hyper-V
  • LXD
  • QEMU
  • VirtualBox
| This affects the [`networks`](/reference/command-line-interface/networks) command, as well as the `--network` and `--bridged` options in [`launch`](/reference/command-line-interface/launch). | -| **Snapshots** |
  • Hyper-V
  • QEMU
  • VirtualBox
| | -| **Clone** |
  • Hyper-V
  • QEMU
  • VirtualBox
| This affects the [`clone`](/reference/command-line-interface/clone) command.| -| **VM suspension** |
  • Hyper-V
  • libvirt
  • QEMU
  • VirtualBox
| This affects the [`suspend`](/reference/command-line-interface/suspend) command. | - - - -[note type="information"] -There are also feature disparities depending on the host platform. See [Platform](/explanation/platform) for more details. -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/host.md b/docs/src/explanation/host.md index 6a3231fbb9..e69de29bb2 100644 --- a/docs/src/explanation/host.md +++ b/docs/src/explanation/host.md @@ -1,7 +0,0 @@ -# Host -In Multipass, **host** refers the actual physical machine on which Multipass is running. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/id-mapping.md b/docs/src/explanation/id-mapping.md index 17ff790795..e69de29bb2 100644 --- a/docs/src/explanation/id-mapping.md +++ b/docs/src/explanation/id-mapping.md @@ -1,33 +0,0 @@ -# ID mapping -> See also: [`mount`](/reference/command-line-interface/mount), [Mount](/explanation/mount), [How to share data with an instance](/how-to-guides/manage-instances/share-data-with-an-instance) - -**ID mapping** refers to the process of aligning user or group IDs between the host system and an instance when mounting directories. This alignment ensures that the files mounted from the host to the instance retain consistent ownership and permission attributes. - -Since ID mappings take effect from host to instance, as well as in the opposite direction, they must be defined as a one-to-one relationship, meaning that each user or group ID on the host system should be mapped directly to a single user or group ID within the virtual machine, and vice versa. - -For example, the user ID `501` can be mapped to the user ID `1000` in the "foo" instance: - -``` -multipass mount ~/Documents foo:Documents -u 501:1000 -``` - -On the other hand, it is not possible to map this same user to a second user ID within the instance, as Multipass would be unable to determine which user ID to assign on the instance to a file with a user ID of `501` on the host system. The following command defines an invalid mount, since more than one ID on the host is mapped to the same ID in the instance: - -`multipass mount ~/Documents foo:Documents -u 501:1000 -u 502:1000` - -Instead, a valid mount that maps two different user IDs could be defined as follows: - -``` -multipass mount ~/Documents foo:Documents -u 501:1000 -u 502:1001 -``` - -The same logic also applies when trying to map a single user or group ID in an instance to two different IDs on the host. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ---- - -**Contributors:** @sharder996 , @gzanchi - diff --git a/docs/src/explanation/image.md b/docs/src/explanation/image.md index 80c5a016f4..e69de29bb2 100644 --- a/docs/src/explanation/image.md +++ b/docs/src/explanation/image.md @@ -1,21 +0,0 @@ -# Image -> See also: [`find`](/reference/command-line-interface/find), [`launch`](/reference/command-line-interface/launch) - -Multipass uses **images** (short for [disk images](https://en.wikipedia.org/wiki/Disk_image) or [system images](https://en.wikipedia.org/wiki/System_image)) tuned for cloud usage to spin up Ubuntu VMs. - -You can use `multipass find` to view a list of the available images. These images are obtained from different sources, such as: -* Ubuntu Cloud Images: https://cloud-images.ubuntu.com/ -* Ubuntu CD Images: https://cdimages.ubuntu.com/ - -and more. - -You can also launch images from a file or URL, as long as they provide the tools required to deploy a cloud. The key requirements are: -* cloud-init -* SSH - -For more information on the system requirements for a particular image, refer to official documentation (for example: [Ubuntu Core system requirements](https://ubuntu.com/core/docs/system-requirements)). - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/index.md b/docs/src/explanation/index.md index 8ffa85bf28..41adb3021a 100644 --- a/docs/src/explanation/index.md +++ b/docs/src/explanation/index.md @@ -1,26 +1,3 @@ -# Explanation -The following explanations provide context and clarification on key-topics related to the use and configuration of Multipass. - -- [About security](/explanation/about-security) -- [About performance](/explanation/about-performance) -- [Alias](/explanation/alias) -- [Authentication](/explanation/authentication) -- [Blueprint](/explanation/blueprint) -- [Driver](/explanation/driver) -- [Host](/explanation/host) -- [ID mapping](/explanation/id-mapping) -- [Image](/explanation/image) -- [Instance](/explanation/instance) -- [Mount](/explanation/mount) -- [Multipass `exec` and shells](/explanation/multipass-exec-and-shells) -- [Platform](/explanation/platform) -- [Service](/explanation/service) -- [Snapshot](/explanation/snapshot) - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ```{toctree} :hidden: diff --git a/docs/src/explanation/instance.md b/docs/src/explanation/instance.md index db9bff2fe5..e69de29bb2 100644 --- a/docs/src/explanation/instance.md +++ b/docs/src/explanation/instance.md @@ -1,29 +0,0 @@ -# Instance -> See also: [How to manage instances](/how-to-guides/manage-instances/manage-instances), [Instance states](/reference/instance-states), [Mount](/explanation/mount) - -An **instance** is a virtual machine created and managed by Multipass. - -> For more information on the naming convention, see [Instance name format](/reference/instance-name-format). - -## Primary instance - -The Multipass [Command-Line Interface](/reference/command-line-interface/command-line-interface) (CLI) provides a few shortcuts using a special instance, called *primary* instance. By default, this is the instance named `primary`. - -When invoked without positional arguments, state transition commands — [`start`](/reference/command-line-interface/start), [`restart`](/reference/command-line-interface/restart), [`stop`](/reference/command-line-interface/stop), and [`suspend`](/reference/command-line-interface/suspend) — operate on this special instance. So does the [`shell`](/reference/command-line-interface/shell) command. Furthermore, `start` and `shell` create the primary instance if it does not yet exist. - -When creating the primary instance, the Multipass CLI client automatically mounts the user's home directory into it. As with any other mount, it can be unmounted with `multipass umount`. For instance, the command `multipass umount primary` will unmount all mounts made by Multipass inside the `primary` instance, including the auto-mounted `Home`. - -[note type="information"] -On Windows, mounts are disabled by default for security reasons. For more details, see [Mount - Security considerations](/t/28470#security-considerations). -``` - -In all other respects, the primary instance is the same as any other instance. Its properties are the same as if it had been launched manually with `multipass launch --name primary`. - -### Selecting the primary instance - -The name of the instance that the Multipass CLI treats as primary can be modified with the setting [`client.primary-name`](/reference/settings/client-primary-name). This setting determines the name of the instance that Multipass creates and operates as primary, providing a mechanism to turn any existing instance into the primary instance, as well as disabling the primary feature. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/mount.md b/docs/src/explanation/mount.md index 52b2b88925..e69de29bb2 100644 --- a/docs/src/explanation/mount.md +++ b/docs/src/explanation/mount.md @@ -1,60 +0,0 @@ -# Mount -> See also: [`mount`](/reference/command-line-interface/mount), [How to share data with an instance](/how-to-guides/manage-instances/share-data-with-an-instance) - -In Multipass, a **mount** is a directory mapping from the host to an [instance](/explanation/instance), making its contents, and changes therein, available on both ends. Make sure to review the [security considerations](#security-considerations) below. - -In Multipass, there are two types of mounts: classic (default) and native. -* [Classic mounts](#classic-mounts) use technology built into Multipass and thus allow for higher compatibility, while slightly reduced performance. -* [Native mounts](#native-mounts), on the other hand, use hypervisor or platform-specific mounts to offer better performance, but limited compatibility. - -## Classic mounts - -Classic mounts use SSHFS (SSH File System) to achieve file/directory sharing. This option is available across all our backends. - -SSHFS is based on SSH, which pays a performance penalty to achieve secure communication. - -## Native mounts - -Native mounts use driver-dependent technologies to achieve the high performance. They are only available in the following cases: - -- On **Hyper-V**, where they are implemented with [SMB/CIFS](https://learn.microsoft.com/en-us/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview). -- On **QEMU**, where they are implemented with [9P](https://en.wikipedia.org/wiki/9P_(protocol)). -- On **LXD**, using that backend's own mounts, which also rely on [9P](https://en.wikipedia.org/wiki/9P_(protocol)). - -> See also: [Driver (backend) - Feature disparities](/t/28410#feature-disparities) - -## Security considerations - -[tabs] - -[tab version="Linux"] -Because mounts are performed as `root` -- unless installed via snap, see below -- they allow write access to the whole host operating system. But since only privileged users (members of `sudo`, `wheel`, `admin` groups) can use Multipass, this isn't a concern on Linux. - -If Multipass is installed via snap package, [snap confinement](https://snapcraft.io/docs/snap-confinement) prevents mounts outside of the `/home` directory (and to hidden files/folders in the `/home` directory) and possibly, removable media (depending on the connected interfaces). Still, a user (A) with access to Multipass could access mounts that a different user (B) established to B's home directory (that is, outside of A's home). -[/tab] - -[tab version="macOS"] -Because mounts are performed as `root`, they allow write access to the whole host operating system. But since only privileged users (members of `sudo`, `wheel`, `admin` groups) can use Multipass, this isn't a concern on macOS. -[/tab] - -[tab version="Windows"] -Because mounts are performed as privileged users (`SYSTEM` on Windows), they allow write access to the whole host operating system. - -For historical reasons, mounts are disabled by default on Windows, even though in the current version of Multipass users need to authenticate with the daemon before it will service their requests. See [`local.privileged-mounts`](/reference/settings/local-privileged-mounts) for information on how to enable them if needed. - - - -[/tab] - -[/tabs] - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ---- - -**Contributors:** @tmihoc, @georgeliaojia, @ricab, @sharder996, @davidekete, @gzanchi - diff --git a/docs/src/explanation/multipass-exec-and-shells.md b/docs/src/explanation/multipass-exec-and-shells.md index f2d785156d..e69de29bb2 100644 --- a/docs/src/explanation/multipass-exec-and-shells.md +++ b/docs/src/explanation/multipass-exec-and-shells.md @@ -1,132 +0,0 @@ -# Multipass `exec` and shells -> See also: [`exec` command](/reference/command-line-interface/exec) - -## How `exec` parses commands - -When you call `multipass exec` from a shell, the command is first parsed by the shell you are in. The result of that parsing is what the multipass client sees in its argument list (`argv`). - -For example, when `multipass exec primary -- ls ~` is entered on a Linux shell, the tilde is translated to the calling user's local home directory before the command is passed to Multipass. But this is not the case on a Windows PowerShell, because “~” does not have the same meaning there. - -### Quoting - -Quoting also depends on the calling shell. On most Linux and macOS shells, single quotes delimit a string that the shell passes verbatim to the program. - -The Windows powershell doesn't treat single quotes this way. A program called with `'abc def'` there would get two arguments: `'abc` and `def'`. Double quotes can be used instead: `"abc def"`, but the string they delimit is subject to shell expansion. For example: - -```plain -set USER=me -multipass exec -n rich-zorilla -- bash -c "echo %USER%" -``` - -The output will be: `me`. - -With Multipass, this is seldom a problem, as expansions use a different syntax on Linux: - -```plain -multipass exec -n rich-zorilla -- bash -c "echo $USER" -``` - -The output in this case is: `ubuntu`. - -## How SSH parses commands - -Multipass executes the command after `--` in the given instance as if there was no further shell in the middle (this is a simplification, as the reality is a little more complicated). - -This is slightly different from what one would get with SSH. Consider the following command in a `bash` shell: - -```plain -multipass exec mp-builder -- python3 -c 'import sys; print(sys.argv)' foo bar -``` - -whose output is: `['-c', 'foo', 'bar']`. - -When using SSH, the entire command would need to be enclosed within quotes: - -```plain -ssh -i /var/root/Library/Application\ Support/multipassd/ssh-keys/id_rsa ubuntu@192.168.66.34 python -c 'import sys; print(sys.argv)' foo bar -``` - -Sample output: - -```plain -bash: -c: line 1: syntax error near unexpected token `sys.argv' -bash: -c: line 1: `python -c import sys; print(sys.argv) foo bar' -``` - -## Using a shell to parse commands - -To overcome the above problem with `multipass exec`, one can still have another shell parse the command in the instance with `multipass exec`, it just needs to be called explicitly. For example: - -```plain -multipass exec calm-woodcock -- sh -c 'ls -a ~' -``` - -Sample output: - -```plain -. .. .bash_logout .bashrc .cache .profile .ssh -``` - -Similarly, on the Windows Command Prompt: - -```plain -multipass exec calm-woodcock -- sh -c "ls -a ~" -``` - -Provided we use the appropriate quoting for the calling shell, this behaves the same regardless of the host platform. Without `sh -c`, it also fails on all platforms (although possibly in different ways, depending on whether or not the nested command is quoted). The inner-shell trick provides a more consistent cross-platform experience. - -## Input/output redirection - -The `multipass exec` command can be used together with piping to redirect input/output between commands run on the host and on the instance. For example, this writes the contents of the current directory on the host to a file called `save` in the instance `rich-zorilla`: - -```plain -ls -la | multipass exec -n rich-zorilla -- bash -c "cat > save" -``` - -Conversely, this saves the contents of the home directory inside `rich-zorilla` to a file on the host: - -```plain -multipass exec -n rich-zorilla -- bash -c "ls -la" | cat > save -``` - -## Other shell tricks - -Other shell features can be combined with `multipass exec` for different effects. Here is an example using bash's here-strings: - -```plain -multipass exec -n primary -- bash << EOF -> hostname -> whoami -> EOF -``` - -Sample output: - -```plain -primary -ubuntu -``` - -And another using command substitution: - -```plain -ping $(multipass exec rich-zorilla -- hostname -I) -``` - -Sample output: - -```plain -PING 10.239.73.39 (10.239.73.39) 56(84) bytes of data. -64 bytes from 10.239.73.39: icmp_seq=1 ttl=64 time=0.371 ms -64 bytes from 10.239.73.39: icmp_seq=2 ttl=64 time=0.304 ms -64 bytes from 10.239.73.39: icmp_seq=3 ttl=64 time=0.439 ms -^C ---- 10.239.73.39 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2054ms -rtt min/avg/max/mdev = 0.304/0.371/0.439/0.055 ms -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/platform.md b/docs/src/explanation/platform.md index 11bd1dcad9..e69de29bb2 100644 --- a/docs/src/explanation/platform.md +++ b/docs/src/explanation/platform.md @@ -1,32 +0,0 @@ -# Platform -> See also: [How to install Multipass](/how-to-guides/install-multipass), [Host](/explanation/host), [Driver](/explanation/driver) - -In Multipass, **platform** refers to the host computer's operating system. This can be Windows, macOS, or Linux. - -## Feature disparities - -While we strive to offer a uniform interface across the board, not all features are available on all platforms and there are some behaviour differences: - -| Feature | Only supported on... | Notes | -|--- | --- | --- | -| **Windows terminal integration** |
  • Windows
| This affects the setting [`client.apps.windows-terminal.profiles`](/reference/settings/client-apps-windows-terminal-profiles) | -| **File and URL launches** |
  • Linux
| This affects the [`launch`](/reference/command-line-interface/launch) command. | -| **Mounts** |
  • Linux
  • macOS
  • Windows (disabled by default)
| On Windows, mounts can be enabled with the setting [`local.privileged-mounts`](/reference/settings/local-privileged-mounts).
This affects the [`mount`](/reference/command-line-interface/mount), [`umount`](/reference/command-line-interface/umount), and [`launch`](/reference/command-line-interface/launch) commands.| -| **Extra networks (QEMU)** |
  • Linux
  • macOS
| When using the QEMU driver, extra networks are only supported on macOS.
This affects the [`networks`](/reference/command-line-interface/networks) command, as well as `--network` and `--bridged` options in [`launch`](/reference/command-line-interface/launch). | -| **Global IPv6 (QEMU)** |
  • Linux
  • macOS
| When using the QEMU driver, global IPv6 addresses are only available on macOS. | -| **Drivers** |
  • Linux
  • macOS
  • Windows
| Different drivers are available on different platforms.
This affects the [`local.driver`](/reference/settings/local-driver) setting.
See [Driver - Feature disparities](/t/28410#feature-disparities) for further behaviour differences depending on the selected driver. | -| **Bridging Wi-Fi networks** |
  • macOS
| Wi-Fi networks are not shown in the output of the [`networks`](/t/multipass-networks-command/19542) command on Linux and Windows. | - - - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/service.md b/docs/src/explanation/service.md index 6af724b077..e69de29bb2 100644 --- a/docs/src/explanation/service.md +++ b/docs/src/explanation/service.md @@ -1,11 +0,0 @@ -# Service -> See also: [Command-line interface](/reference/command-line-interface/command-line-interface), [GUI client](/reference/gui-client), [Instance](/explanation/instance), [Use Multipass remotely](/) - -In Multipass, the **service** refers to the Multipass server that clients connect to and controls and manages Multipass instances. This can also be referred to as the 'daemon'. Multipass daemon (`multipassd)` runs in the background and it processes the requests from the Multipass [command-line interface](/reference/command-line-interface/command-line-interface), [GUI client](/reference/gui-client), daemon is also in charge of the lifecycle of the [Instances](/explanation/instance). The separation between the client (CLI or GUI) and daemon is a popular architecture because of his advantage, flexibility. For instance, the daemon process can be on a different machine from the client, see [Use Multipass remotely](/) for more details. - -The automatic start of the daemon process is triggered right after the Multipass installation. After that, it is also set up to start automatically at system boot. This setup ensures that the Multipass client can immediately interact with the instances without the need to launch the daemon manually, and restores any persistent instances of Multipass after a system restart. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/explanation/snapshot.md b/docs/src/explanation/snapshot.md index d8f70740e1..e69de29bb2 100644 --- a/docs/src/explanation/snapshot.md +++ b/docs/src/explanation/snapshot.md @@ -1,27 +0,0 @@ -# Snapshot -A snapshot is an conceptual image of an instance at some point in time, that can be used to restore the instance to what it was at that instant. - -To achieve this, a snapshot records all mutable properties of an instance, that is, all the properties that can change through interaction with Multipass. These include disk contents and size, number of CPUs, amount of memory, and mounts. On the other hand, aliases are not considered part of the instance and are not recorded. - -## Usage - -You can take a snapshot of an instance with the [`snapshot`](/reference/command-line-interface/snapshot) command, and restore it with the [`restore`](/reference/command-line-interface/restore) command. Taking and restoring a snapshot requires the instance to be stopped. - -You can view a list of the available snapshots with `multipass list --snapshots` and the details of a particular snapshot with `multipass info .`. To delete a snapshot, use the [`multipass delete`](/reference/command-line-interface/delete) command. - -> See also: [`list`](/reference/command-line-interface/list), [`info`](/reference/command-line-interface/info) - -## Parents - -An instance's disk contents are recorded by snapshots in layers: each new snapshot records changes with respect to its parent snapshot. A snapshot's parent is the snapshot that was last taken or restored when the new snapshot is taken. Parent and children snapshots of a deleted snapshot retain a consistent record of the instance. Multipass provides information of snapshots' parent/child relations to help identify their role or contents. - -```{caution} -**Caveats:** -- Long chains of snapshots have a detrimental effect on performance. Since they rely on layers of disk diffs, the more snapshots there are in a sequence, the more hops are necessary to read data that is recorded by the most ancient layers. -- While snapshots are useful to save and recover instance states, their utility as safe backups is limited. Since they are stored in the same medium as the original images, they are as likely to be affected by disk failures. -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md b/docs/src/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md index 8fd4b20cca..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md +++ b/docs/src/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md @@ -1,112 +0,0 @@ -# Authenticate clients with the Multipass service -> See also: [`authenticate`](/reference/command-line-interface/authenticate), [local.passphrase](/reference/settings/local-passphrase), [Service](/explanation/service) - -Multipass requires clients to be authenticated with the service before allowing commands to complete. - -## Setting the passphrase - -The administrator needs to set a passphrase for clients to authenticate with the Multipass service. The client setting the passphrase will need to already be authenticated. - -There are two ways to proceed: - -* Set the passphrase with an echoless interactive entry, where the passphrase is hidden from view: - - ```plain - multipass set local.passphrase - ``` - - The system will then prompt you to enter a passphrase: - - ```plain - Please enter passphrase: - Please re-enter passphrase: - ``` - -* Set the passphrase in the command line, where the passphrase is visible: - - ```plain - multipass set local.passphrase=foo - ``` - -## Authenticating the client - -A client that is not authorized to connect to the Multipass service will fail when running `multipass` commands. An error will be displayed when this happens. - -For example, if you try running the `multipass list` command: - -```plain -list failed: The client is not authenticated with the Multipass service. -Please use 'multipass authenticate' before proceeding. -``` - -At this time, the client will need to provide the previously set passphrase. This can be accomplished in two ways: - -* Authenticate with an echoless interactive entry, where the passphrase is hidden from view: - - ```plain - multipass authenticate - ``` - - The system will prompt you to enter the passphrase: - - ```plain - Please enter passphrase: - ``` - -* Authenticate in the command line, where the passphrase is visible: - - ```plain - multipass authenticate foo - ``` - -## Troubleshooting - -Here you can find solutions and workarounds for common issues that may arise. - -### The client cannot be authorized and the passphrase cannot be set - -It is possible that another client that is privileged to connect to the Multipass socket will connect first and make it seemingly impossible to set the `local.passphrase` and also `authorize` the client with the service. - -If this is the case, you will see something like the following when you run: - -* `multipass list` - - ```plain - list failed: The client is not authenticated with the Multipass service. - Please use 'multipass authenticate' before proceeding. - ``` - -* `multipass authenticate` - - ```plain - Please enter passphrase: - authenticate failed: Passphrase is not set. Please `multipass set - local.passphrase` with a trusted client. - ``` - -* `multipass set local.passphrase` - - ```plain - Please enter passphrase: - Please re-enter passphrase: - set failed: The client is not authenticated with the Multipass service. - Please use 'multipass authenticate' before proceeding. - ``` - -This may not even work when using `sudo`. - -The following workaround should help get out of this situation: - -```plain -cat ~/snap/multipass/current/data/multipass-client-certificate/multipass_cert.pem | sudo tee -a /var/snap/multipass/common/data/multipassd/authenticated-certs/multipass_client_certs.pem > /dev/null -snap restart multipass -``` - -You may need `sudo` with this last command: `sudo snap restart multipass`. - -At this point, your client should be authenticated with the Multipass service. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/build-multipass-images-with-packer.md b/docs/src/how-to-guides/customise-multipass/build-multipass-images-with-packer.md index d0c12fc246..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/build-multipass-images-with-packer.md +++ b/docs/src/how-to-guides/customise-multipass/build-multipass-images-with-packer.md @@ -1,64 +0,0 @@ -# Build Multipass images with Packer -[note type="information"] -Custom images are only supported on Linux. -``` - -[Packer](http://packer.io/) is a utility that lets you (re)build images to run in a variety of environments. Multipass can run those images too, provided some requirements are met (namely, the image has to boot on the hypervisor in use, and [cloud-init](https://cloudinit.readthedocs.io/en/latest/) needs to be available). - -## Setting up the build directory - -The easiest way is to start from an existing [Ubuntu Cloud Image](http://cloud-images.ubuntu.com/), and the base project setup follows (you can click on the filenames to see their contents, `meta-data` is empty on purpose): - -``` -├── cloud-data -│ ├── meta-data -│ └── user-data -└── template.json - -1 directory, 3 files -``` - -To specify a different image or image type, modify the `iso_checksum` and `iso_url` fields within `template.json` - -## Building the image - -You will need to install QEMU and Packer (e.g. `sudo apt install qemu packer`), and from there you can run the following commands: - -```plain -packer build template.json -multipass launch file://$PWD/output-qemu/packer-qemu --disk 5G -``` - -Now, shell into the new instance that was created, for example: - -```plain -multipass shell tolerant-hammerhead -``` - -## Customizing the image - -Now the above works for you, delete the test instance with `multipass delete --purge tolerant-hammerhead` and edit the following section in the `template.json` file: - -```json - { - "type": "shell", - "inline": ["echo Your steps go here."] - }, -``` - -Anything you do here will be reflected in the resulting image. You can install packages, configure services, anything you can do on a running system. You'll need `sudo` (passwordless) for anything requiring admin privileges, or you could add this to the above provisioner to run the whole script privileged: - -```json - "execute_command": "sudo sh -c '{{ .Vars }} {{ .Path }}'", -``` - -## Next steps - -Go to [Packer's documentation](https://developer.hashicorp.com/packer/docs) to learn about the QEMU builder, other provisioners and their configurations as well as everything else that might come in handy. Alternatively, you could extend `user-data` with other `cloud-init` [modules](https://cloudinit.readthedocs.io/en/latest/reference/modules.html#modules) to provision your image. - -Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/multipass/) and let us know about your images! - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/configure-multipasss-default-logging-level.md b/docs/src/how-to-guides/customise-multipass/configure-multipasss-default-logging-level.md index 28783dcb37..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/configure-multipasss-default-logging-level.md +++ b/docs/src/how-to-guides/customise-multipass/configure-multipasss-default-logging-level.md @@ -1,93 +0,0 @@ -# Configure Multipass’s default logging level -> See also: [Logging levels](/reference/logging-levels) - -This document demonstrates how to configure the default logging level of the Multipass service. Changing the logging level can be useful, for example, if you want to decrease the size of logging files or get more detailed information about what the daemon is doing. Logging levels can be set to one of the following: `error`, `warning`, `info`, `debug`, or `trace`, with case sensitivity. - -## Changing the default logging level - -[tabs] - -[tab version="Linux"] - -First, stop the Multipass daemon: - -```bash -sudo snap stop multipass -``` - -After that, create the override config file, replacing `` with your desired logging level: - -```bash -sudo mkdir /etc/systemd/system/snap.multipass.multipassd.service.d/ -sudo tee /etc/systemd/system/snap.multipass.multipassd.service.d/override.conf < -EOF -sudo systemctl daemon-reload -``` - -Finally, start the Multipass daemon: - -```bash -sudo snap start multipass -``` - -[/tab] - -[tab version="macOS"] - -First, become `root`: - -```bash -sudo su -``` - -Stop the Multipass daemon: - -```bash -launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist -``` - -Then, open `/Library/LaunchDaemons/com.canonical.multipassd.plist` in your favorite [text editor](https://www.google.com/search?q=vi) and edit the path `/dict/array/string[2]` from `debug` to the logging level of your choice. - -Finally, start the Multipass daemon: - -```bash -launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist -``` - -[/tab] - -[tab version="Windows"] - -First, open an administrator privileged PowerShell prompt. - -Stop the Multipass service: - -```powershell -Stop-Service Multipass -``` - -Then, edit the Multipass service registry key with the following command: - -```powershell -Set-ItemProperty -path HKLM:\System\CurrentControlSet\Services\Multipass -Name ImagePath -Value "'C:\Program Files\Multipass\bin\multipassd.exe' /svc --verbosity " -``` - -Replacing `` with your desired logging level. - -Finally, start the Multipass service: - -```powershell -Start-Service Multipass -``` - -[/tab] - -[/tabs] - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md b/docs/src/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md index 57d04cd130..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md +++ b/docs/src/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md @@ -1,288 +0,0 @@ -# Configure where Multipass stores external data -This document demonstrates how to configure the location where Multipass stores instances, caches images, and other data. Configuring a new storage location can be useful, for example, if you need to free up storage space on your boot partition. - -## Configuring a new storage location - -```{caution} -**Caveats:** -- Multipass will not migrate your existing data; 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. -- When uninstalling Multipass, the uninstaller will not remove data stored in custom locations, so you'll have to deleted it manually. -``` - -[tabs] - -[tab version="Linux"] - -First, stop the Multipass daemon: - -```plain -sudo snap stop multipass -``` - -Since Multipass is installed using a strictly confined snap, it is limited on what it can do or access on your host. 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](https://snapcraft.io/docs/snap-confinement), this directory needs to be located in either `/home` (connected by default) or one of the removable mounts points (`/mnt` or `/media`). To connect the removable mount points, use the command: - - ```plain - sudo snap connect multipass:removable-media - ``` - -Create the new directory in which Multipass will store its data: - -```plain -mkdir -p -sudo chown root -``` - -After that, create the override config file, replacing `` with the absolute path of the directory created above. - -```plain -sudo mkdir /etc/systemd/system/snap.multipass.multipassd.service.d/ -sudo tee /etc/systemd/system/snap.multipass.multipassd.service.d/override.conf < -EOF -``` - -The output at this point will be: -```plain -[Service] -Environment=MULTIPASS_STORAGE= -``` - -Then, instruct `systemd` to reload the daemon configuration files: - -```plain -sudo systemctl daemon-reload -``` - -Now you can transfer the data from its original location to the new location: - -```plain -sudo cp -r /var/snap/multipass/common/data/multipassd /data -sudo cp -r /var/snap/multipass/common/cache/multipassd /cache -``` - - - -You also need to edit the following configuration files so that the specified paths point to the new Multipass storage directory, otherwise your instances will fail to start: - -* `multipass-vm-instances.json`: Update the absolute path of the instance images in the "arguments" key for each instance. -* `vault/multipassd-instance-image-records.json`: Update the "path" key for each instance. - -Finally, start the Multipass daemon: - -```plain -sudo snap start multipass -``` - -You can delete the original data at your discretion, to free up space: - -```plain -sudo rm -rf /var/snap/multipass/common/data/multipassd -sudo rm -rf /var/snap/multipass/common/cache/multipassd -``` - -[/tab] - -[tab version="macOS"] - -First, become `root`: - -```plain -sudo su -``` - -Stop the Multipass daemon: - -```plain -launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist -``` - -Move your current data from its original location to ``, replacing `` with your custom location of choice: - -```plain -mv /var/root/Library/Application\ Support/multipassd -``` - -```{caution} -Make sure the `multipassd` directory is moved to ``, and not inside the `` folder. -``` - -Define a symbolic link from the original location to the absolute path of new location: - -```plain -ln -s /var/root/Library/Application\ Support/multipassd -``` - -Finally, start the Multipass daemon: - -```plain -launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist -``` - -[/tab] - -[tab version="Windows"] - -First, open a PowerShell prompt with administration privileges. - -Stop the Multipass daemon: - -```powershell -Stop-Service Multipass -``` - -Create and set the new storage location, replacing `` with the absolute path of your choice: - -```powershell -New-Item -ItemType Directory -Path "" -Set-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\Session Manager\Environment" -Name MULTIPASS_STORAGE -Value "" -``` - -Now you can transfer the data from its original location to the new location: - -```powershell -Copy-Item -Path "C:\ProgramData\Multipass\*" -Destination "" -Recurse -``` - -```{caution} -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: - -```powershell -Start-Service Multipass -``` - -You can delete the original data at your discretion, to free up space: - -```powershell -Remove-Item -Path "C:\ProgramData\Multipass\*" -Recurse -``` - -[/tab] - -[/tabs] - -## Reverting back to the default location - -[tabs] - -[tab version="Linux"] - -Stop the Multipass daemon: - -```plain -sudo snap stop multipass -``` - -Although not required, to make sure that Multipass does not have access to directories that it shouldn't, you can disconnect the respective interface depending on where the custom storage location was set (see [Configuring a new storage location](#configuring-a-new-storage-location) above). For example, to disconnect the removable mounts points (`/mnt` or `/media`), run: - -```plain -sudo snap disconnect multipass:removable-media -``` - -Then, remove the override config file: - -```plain -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: - -```plain -sudo cp -r /data /var/snap/multipass/common/data/multipassd -sudo cp -r /cache /var/snap/multipass/common/cache/multipassd -``` - -Finally, start the Multipass daemon: - -```plain -sudo snap start multipass -``` - -You can delete the data from the custom location at your discretion, to free up space: - -```plain -sudo rm -rf -``` - -[/tab] - -[tab version="macOS"] - -First, become `root`: - -```plain -sudo su -``` - -Stop the Multipass daemon: - -```plain -launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist -``` - -Remove the link pointing to your custom location: - -```plain -unlink /var/root/Library/Application\ Support/multipassd -``` - -Move the data from your custom location back to its original location: - -```plain -mv /var/root/Library/Application\ Support/multipassd -``` - -Finally, start the Multipass daemon: - -```plain -launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist -``` - -[/tab] - -[tab version="Windows"] - -First, open a PowerShell prompt with administrator privileges. - -Stop the Multipass daemon: - -```powershell -Stop-Service Multipass -``` - -Remove the setting for the custom storage location: - -```powershell -Remove-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\Session Manager\Environment" -Name MULTIPASS_STORAGE -``` - -Now you can transfer the data back to its original location: - -```powershell -Copy-Item -Path "\*" -Destination "C:\ProgramData\Multipass" -Recurse -``` - -Finally, start the Multipass daemon: - -```powershell -Start-Service Multipass -``` - -You can delete the data from the custom location at your discretion, to free up space: - -```powershell -Remove-Item -Path "" -Recurse -``` - -[/tab] - -[/tabs] - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal.md b/docs/src/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal.md index 42c374d955..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal.md +++ b/docs/src/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal.md @@ -1,45 +0,0 @@ -# How to integrate with Windows Terminal -If you are on Windows and you want to use [Windows Terminal](https://aka.ms/terminal), Multipass can integrate with it to offer you an automatic `primary` profile. - -## Multipass profile - -Currently, Multipass can add a profile to Windows Terminal for the [primary instance](/t/28469#primary-instance). When you open a Windows Terminal tab with this profile, you'll automatically find yourself in a primary instance shell. Multipass automatically starts or launches the primary instance if needed. - -![screenshot-primary-shell|800x490, 85%](upload://zrYHMyoT4r9Xvz8DtFLH96uPfBu.png) - -## Install Windows Terminal - -The first step is to [install Windows Terminal](https://github.com/microsoft/terminal#installing-and-running-windows-terminal). Once you have it along [Multipass](https://multipass.run/docs/installing-on-windows), you can enable the integration. - -## Enable integration - -Open a terminal (Windows Terminal or any other) and enable the integration with the following command: - -``` -multipass set client.apps.windows-terminal.profiles=primary -``` - -The setting is documented [here](/reference/settings/client-apps-windows-terminal-profiles) for more info. Until you modify it, Multipass will try to add the profile if it finds it missing. To remove the profile see [Revert](#revert) below. - -## Open a Multipass tab - -You can now open a "Multipass" tab to get a shell in the primary instance. That can be achieved by clicking the new-tab drop-down and selecting the Multipass profile: - -![screenshot-dropdown|800x490, 85%](upload://tRzbGEZmSLvoM09kVgbG23BxU00.jpeg) - -That's it! - -## Revert - -If you want to disable the profile again, you can do so with: - -``` -multipass set client.apps.windows-terminal.profiles=none -``` - -Multipass will then remove the profile if it exists. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/index.md b/docs/src/how-to-guides/customise-multipass/index.md index 98a626f36f..41adb3021a 100644 --- a/docs/src/how-to-guides/customise-multipass/index.md +++ b/docs/src/how-to-guides/customise-multipass/index.md @@ -1,24 +1,3 @@ -# Customise-Multipass -The following guides provide step-by-step instructions on how to customise Multipass to address specific needs, from managing Multipass drivers to configuring a graphical user interface. - -- [Set up the driver](/how-to-guides/customise-multipass/set-up-the-driver) -- [Migrate from Hyperkit to QEMU on macOS](/how-to-guides/customise-multipass/migrate-from-hyperkit-to-qemu-on-macos) -- [Authenticate clients with the Multipass service](/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service) -- [Build Multipass images with Packer](/how-to-guides/customise-multipass/build-multipass-images-with-packer) -- [Set up a graphical interface](/how-to-guides/customise-multipass/set-up-a-graphical-interface) -- [Use a different terminal from the system icon](/how-to-guides/customise-multipass/use-a-different-terminal-from-the-system-icon) -- [Integrate with Windows Terminal](/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal) -- [Configure where Multipass stores external data](/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data) -- [Configure Multipass’s default logging level](/how-to-guides/customise-multipass/configure-multipasss-default-logging-level) - - - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ```{toctree} :hidden: diff --git a/docs/src/how-to-guides/customise-multipass/migrate-from-hyperkit-to-qemu-on-macos.md b/docs/src/how-to-guides/customise-multipass/migrate-from-hyperkit-to-qemu-on-macos.md index 6159acbd7d..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/migrate-from-hyperkit-to-qemu-on-macos.md +++ b/docs/src/how-to-guides/customise-multipass/migrate-from-hyperkit-to-qemu-on-macos.md @@ -1,38 +0,0 @@ -# Migrate from Hyperkit to QEMU on macOS -> See also: [`set`](/explanation/driver), [local.driver](/explanation/driver), [Driver](/explanation/driver), [How to set up the driver](/how-to-guides/customise-multipass/set-up-the-driver) - -As of Multipass 1.12, the Hyperkit driver is being deprecated. New installs will start with the QEMU driver set by default, but existing installs will retain the previous driver setting. Multipass will warn Hyperkit users of the deprecation and ask them to move to QEMU. To facilitate that, Multipass 1.12 will migrate Hyperkit instances to QEMU. - -To migrate from Hyperkit to QEMU and bring your instances along, simply stop them and set the driver to QEMU: - -``` -multipass stop --all -multipass set local.driver=qemu -``` - -If you already had QEMU instances, they are not affected by the migration. Instances whose name is taken on the QEMU side are not migrated. - -## Repeated driver switches - -The original Hyperkit instances are retained until explicitly deleted. You can achieve that by temporarily moving back to Hyperkit and using the delete command: - -``` -multipass set local.driver=hyperkit -multipass delete [-p] [...] -multipass set local.driver=qemu -``` - -When switching to QEMU again, migrated instances are not overwritten. If, for any reason, you want to repeat a migration, you can achieve that by deleting the QEMU counterpart first. - -You can choose a convenient time to do any of this and you can set the driver to Hyperkit and move back and forth as many times as you want. Apart from the deprecation warning, functionality remains the same until the driver is removed entirely. When that happens, it will no longer be possible to migrate Multipass (unless you downgrade to version 1.12). - -## Demo - -Here is a video demonstration of the migration: - -[![Hyperkit Migration in Multipass](https://asciinema.org/a/556203.svg)](https://asciinema.org/a/556203) - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/customise-multipass/set-up-a-graphical-interface.md b/docs/src/how-to-guides/customise-multipass/set-up-a-graphical-interface.md index 50b6a03a2a..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/set-up-a-graphical-interface.md +++ b/docs/src/how-to-guides/customise-multipass/set-up-a-graphical-interface.md @@ -1,203 +0,0 @@ -# Set up a graphical interface - - - - -You can display the graphical desktop in various ways. In this document, we describe two options: RDP (Remote Display Protocol) and plain X11 forwarding. Other methods include VNC and running a Mir shell through X11 forwarding, as described in [A simple GUI shell for a Multipass VM](/). - -## Using RDP - -The images used by Multipass do not come with a graphical desktop installed. For this reason, you will have to install a desktop environment (here we use `ubuntu-desktop` but there are as many other options as flavors of Ubuntu exist) along with the RDP server (we will use `xrdp` but there are also other options such as `freerdp`). - -To do this, first you need to log into a running Multipass instance. Start by listing your instances: - -```plain -multipass list -``` - -Sample output: - -```plain -Name State IPv4 Image -headbanging-squid Running 10.49.93.209 Ubuntu 22.04 LTS -``` - -Next, open a shell into the running instance: - -```plain -multipass shell headbanging-squid -``` - -Once inside the instance, run the following commands to install `ubuntu-desktop` and `xrdp`: - -```plain -sudo apt update -sudo apt install ubuntu-desktop xrdp -``` - -Now we need a user with a password to log in. One possibility is setting a password for the default `ubuntu` user: - -```plain -sudo passwd ubuntu -``` - -You will be asked to enter and re-enter a password. - -You are done on the server side! - -Quit the Ubuntu shell on the running instance with the `exit` command, and take note of the IP address to connect to. You can find the instance's IP address in the output of `multipass list` from the first step above, or you can use the `multipass info` command as well. - -```plain -multipass info headbanging-squid -``` - -Sample output: - -```plain -Name: headbanging-squid -State: Running -Snapshots: 0 -IPv4: 10.49.93.209 -Release: Ubuntu 22.04 LTS -Image hash: 2e0c90562af1 (Ubuntu 22.04 LTS) -CPU(s): 4 -Load: 0.00 0.00 0.00 -Disk usage: 1.8GiB out of 5.7GiB -Memory usage: 294.2MiB out of 3.8GiB -Mounts: -- -``` - -In this example, we will use the IP address `10.49.93.209` to connect to the RDP server on the instance. - -[note type="information"] -If the IP address of the instance is not displayed in the output of `multipass list`, you can obtain it directly from the instance, with the command `ip addr`. -``` - -[tabs] - -[tab version="Linux"] - -On Linux, there are applications such as Remmina to visualize the desktop (make sure the package `remmina-plugin-rdp` is installed in your host along with `remmina`). - -To directly launch the client, run the following command: - -```plain -remmina -c rdp://10.49.93.209 -``` - -The system will ask for a username (`ubuntu`) and the password set above, and then the Ubuntu desktop on the instance will be displayed. - -![Logging in to the RDP server with Remmina|690x567](upload://iNMPPVChbKiM2MIo7sGoHMLctcv.png) - -[/tab] - -[tab version="macOS"] - -To connect on MacOS, we can use the “Microsoft Remote Desktop” application, from the Mac App Store. - -[/tab] - -[tab version="Windows"] - -On Windows, we can connect to the RDP server with the “Remote Desktop Connection” application. There, we enter the virtual machine’s IP address, set the session to XOrg and enter the username and password we created on the previuos step. - -[/tab] - -[/tabs] - -And we are done… a graphical desktop! - -## Using X11 forwarding - -[tabs] - -It might be the case that we only want Multipass to launch one application and to see only that window, without having the need for a complete desktop. It turns out that this setup is simpler than the RDP approach, because we do not need the Multipass instance to deploy a full desktop. Instead, we can use X11 to connect the applications in the instance with the graphical capabilities of the host. - -[tab version="Linux"] - -Linux runs X by default, so no extra software in the host is needed. - -On Linux, we can use authentication in X forwarding to add a bit more security. However, we will forward through SSH to avoid struggling with `xauth`. Our user in the host will log in to the Multipass instance through SSH, so that we can pass extra parameters to it. - -To make this possible, copy your public key, stored in `~/.ssh/id_rsa.pub`, to the list of authorized keys of the instance, into the file `~/.ssh/authorized_keys`. Remember to replace the instance name used in the example with yours: - -```plain -multipass exec headbanging-squid -- bash -c "echo `cat ~/.ssh/id_rsa.pub` >> ~/.ssh/authorized_keys" -``` - -[note type=information] -If the file `~/.ssh/id_rsa.pub` does not exist, it means that you need to create your SSH keys. Use `ssh-keygen` to create them and then run the previous command again. -``` - -Check the IP address of the instance, using `multipass info headbanging-squid` Finally, log in to the instance using X forwarding using the command (replace `xx.xx.xx.xx` with the IP address obtained above): - -```plain -ssh -X ubuntu@xx.xx.xx.xx -``` - -Test the setting running a program of your choice on the instance; for example: - -```plain -sudo apt -y install x11-apps -xlogo & -``` - -![xlogo on Linux|420x455](upload://etvJU6k1tfuZ0QsKd4TZM1ogsgR.png) - -A small window containing the X logo will show up. Done! - -[/tab] - -[tab version="macOS"] - -The first step in Mac is to make sure a X server is running. The easiest way is to install [XQuartz](https://www.xquartz.org). - -Once the X server is running, the procedure for macOS is the same as for Linux. - -[note type="information"] -Note to Apple Silicon users: some applications requiring OpenGL will not work through X11 forwarding. -``` - -[/tab] - -[tab version="Windows"] - -Windows knows nothing about X, therefore we need to install an X server. Here we will use [VcXsrv](https://sourceforge.net/projects/vcxsrv/). Other options would be [Xming](http://www.straightrunning.com/XmingNotes/) (the newest versions are paid, but older versions can still be downloaded for free from their [SourceForge site](https://sourceforge.net/projects/xming/)) or installing an X server in [Cygwin](http://cygwin.com/). - -The first step would be thus to install VcXsrv and run the X server through the newly created start menu entry "XLaunch". Some options will be displayed. In the first screen, select "Multiple windows" and set the display number; leaving it in -1 is a safe option. The "Next" button brings you to the "Client startup" window, where you should select "Start no client". Click "Next" to go to the "Extra settings" screen, where you should activate the option "Disable access control". When you click "Next" you will be given the option to save the settings, and finally you can start the X server. - -An icon will show up in the dock: you are done with the X server! - -To configure the client (that is, the Multipass instance) you will need the host IP address; you can obtain it with the console command `ipconfig`. - -Then, start the instance and set the `DISPLAY` environment variable to the server display on the host IP (replace `xx.xx.xx.xx` with the IP address obtained above): - -```plain -export DISPLAY=xx.xx.xx.xx:0.0 -``` - -You are done, and you can now test forwarding running a program of your choice on the instance; for example: - -```plain -sudo snap install firefox -firefox & -``` - -![Firefox running on the Multipass instance|690x388](upload://iy5xIwIRyMXjYqyhefIfdDoXnAi.jpeg) - -[/tab] - -[/tabs] - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ---- -**Contributors:** @andreitoterman , @luisp , @ricab , @gzanchi @dan-roscigno - diff --git a/docs/src/how-to-guides/customise-multipass/set-up-the-driver.md b/docs/src/how-to-guides/customise-multipass/set-up-the-driver.md index 6ac9fb004f..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/set-up-the-driver.md +++ b/docs/src/how-to-guides/customise-multipass/set-up-the-driver.md @@ -1,114 +0,0 @@ -# Set up the driver -> See also: [Driver](/explanation/driver), [`local.driver`](/reference/settings/local-driver) - -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. -``` - -[/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 diff --git a/docs/src/how-to-guides/customise-multipass/use-a-different-terminal-from-the-system-icon.md b/docs/src/how-to-guides/customise-multipass/use-a-different-terminal-from-the-system-icon.md index 14968a29b0..e69de29bb2 100644 --- a/docs/src/how-to-guides/customise-multipass/use-a-different-terminal-from-the-system-icon.md +++ b/docs/src/how-to-guides/customise-multipass/use-a-different-terminal-from-the-system-icon.md @@ -1,40 +0,0 @@ -# Use a different terminal from the system icon -> See also: [How to install Multipass](/how-to-guides/install-multipass), [`shell`](/reference/command-line-interface/shell). - -If you want, you can change the terminal application used by the Multipass system menu icon. - -[note type='information'] -Currently available only for macOS -``` - -To do so, you need to tell macOS which terminal to use for the `.command` file type. This document presents two ways of achieving this. - -## Using `duti` - -[`duti`](https://github.com/moretension/duti/) is a small helper application that can modify the default application preferences. It's also [available from `brew`](https://formulae.brew.sh/formula/duti). - -Find out your preferred terminal's bundle identifier using `mdls`: - -```console -mdls /Applications/iTerm.app/ | grep BundleIdentifier -kMDItemCFBundleIdentifier = "com.googlecode.iterm2" -``` - -And make it the default for script files using `duti`: - -```console -duti -s com.googlecode.iTerm2 com.apple.terminal.shell-script shell -``` - -## Using Finder - -Create an empty file with a `.command` extension and find it in Finder. Select the file and press `⌘I`. You should be presented with an information pane like this: - -![obraz|289x366](upload://47AaFCBSwPTDyEAbMjKkclk8DfA.png) - -Expand the "Open with:" section, select your preferred terminal application and click on "Change All…". - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/index.md b/docs/src/how-to-guides/index.md index 28eacb52f3..0357c561cf 100644 --- a/docs/src/how-to-guides/index.md +++ b/docs/src/how-to-guides/index.md @@ -1,4 +1,6 @@ +(how-to-guides-index)= # How-To-Guides + The following how-to guides provide step-by-step instructions on the installation, use, management and troubleshooting of Multipass. ## Install and deploy Multipass diff --git a/docs/src/how-to-guides/install-multipass.md b/docs/src/how-to-guides/install-multipass.md index 28a0c40a02..79793cca2e 100644 --- a/docs/src/how-to-guides/install-multipass.md +++ b/docs/src/how-to-guides/install-multipass.md @@ -1,11 +1,13 @@ +(how-to-guides-install-multipass)= # Install Multipass + This guide explains how to install and manage Multipass on your system. -[note type="information"] +```{note} Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. ``` @@ -118,11 +120,11 @@ installed: 1.3.0 (2205) 228MB - [tab version="macOS"] -[note type=information] +```{note} You will need an account with administrator privileges to complete the installation. ``` -Download the latest installer from [our download page](https://multipass.run/download/macos). You can also get pre-release versions from the [GitHub releases](https://github.com/canonical/multipass/releases/) page, look for the `.pkg` package. +Download the latest installer from [our download page](https://canonical.com/multipass/download/macos). You can also get pre-release versions from the [GitHub releases](https://github.com/canonical/multipass/releases/) page, look for the `.pkg` package. Run the downloaded installer and follow the guided procedure. @@ -132,11 +134,11 @@ Run the downloaded installer and follow the guided procedure. [tab version="Windows"] -[note type=information] +```{note} You will need either Hyper-V enabled (only Windows 10 Professional or Enterprise), or VirtualBox installed. See [Check prerequisites](#check-prerequisites). ``` -Download the latest installer from [our download page](https://multipass.run/download/windows). You can also get pre-release versions from the [GitHub releases](https://github.com/CanonicalLtd/multipass/releases/) page, look for the `.msi` file. +Download the latest installer from [our download page](https://canonical.com/multipass/download/windows). You can also get pre-release versions from the [GitHub releases](https://github.com/CanonicalLtd/multipass/releases/) page, look for the `.msi` file. Run the downloaded installer and follow the guided procedure. The installer will require to be granted Administrator privileges. @@ -192,11 +194,11 @@ As the installation happened via snap, you don't need to worry about upgrading-- [tab version="macOS"] -[note type=information] +```{note} You will need an account with administrator privileges to complete the upgrade. ``` -To upgrade, download the latest installer from [our download page](https://multipass.run/download/macos). You can also get pre-release versions from the [GitHub releases](https://github.com/canonical/multipass/releases/) page, look for the `.pkg` package. +To upgrade, download the latest installer from [our download page](https://canonical.com/multipass/download/macos). You can also get pre-release versions from the [GitHub releases](https://github.com/canonical/multipass/releases/) page, look for the `.pkg` package. Run the downloaded installer and follow the guided procedure. @@ -206,7 +208,7 @@ Any existing instances will be preserved. [tab version="Windows"] -To upgrade, [download the latest installer](https://multipass.run/download/windows) and run it. You can also get pre-release versions from the [GitHub releases](https://github.com/canonical/multipass/releases/) page, look for the `.msi` package. +To upgrade, [download the latest installer](https://canonical.com/multipass/download/windows) and run it. You can also get pre-release versions from the [GitHub releases](https://github.com/canonical/multipass/releases/) page, look for the `.msi` package. You will be asked to uninstall the old version, and then whether to remove all data when uninstalling. If you want to keep your existing instances, answer "No" (default). [/tab] @@ -242,7 +244,7 @@ Uninstall Multipass as you would any other program, following the usual procedur --- -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* +*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* --- diff --git a/docs/src/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md b/docs/src/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md index 96612e0bc6..5e6cb8b19f 100644 --- a/docs/src/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md +++ b/docs/src/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-add-a-network-to-an-existing-instance)= # Add a network to an existing instance + > See also: [`networks`](/reference/command-line-interface/networks), [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`local..bridged`](/reference/settings/local-instance-name-bridged) This guide explains how to bridge an existing Multipass instance with the available networks. diff --git a/docs/src/how-to-guides/manage-instances/configure-static-ips.md b/docs/src/how-to-guides/manage-instances/configure-static-ips.md index aa1a8cb44b..e69de29bb2 100644 --- a/docs/src/how-to-guides/manage-instances/configure-static-ips.md +++ b/docs/src/how-to-guides/manage-instances/configure-static-ips.md @@ -1,101 +0,0 @@ -# Configure static IPs -> See also: [Instance](/explanation/instance) - -This guide explains how to create instances with static IPs in a new network, internal to the host. With this approach, instances get an extra IP that does not change with restarts. By using a separate, local network we avoid any IP conflicts. Instances retain the usual default interface with a DHCP-allocated IP, which gives them connectivity to the outside. - -## Step 1: Create a Bridge - -The first step is to create a new bridge/switch with a static IP on your host. - -This is beyond the scope of Multipass but, as an example, here is how this can be achieved with NetworkManager on Linux (e.g. on Ubuntu Desktop): - -``` -nmcli connection add type bridge con-name localbr ifname localbr \ - ipv4.method manual ipv4.addresses 10.13.31.1/24 -``` - -This will create a bridge named `localbr` with IP `10.13.31.1/24`. You can see the new device and address with `ip -c -br addr show dev localbr`. This should show: - -``` -localbr DOWN 10.13.31.1/24 -``` - -You can also run `multipass networks` to confirm the bridge is available for Multipass to connect to. - -## Step 2: Launch an instance with a manual network - -Next we launch an instance with an extra network in manual mode, connecting it to this bridge: - -``` -multipass launch --name test1 --network name=localbr,mode=manual,mac="52:54:00:4b:ab:cd" -``` - -You can also leave the MAC address unspecified (just `--network name=localbr,mode=manual`). If you do so, Multipass will generate a random MAC for you, but you will need to retrieve it in the next step. - -## Step 3: Configure the extra interface - -We now need to configure the manual network interface inside the instance. We can achieve that using Netplan. The following command plants the required Netplan configuration file in the instance: - -``` -multipass exec -n test1 -- sudo bash -c 'cat << EOF > /etc/netplan/10-custom.yaml -network: - version: 2 - ethernets: - extra0: - dhcp4: no - match: - macaddress: "52:54:00:4b:ab:cd" - addresses: [10.13.31.13/24] -EOF' -``` - -The IP address needs to be unique and in the same subnet as the bridge. The MAC address needs to match the extra interface inside the instance: either the one provided in step 2 or the one Multipass generated (you can find it with `ip link`). - -If you want to set a different name for the interface, you can add a [`set-name` property](https://netplan.readthedocs.io/en/stable/netplan-yaml/#properties-for-physical-device-types). - -## Step 4: Apply the new configuration - -We now tell `netplan` apply the new configuration inside the instance: - -``` -multipass exec -n test1 -- sudo netplan apply -``` - -You may also use `netplan try`, to have the outcome reverted if something goes wrong. - -## Step 5: Confirm that it works - -You can confirm that the new IP is present in the instance with Multipass: - -``` -multipass info test1 -``` - -The command above should show two IPs, the second of which is the one we just configured (`10.13.31.13`). You can use `ping` to confirm that it can be reached from the host: - -``` -ping 10.13.31.13 -``` - -Conversely, you can also ping from the instance to the host: - -``` -multipass exec -n test1 -- ping 10.13.31.1 -``` - -## Step 6: More instances - -If desired, repeat steps 2-5 with different names/MACs/IP terminations (e.g. `10.13.31.14`) to launch other instances with static IPs in the same network. You can ping from one instance to another to confirm that they are connected. For example: - -``` -multipass exec -n test1 -- ping 10.13.31.14 -``` - -## Conclusion - -You have now created a small internal network, local to your host, with Multipass instances that you can reach on the same IP across reboots. Instances still have the default NAT-ed network, which they can use to reach the outside world. You can combine this with other networks if you want to (e.g. for bridging). - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/manage-instances/create-an-instance.md b/docs/src/how-to-guides/manage-instances/create-an-instance.md index 3d06c0ec62..6c1e62deb6 100644 --- a/docs/src/how-to-guides/manage-instances/create-an-instance.md +++ b/docs/src/how-to-guides/manage-instances/create-an-instance.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-create-an-instance)= # Create an instance + > See also: [`launch`](/reference/command-line-interface/launch), [Instance](/explanation/instance) This document demonstrates various ways to create an instance with Multipass. While every method is a one-liner involving the command `multipass launch`, each showcases a different option that you can use to get exactly the instance that you want. diff --git a/docs/src/how-to-guides/manage-instances/index.md b/docs/src/how-to-guides/manage-instances/index.md index 4fe658cce5..0d03c7d11c 100644 --- a/docs/src/how-to-guides/manage-instances/index.md +++ b/docs/src/how-to-guides/manage-instances/index.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-index)= # Manage-Instances + The following guides provide step-by-step instructions on how to manage Multipass instances. Multipass allows you to create Ubuntu instances with a single command. As your needs grow, you can modify and customise instances as well as use and create blueprints for customised instances: diff --git a/docs/src/how-to-guides/manage-instances/modify-an-instance.md b/docs/src/how-to-guides/manage-instances/modify-an-instance.md index 7f97017411..712c2805e7 100644 --- a/docs/src/how-to-guides/manage-instances/modify-an-instance.md +++ b/docs/src/how-to-guides/manage-instances/modify-an-instance.md @@ -1,7 +1,9 @@ +(how-to-guides-manage-instances-modify-an-instance)= # Modify an instance -> See also: [Instance](/explanation/instance), [`launch`](/reference/command-line-interface/launch), [`set`](/reference/command-line-interface/set), [Settings](/reference/settings/settings) -This document shows further ways to customize an instance outside of the [`launch`](/reference/command-line-interface/launch) command using the Multipass [settings](/reference/settings/settings). +> See also: [Instance](/explanation/instance), [`launch`](/reference/command-line-interface/launch), [`set`](/reference/command-line-interface/set), [Settings](/reference/settings/index) + +This document shows further ways to customize an instance outside of the [`launch`](/reference/command-line-interface/launch) command using the Multipass [settings](/reference/settings/index). ## Set the CPUs , RAM or disk space of an instance @@ -18,7 +20,7 @@ multipass set local.handsome-ling.disk=60G multipass set local.handsome-ling.memory=7G ``` -[note type="information"] +```{note} The disk size can only be increased. ``` @@ -48,13 +50,13 @@ When done, run `sudo resize2fs /dev/sda1`. You can view these properties using the `get` command, without the need to stop instances. For example, `multipass get local.handsome-ling.cpus` returns the configured number of CPUs, which in our example is "4". -[note type="information"] +```{note} You can only update the properties of `Stopped`, non-deleted instances. If you try to update an instance that is in `Running`, `Suspended`, or `Deleted` status you'll incur an error. On the other hand, it's always possible to fetch properties for all instances. Use `multipass get --keys` to obtain their settings keys. ``` -[note type="information"] +```{note} Modifying instance settings is not supported when using the Hyperkit driver, which has been deprecated in favor of QEMU. The QEMU and VirtualBox drivers on Intel-based macOS hosts do support instance modification. ``` diff --git a/docs/src/how-to-guides/manage-instances/remove-an-instance.md b/docs/src/how-to-guides/manage-instances/remove-an-instance.md index 330882fc64..8a9d1bb67d 100644 --- a/docs/src/how-to-guides/manage-instances/remove-an-instance.md +++ b/docs/src/how-to-guides/manage-instances/remove-an-instance.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-remove-an-instance)= # Remove an instance + > See also: [Instance](/explanation/instance) This guide demonstrates how to remove an instance, either temporarily or permanently. diff --git a/docs/src/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md b/docs/src/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md index 25d95d349c..e69de29bb2 100644 --- a/docs/src/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md +++ b/docs/src/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md @@ -1,143 +0,0 @@ -# Run a Docker container in Multipass - - - - -## Overview - -Multipass has a Docker blueprint that gives its users access to out-of-the-box Docker on any platform. This new blueprint makes it easy to develop and test Docker containers locally on macOS, Windows, or Linux. - -In this tutorial, you will see how to get started with the Docker blueprint by creating a blog in a Docker container in Multipass. - -### What you’ll learn - -- How to use Docker on macOS or Windows with Multipass - -- How to alias the `docker` command to your host command line - -- How to use [Portainer](https://www.portainer.io/) to launch a Docker container in [Multipass](http://multipass.run) - -### What you’ll need - -- Any computer with an internet connection - -## Install Multipass - -Duration: 3 minutes - -Let's start by installing Multipass on your machine, following the steps in [How to install Multipass](/how-to-guides/install-multipass). - -![|720x643](https://assets.ubuntu.com/v1/25ca03d0-mp-docker.png) - -## Launch a Docker VM - -Duration: 1 minute - -Now that Multipass is installed, you can create a VM running Docker very simply. Open up a terminal and type - -```plain -multipass launch docker -``` - -This command will create a virtual machine running the latest version of Ubuntu, with Docker and Portainer installed. You can now use Docker already! Try the command below to see for yourself! - -```plain -multipass exec docker docker` -``` - -![|720x540](https://assets.ubuntu.com/v1/29e87039-mp-docker-2.png) - -## Alias of the Docker commands - -Duration: 1 minute - -The Docker blueprint creates automatically two aliases, that is, two commands which can be run from the host to use commands in the instance as if they were in the host. In particular, the host `docker` command executes `docker` in the instance, and the host `docker-compose` command executes `docker-compose` in the instance. - -In order for these to work, you just need to add them to the path so that you can use them directly from your command line. If this was not done before, launching the Docker blueprint will return instructions showing how to add the aliases to your path. Simply copy and paste the command shown. It will likely be of this form: - -```plain -PATH="$PATH:/home//snap/multipass/common/bin" -``` - - - -Run the command: - -```plain -multipass launch docker -``` - -Sample output: - -```plain -You'll need to add this to your shell configuration (.bashrc, .zshrc or so) for -aliases to work without prefixing with `multipass`: - -PATH="$PATH:/home/nhart/snap/multipass/common/bin" -``` - -You can now use `docker` straight from the command line. To try it out, run - -```plain -docker run hello-world -``` - -## Using Portainer - -Duration: 5 minutes - -Let's now go one step further, with Portainer. The Docker blueprint comes with Portainer installed, which gives an easy-to-use graphical interface for managing your Docker containers. To access Portainer, you will first need its IP address. The following command will show the IP addresses associated with the Ddocker VM you created in the previous steps: - -```plain -multipass list -``` - -![|720x188](https://assets.ubuntu.com/v1/1e998c4e-mp-docker-4.png) - -There should be two IP addresses listed, one for the Docker instance, the other for Portainer. The Portainer IP should start with a 10. - -In a web browser, enter the Portainer IP address from the previous step followed by the Portainer port, 9000, like this: “:9000”. Set up a username and password at the prompt, then select the option for managing a *local* Docker environment and click *connect*. - -![|720x596](https://assets.ubuntu.com/v1/0f980233-mp-docker-5.png) - -Click on the newly created “Local” environment to manage the Docker instance on your local VM. - -![|720x459](https://assets.ubuntu.com/v1/3a7af624-mp-docker-6.png) - -## Launching a container - -Duration: 5 minutes - -For this tutorial, you will be creating a blog using the Ghost template in Portainer. Portainer has many other app templates if you are looking for more ideas. If you want more selection, you can launch containers from the Docker hub from Portainer or from the command line. - -Inside Portainer, click on **App Templates** in the left toolbar, and scroll down to the **Ghost** template. - -![|720x461](https://assets.ubuntu.com/v1/b80ef240-mp-docker-7.png) - -Now, you can configure and deploy the template. Enter a name and click deploy. The **bridge** network is the default and correct option. - -![|720x541](https://assets.ubuntu.com/v1/1ade4cfc-mp-docker-8.png) - -On the **Containers** page, you should now see two containers running. One containing Ghost, and the other containing Portainer itself. - -![|720x373](https://assets.ubuntu.com/v1/0e720c25-mp-docker-9.png) - -You can now access your Ghost blog by going to the published port indicated in the Containers page, i.e., **\:\**. - -![|720x603](https://assets.ubuntu.com/v1/357843ef-mp-docker-10.png) - -There it is, your blog running within a Docker container inside Multipass! - -For next steps, try out Portainer’s other App Templates (Step 5), or check out [Docker Hub](https://hub.docker.com/search?type=image) for more containers to try. If you want to try out container orchestration, [Microk8s](https://microk8s.io/) or Multipass’ [Minikube](https://minikube.sigs.k8s.io/docs/) blueprint are great places to start. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/manage-instances/share-data-with-an-instance.md b/docs/src/how-to-guides/manage-instances/share-data-with-an-instance.md index 42906c6297..097f84de58 100644 --- a/docs/src/how-to-guides/manage-instances/share-data-with-an-instance.md +++ b/docs/src/how-to-guides/manage-instances/share-data-with-an-instance.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-share-data-with-an-instance)= # Share data with an instance + > See also: [Instance](/explanation/instance), [Mount](/explanation/mount), [ID mapping](/explanation/id-mapping), [`launch`](/reference/command-line-interface/launch), [`mount`](/reference/command-line-interface/mount), [`umount`](/reference/command-line-interface/umount), [`transfer`](/reference/command-line-interface/transfer) This guide explains how to share data between your host and an instance. There are two ways to accomplish this: diff --git a/docs/src/how-to-guides/manage-instances/use-a-blueprint.md b/docs/src/how-to-guides/manage-instances/use-a-blueprint.md index 4828236991..e69de29bb2 100644 --- a/docs/src/how-to-guides/manage-instances/use-a-blueprint.md +++ b/docs/src/how-to-guides/manage-instances/use-a-blueprint.md @@ -1,35 +0,0 @@ -# Use a blueprint -> See also: [Blueprint](/explanation/blueprint) - -Blueprints provide a shortcut to initialising Multipass instances for a variety of applications. - -To see what blueprints are available, run - -```plain -multipass find --only-blueprints -``` - -> See more: [`multipass find`](/reference/command-line-interface/find) - -To use a blueprint run: - -```plain -multipass launch -``` - -Launching a blueprint can take the same arguments as launching any other type of instance. If no further arguments are specified, the instance will launch with the defaults defined in the blueprint. Here’s an example of creating an instance from the Docker blueprint with a few more parameters specified: - -```plain -multipass launch docker --name docker-dev --cpus 4 --memory 8G --disk 50G --bridged -``` - -This command will create an instance based on the Docker blueprint, with 4 CPU cores, 8GB of RAM, 50 GB of disk space, and connect that instance to the (predefined) bridged network. - -Blueprints also provide a way of exchanging files between the host and the instance. For this, a folder named `multipass/` is created in the user's home directory on the host and mounted in `` in the user's home directory on the instance. - -> See more: [`multipass launch`](/reference/command-line-interface/launch) - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/manage-instances/use-an-instance.md b/docs/src/how-to-guides/manage-instances/use-an-instance.md index 0a85a2cd02..9482da0145 100644 --- a/docs/src/how-to-guides/manage-instances/use-an-instance.md +++ b/docs/src/how-to-guides/manage-instances/use-an-instance.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-use-an-instance)= # Use an instance + > See also: [Instance](/explanation/instance) This document demonstrates various ways to use an instance. @@ -45,7 +47,7 @@ As shown in the example above, an Ubuntu prompt is displayed as a result of the To end the session, use `logout`, `exit`, or the `Ctrl-D` shortcut. -[note type="information"] +```{note} This is also available on the GUI. ``` @@ -85,7 +87,7 @@ multipass start --all If no options are specified, the `multipass start` command starts the primary instance, creating it if needed. -[note type="information"] +```{note} This is also available on the GUI. ``` @@ -147,7 +149,7 @@ multipass stop --force ```{caution} The `stop --force` command is analogous to unplugging the power cord from a physical machine – it immediately halts all computing activities. This may be necessary under certain circumstances but can potentially lead to data loss or corruption. ``` -[note=information] This command is also available on the Multipass GUI. ``` +```{note} This command is also available on the Multipass GUI. ``` diff --git a/docs/src/how-to-guides/manage-instances/use-instance-command-aliases.md b/docs/src/how-to-guides/manage-instances/use-instance-command-aliases.md index dd98548c64..f3927a0a37 100644 --- a/docs/src/how-to-guides/manage-instances/use-instance-command-aliases.md +++ b/docs/src/how-to-guides/manage-instances/use-instance-command-aliases.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-use-instance-command-aliases)= # Use instance command aliases + > See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases), [Instance](/explanation/instance). This guide demonstrates how to create, list, run and remove aliases for commands running inside an instance. @@ -124,7 +126,7 @@ You can modify the path by appending a line to the `.bashrc` file, such as: export PATH="$PATH:/home/user/snap/multipass/common/bin" ``` -[note type="information"] +```{note} Remember to replace the correct folder, as indicated in the output of the Multipass command above, and to restart the shell when done. If your shell is `zsh` and not `bash`, the file to modify is `.zshrc` instead of `.bashrc`. The procedure is the same. @@ -143,7 +145,7 @@ You can modify the path by appending a line to the `.zshrc` file, such as: export PATH="$PATH:/Users//Library/Application Support/multipass/bin" ``` -[note type="information"] +```{note} Remember to replace the correct folder, as indicated in the output of the Multipass command above, and to restart the shell when done. ``` @@ -213,7 +215,7 @@ You can also use the `--all` option to remove all the defined aliases in the cur multipass unalias --all ``` -[note type="information] +```{note} Aliases are also removed when the instance for which they were defined is deleted and purged. This means that `multipass delete crazy-cat --purge` will also remove the aliases `lscc` and `pwdcc`. ``` diff --git a/docs/src/how-to-guides/manage-instances/use-the-docker-blueprint.md b/docs/src/how-to-guides/manage-instances/use-the-docker-blueprint.md index 5745160bfa..e69de29bb2 100644 --- a/docs/src/how-to-guides/manage-instances/use-the-docker-blueprint.md +++ b/docs/src/how-to-guides/manage-instances/use-the-docker-blueprint.md @@ -1,27 +0,0 @@ -# Use the Docker blueprint -The Docker blueprint gives Multipass users an easy way to create Ubuntu instances with Docker installed. It is based on the latest LTS release of Ubuntu, and includes docker engine and [Portainer](https://www.portainer.io/). The Docker blueprint automatically aliases the `docker` and `docker-compose` commands to your host, and creates a workspace that is shared between the host and the instance. - -To use the Docker blueprint, run `multipass launch docker`, which will launch an instance with default parameters. - -Next, follow the instructions in the output to add the aliased command to your path, it should look something like this: - -```plain -You'll need to add this to your shell configuration (.bashrc, .zshrc or so) for - -aliases to work without prefixing with `multipass`: - -PATH="$PATH:/home/user/snap/multipass/common/bin" -``` - -[note type=tip] -Running `which docker` from your host command line should confirm that you are running Docker inside Multipass. -``` - -To access Portainer, run `multipass ls` and copy the IP address of the multipass instance (the first in the list), then enter it into your browser followed by a colon and Portainer’s port number, 9000 (something like this: 10.21.145.191:9000). This gives you Portainer's web interface for visually managing your containers. - -You can mount files into this instance as with any Multipass instance, but the default shared workspace is an easy way to edit your `dockerfiles` and `docker-compose.yaml` files from your host. With working directory mapping, you can run the `docker-compose` command from your host inside the shared directory, and have it run within that same directory in your Multipass instance. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/how-to-guides/manage-instances/use-the-primary-instance.md b/docs/src/how-to-guides/manage-instances/use-the-primary-instance.md index 3144736184..66979c8f33 100644 --- a/docs/src/how-to-guides/manage-instances/use-the-primary-instance.md +++ b/docs/src/how-to-guides/manage-instances/use-the-primary-instance.md @@ -1,4 +1,6 @@ +(how-to-guides-manage-instances-use-the-primary-instance)= # Use the primary instance + > See also: [Instance](/explanation/instance), [client.primary-name](/reference/settings/client-primary-name), [`shell`](/reference/command-line-interface/shell), [`mount`](/reference/command-line-interface/mount) Multipass offers a quick way to access an Ubuntu instance via a simple `multipass shell` command. This is achieved via the so-called [primary instance](/t/28469#primary-instance) that is also automatically created (if it doesn't exist) when the user runs the [`multipass start`](/reference/command-line-interface/start) or [`multipass shell`](/reference/command-line-interface/shell) commands without any arguments. @@ -19,7 +21,7 @@ In the command line, it is used as the default when no instance name is specifie When launching the primary instance, whether implicitly or explicitly, Multipass automatically mounts the user's home inside it, in the folder `Home`. As with any other mount, you can unmount it with `multipass umount`. For instance, `multipass umount primary` will unmount all mounts made by Multipass inside `primary`, including the auto-mounted `Home`. -[note type=information] +```{note} On Windows mounts are disabled by default for security reasons. See [`multipass set`](/reference/command-line-interface/set) and [local.privileged-mounts](/reference/settings/local-privileged-mounts) for information on how to enable them if needed. ``` diff --git a/docs/src/how-to-guides/troubleshoot/access-logs.md b/docs/src/how-to-guides/troubleshoot/access-logs.md index 0603cf89d9..af5be1ae3e 100644 --- a/docs/src/how-to-guides/troubleshoot/access-logs.md +++ b/docs/src/how-to-guides/troubleshoot/access-logs.md @@ -1,5 +1,7 @@ +(how-to-guides-troubleshoot-access-logs)= # Access logs -Logs are our first go-to when something goes wrong. Multipass is comprised of a daemon process (service) and the [CLI](/reference/command-line-interface/command-line-interface) and [GUI](/reference/gui-client) clients, each of them reporting on their own health. + +Logs are our first go-to when something goes wrong. Multipass is comprised of a daemon process (service) and the [CLI](/reference/command-line-interface/index) and [GUI](/reference/gui-client) clients, each of them reporting on their own health. The `multipass` command accepts the `--verbose` option (`-v` for short), which can be repeated to go from the default (*error*) level through *warning*, *info*, *debug* up to *trace*. diff --git a/docs/src/how-to-guides/troubleshoot/index.md b/docs/src/how-to-guides/troubleshoot/index.md index fdf20326ac..41adb3021a 100644 --- a/docs/src/how-to-guides/troubleshoot/index.md +++ b/docs/src/how-to-guides/troubleshoot/index.md @@ -1,15 +1,3 @@ -# Troubleshoot -The following guides provide step-by-step instructions on how to troubleshoot issues with your Multipass installation, beginning by inspecting the logs. - -- [Access logs](/how-to-guides/troubleshoot/access-logs) -- [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder) -- [Troubleshoot launch/start issues](/how-to-guides/troubleshoot/troubleshoot-launch-start-issues) -- [Troubleshoot networking](/how-to-guides/troubleshoot/troubleshoot-networking) - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ```{toctree} :hidden: diff --git a/docs/src/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md b/docs/src/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md index cec29270c2..874c27521b 100644 --- a/docs/src/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md +++ b/docs/src/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md @@ -1,10 +1,12 @@ +(how-to-guides-troubleshoot-mount-an-encrypted-home-folder)= # Mount an encrypted home folder + > See also: [`mount`](/reference/command-line-interface/mount), [Instance](/explanation/instance) -When you create the [primary instance](/t/28469#primary-instance-1) using `multipass start` or `multipass shell` without additional arguments, Multipass automatically mounts your home directory into it. +When you create the [primary instance](/) using `multipass start` or `multipass shell` without additional arguments, Multipass automatically mounts your home directory into it. On Linux, if your local home folder is encrypted using ` fscrypt`, [snap confinement](https://snapcraft.io/docs/snap-confinement) prevents you from accessing its contents from a Multipass mount due the peculiar directory structure (`/home/.ecryptfs//.Private/`). This also applies to the primary instance, where the home folder is mounted automatically. diff --git a/docs/src/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md b/docs/src/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md index 78a7f02e9f..7c20162466 100644 --- a/docs/src/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md +++ b/docs/src/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md @@ -1,4 +1,6 @@ +(how-to-guides-troubleshoot-troubleshoot-launch-start-issues)= # Troubleshoot launch/start issues + This topic addresses common issues when launching or starting instances, such as *timeouts or "unknown state" errors*. diff --git a/docs/src/how-to-guides/troubleshoot/troubleshoot-networking.md b/docs/src/how-to-guides/troubleshoot/troubleshoot-networking.md index 9d7f490b14..7d3c49279c 100644 --- a/docs/src/how-to-guides/troubleshoot/troubleshoot-networking.md +++ b/docs/src/how-to-guides/troubleshoot/troubleshoot-networking.md @@ -1,4 +1,6 @@ +(how-to-guides-troubleshoot-troubleshoot-networking)= # Troubleshoot networking + -# Multipass documentation - Multipass is a tool to generate cloud-style Ubuntu VMs quickly on Linux, macOS and Windows. It provides a simple but powerful CLI that enables you to quickly access an Ubuntu command line or create your own local mini-cloud. Local development and testing can be challenging, but Multipass simplifies these processes by automating setup and teardown. Multipass has a growing library of images that you can use to launch purpose-built VMs or custom VMs you’ve configured yourself through its powerful `cloud-init` interface. @@ -24,8 +23,8 @@ Developers can use Multipass to prototype cloud deployments and to create fresh, | | | |------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| -| [Tutorial](/tutorial/tutorial)
Get started - a hands-on introduction to Multipass for new users
| [How-to guides](/how-to-guides/how-to-guides)
Step-by-step guides covering key operations and common tasks | -| [Explanation](/explanation/explanation)
Concepts - discussion and clarification of key topics | [Reference](/reference/reference)
Technical information - specifications, APIs, architecture | +| [Tutorial](/tutorial)
Get started - a hands-on introduction to Multipass for new users
| [How-to guides](/how-to-guides/index)
Step-by-step guides covering key operations and common tasks | +| [Explanation](/explanation/index)
Concepts - discussion and clarification of key topics | [Reference](/reference/index)
Technical information - specifications, APIs, architecture | --- @@ -39,13 +38,6 @@ We value your input and contributions! Here are some ways you can join our commu * Report an issue or contribute to the code on [GitHub](https://github.com/canonical/multipass/issues) -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - ---- - -**Contributors:** @nhart, @saviq, @townsend, @andreitoterman, @tmihoc, @luisp, @ricab, @sharder996, @georgeliaojia, @gzanchi - - ```{toctree} :hidden: :titlesonly: @@ -53,8 +45,8 @@ We value your input and contributions! Here are some ways you can join our commu :glob: Home -tutorial +/tutorial*/index /how*/index /reference*/index /explanation*/index -contribute-to-multipass-docs +* diff --git a/docs/src/reference/command-line-interface/alias.md b/docs/src/reference/command-line-interface/alias.md index d6b568bdf1..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/alias.md +++ b/docs/src/reference/command-line-interface/alias.md @@ -1,43 +0,0 @@ -# alias -> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases). - -The `alias` command makes Multipass create a persistent alias to run commands on a given instance. Its syntax is the following: - -```plain -multipass alias instance:command [name] -``` - -If `name` is omitted, the alias name defaults to `command`. - -After running this command, a new alias is defined as running the `command` on the given instance. - -By default, if the host folder where the alias is being executed is mounted on the instance, the instance's working directory is changed to the mounted directory. This behaviour can be avoided by defining the alias with the option `--no-map-working-directory`. - ---- - -The full `multipass help alias` output explains the available options: - -```plain -Usage: multipass alias [options] [] -Create an alias to be executed on a given instance. - -Options: - -h, --help Displays help on commandline options - -v, --verbose Increase logging verbosity. Repeat the 'v' in - the short option for more detail. Maximum - verbosity is obtained with 4 (or more) v's, - i.e. -vvvv. - -n, --no-map-working-directory Do not automatically map the host execution - path to a mounted path - -Arguments: - definition Alias definition in the form - : - name Name given to the alias being defined, - defaults to -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/command-line-interface/aliases.md b/docs/src/reference/command-line-interface/aliases.md index 9597b8d0c6..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/aliases.md +++ b/docs/src/reference/command-line-interface/aliases.md @@ -1,49 +0,0 @@ -# aliases -> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) - -The `aliases` command shows the aliases defined for all the instances. - -```plain -multipass aliases -``` - -The output will be similar to the following: - -```plain -Alias Instance Command Working directory -lsrm rewarded-merlin ls default -topfp flying-pig top map -``` - -The `Working directory` column tells us the directory of the host where the alias will be run. The value `default` means that the alias will be run in the instance's default working directory (normally, `/home/ubuntu`). The value `map` means that, if the host directory from which the user calls the alias is mounted on the instance, the alias will be run on the mounted directory on the instance. - -[note type="information"] -The value will be `default` only if the alias was created with the `--no-map-working-directory` option. -``` - -The command can be used in conjunction with the `--format` or `-f` options to specify the desired output format: `csv`, `json`, `table` or `yaml`. - ---- - -The full `multipass help aliases` output explains the available options: - -```plain -Usage: multipass aliases [options] -List available aliases - -Options: - -h, --help Displays help on commandline options - -v, --verbose Increase logging verbosity. Repeat the 'v' in the short - option for more detail. Maximum verbosity is obtained with - 4 (or more) v's, i.e. -vvvv. - --format Output list in the requested format. Valid formats are: - table (default), json, csv and yaml. The output working - directory states whether the alias runs in the instance's - default directory or the alias running directory should try - to be mapped to a mounted one. -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/command-line-interface/authenticate.md b/docs/src/reference/command-line-interface/authenticate.md index 53b4f12ec3..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/authenticate.md +++ b/docs/src/reference/command-line-interface/authenticate.md @@ -1,38 +0,0 @@ -# authenticate -> See also: [Authentication](/explanation/authentication), [How to authenticate clients with the Multipass service](/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service), [`local.passhprase`](/reference/settings/local-passphrase) - -The `authenticate` command is used to authenticate a client with the Multipass service. Once authenticated, the client can issue commands such as `list`, `launch`, etc. - -To help reduce the amount of typing for `authenticate`, one can also use `multipass auth` as an alias: - -```plain -multipass auth foo -``` - -If no passphrase is specified in the `multipass authenticate` command line, you will be prompted to enter it. - ---- - -The full `multipass help authenticate` output explains the available options: - -```plain -Usage: multipass authenticate [options] [] -Authenticate with the Multipass service. -A system administrator should provide you with a passphrase -to allow use of the Multipass service. - -Options: - -h, --help Displays help on commandline options - -v, --verbose Increase logging verbosity. Repeat the 'v' in the short option - for more detail. Maximum verbosity is obtained with 4 (or more) - v's, i.e. -vvvv. - -Arguments: - passphrase Passphrase to register with the Multipass service. If omitted, - a prompt will be displayed for entering the passphrase. -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/command-line-interface/clone.md b/docs/src/reference/command-line-interface/clone.md index 1a2ac5bfe8..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/clone.md +++ b/docs/src/reference/command-line-interface/clone.md @@ -1,51 +0,0 @@ -# clone -The `multipass clone` command creates a clone of an instance. A cloned instance is a standalone instance that is a replica of the original instance in terms of its configuration, installed software, and data at the time of cloning. Cloning an instance can be useful for backup or testing purposes, or to create identical VMs from a working template. - -```{caution} -The `clone` command is available since Multipass version 1.15.0. -``` - -Currently, only instances that are in the `Stopped` state can be cloned. - -You can run the `clone` command on a source instance without any additional options. For example, `multipass clone natty-nilgai` will produce the following output: - -```plain -… -Cloned from natty-nilgai to natty-nilgai-clone1. -``` - -By default, the `multipass clone` command automatically generates a name for the cloned instance using the format *-cloneN*, where *N* represents the number of instances cloned from that specific source instance, starting at 1. In the example, the name of the source VM is "natty-nilgai" and the automatically generated name for its clone is "natty-nilgai-clone1". - -Alternatively, you can specify a custom name for the cloned instance using `--name` option, following the [standard instance name format](/reference/instance-name-format). For example: - -``` -multipass clone natty-nilgai --name custom-clone -``` - ---- - -The full `multipass help clone` output explains the available options: - -```plain -Usage: multipass clone [options] -Create an independent copy of an existing (stopped) instance. - -Options: - -h, --help Displays help on commandline options - -v, --verbose Increase logging verbosity. Repeat the 'v' in - the short option for more detail. Maximum - verbosity is obtained with 4 (or more) v's, - i.e. -vvvv. - -n, --name An optional custom name for the cloned - instance. The name must follow the usual - validity rules (see "help launch"). Default: - "-cloneN", where N is the Nth - cloned instance. - -Arguments: - source_name The name of the source instance to be cloned -``` ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/command-line-interface/delete.md b/docs/src/reference/command-line-interface/delete.md index b378c0c852..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/delete.md +++ b/docs/src/reference/command-line-interface/delete.md @@ -1,49 +0,0 @@ -# delete -> See also: [`recover`](/reference/command-line-interface/recover), [`purge`](/reference/command-line-interface/purge) - -The `multipass delete` command deletes the instances or snapshots that are specified as arguments. - -You can provide multiple arguments in the same delete command, including both instances and snapshots; for example: - -```plain -multipass delete --purge legal-takin calm-squirrel.snapshot2 -``` - -Deleted instances are marked as such and removed from use, but you can still recover them using the `multipass recover` command, unless you used the `-p`/`--purge` option to delete them permanently. - -To completely destroy instances and release the disk space they take up, use the `--purge` option or the [`multipass purge`](/reference/command-line-interface/purge) command. - -```{caution} -When you delete a [snapshot](/explanation/snapshot), or when you delete an instance using the [GUI client](/reference/gui-client), Multipass removes them permanently (even if you didn't use the `--purge` option) and they cannot be recovered. - -``` - -The `--all` option will delete all instances and their snapshots. Take care if using this option. - ---- - -The output of `multipass help delete` explains the available options: - -```plain -Usage: multipass delete [options] [.snapshot] [[.snapshot] ...] -Delete instances and snapshots. Instances can be purged immediately or later on, -with the "purge" command. Until they are purged, instances can be recovered -with the "recover" command. Snapshots cannot be recovered after deletion and must be purged at once. - -Options: - -h, --help Displays help on commandline options - -v, --verbose Increase logging verbosity. Repeat the 'v' in the short option - for more detail. Maximum verbosity is obtained with 4 (or more) - v's, i.e. -vvvv. - --all Delete all instances and snapshots - -p, --purge Permanently delete specified instances and snapshots - immediately - -Arguments: - name Names of instances and snapshots to delete -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/command-line-interface/exec.md b/docs/src/reference/command-line-interface/exec.md index 8b0d6603c9..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/exec.md +++ b/docs/src/reference/command-line-interface/exec.md @@ -1,75 +0,0 @@ -# exec -> See also: [Multipass `exec` and shells](/explanation/multipass-exec-and-shells), [How to use instance command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) - -The `exec` command runs the given commands inside the instance. The first argument is the instance to run the commands on, `--` optionally separates the `multipass` options from the rest - the command to run itself: - -```plain -multipass exec primary -- uname -r -``` - -Sample output: - -```plain -4.15.0-48-generic -``` - -You can pipe standard input and output to/from the command; for example: - -```plain -multipass exec primary -- lsb_release -a | grep ^Codename: -``` - -Sample output: - -```plain -No LSB modules are available. -Codename: bionic -``` - -The `--` separator is required if you want to pass options to the command being run. Options to the `exec` command itself must be specified before `--`. - -You can specify on which instance directory the command must be run in three different ways. - -The first one is `--working-directory `, which tells Multipass that the command must be run in the folder ``. For example: - -```plain -multipass exec arriving-pipefish --working-directory /home -- ls -a -``` - -The `ls -la` command shows the contents of the `/home` directory, because it was run from there: - -```plain -. .. ubuntu -``` - -The second option to specify the working directory is to look through the mounted folders first. In case we are running the alias on the host from a directory which is mounted on the instance, the command will be run on the instance from there. If the working directory is not mounted on the instance, the command will be run on the default directory on the instance. This is the default behaviour and no parameter must be specified for this mapping to happen. - -The third option is to directly run the command in the default directory in the instance (usually, it is `/home/ubuntu`. The parameter to force this behaviour is `--no-map-working-directory`. - ---- - -The full `multipass help exec` output explains the available options: - -```plain -Usage: multipass exec [options] [--] -Run a command on an instance - -Options: - -h, --help Displays help on commandline options - -v, --verbose Increase logging verbosity. Repeat the 'v' in - the short option for more detail. Maximum - verbosity is obtained with 4 (or more) v's, - i.e. -vvvv. - -d, --working-directory Change to before execution - -n, --no-map-working-directory Do not map the host execution path to a - mounted path - -Arguments: - name Name of instance to execute the command on - command Command to execute on the instance -``` - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/command-line-interface/find.md b/docs/src/reference/command-line-interface/find.md index 13bcace8e4..e69de29bb2 100644 --- a/docs/src/reference/command-line-interface/find.md +++ b/docs/src/reference/command-line-interface/find.md @@ -1,7 +0,0 @@ -# find - -These instance states reflect the various stages an instance can be in while using Multipass. Instances in different states can accept different commands. See [Multipass CLI commands](/t/multipass-cli-commands/29329) for more information on which commands can be used and when. +These instance states reflect the various stages an instance can be in while using Multipass. Instances in different states can accept different commands. See [Multipass CLI commands](/) for more information on which commands can be used and when. --- diff --git a/docs/src/reference/logging-levels.md b/docs/src/reference/logging-levels.md index dee394983c..1bfebdc449 100644 --- a/docs/src/reference/logging-levels.md +++ b/docs/src/reference/logging-levels.md @@ -1,4 +1,6 @@ +(reference-logging-levels)= # Logging levels + > See also: [Configure Multipass’s default logging level](/how-to-guides/customise-multipass/configure-multipasss-default-logging-level) In Multipass, a hierarchy of logging levels is used is used to convey severity and improve visibility of important events. Multipass uses the following levels ranked from most severe to least severe for its background daemon and child processes. diff --git a/docs/src/reference/settings/client-apps-windows-terminal-profiles.md b/docs/src/reference/settings/client-apps-windows-terminal-profiles.md index 49e0f9c74a..f62d226a55 100644 --- a/docs/src/reference/settings/client-apps-windows-terminal-profiles.md +++ b/docs/src/reference/settings/client-apps-windows-terminal-profiles.md @@ -1,4 +1,6 @@ +(reference-settings-client-apps-windows-terminal-profiles)= # client.apps.windows-terminal.profiles + > See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [How to integrate with Windows Terminal](/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal) ## Key diff --git a/docs/src/reference/settings/client-gui-autostart.md b/docs/src/reference/settings/client-gui-autostart.md index c5823d6015..e69de29bb2 100644 --- a/docs/src/reference/settings/client-gui-autostart.md +++ b/docs/src/reference/settings/client-gui-autostart.md @@ -1,32 +0,0 @@ -# client.gui.autostart -```{caution} -This setting has been removed from the CLI starting from Multipass version 1.14. -It is now only available in the [GUI client](/reference/gui-client). -``` - -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [GUI client](/reference/gui-client) - -## Key - -`client.gui.autostart` - -## Description - -Whether or not the Multipass GUI should start automatically on startup. - -## Possible values - -Any case variations of `on`|`off`, `yes`|`no`, `1`|`0` or `true`|`false`. - -## Examples - -`multipass set client.gui.autostart=true` - -## Default value - -`true` (on Linux and macOS it only takes effect after the client (CLI or GUI) is run for the first time) - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/client-gui-hotkey.md b/docs/src/reference/settings/client-gui-hotkey.md index fd06ffe76a..e69de29bb2 100644 --- a/docs/src/reference/settings/client-gui-hotkey.md +++ b/docs/src/reference/settings/client-gui-hotkey.md @@ -1,48 +0,0 @@ -# client.gui.hotkey -```{caution} -This setting has been removed from the CLI starting from Multipass version 1.14. -It is now only available in the [GUI client](/reference/gui-client). -``` - -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [GUI client](/reference/gui-client) - -## Key - -`client.gui.hotkey` - -## Description - -A keyboard shortcut for the GUI to open a shell into the [primary instance](/t/28469#primary-instance). - -## Possible values - -A single case-insensitive sequence of keys, containing: - - * zero or more modifiers (such as `Ctrl`, `Alt`, `Cmd`, `Command`, `Opt`, etc.) - * one non-modifier key (such as `u`, `4`, `.`, `Space`, `Tab`, `Pause`, `F3`). When key names have multiple words, quote and use spaces (for example: `"Print Screen"`). - * (on macOS) alternatively, UTF-8 characters for Mac keys (such as ⌘, ⌥, ⇧, ⌃) - * a plus (`+`) sign separating each alphabetic word (but not key symbols) from the next - * the empty string (`""`) to disable the hotkey - -```{caution} -**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). -``` - -## 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=""` - -## Default value - -* `Ctrl+Alt+U` on Linux and Windows -* `⌥⌘U` on macOS - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/client-primary-name.md b/docs/src/reference/settings/client-primary-name.md index f65635a991..bcff8ddfa1 100644 --- a/docs/src/reference/settings/client-primary-name.md +++ b/docs/src/reference/settings/client-primary-name.md @@ -1,4 +1,6 @@ +(reference-settings-client-primary-name)= # client.primary-name + > See also: [Instance](/explanation/instance), [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch) ## Key diff --git a/docs/src/reference/settings/index.md b/docs/src/reference/settings/index.md index 27d1973d9e..88c5094a7f 100644 --- a/docs/src/reference/settings/index.md +++ b/docs/src/reference/settings/index.md @@ -1,4 +1,6 @@ +(reference-settings-index)= # Settings + > See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [GUI client](/reference/gui-client) Multipass can be configured with a number of **settings** that are read and written by the [`get`](/reference/command-line-interface/get) and [`set`](/reference/command-line-interface/set) CLI commands, respectively. Some settings are also available in the [GUI client](/reference/gui-client). diff --git a/docs/src/reference/settings/local-bridged-network.md b/docs/src/reference/settings/local-bridged-network.md index 74fad70db2..e69de29bb2 100644 --- a/docs/src/reference/settings/local-bridged-network.md +++ b/docs/src/reference/settings/local-bridged-network.md @@ -1,29 +0,0 @@ -# local.bridged-network -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch), [`networks`](/reference/command-line-interface/networks), [Create an instance with multiple network interfaces](/t/27188#create-an-instance-with-multiple-network-interfaces), [Add a network to an existing instance](/how-to-guides/manage-instances/add-a-network-to-an-existing-instance), [`local..bridged`](/reference/settings/local-instance-name-bridged) - -## Key - -`local.bridged-network` - -## Description - -The name of the interface to connect the instance to when the shortcut `launch --bridged` is issued. - -## Possible values - -Any name from [`multipass networks`](/reference/command-line-interface/networks). - -Validation is deferred to [`multipass launch`](/reference/command-line-interface/launch). - -## Examples - -`multipass set local.bridged-network=en0` - -## Default value - -`` (`""`). - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-driver.md b/docs/src/reference/settings/local-driver.md index d3f87cf340..e69de29bb2 100644 --- a/docs/src/reference/settings/local-driver.md +++ b/docs/src/reference/settings/local-driver.md @@ -1,28 +0,0 @@ -# local.driver -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [Driver](/explanation/driver), [How to use libvirt in Multipass](/) - -## Key - -`local.driver` - -## Description - -A string identifying the hypervisor back-end in use. - -## Possible values - - - `qemu`, [`libvirt`](/) and `lxd` on Linux - - `hyperv` and `virtualbox` on Windows - - `qemu` and `virtualbox` on macOS 10.15+ - - *(deprecated)* `hyperkit` on Intel macOS 10.15+ - -## Default values - - - `qemu` on macOS and amd64 Linux - - `lxd` on non-amd64 Linux - - `hyperv` on Windows - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-instance-name-bridged.md b/docs/src/reference/settings/local-instance-name-bridged.md index 2dd48872ea..e69de29bb2 100644 --- a/docs/src/reference/settings/local-instance-name-bridged.md +++ b/docs/src/reference/settings/local-instance-name-bridged.md @@ -1,45 +0,0 @@ -# local.\.bridged -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`local.bridged-network`](/reference/settings/local-bridged-network), [How to add networks to existing instances](/how-to-guides/manage-instances/add-a-network-to-an-existing-instance) - -## Key - -`local..bridged` - -where `` is the name of a Multipass instance. - -## Description - -Whether or not the virtual machine is connected to the preferred bridge that is currently defined by `local..bridged`. - -Setting this to `true` will cause the instance to be bridged to that host network interface. - -Removing a bridged network from an instance is currently not supported. - -## Possible values - -This setting can have a boolean value (`true` or `false`). However, at this time, it can only be manually set to `true`, but not to `false`. - -The value of this setting depends on the value of [`local.bridged-network`](/reference/settings/local-bridged-network); that is, it varies dynamically according to the configured preferred network and the networks that have been added to the instance so far. - -## Examples - -`multipass set local.ultimate-grosbeak.bridged=true` - -If the instance `ultimate-grosbeak` was launched with the command `multipass launch --network eth0`, the result of `multipass get local.ultimate-grosbeak.bridged` will be `true` for as long as the value of `local.bridged-network` is `eth0`. - -If you run the command `multipass set local.bridged-network=eth1`, the result of `multipass get local.ultimate-grosbeak.bridged` will become `false`. At that point, you could run the command `multipass set local.ultimate-grosbeak.bridged=true` to bridge `ultimate-grosbeak` with `eth1`. - -### Bridged connection to a physical network interface - -On some platforms/backends, Multipass cannot connect instances directly to physical network interface controllers (NICs). In this case, Multipass offers to create a bridge/switch on the host connecting to that NIC. The instance is then connected to the bridge/switch, achieving the same effect as if it had been connected to the physical NIC directly. An instance that is indirectly connected with a physical NIC in this fashion is also considered to be bridged with that NIC by Multipass. - -For example, if the preferred network is `eth1` and the instance `ultimate-grosbeak` is connected with a bridge `br-eth1` that is linked with `eth1`, then `multipass get local.ultimate-grosbeak.bridged` will return `true`. - -## Default value - -`true` if the instance is bridged with the preferred network, `false` otherwise. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-instance-name-cpus.md b/docs/src/reference/settings/local-instance-name-cpus.md index 39c705ce3e..e69de29bb2 100644 --- a/docs/src/reference/settings/local-instance-name-cpus.md +++ b/docs/src/reference/settings/local-instance-name-cpus.md @@ -1,29 +0,0 @@ -# local.\.cpus -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch). - -## Key - -`local..cpus` - -where `` is the name of a 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. - -## Possible values - -A positive integer number. Multipass does not impose an upper limit on the possible values, but the underlying backend may do so. - -## Examples - -`multipass set local.handsome-ling.cpus=4` - -## Default value - -The number of CPUs that the instance was launched with. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-instance-name-disk.md b/docs/src/reference/settings/local-instance-name-disk.md index af17f4fabe..e69de29bb2 100644 --- a/docs/src/reference/settings/local-instance-name-disk.md +++ b/docs/src/reference/settings/local-instance-name-disk.md @@ -1,42 +0,0 @@ -# local.\.disk -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch) - -## Key - -`local..disk` - -where `` is the name of a Multipass instance. - -## Description - -The size of the instance's disk. - -```{caution} -The disk size can only be increased. -Decreasing the disk size is not permitted since it could cause data loss and the VM might break. -``` - -## 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 - -[note type="information"] -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 value - -The size of the disk that the instance was launched with. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-instance-name-memory.md b/docs/src/reference/settings/local-instance-name-memory.md index 951acffcc2..e69de29bb2 100644 --- a/docs/src/reference/settings/local-instance-name-memory.md +++ b/docs/src/reference/settings/local-instance-name-memory.md @@ -1,45 +0,0 @@ -# local.\.memory -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch) - -## Key - -`local..memory` - -where `` is the name of a Multipass instance. - -## Description - -The amount of RAM that is allocated to the instance. - -[note type="information"] -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`). -``` - -[note type="information"] -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 - -[note type="information"] -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 value - -The amount of memory that the instance was launched with. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-instance-name-snapshot-name-comment.md b/docs/src/reference/settings/local-instance-name-snapshot-name-comment.md index 38cdbb09aa..e69de29bb2 100644 --- a/docs/src/reference/settings/local-instance-name-snapshot-name-comment.md +++ b/docs/src/reference/settings/local-instance-name-snapshot-name-comment.md @@ -1,29 +0,0 @@ -# local.\.\.comment -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`snapshot`](/reference/command-line-interface/snapshot) - -## Key - -`local...comment` - -Where `` is the name of a Multipass instance and `` is the current name of one of its snapshots. - -## Description - -An optional free piece of text that is associated with the snapshot. This can be used to describe the snapshot, recognize its role, or any other purpose. - -## Possible values - -Any string that your terminal can encode. - -## Examples - -`multipass set local.relative-lion.snaphot2.comment="Got it! 😏"` - -## Default value - -The comment that was assigned to the snapshot when it was taken. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-instance-name-snapshot-name-name.md b/docs/src/reference/settings/local-instance-name-snapshot-name-name.md index 5be0f2ebc2..e69de29bb2 100644 --- a/docs/src/reference/settings/local-instance-name-snapshot-name-name.md +++ b/docs/src/reference/settings/local-instance-name-snapshot-name-name.md @@ -1,29 +0,0 @@ -# local.\.\.name -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`snapshot`](/reference/command-line-interface/snapshot), [Instance](/explanation/instance) - -## Key - -`local...name` - -where `` is the name of a Multipass instance and `` is the current name of one of its snapshots. - -## Description - -The name that identifies the snapshot in the context of its instance. Snapshot names cannot be repeated. - -## Possible values - -Any name that follows the same rules as [instance names](/t/28469#heading--Instance-name-format) and is not currently in use by another instance. - -## Examples - -`multipass set local.relative-lion.snaphot2.name=primed` - -## Default value - -The name that was assigned to the snapshot when it was taken. - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-passphrase.md b/docs/src/reference/settings/local-passphrase.md index 943f89438a..e69de29bb2 100644 --- a/docs/src/reference/settings/local-passphrase.md +++ b/docs/src/reference/settings/local-passphrase.md @@ -1,31 +0,0 @@ -# local.passphrase -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`authenticate`](/reference/command-line-interface/authenticate) - -## Key - -`local.passphrase` - -## Description - -Passphrase used by clients requesting access to the Multipass service via the [`multipass authenticate`](/reference/command-line-interface/authenticate) command. - -The passphrase can be given directly in the command line; if omitted, the user will be prompted to enter it. - - - -## Possible values - -Any string - -## Examples - -`multipass set local.passphrase` - -## Default value - -Not set (expressed as `false` by `multipass get`) - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/reference/settings/local-privileged-mounts.md b/docs/src/reference/settings/local-privileged-mounts.md index 1161ffd40f..e69de29bb2 100644 --- a/docs/src/reference/settings/local-privileged-mounts.md +++ b/docs/src/reference/settings/local-privileged-mounts.md @@ -1,28 +0,0 @@ -# local.privileged-mounts -> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`mount`](/reference/command-line-interface/mount), [Mount](/explanation/mount) - -## Key - -`local.privileged-mounts` - -## Description - -Controls whether [`multipass mount`](/reference/command-line-interface/mount) is allowed. - -## Possible values - -Any case variations of `on`|`off`, `yes`|`no`, `1`|`0` or `true`|`false`. - -## Examples - -`multipass set local.privileged-mounts=Yes` - -## Default value - - - `true` on Linux and macOS - - `false` on Windows - ---- - -*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.* - diff --git a/docs/src/tutorial.md b/docs/src/tutorial.md index b4f3af2916..b5ecbd04f1 100644 --- a/docs/src/tutorial.md +++ b/docs/src/tutorial.md @@ -1,4 +1,6 @@ +(tutorial)= # Tutorial + Multipass is a flexible and powerful tool that can be used for many purposes. In its simplest form, you can use it to quickly create and destroy Ubuntu VMs (instances) on any host machine. But you can also use Multipass to build a local mini-cloud on your laptop, to test and develop multi-instance or container-based cloud applications. @@ -9,7 +11,7 @@ This tutorial will help you understand how Multipass works, and the skills you n Multipass is available for Linux, macOS and Windows. To install it on the OS of your choice, please follow the instructions provided in [How to install Multipass](/how-to-guides/install-multipass). -[note type="information"] +```{note} Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. ``` @@ -676,7 +678,7 @@ From the Portainer dashboard, you can see the ports available on nginx. To verif Congratulations! You can now use Multipass proficiently. -There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/how-to-guides) for ideas and help with your project. In our [Explanation](/explanation/explanation) and [Reference](/reference/reference) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more. +There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/index) for ideas and help with your project. In our [Explanation](/explanation/index) and [Reference](/reference/index) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more. Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/multipass/) and let us know what you are doing with your instances! @@ -687,3 +689,4 @@ Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/mult --- **Contributors:** @nhart, @saviq, @townsend, @andreitoterman, @tmihoc, @luisp, @ricab, @sharder996, @georgeliaojia, @mscho7969, @itecompro, @mr-cal, @sally-makin, @gzanchi, @bagustris , @pitifulpete +