Skip to content

Commit

Permalink
Updating source files
Browse files Browse the repository at this point in the history
  • Loading branch information
@giuliazanchi
giuliazanchi committed Jan 8, 2025
1 parent bb7ae98 commit 83ad171
Show file tree
Hide file tree
Showing 100 changed files with 104 additions and 4,100 deletions.
22 changes: 22 additions & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -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 <setup>` and for :ref:`updating it <update>`.

You can also find detailed information about the :ref:`automatic-checks` included in the starter pack, and a :ref:`list of projects <examples>` that use the starter pack.

.. toctree::
:hidden:
:maxdepth: 2

/content/quickstart
/content/setup
/content/update
/content/automatic_checks
/content/examples
/content/contributing
58 changes: 0 additions & 58 deletions docs/src/contribute-to-multipass-docs.md
View file
Original file line number Diff line number Diff line change
@@ -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/<page-slug>/` 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!

44 changes: 0 additions & 44 deletions docs/src/explanation/about-performance.md
View file
Original file line number Diff line number Diff line change
@@ -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? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/about-performance" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*

23 changes: 0 additions & 23 deletions docs/src/explanation/about-security.md
View file
Original file line number Diff line number Diff line change
@@ -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? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/about-security" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*

9 changes: 0 additions & 9 deletions docs/src/explanation/alias.md
View file
Original file line number Diff line number Diff line change
@@ -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? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/alias" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*

31 changes: 0 additions & 31 deletions docs/src/explanation/authentication.md
View file
Original file line number Diff line number Diff line change
@@ -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? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/authentication" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*

44 changes: 0 additions & 44 deletions docs/src/explanation/blueprint.md
View file
Original file line number Diff line number Diff line change
@@ -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/<name>.yaml
description: <string> # * a short description of the blueprint ("tagline")
version: <string> # * 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:
<name>: # * equal to the blueprint name
image: <base image> # a valid image alias, see `multipass find` for available values
limits:
min-cpu: <int> # the minimum number of CPUs this blueprint can work with
min-mem: <string> # the minimum amount of memory (can use G/K/M/B suffixes)
min-disk: <string> # and the minimum disk size (as above)
timeout: <int> # maximum time for the instance to launch, and separately for cloud-init to complete
cloud-init:
vendor-data: | # cloud-init vendor data
<string>
health-check: | # a health-check shell script ran by integration tests
<string>
```

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? <a href="https://docs.google.com/forms/d/e/1FAIpQLSd0XZDU9sbOCiljceh3rO_rkp6vazy2ZsIWgx4gsvl_Sec4Ig/viewform?usp=pp_url&entry.317501128=https://multipass.run/docs/blueprint" target="_blank">Let us know</a> or <a href="https://github.com/canonical/multipass/issues/new/choose" target="_blank">open an issue on GitHub</a>.*

Loading

0 comments on commit 83ad171

Please sign in to comment.