diff --git a/BUILD.linux.md b/BUILD.linux.md index 904c5fd126b..43f1b7c6749 100644 --- a/BUILD.linux.md +++ b/BUILD.linux.md @@ -84,7 +84,7 @@ Copy the desktop file that Multipass clients expect to find in your home: ``` mkdir -p ~/.local/share/multipass/ -cp /data/multipass.gui.autostart.desktop ~/.local/share/multipass/ +cp /src/client/gui/assets/multipass.gui.autostart.desktop ~/.local/share/multipass/ ``` Optionally, enable auto-complete in Bash: @@ -93,6 +93,12 @@ Optionally, enable auto-complete in Bash: source /completions/bash/multipass ``` +To be able to use the binaries without specifying their path: + +``` +export PATH=/build/bin +``` + Now you can use the `multipass` command from your terminal (for example `/build/bin/multipass launch --name foo`) or launch the GUI client with the command `/build/bin/multipass.gui`. diff --git a/BUILD.windows.md b/BUILD.windows.md index c5875784003..b29f7c50c8a 100644 --- a/BUILD.windows.md +++ b/BUILD.windows.md @@ -1,43 +1,63 @@ -Build instructions for Windows 10 -================================= +# Build instructions for Windows 10/11 Pro -Environment Setup ------------------ +## Environment Setup ### Chocolatey -Install chocolatey, a package manager, to download the rest of the dependencies: +Install chocolatey, a package manager, to download the rest of the dependencies: . -Press Windows Key+X and Run Windows PowerShell(Admin) then follow the chocolatey instructions to "Install with -Powershell.exe" +Press Windows Key+X and Run Windows PowerShell(Admin) or Terminal(Admin) then follow the chocolatey +instructions to "Install with Powershell.exe". -After chocolatey is installed you can now install the rest of the dependencies: +### Dependencies - choco install visualstudio2019buildtools visualstudio2019-workload-vctools cmake ninja cmder qemu-img openssl -yfd +After chocolatey is installed you can now install the rest of the dependencies from the +Powershell(Admin). To get the best results, in the following order: -You may have to disable Windows Defender Real-time protection if you want the packages to install quicker. Search for -Windows Defender Security Center, go to Virus & threat protection, then Virus and thread protection settings, disable -Real-time protection. +```[pwsh] +choco install cmake ninja qemu-img openssl git wget unzip -yfd +``` + +```[pwsh] +choco install visualstudio2019buildtools visualstudio2019-workload-vctools -yfd +``` + +NOTE: visualcpp-build-tools is only the installer package. For this reason, choco cannot detect any +new compiler tool updates so choco upgrade will report no new updates available. To update the +compiler and related tooling or fix a broken `visualstudio2019buildtools` installation do the following: -NOTE: visualcpp-build-tools is only the installer package. For this reason, choco cannot detect any new compiler tool -updates so choco upgrade will report no new updates available. To update the compiler and related tooling, you will need -to search for "Add or remove programs", find "Microsoft Visual Studio Installer" and click "Modify". +1. Go to "Add or remove programs" +2. Search for the Microsoft Visual Studio Installer +3. Click Modify +4. Click Modify in the Installer interface +5. For Windows 11, add "C++/CLI support for v142 build tools" in the "Desktop development with C++" kit +6. Complete the installation ### Git You need to enable symlinks in Windows Git, have a look at [the git-for-windows docs](https://github.com/git-for-windows/git/wiki/Symbolic-Links). +For Windows 11: + +1. Go to "Developer Settings" +2. Enable "Developer mode" + ### Qt6 -Install the latest stable version of Qt6 (6.2.4 at the moment): . +To install Qt6, use `aqt`. First install it with chocolatey: + +```[pwsh] +choco install aqt -yfd +``` -In the online installer, under Qt, select MSVC 2019 64-bit. +Then specify the following options in the installation command: -If you already have Qt installed, run the MaintenanceTool included in the Qt directory to update to the latest version. +```[pwsh] +aqt install-qt windows desktop 6.2.4 win64_msvc2019_64 -O C:/Qt +``` -Alternatively, download the -[qtbase archive](https://download.qt.io/online/qtsdkrepository/windows_x86/desktop/qt6_624/qt.qt6.624.win64_msvc2019_64/6.2.4-0-202203140926qtbase-Windows-Windows_10_21H2-MSVC2019-Windows-Windows_10_21H2-X86_64.7z) +Alternatively, download the [qtbase archive](https://download.qt.io/online/qtsdkrepository/windows_x86/desktop/qt6_624/qt.qt6.624.win64_msvc2019_64/6.2.4-0-202203140926qtbase-Windows-Windows_10_21H2-MSVC2019-Windows-Windows_10_21H2-X86_64.7z) and extract it to `C:\Qt` (so it ends up in `C:\Qt\6.2.4`). ### Path setup @@ -49,46 +69,52 @@ Search for "Edit environment variables for your account" then edit your Path var - `C:\Program Files\CMake\bin` - `C:\Qt\6.2.4\msvc2019_64\bin` -### Cmder setup +### Console setup + +#### Cmder Cmder is a sane terminal emulator for windows, which includes git and SSH support among other things. -The following will setup a task that you can use to build things with the VS2019 compiler toolchain. +Install with chocolatey: + +```[pwsh] +choco install cmder -yfd +``` -Run cmder which should be installed by default on C:\tools\cmder\Cmder.exe -Click on the green "+" sign on the right lower corner of cmder -Select "Setup tasks..." -Click the "+" button to add a new task -In the task parameters box add (basically copying from cmd:Cmder task): -``/icon "%CMDER_ROOT%\icons\cmder.ico"`` -In the commands box, add: -``cmd /k ""%ConEmuDir%\..\init.bat" && "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64" -new_console:d:%USERPROFILE%`` +The following will setup a task that you can use to build things with the VS2019 compiler toolchain. -Give the task a name (first box), such as vs2019 and click Save Settings. +1. Run cmder which should be installed by default on C:\tools\cmder\Cmder.exe +2. Click the dropdown arrow next to the green "+" sign in the lower right corner of cmder +3. Select "Setup tasks..." +4. Click the "+" button to add a new task +5. In the task parameters box add (basically copying from cmd:Cmder task): + ``/icon "%CMDER_ROOT%\icons\cmder.ico"`` +6. In the commands box, add: -Building ---------------------------------------- + ```[] + cmd /k ""%ConEmuDir%\..\init.bat" && "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64" -new_console:d:%USERPROFILE% + ``` -Run cmder, click on the green "+" and click on the vs2019 task +7. Give the task a name (first box), such as vs2019 and click Save Settings. +8. Now run cmder, click on the green "+" and click on the vs2019 task This will open a new terminal tab and run the VS2019 setup. CMake can now find the VS compiler. +Go to the [Building](./BUILD.windows.md#building) section. - cd - git submodule update --init --recursive - mkdir build - cd build - cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo ../ - ninja +#### x64 Native Tools Command Prompt -This builds multipass and multipassd. -To create an installer, run `ninja package` +x64 Native Tools Command Prompt is the native console from the MVSC installation. On startup it +updates its environment variables to include all tools installed via MSVC for 64-bit. If you are +using 32-bit, use the x86 Native Tools Command Prompt. -Building (alternative, PowerShell only) ---------------------------------------- +If you want to use the environment variables in a different console, look at: +[Use the Microsoft C++ toolset from the command line](https://learn.microsoft.com/nb-no/cpp/build/building-on-the-command-line?view=msvc-170). + +#### Powershell only Using a Visual-Studio command-prompt-enabled PowerShell to build the project is also possible. Open a new PowerShell terminal, then invoke the following commands: -```pwsh +```[pwsh] # Try to determine the Visual Studio install path $VSPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -products Microsoft.VisualStudio.Product.BuildTools -latest -property installationPath @@ -99,40 +125,77 @@ Import-Module "$VSPath\Common7\Tools\Microsoft.VisualStudio.DevShell.dll" Enter-VsDevShell -VsInstallPath "$VSPath" -DevCmdArguments '-arch=x64' ``` -Then, follow the steps in the previous "Building" step to build the project. +## Building -Running multipass ---------------------------------------- +```[batch] +cd +git submodule update --init --recursive +mkdir build +cd build +``` + +```[batch] +cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_TOOLCHAIN_FILE=..\3rd-party\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_PREFIX_PATH=C:\Qt\6.2.4\msvc2019_64\ ../ +``` + +```[batch] +cmake --build . +``` + +This builds `multipass` and `multipassd`. +To create an installer, run `cmake --build . --target package`. + +## Running `multipass` ### Enable Hyper-V -Before starting multipassd, you'll have to enable the Hyper-V functionality in Windows 10 Pro. -See: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v +Before starting `multipassd`, you'll have to enable the Hyper-V functionality in Windows 10/11 Pro. +See: [Install Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) - Press Windows Key + X, Select Windows PowerShell (Admin) - Run "Enable-WindowsOptionalFeature -Online -FeatureName:Microsoft-Hyper-V -All" +Press Windows Key + X, Select Windows PowerShell (Admin) or Terminal(Admin) and run: + +```[pwsh] +Enable-WindowsOptionalFeature -Online -FeatureName:Microsoft-Hyper-V -All +``` -### Start the daemon (multipassd) +### Start the daemon (`multipassd`) - Press Windows Key + X, Select Windows PowerShell (Admin) - Run multipassd (for example: multipassd --logger=stderr) - Alternatively, you can install multipassd as a Windows Service (Run "multipassd /install") - To stop and uninstall the Windows service, Run "multipassd /uninstall" +1. Press Windows Key + X, Select Windows PowerShell (Admin) or Terminal(Admin) +2. Run `multipassd` (for example: `multipassd --logger=stderr`) +3. Alternatively, you can install `multipassd` as a Windows Service (Run `multipassd /install` in a + Powershell(Admin)). Installing `multipassd` as a Windows Service is a must for Windows 11 +4. To stop and uninstall the Windows service, Run `multipassd /uninstall` -### Run multipass +### Run `multipass` - With the multipassd daemon now running on another shell (or as a windows service) you can now run multipass. - Press Windows Key + X, Select Windows PowerShell, or alternatively run cmd.exe on the search bar - Try "multipass help" +With the `multipassd` daemon now running on another shell (or as a windows service) you can now run `multipass`. -### Permissions/privileges for multipassd +1. Press Windows Key + X, Select Windows PowerShell, or Terminal. +2. [Extend the Path variable](./BUILD.windows.md#Extend the Path variable). +3. Then, try `multipass help`. -multipassd needs Administrator privileges in order to create symlinks when using mounts and to manage Hyper-V instances. +### Permissions/privileges for `multipassd` -If you don't need symlink support you can run multipassd on a less privileged shell but your user account +`multipassd` needs Administrator privileges in order to create symlinks when using mounts and to +manage Hyper-V instances. + +If you don't need symlink support you can run `multipassd` on a less privileged shell but your user account needs to be part of the Hyper-V Administrators group: - Press Windows key + X, Select "Computer Management" - Under System Tools->Local Users and Groups->Groups - Select on Hyper-V Administrators, add your account - Sign out or reboot for changes to take effect +1. Press Windows key + X, Select "Computer Management" +2. Under System Tools->Local Users and Groups->Groups +3. Select on Hyper-V Administrators, add your account +4. Sign out or reboot for changes to take effect + +### Run `multipass.gui` + +1. [Extend the Path variable](./BUILD.windows.md#Extend the Path variable). +2. Now you can run `multipass.gui`. + +### Extend the Path variable + +To avoid conflict with a multipass installation, include the necessary paths to the Path variable in your current session only: +``` +$env:Path += ";\build\bin" +$env:Path += ";\build\bin\windows\x64\runner\Release" +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0706918674f..a6d9a3ad8ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,17 +35,17 @@ with governance goals. **META1.** Everyone in the team can propose additional guidelines.
**META2.** Everyone in the team can question and propose changes to guidelines.
-**META3.** Before the first set of guidelines is established, everyone in the team is invited to +**META3.** Before the *first* set of guidelines is established, everyone in the team is invited to participate in live discussions about them.
**META4.** Before a new version of these guidelines is established, everyone in the team reviews it independently, except if away on prolonged absence.
-**META5.** Ideally, all team members come to agree on any given version of these guidelines before +**META5.** Ideally, all team members come to *agree* on any given version of these guidelines before it is established.
-**META6.** Where that is not possible, preferably a majority of the team agrees with any given +**META6.** Where that is not possible, preferably a majority of the team *agrees* with any given version of these guidelines before it is established.
-**META7.** Preferably, all team members accept the latest established version of these guidelines, +**META7.** Preferably, all team members *accept* the latest established version of these guidelines, until the team agrees to modify it.
-**META8.** In any case, all team members abide by the latest established version of these +**META8.** In any case, all team members *abide* by the latest established version of these guidelines, until the team agrees to modify it.
**META9.** Established guidelines are taken seriously, but with a grain of salt. They are guidelines after all, not absolute rules.
@@ -57,11 +57,14 @@ pull requests.
### Core principles (MU) -Principles for the members of the Multipass team. Many of these are inspired by Canonical's values, +Principles for the members of the Multipass team. Many of these are inspired +by [Canonical's values](https://discourse.canonical.com/t/reaffirming-our-company-values/4525), which we should keep in mind. **MU1.** Aim at excellence.
-**MU2.** Follow best practices (refer to other pertinent documents, e.g.CppCoreGuidelines).
+**MU2.** +Follow best practices (refer to other pertinent documents, +e.g. [CppCoreGuidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines)).
**MU3.** Think critically (even about best practices).
**MU4.** Favor collaboration.
**MU5.** Be open to feedback.
@@ -80,40 +83,40 @@ which we should keep in mind. Descriptive rules of how releases are obtained from Git. -**REL1.** The trunk of Multipass development happens in the main branch, which releases branch out +**REL1.** The trunk of Multipass development happens in the `main` branch, which releases branch out of.
-**REL2.** Preferably, release branches contain only commits that are directly reachable from main or -cherry-picked from it.
+**REL2.** Preferably, release branches contain only commits that are directly reachable from `main` +or cherry-picked from it.
**REL3.** Cherry-picked commits in release branches may differ from the original ones only where necessary to avoid or fix conflicts.
**REL4.** In exceptional cases, release branches may contain dedicated commits for bug, build, or conflict fixes.
-**REL5.** After a release is published, the corresponding release branch is merged back into main.
+**REL5.** After a release is published, the corresponding release branch is merged back into +`main`.
### Pull Requests (PR) Guidelines for how we use and handle pull requests. -**PR1.** Concrete modifications of Multipass can be proposed via Pull Requests (AKA PRs) targeting -the main branch.
-**PR2.** Prefer small, single issue PRs.
+**PR1.** Concrete modifications of Multipass can be proposed +via [Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) +(AKA PRs) targeting the `main` branch.
+**PR2.** Prefer small, single-issue PRs.
**PR3.** A PR should introduce a coherent change that appears as a unit in a medium or high level of abstraction.
-**PR4.** The main branch is modified exclusively via PRs, except for an empty commit after branching -for release.
-**PR5.** PRs accepted into main are merged with merge commits.
-**PR6.** PRs to main should typically be covered by automated tests.
+**PR4.** The `main` branch is modified exclusively via PRs, except for an empty commit after +branching for release.
+**PR5.** PRs accepted into `main` are merged with merge commits.
+**PR6.** PRs to `main` should typically be covered by automated tests.
**PR7.** If a PR is valuable on its own, does not depend on others, and does not involve dead code, -target the main branch, even if it is part of a larger task. This should be the most common case.
+target the `main` branch, even if it is part of a larger task. This should be the most common +case.
**PR8.** If your PR relies on another one, target the other's branch.
-**PR9.** When working on a larger set of changes with cohesive interdependence, consider using a -feature branch.
-**PR10.** Try to keep the number of concurrent feature branches small.
-**PR11.** When PRs are stacked, prefer to merge them in order. The target branch will update +**PR9.** When PRs are stacked, prefer to merge them in order. The target branch will update automatically upon merging.
-**PR12.** PRs should include descriptions and/or point to appropriate context (within reason).
-**PR13.** When authoring a PR, make sure to test it.
-**PR14.** When authoring a PR, make sure to review its diff.
+**PR10.** PRs should include descriptions and/or point to appropriate context (within reason).
+**PR11.** When authoring a PR, make sure to test it.
+**PR12.** When authoring a PR, make sure to review its diff.
### Reviews (RVW) @@ -128,9 +131,34 @@ is mandatory for external PRs (authored or committed from outside the Multipass Renovate bot).
**RVW6.** After a PR is approved by multiple people, small updates require only a single additional approval (i.e. after multiple approvals are dismissed).
-**RVW7.** Notably trivial PRs by the Multipass team may be merged after a single primary approval.
+**RVW7.** Notably trivial PRs by the Multipass team may be merged after a single primary +approval.
**RVW8.** Renovate PRs may be merged after a single primary approval.
-**RVW9.** Review comments should be acknowledged by the author, but resolved by the reviewer.
+**RVW9.** Review comments should be acknowledged by the author, but *resolved* by the reviewer.
+ +### Feature flags (FF) + +**FF1.** When making an interdependent set of changes too large to review and merge as a single PR, +consider adding a feature flag for it.
+**FF2.** Feature flags should be used to disable any new code or behavior which is part of the given +feature; with the feature flag disabled, Multipass should behave identically to before the flag's +introduction.
+**FF3.** Strive to encapsulate code that is dependent on a feature flag, preferably in its own +files, so that those files can be entirely included or excluded from builds.
+**FF4.** If necessary, create stub implementations of new feature APIs to allow other Multipass code +to work with the new interfaces. When possible, put the stub implementations in separate files and +conditionally compile them or the real implementations based on the state of the feature flag.
+**FF5.** Where separate files are not feasible or justified, use preprocessor directives to +selectively enable or disable feature code. Keep this approach as the exception rather than the +norm.
+**FF6.** Minimize unreachable code under a feature flag, i.e., code that can't be reached even +though the feature is enabled.
+**FF7.** PRs for code behind a feature flag should otherwise be treated as usual, with authors and +reviewers maintaining the same standards of quality as for other PRs.
+**FF8.** When a feature is fully-complete and suitable for release, the corresponding feature flag +should be completely removed from Multipass.
+**FF9.** Once a feature flag is removed, all newly-unreachable code should be removed along with +it.
### Versioning (GIT) @@ -141,16 +169,21 @@ there should be two commits instead.
**GIT3.** Strive to preserve a clean but detailed git history.
**GIT4.** Avoid squashing.
**GIT5.** Prefer additional commits during review (easier for reviewers to see the diff).
-**GIT6.** Avoid merging the target branch back into topic. Rebase instead.
-**GIT7.** External contributors are encouraged to sign their commits, while Multipass team members -are required to do so.
+**GIT6.** Avoid merging the target branch back into the topic branch. Rebase instead.
+**GIT7.** External contributors are encouraged to +[sign their commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits), +while Multipass team members are required to do so.
**GIT8.** Use kebab-case branch names (i.e. lower-case-words-separated-with-hyphens).
**GIT9.** Do not introduce whitespace errors.
### Commit messages (MSG) -Guidelines for writing commit messages for non-merge commits. They are inspired by this and other -posts. The category prefix is the main originality. +Guidelines for writing commit messages for non-merge commits. They are inspired by +[this](https://cbea.ms/git-commit/) +[and](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) +[other](https://preslav.me/2015/02/21/what-s-with-the-50-72-rule/) +[posts](https://stackoverflow.com/questions/2290016/git-commit-messages-50-72-formatting). +The category prefix is the main originality. **MSG1.** Begin with a subject line.
**MSG2.** Start the subject line with a lower-case, single-word category, within square brackets @@ -167,10 +200,10 @@ try to find a generic unifying category, or choose the most relevant.
**MSG10.** Do not include more than 1 consecutive blank line.
**MSG11.** Use punctuation normally in the body.
**MSG12.** Wrap the body at 72 characters.
-**MSG13.** Use the body to explain what and why, rather than how.
+**MSG13.** Use the body to explain *what* and *why*, rather than *how*.
**MSG14.** Be descriptive but succinct and avoid filler text.
**MSG15.** Omit the body if the subject is self-explanatory.
-**MSG16.** Common abbreviations are fine (e.g. "msg" or "var")
+**MSG16.** Common abbreviations are fine (e.g. "msg" or "var").
#### Examples @@ -188,13 +221,15 @@ code injection (now or in the future). #### Helper tools -- Consider setting your commit template to the .gitmessage file in the repository root. -- Consider adding the commit-msg file in the repository root as a git hook (in .git/hooks) +- Consider setting your commit template to the `.gitmessage` file in the repository root: + * `git config --local commit.template .gitmessage` +- Consider adding the `commit-msg` file in the repository root as a git hook (in `.git/hooks`) + * `ln -s ../../git-hooks/commit-msg.py .git/hooks/commit-msg` ### Dependencies (DEP) **DEP1.** Acceptable mechanisms to adopt source-code dependencies are, in decreasing order of -preference: vcpkg (for C++) > FetchContent > submodule.
+preference: Vcpkg (for C++) > FetchContent > submodule.
**DEP2.** Avoid vendoring (copied source code).
### Code @@ -206,12 +241,14 @@ tension and have to be balanced. **COD1.** Avoid duplicate sources of truth.
**COD2.** Prefer small units, be they functions, classes, files, etc.
-**COD3.** Follow SOLID principles.
-**COD4.** Pay special attention to the principles of single responsibility and separation of -concerns.
-**COD5.** Don't repeat yourself (DRY).
+**COD3.** Follow [SOLID principles](https://en.wikipedia.org/wiki/SOLID).
+**COD4.** Pay special attention to the principles of +[single responsibility](https://en.wikipedia.org/wiki/Single-responsibility_principle) and +[separation of concerns](https://en.wikipedia.org/wiki/Separation_of_concerns).
+**COD5.** Don't repeat yourself ([DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)).
**COD6.** Don't reinvent the wheel.
-**COD7.** Don't over-engineer (YAGNI).
+**COD7.** Don't +overengineer ([YAGNI](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it)).
**COD8.** Avoid coupling functionality that isn't logically coupled.
**COD9.** Encapsulate, within each unit, all information that other units don't need.
**COD10.** Encapsulate data with dependent behavior.
@@ -221,7 +258,8 @@ concerns.
**COD14.** All else being equal, less code is better code.
**COD15.** Don't try to maximize LoC metrics.
**COD16.** Aim for consistency.
-**COD17.** If it is all the same otherwise, follow a single approach (see how it is done elsewhere).
+**COD17.** If it is all the same otherwise, follow a single approach (see how it is done +elsewhere).
**COD18.** Be creative. If you have a better approach, propose it and discuss it openly.
**COD19.** Prioritize. Balance idealism with pragmatism.
**COD20.** Document public, user-facing interfaces.
@@ -229,23 +267,59 @@ concerns.
#### C++ (CPP) -**CPP1.** Stick to standard C++17, with the exception of #pragma once.
-**CPP2.** Prefer "#pragma once" to header guards
+**CPP1.** Stick to standard C++17, with the exception of `#pragma once`.
+**CPP2.** Prefer `#pragma once` to header guards
**CPP3.** Prefer enforcing correct usage (prevent misuse) at compilation time.
-**CPP4.** If a type isn't meant to be copied or moved, inherit from DisabledCopyMove (either +**CPP4.** If a type isn't meant to be copied or moved, inherit from `DisabledCopyMove` (either directly or indirectly).
**CPP5.** For such types, define only constructors that fully initialize objects. Avoid a default constructor unless the object needs no parameterization.
-**CPP6.** Make copyable types semi-regular.
+**CPP6.** Make copyable +types [semiregular](https://en.cppreference.com/w/cpp/concepts/semiregular).
**CPP7.** Avoid two-stage initialization. Initialize objects fully in the constructor.
-**CPP8.** Avoid const by-value params (e.g. no void foo(const bool flag);)
+**CPP8.** Avoid const by-value params (e.g. no `void foo(const bool flag);`)
**CPP9.** Encapsulate platform-dependent functionality in dedicated units (types, functions) and do -not use platform #ifdefs (or other platform-conditional logic) outside of those units.
-**CPP10.** Use CamelCase for types, but snake_case for variables and functions.
+not use platform `#ifdef`s (or other platform-conditional logic) outside of those units.
+**CPP10.** Use `CamelCase` for types, but `snake_case` for variables and functions.
**CPP11.** Avoid magic numbers.
**CPP12.** Declare generic constants in a dedicated header.
**CPP13.** Avoid compilation warnings.
-**CPP14.** To mock free functions and external APIs, wrap them with MockableSingleton
+**CPP14.** To mock free functions and external APIs, wrap them with `MockableSingleton`.
+ +### Text + +Prescriptive guidelines concerning text and written communication, including but not limited to: +PR descriptions, commit messages, comments, and documentation. + +**TXT1.** Be clear, precise, informative, and organized.
+**TXT2.** Avoid filler text or fluff.
+**TXT3.** Avoid repetition.
+**TXT4.** Use references, quotes, citations, or links to provide context, substantiate claims, +and increase reliability.
+**TXT5.** Express the same idea more than once only to add relevant information, improve precision, +provide a different perspective, or help clarify complexity.
+ +### AI + +Prescriptive guidelines concerning the use of Artificial Intelligence (AI) when contributing to +Multipass, in particular generative AI and LLMs. + +**AI1.** Every contribution must be authored by human beings (one or more), +possibly with the help of AI tools. In addition to code contributions, this applies to issues, pull +requests, discussions, and any other comments or communications, regardless of the platform.
+**AI2.** Contributors are free to use any tools they see fit, including AI tools, provided they do +so lawfully and ethically.
+**AI3.** Git commits must have a human author, with a valid human-managed email address.
+**AI4.** The author(s) of a contribution must be able to explain the contribution in detail, +including any code or textual changes.
+**AI5.** Contributors must refrain from submitting code, text, or any other content that they don't +fully understand.
+**AI6.** Contributors must submit only modifications that they have reviewed thoroughly, +especially if it includes AI-generated content.
+**AI7.** When using AI, contributors should make an extra effort to ensure good information density +(i.e. high signal-to-noise ratio). This includes code and text.
+**AI8.** Authors are ultimately responsible for their entire contributions, +including all components, contents, format, presentation, and communication.
# Further Information diff --git a/README.md b/README.md index 1b1271a5fa7..bc000ecbf97 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ Name State IPv4 Image dancing-chipmunk Running 192.168.64.8 Ubuntu 24.04 LTS phlegmatic-bluebird Stopped -- Ubuntu 22.04 LTS docker Running 192.168.64.11 Ubuntu 22.04 LTS - 172.17.0.1 + 172.17.0.1 ``` ## Learn more about an instance @@ -147,7 +147,7 @@ Name State IPv4 Image dancing-chipmunk Deleted -- Ubuntu 24.04 LTS phlegmatic-bluebird Stopped -- Ubuntu 22.04 LTS docker Running 192.168.64.11 Ubuntu 22.04 LTS - 172.17.0.1 + 172.17.0.1 ``` If you want to completely get rid of it: @@ -171,14 +171,30 @@ before contributing to the project. ## Building Multipass -For build instructions, please refer to the following files: +Please follow the platform-specific build instructions in the files below: -- [BUILD.linux.md](BUILD.linux.md) for Linux -- [BUILD.macOS.md](BUILD.macOS.md) for macOS -- [BUILD.windows.md](BUILD.windows.md) for Windows +* [BUILD.linux.md](./BUILD.linux.md) for Linux +* [BUILD.macOS.md](./BUILD.macOS.md) for macOS +* [BUILD.windows.md](./BUILD.windows.md) for Windows -Please report any outdated information or inconsistencies in these files. Or, even better, submit a pull request with -the changes! Our CI setup is also a good reference for building and testing Multipass. +### Generic build tips + +**Qt version compatibility** +Multipass is tested with **Qt 6.2.4**. Newer patch versions along the 6.2 track (e.g. 6.2.8) should be fine. Newer minor versions may work, but they may cause compatibility issues. + +**ARM64 and cross-compilation** +If you're using Apple Silicon (arm64) or cross-compiling, ensure that your `PATH` and `CMAKE_PREFIX_PATH` environment variables point to the correct Qt installation for your system architecture. + +You may use your preferred package manager to install Multipass. +Note that only the official installers are supported. +See the [installation guide](https://documentation.ubuntu.com/multipass/en/latest/how-to-guides/install-multipass/) for details. + +For backend support and system requirements, refer to the +[Multipass driver documentation](https://documentation.ubuntu.com/multipass/en/latest/explanation/driver/). + +If you notice outdated information or inconsistencies in these files, please [open an issue](https://github.com/canonical/multipass/issues) or, even better, submit a pull request! + +You can also reference our [GitHub Actions CI](https://github.com/canonical/multipass/actions) to see how Multipass is built and tested across platforms. ### Automatic linker selection diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 22656b6ab1b..baa3ace5d09 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,221 +1,25 @@ -# Leave a blank line at the end of this file to support concatenation -anbox -AnyConnect -ApplicationFirewall -ARP -autostart -backend +# Leave a black line at the bottom backend's -backends -BBCcode boolean -bootpd -BPF -cal -cdimages -CIFS -Citrix -cjk -cloneN -CloudFlare -cloudflared -CommonMark -conf -config CPU -cpu CPUs -cpus -cryptographically -CSV -customisations -customized -Cygwin -de dev -DHCP -DNS -dnscrypt -dnsmasq -dvipng echoless -ESET ethernet -facto -Fi -filesystem -fonts -freefont -GiB -GID -github -GPG -GUI -gui -gyre -hacky -hardcoded -https Hyperkit -ICMP -ing -init -init's -IP -ip IPs -ips -IPv -iUDP -jellyfin Junos Kaspersky -KiB -Kudu -lang -latexmk -launchd -libexec -libvirt -lifecycle -liger -localhost -lsof -macOS -macOS's -MACs -mDNSResponder -mentorship -metallb -MiB -microk -Microk -Microk8s -Minikube -minikube misconfiguration -mr -mscho -multipass -Multipass -Multipass's multipassd -netplan -Netplan -Netscaler -NetworkManager -NGINX -nginx -nic NIC NICs -nilgai -numpad -OpenConnect -OpenGL -OpenSSL -OpenVPN -otf overallocate passwordless -plantuml -plist Portainer -Portainer's -PowerShell -provisioner -provisioners -PsExec -PSTools -QCOW -QEMU -RDP -Remmina -repo -resolv -SHA -SMB -snapshotN -socketfilterfw -SonicWall -SourceForge -SSHFS -subnet -sudo Symantec -TCP teardown -tex -texlive -TLS -TOC -trumpetfish -Tunnelblick -ubuntu -Ubuntu -UDP -UEFI -UID -umount -unalias unmount -Unmounting unmounts -userspace -usr -UTF -utils -VcXsrv -VirtualBox -VirtualBox's -vm -VM -VM's -vmnet -VMs -VNC -VPN +vcpkg VPNs -WCAG -whipsnake -Wi -xetex -xindy -XLaunch -Xming -XOrg -XQuartz - -aaryan -andreitoterman -bagustris -bo -candlerb -dan -davidekete -georgeliaojia -gzanchi -henryschreineriii -itecompro -luisp -makin -naynayu -ng -nhart -nottrobin -pitifulpete -porwal -QuantumLibet -ricab -ros -roscigno -saviq -sergiusens -sharder -shuuji -sowasred -sparkiegeek -sven -tmihoc -townsend -undefynd diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt index be5021a1f64..e9cc79a81cc 100644 --- a/docs/.sphinx/.wordlist.txt +++ b/docs/.sphinx/.wordlist.txt @@ -61,4 +61,4 @@ UI UUID VM webhook -YAML +YAML \ No newline at end of file diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py index 9ee2d0b5f66..ec1bf0f1ff7 100644 --- a/docs/.sphinx/get_vale_conf.py +++ b/docs/.sphinx/get_vale_conf.py @@ -5,7 +5,6 @@ DIR = os.getcwd() - def main(): if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"): print("Vale directory exists") @@ -23,6 +22,22 @@ def main(): file.write(download.text) file.close() + # Update dictionary + if os.path.exists(f"{DIR}/.sphinx/styles/config/dictionaries"): + print("Dictionary directory exists") + else: + os.makedirs(f"{DIR}/.sphinx/styles/config/dictionaries") + url = ( + "https://api.github.com/repos/canonical/praecepta/" + + "contents/styles/config/dictionaries" + ) + r = requests.get(url) + for item in r.json(): + download = requests.get(item["download_url"]) + file = open(".sphinx/styles/config/dictionaries/" + item["name"], "w") + file.write(download.text) + file.close() + if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"): print("Vocab directory exists") else: @@ -50,4 +65,4 @@ def main(): if __name__ == "__main__": - main() + main() \ No newline at end of file diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt index ee0598a11a8..b7741a1a473 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/.sphinx/requirements.txt @@ -3,3 +3,4 @@ sphinx-autobuild sphinxcontrib-svg2pdfconverter[CairoSVG] sphinx-last-updated-by-git sphinx-sitemap +myst-parser~=4.0 diff --git a/docs/Makefile b/docs/Makefile index ed04e3a3c91..8042799d5aa 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,6 +17,7 @@ ALLFILES = *.rst **/*.rst METRICSDIR = $(SOURCEDIR)/.sphinx/metrics REQPDFPACKS = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng CONFIRM_SUDO ?= N +VALE_CONFIG = $(SPHINXDIR)/vale.ini # Put it first so that "make" without argument is like "make help". help: @@ -61,6 +62,14 @@ $(VENVDIR): @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt @touch $(VENVDIR) +vale-install: install + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale + @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py + @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter + @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter + @echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --version \; + woke-install: @type woke >/dev/null 2>&1 || \ { \ @@ -124,10 +133,17 @@ clean-doc: git clean -fx "$(BUILDDIR)" rm -rf $(SPHINXDIR)/.doctrees -spellcheck: spellcheck-install - . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) +vale-spelling: vale-install + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + + +spellcheck: vale-spelling -spelling: html spellcheck +spelling: clean-doc vale-spelling # clean built html and Use Vale for spelling check linkcheck: install . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; } @@ -140,16 +156,11 @@ woke: woke-install pa11y: pa11y-install html find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) -vale: install - @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale - @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py - @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; +vale: vale-install @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt - @echo "" @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" - @echo "" - @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,rst}' $(TARGET) || true + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt pdf-prep: install diff --git a/docs/conf.py b/docs/conf.py index 564263a6285..a506aea4dcf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,6 @@ import datetime import ast +import os # Configuration for the Sphinx documentation builder. # All configuration specific to your project should be done in this file. @@ -70,10 +71,10 @@ # NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph # and is used by social media platforms; see https://ogp.me/ -ogp_site_url = "https://documentation.ubuntu.com/multipass/en/latest/" +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") +ogp_site_url = html_baseurl -html_baseurl = "https://documentation.ubuntu.com/multipass/" # for sitemap.xml, the trailing slash is important -sitemap_url_scheme = "en/latest/{link}" +sitemap_url_scheme = "{link}" # Preview name of the documentation website # @@ -208,13 +209,15 @@ "https://sourceforge.net/projects/xming/", "http://www.straightrunning.com/XmingNotes/", "https://unix.stackexchange.com", # it seems stackexchange is now blocking bots + "https://developer.hashicorp.com/packer", + "https://www.freedesktop.org/*" ] linkcheck_retries = 3 # A regex list of URLs where anchors are ignored by 'make linkcheck' -linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] +linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*",r"https://matrix\.to/.*"] ######################## diff --git a/docs/explanation/about-performance.md b/docs/explanation/about-performance.md index c6bd9e69d8f..1af0cdcd81a 100644 --- a/docs/explanation/about-performance.md +++ b/docs/explanation/about-performance.md @@ -4,7 +4,7 @@ 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) +* the host machine 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. diff --git a/docs/explanation/about-security.md b/docs/explanation/about-security.md index 79040ed9a95..a355cbaa730 100644 --- a/docs/explanation/about-security.md +++ b/docs/explanation/about-security.md @@ -1,7 +1,7 @@ (explanation-about-security)= # 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) +> See also: [Authentication](/explanation/authentication), [How to authenticate users with the Multipass service](how-to-guides-customise-multipass-authenticate-users-with-the-multipass-service), [`authenticate`](/reference/command-line-interface/authenticate), [`local.passphrase`](/reference/settings/local-passphrase) ```{caution} **WARNING** @@ -15,6 +15,6 @@ 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 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 user'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. +The first user to connect that is a member of the `sudo` group (or `wheel`/`adm`, depending on the OS) will automatically have their TLS certificate imported into the Multipass daemon and will be authenticated to connect. After this, any other user connecting will need to [`authenticate`](/reference/command-line-interface/authenticate) first by providing a [passphrase](/reference/settings/local-passphrase) set by the administrator. diff --git a/docs/explanation/alias.md b/docs/explanation/alias.md deleted file mode 100644 index b5bd35f60bc..00000000000 --- a/docs/explanation/alias.md +++ /dev/null @@ -1,6 +0,0 @@ -(explanation-alias)= -# 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. diff --git a/docs/explanation/authentication.md b/docs/explanation/authentication.md index c125ab6f007..3e6f2589998 100644 --- a/docs/explanation/authentication.md +++ b/docs/explanation/authentication.md @@ -1,28 +1,28 @@ (explanation-authentication)= # Authentication -> See also: [How to authenticate clients with the Multipass service](/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service) +> See also: [How to authenticate users with the Multipass service](how-to-guides-customise-multipass-authenticate-users-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. +Before executing any commands, Multipass requires users 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 users. When a user connects, Multipass validates the certificate to ensure only verified users can access the service. -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} 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). +After the first client connects with a user belonging to the socket's admin group, the user's OpenSSL certificate will be accepted by the daemon and the socket will 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). ```` -````{group-tab} macOS +````{tab-item} 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). +After the first client connects with a user belonging to the socket's admin group, the user's OpenSSL certificate will be accepted by the daemon and the socket will 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). ```` -````{group-tab} 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. +````{tab-item} 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 user 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). +To close this gap, the user will now need to be authenticated with the Multipass service. To ease the burden of having to authenticate, 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). ```` ````` diff --git a/docs/explanation/host.md b/docs/explanation/host.md deleted file mode 100644 index d53e66dbb91..00000000000 --- a/docs/explanation/host.md +++ /dev/null @@ -1,4 +0,0 @@ -(explanation-host)= -# Host - -In Multipass, **host** refers the actual physical machine on which Multipass is running. diff --git a/docs/explanation/index.md b/docs/explanation/index.md index cf545bee059..a0116296b3d 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -1,12 +1,86 @@ (explanation-index)= # Explanation -The following explanations provide context and clarification on key-topics related to the use and configuration of Multipass. +The following guides provide conceptual context and clarification on the key topics related to using and configuring Multipass. + +## Architecture + +These topics cover the foundations of how Multipass operates on your machine, providing a high-level overview of its structure and components. + +- [Reference architecture](explanation-reference-architecture): A high-level overview of how Multipass is structured, including its clients, daemon, storage, instances, and networking. +- [Host](explanation-host) +- [Platform](explanation-platform) +- [Service](explanation-service) +- [Driver](explanation-driver) + + + +## Instances + +These guides explain the lifecycle, identity, and resources of the virtual machines you create. + +- [Instance](explanation-instance) +- [Image](explanation-image) +- [Settings keys and values](explanation-settings-keys-values) +- [Blueprint (removed)](explanation-blueprint) + +## Using Multipass + +Concepts related to interacting and extending the functionality of your instances. + +- [Multipass exec and shells](explanation-multipass-exec-and-shells) +- [Mount](explanation-mount) +- [Alias](explanation-alias) +- [Snapshot](explanation-snapshot) + +In Multipass, an **alias** is a shortcut for a command that runs inside a given instance. + +## Security and performance + +Technical background on protecting your environment and ensuring it runs efficiently. + +- [About security](explanation-about-security) +- [Authentication](explanation-authentication) +- [ID mapping](explanation-id-mapping) +- [About performance](explanation-about-performance) + +--- + +## Glossary + +(explanation-alias)= +### Alias + +``` {seealso} +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. + + +(explanation-host)= +### Host + +In Multipass, **host** refers the actual physical machine on which Multipass is running. + ```{toctree} :titlesonly: :maxdepth: 2 -:glob: +:hidden: -* +reference-architecture +platform +service +driver +instance +image +settings-keys-values +blueprint +multipass-exec-and-shells +mount +snapshot +about-security +authentication +id-mapping +about-performance ``` diff --git a/docs/explanation/mount.md b/docs/explanation/mount.md index 58710e9b356..0b59beaf61b 100644 --- a/docs/explanation/mount.md +++ b/docs/explanation/mount.md @@ -30,19 +30,19 @@ Native mounts use driver-dependent technologies to achieve the high performance. (security-considerations-mount)= ## Security considerations -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} 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). ```` -````{group-tab} macOS +````{tab-item} 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. ```` -````{group-tab} Windows +````{tab-item} 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. diff --git a/docs/explanation/platform.md b/docs/explanation/platform.md index 056b2f1473a..0ff0c060cce 100644 --- a/docs/explanation/platform.md +++ b/docs/explanation/platform.md @@ -1,7 +1,7 @@ (explanation-platform)= # Platform -> See also: [How to install Multipass](/how-to-guides/install-multipass), [Host](/explanation/host), [Driver](/explanation/driver) +> See also: [How to install Multipass](/how-to-guides/install-multipass), [Driver](/explanation/driver) In Multipass, **platform** refers to the host computer's operating system. This can be Windows, macOS, or Linux. diff --git a/docs/explanation/reference-architecture.md b/docs/explanation/reference-architecture.md new file mode 100644 index 00000000000..036a61f35c0 --- /dev/null +++ b/docs/explanation/reference-architecture.md @@ -0,0 +1,47 @@ +(explanation-reference-architecture)= +# Reference architecture + +```{seealso} +[Mount](explanation-mount), [GUI Client](reference-gui-client), [Instance](explanation-instance) +``` + +Multipass is a tool to generate cloud-style Ubuntu VMs quickly on Linux, macOS and Windows. It provides a GUI and a simple but powerful CLI, enabling you to quickly access an Ubuntu command line or create your own local mini-cloud. + +```{figure} /images/multipass-reference-architecture.jpg + :alt: Multipass reference architecture diagram +``` + +## Clients + +A term we borrow from the client/server model. Multipass clients provide users with an interface to Multipass and its instances, delegating requests on the Multipass daemon. There are two clients in Multipass, both offering a user interface: one on the command line — the Command Line Interface, or CLI — and one graphical — The Graphical User Interface, or GUI. + +## CLI (Command Line Interface) + +Is one of the two user interfaces that Multipass offers, in a client program that communicates with the daemon and which can be invoked on the command line: multipass. It is through this client that users can control Multipass and its instances in the terminal, with commands like multipass launch or `multipass start`. + +## GUI (Graphical User Interface) + +The Multipass GUI provides a visual, point-and-click interface for managing Multipass and its instances. It runs as a separate client application which (like the CLI) communicates with, and delegates operations to, the Multipass daemon. The Multipass GUI provides a visual, point-and-click interface for managing Multipass and its instances. + +## Daemon/Service + +A long living background process that is responsible for a variety of tasks, like managing instances, client authentication, storing configuration settings, or providing file system shares. The daemon provides the services that the clients use. It runs as a privileged user allowing it to interact directly with system resources and control which users have access to Multipass’s instances. + +## Storage/Mounts + +A filesystem share between the host machine and a guest instance. Mounts expose host directories inside the virtual machine and can be used for bidirectional file transfer. The underlying technology depends on the mount type and host platform, and it can be either SSHFS/SFTP, 9P, or SMB. + +## Instances +A Linux virtual machine hosted by the user’s machine. Multipass uses a hypervisor technology specific to the user’s native operating system which is used to emulate the instance. + +## Image Hosts + +Remote source to obtain disk images from. As of now, these are public online repositories of cloud Linux images that Multipass creates new instances from. Multipass periodically fetches and updates the image metadata from image hosts, pruning old images and downloading new ones on demand. + +## Networking + +Multipass creates a virtual network using a dedicated subnet on the host. Each instance obtains an IP address from this private network, via DHCP. Within this private network, instances can initiate outbound connections (egress), communicate with each other, and be reached from the host, but they remain inaccessible from outside the host. For that, instances can be bridged to the host's physical network, allowing inbound connections (ingress) from other nodes (e.g. other computers on a home network). + +## Web + +Multipass instances are online by default (provided the host is). They can reach the web via either the private or the public network. The Multipass daemon also fetches information from the web, in particular image hosts. diff --git a/docs/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md b/docs/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md deleted file mode 100644 index 0cd570b9174..00000000000 --- a/docs/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service.md +++ /dev/null @@ -1,113 +0,0 @@ -(how-to-guides-customise-multipass-authenticate-clients-with-the-multipass-service)= -# 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. The installing user is automatically authenticated. - -## 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: - - ```{code-block} text - multipass set local.passphrase - ``` - - The system will then prompt you to enter a passphrase: - - ```{code-block} text - Please enter passphrase: - Please re-enter passphrase: - ``` - -* Set the passphrase in the command line, where the passphrase is visible: - - ```{code-block} text - multipass set local.passphrase=foo - ``` - -## Authenticating the client - -A client that is not authorised 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: - -```{code-block} text -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: - - ```{code-block} text - multipass authenticate - ``` - - The system will prompt you to enter the passphrase: - - ```{code-block} text - Please enter passphrase: - ``` - -* Authenticate in the command line, where the passphrase is visible: - - ```{code-block} text - multipass authenticate foo - ``` - -## Troubleshooting - -Here you can find solutions and workarounds for common issues that may arise. - -### The client cannot be authorised 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. This usually occurs when Multipass is installed as root/admin but -the client is run as another user, or vice versa. - -If this is the case, you will see something like the following when you run: - -* `multipass list` - - ```{code-block} text - list failed: The client is not authenticated with the Multipass service. - Please use 'multipass authenticate' before proceeding. - ``` - -* `multipass authenticate` - - ```{code-block} text - Please enter passphrase: - authenticate failed: Passphrase is not set. Please `multipass set - local.passphrase` with a trusted client. - ``` - -* `multipass set local.passphrase` - - ```{code-block} text - 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: - -```{code-block} text -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. diff --git a/docs/how-to-guides/customise-multipass/authenticate-users-with-the-multipass-service.md b/docs/how-to-guides/customise-multipass/authenticate-users-with-the-multipass-service.md new file mode 100644 index 00000000000..63dc0230f54 --- /dev/null +++ b/docs/how-to-guides/customise-multipass/authenticate-users-with-the-multipass-service.md @@ -0,0 +1,117 @@ +(how-to-guides-customise-multipass-authenticate-users-with-the-multipass-service)= +# Authenticate users with the Multipass service + +> See also: [`authenticate`](reference-command-line-interface-authenticate), [local.passphrase](reference-settings-local-passphrase), [Service](explanation-service) + +Multipass requires users to be authenticated with the service before allowing commands to complete. The installing user is automatically authenticated. + +## Setting the passphrase + +The administrator needs to set a passphrase for users to authenticate with the Multipass service. The user 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: + + ```{code-block} text + multipass set local.passphrase + ``` + + The system will then prompt you to enter a passphrase: + + ```{code-block} text + Please enter passphrase: + Please re-enter passphrase: + ``` + +* Set the passphrase in the command line, where the passphrase is visible: + + ```{code-block} text + multipass set local.passphrase=foo + ``` + +## Authenticating the user + +A user 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: + +```{code-block} text +list failed: The user is not authenticated with the Multipass service. + +Please authenticate before proceeding (e.g. via 'multipass authenticate'). Note that you first need an authenticated user to set and provide you with a trusted passphrase (e.g. via 'multipass set local.passphrase'). +``` + +At this time, the user 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: + + ```{code-block} text + multipass authenticate + ``` + + The system will prompt you to enter the passphrase: + + ```{code-block} text + Please enter passphrase: + ``` + +* Authenticate in the command line, where the passphrase is visible: + + ```{code-block} text + multipass authenticate foo + ``` + +## Troubleshooting + +Here you can find solutions and workarounds for common issues that may arise. + +### The user cannot be authorized and the passphrase cannot be set + +It is possible that another user 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 user with the service. This usually occurs when Multipass is installed as `root/admin` but +the user is run as another user, or vice versa. + +If this is the case, you will see something like the following when you run: + +* `multipass list` + + ```{code-block} text + list failed: The user is not authenticated with the Multipass service. + + Please authenticate before proceeding (e.g. via 'multipass authenticate'). Note that you first need an authenticated user to set and provide you with a trusted passphrase (e.g. via 'multipass set local.passphrase'). + ``` + +* `multipass authenticate` + + ```{code-block} text + Please enter passphrase: + authenticate failed: No passphrase is set. + + Please ask an authenticated user to set one and provide it to you. They can achieve so with 'multipass set local.passphrase'. Note that only the user who installs Multipass is automatically authenticated. + ``` + +* `multipass set local.passphrase` + + ```{code-block} text + Please enter passphrase: + Please re-enter passphrase: + set failed: The user is not authenticated with the Multipass service. + + Please authenticate before proceeding (e.g. via 'multipass authenticate'). Note that you first need an authenticated user to set and provide you with a trusted passphrase (e.g. via 'multipass set local.passphrase'). + ``` + +This may not even work when using `sudo`. + +The following workaround should help get out of this situation: + +```bash +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 user should be authenticated with the Multipass service. diff --git a/docs/how-to-guides/customise-multipass/build-multipass-images-with-packer.md b/docs/how-to-guides/customise-multipass/build-multipass-images-with-packer.md index 8ef6ecaf946..5a0c3d58310 100644 --- a/docs/how-to-guides/customise-multipass/build-multipass-images-with-packer.md +++ b/docs/how-to-guides/customise-multipass/build-multipass-images-with-packer.md @@ -5,7 +5,7 @@ Custom images are only supported on Linux. ``` -[Packer](https://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). +[Packer](https://developer.hashicorp.com/packer) 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 diff --git a/docs/how-to-guides/customise-multipass/configure-multipass-default-logging-level.md b/docs/how-to-guides/customise-multipass/configure-multipass-default-logging-level.md index a7f53a474aa..ef51708efd0 100644 --- a/docs/how-to-guides/customise-multipass/configure-multipass-default-logging-level.md +++ b/docs/how-to-guides/customise-multipass/configure-multipass-default-logging-level.md @@ -1,15 +1,15 @@ (how-to-guides-customise-multipass-configure-multipass-default-logging-level)= # Configure Multipass’s default logging level -> See also: [Logging levels](/reference/logging-levels) +> 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-set} -````{group-tab} Linux +````{tab-item} Linux First, stop the Multipass daemon: @@ -37,7 +37,7 @@ sudo snap start multipass ```` -````{group-tab} macOS +````{tab-item} macOS First, become `root`: @@ -61,7 +61,7 @@ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist ```` -````{group-tab} Windows +````{tab-item} Windows First, open an administrator privileged PowerShell prompt. diff --git a/docs/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md b/docs/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md index 38a1796ff23..27d096c994f 100644 --- a/docs/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md +++ b/docs/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md @@ -12,9 +12,10 @@ This document demonstrates how to configure the location where Multipass stores - When uninstalling Multipass, the uninstaller will not remove data stored in custom locations, so you'll have to delete it manually. ``` -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux First, stop the Multipass daemon: @@ -22,7 +23,7 @@ First, stop the Multipass daemon: 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: +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 your home directory (`~`, e.g. `/home/username/`, which is connected by default) or one of the removable mounts points (`/mnt` or `/media`). To connect the removable mount points, use the command: ```{code-block} text sudo snap connect multipass:removable-media @@ -86,7 +87,8 @@ sudo rm -rf /var/snap/multipass/common/cache/multipassd ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS First, become `root`: @@ -124,7 +126,8 @@ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows First, open a PowerShell prompt with administration privileges. @@ -154,7 +157,7 @@ Copy-Item -Path "C:\ProgramData\Multipass\*" -Recurse -Force -Destination " ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS First, become `root`: @@ -265,7 +270,8 @@ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows First, open a PowerShell prompt with administrator privileges. diff --git a/docs/how-to-guides/customise-multipass/index.md b/docs/how-to-guides/customise-multipass/index.md index 85117b22e13..9fed3739e86 100644 --- a/docs/how-to-guides/customise-multipass/index.md +++ b/docs/how-to-guides/customise-multipass/index.md @@ -3,15 +3,15 @@ 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](set-up-the-driver) -- [Migrate from Hyperkit to QEMU on macOS](migrate-from-hyperkit-to-qemu-on-macos) -- [Authenticate clients with the Multipass service](authenticate-clients-with-the-multipass-service) -- [Build Multipass images with Packer](build-multipass-images-with-packer) -- [Set up a graphical interface](set-up-a-graphical-interface) -- [Use a different terminal from the system icon](use-a-different-terminal-from-the-system-icon) -- [Integrate with Windows Terminal](integrate-with-windows-terminal) -- [Configure where Multipass stores external data](configure-where-multipass-stores-external-data) -- [Configure Multipass’s default logging level](configure-multipass-default-logging-level) +- [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 users with the Multipass service](how-to-guides-customise-multipass-authenticate-users-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-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-multipass-default-logging-level) @@ -29,7 +31,8 @@ The default backend on macOS is `qemu`, wrapping Apple's Hypervisor framework. Y ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows ### Hyper-V @@ -45,9 +48,10 @@ Multipass also supports using VirtualBox as a virtualisation provider. You can d ## Install -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux To install Multipass, run the following command: @@ -122,7 +126,8 @@ installed: 1.3.0 (2205) 228MB - ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS ```{note} You will need an account with administrator privileges to complete the installation. @@ -143,7 +148,8 @@ Run the downloaded installer and follow the guided procedure. ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows ```{note} You will need either Hyper-V enabled (only Windows 10 Professional or Enterprise), or VirtualBox installed. See {ref}`install-multipass-prerequisites`. @@ -161,15 +167,17 @@ Alternatively, you can also check your preferred package manager to see if it pr ## Run -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux You've installed Multipass. Time to run your first commands! Use `multipass version` to check your version or `multipass launch` to create your first instance. ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS You've installed Multipass. Time to run your first commands! Use `multipass version` to check your version or `multipass launch` to create your first instance. @@ -179,7 +187,8 @@ You've installed Multipass. Time to run your first commands! Use `multipass vers ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows You've installed Multipass. Time to run your first commands! Launch a **Command Prompt** (`cmd.exe`) or **PowerShell** as a regular user. Use `multipass version` to check your version or `multipass launch` to create your first instance. @@ -194,18 +203,20 @@ multipass set local.driver=virtualbox ```` ````` - +(how-to-guides-install-multipass-upgrade)= ## Upgrade -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux As the installation happened via snap, you don't need to worry about upgrading---it will be done automatically. ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS ```{note} You will need an account with administrator privileges to complete the upgrade. @@ -219,7 +230,8 @@ Any existing instances will be preserved. ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows 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. @@ -231,9 +243,10 @@ You will be asked to uninstall the old version, and then whether to remove all d ## Uninstall -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux To uninstall Multipass, run the following command: @@ -243,7 +256,8 @@ snap remove multipass ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS To uninstall Multipass, run the script: ```{code-block} text @@ -252,7 +266,8 @@ sudo sh "/Library/Application Support/com.canonical.multipass/uninstall.sh" ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows Uninstall Multipass as you would any other program, following the usual procedure. diff --git a/docs/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md b/docs/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md index 9e53ccc6d7e..59e55235728 100644 --- a/docs/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md +++ b/docs/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md @@ -2,8 +2,8 @@ # Add a network to an existing instance ```{seealso} -[`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) -``` +[`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. @@ -11,7 +11,7 @@ This guide explains how to bridge an existing Multipass instance with the availa This feature is available starting from Multipass version 1.14. ``` -First, you need to select a Multipass-wide preferred network to bridge with (you can always change it later). To do so, list all available networks using the [`multipass networks`](/reference/command-line-interface/networks) command. The output will be similar to the following: +First, you need to select a Multipass-wide preferred network to bridge with (you can always change it later). To do so, list all available networks using the [`multipass networks`](reference-command-line-interface-networks) command. The output will be similar to the following: ```{code-block} text Name Type Description @@ -24,19 +24,19 @@ mpbr0 bridge Network bridge for Multipass virbr0 bridge Network bridge ``` -Set the preferred network (for example, `eth0`) using the [`set`](/reference/command-line-interface/set) command: +Set the preferred network (for example, `eth0`) using the [`set`](reference-command-line-interface-set) command: ```{code-block} text multipass set local.bridged-network=eth0 ``` -Before bridging the network, you need to stop the instance (called `ultimate-grosbeak` in our example) using the [`stop`](/reference/command-line-interface/stop) command: +Before bridging the network, you need to stop the instance (called `ultimate-grosbeak` in our example) using the [`stop`](reference-command-line-interface-stop) command: ```{code-block} text multipass stop ultimate-grosbeak ``` -You can now ask Multipass to bridge your preferred network using the [`local..bridged`](/reference/settings/local-instance-name-bridged) setting: +You can now ask Multipass to bridge your preferred network using the [`local..bridged`](reference-settings-local-instance-name-bridged) setting: ```{code-block} text multipass set local.ultimate-grosbeak.bridged=true @@ -49,7 +49,7 @@ multipass set local.bridged-network=eth1 multipass set local.ultimate-grosbeak.bridged=true ``` -Use the [`get`](/reference/command-line-interface/get) command to check whether an instance is bridged with the currently configured preferred network: +Use the [`get`](reference-command-line-interface-get) command to check whether an instance is bridged with the currently configured preferred network: ```{code-block} text multipass get local.ultimate-grosbeak.bridged @@ -57,7 +57,7 @@ multipass get local.ultimate-grosbeak.bridged After following the recipe above, the result should be `true`. -Now, [`start`](/reference/command-line-interface/start) the instance. +Now, [`start`](reference-command-line-interface-start) the instance. ```{code-block} text multipass start ultimate-grosbeak diff --git a/docs/how-to-guides/manage-instances/configure-static-ips.md b/docs/how-to-guides/manage-instances/configure-static-ips.md index 40829ebc03c..a5b0a685fc0 100644 --- a/docs/how-to-guides/manage-instances/configure-static-ips.md +++ b/docs/how-to-guides/manage-instances/configure-static-ips.md @@ -1,7 +1,7 @@ (how-to-guides-manage-instances-configure-static-ips)= # Configure static IPs -> See also: [Instance](/explanation/instance) +> 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. diff --git a/docs/how-to-guides/manage-instances/create-an-instance.md b/docs/how-to-guides/manage-instances/create-an-instance.md index 19f3683d82f..e31eed296be 100644 --- a/docs/how-to-guides/manage-instances/create-an-instance.md +++ b/docs/how-to-guides/manage-instances/create-an-instance.md @@ -1,13 +1,13 @@ (how-to-guides-manage-instances-create-an-instance)= # Create an instance -> See also: [`launch`](/reference/command-line-interface/launch), [Instance](/explanation/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. ## Create an instance -> See also: [`launch`](/reference/command-line-interface/launch), [`info`](/reference/command-line-interface/info) +> See also: [`launch`](reference-command-line-interface-launch), [`info`](reference-command-line-interface-info) To create an instance with Multipass, run the command `multipass launch`. This launches a new instance, which is randomly named; for example: @@ -32,7 +32,7 @@ Memory usage: 71.6M out of 985.4M ## Create an instance with a specific image -> See also: [`find`](/reference/command-line-interface/find), [`launch `](/reference/command-line-interface/launch), [`info`](/reference/command-line-interface/info) +> See also: [`find`](reference-command-line-interface-find), [`launch `](reference-command-line-interface-launch), [`info`](reference-command-line-interface-info) To find out which images are available, run `multipass find`. Here's a sample output: @@ -77,7 +77,7 @@ Mounts: -- ## Create an instance with a custom name -> See also: [`launch --name`](/reference/command-line-interface/launch) +> See also: [`launch --name`](reference-command-line-interface-launch) To launch an instance with a specific name, add the `--name` option to the command line; for example `multipass launch kinetic --name helpful-duck`: @@ -88,7 +88,7 @@ Launched: helpful-duck ## Create an instance with custom CPU number, disk and RAM -> See also: [`launch --cpus --disk --memory`](/reference/command-line-interface/launch) +> See also: [`launch --cpus --disk --memory`](reference-command-line-interface-launch) You can specify a custom number of CPUs, disk and RAM size using the `--cpus`, `--disk` and `--memory` arguments, respectively. For example: @@ -98,7 +98,7 @@ multipass launch --cpus 4 --disk 20G --memory 8G ## Create an instance with primary status -> See also: [`launch --name primary`](/reference/command-line-interface/launch) +> See also: [`launch --name primary`](reference-command-line-interface-launch) An instance can obtain the primary status at creation time if its name is `primary`: @@ -106,14 +106,14 @@ An instance can obtain the primary status at creation time if its name is `prima multipass launch kinetic --name primary ``` -For more information, see [How to use the primary instance](/how-to-guides/manage-instances/use-the-primary-instance). +For more information, see [How to use the primary instance](how-to-guides-manage-instances-use-the-primary-instance). (create-an-instance-with-multiple-network-interfaces)= ## Create an instance with multiple network interfaces -> See also: [`launch --network`](/reference/command-line-interface/launch) +> See also: [`launch --network`](reference-command-line-interface-launch) -Multipass can create instances with additional network interfaces using the `multipass launch` command with the `--network` option. This is complemented by the [`networks`](/reference/command-line-interface/networks) command, that you can use to find available host networks to bridge with. +Multipass can create instances with additional network interfaces using the `multipass launch` command with the `--network` option. This is complemented by the [`networks`](reference-command-line-interface-networks) command, that you can use to find available host networks to bridge with. This feature is only supported for images with [`cloud-init` support for v2 network config](https://cloudinit.readthedocs.io/en/latest/topics/network-config-format-v2.html), which in turn requires [netplan](https://netplan.io/) to be installed, meaning that you'll require Ubuntu 17.10 and Ubuntu Core 16 (except `snapcraft:core16`) or later. More specifically, this feature is only supported in the following scenarios: @@ -123,7 +123,7 @@ This feature is only supported for images with [`cloud-init` support for v2 netw The `--network` option can be given multiple times to request multiple network interfaces beyond the default one, which is always present. Each time you add the `--network` option you also need to provide an argument specifying the properties of the desired interface: -- `name` - This is the only required value, used to identify the host network to connect the instance's device to (see [`networks`](/reference/command-line-interface/networks) for possible values). +- `name` - This is the only required value, used to identify the host network to connect the instance's device to (see [`networks`](reference-command-line-interface-networks) for possible values). - `mode` - Either `auto` (default) or `manual`; with `auto`, the instance will attempt to configure the network automatically. - `mac` - Custom MAC address to use for the device. @@ -231,11 +231,11 @@ Another option is to install `NetworkManager`, but other network handlers need t ## Create an instance with a custom DNS -In some scenarios the default of using the system-provided DNS will not be sufficient. When that's the case, you can use the `--cloud-init` option to the [`launch`](/reference/command-line-interface/launch) command, or modify the networking configuration after the instance started. +In some scenarios the default of using the system-provided DNS will not be sufficient. When that's the case, you can use the `--cloud-init` option to the [`launch`](reference-command-line-interface-launch) command, or modify the networking configuration after the instance started. ### The `--cloud-init` approach -> See also: [`launch --cloud-init`](/reference/command-line-interface/launch) +> See also: [`launch --cloud-init`](reference-command-line-interface-launch) To use a custom DNS in your instances, you can use this `cloud-init` snippet: diff --git a/docs/how-to-guides/manage-instances/index.md b/docs/how-to-guides/manage-instances/index.md index 519c4dcfce7..6a10d818369 100644 --- a/docs/how-to-guides/manage-instances/index.md +++ b/docs/how-to-guides/manage-instances/index.md @@ -5,19 +5,19 @@ The following guides provide step-by-step instructions on how to manage Multipas 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: -- [Create an instance](create-an-instance) -- [Modify an instance](modify-an-instance) -- [Launch customized instances with Multipass and cloud-init](launch-customized-instances-with-multipass-and-cloud-init) -- [Use an instance](use-an-instance) -- [Use the primary instance](use-the-primary-instance) -- [Use instance command aliases](use-instance-command-aliases) -- [Share data with an instance](share-data-with-an-instance) -- [Remove an instance](remove-an-instance) -- [Add a network to an existing instance](add-a-network-to-an-existing-instance) -- [Configure static IPs](configure-static-ips) -- [Use a blueprint](use-a-blueprint) -- [Use the Docker blueprint](use-the-docker-blueprint) -- [Run a Docker container in Multipass](run-a-docker-container-in-multipass) +- [Create an instance](how-to-guides-manage-instances-create-an-instance) +- [Modify an instance](how-to-guides-manage-instances-modify-an-instance) +- [Launch customized instances with Multipass and cloud-init](how-to-guides-manage-instances-launch-customized-instances-with-multipass-and-cloud-init) +- [Use an instance](how-to-guides-manage-instances-use-an-instance) +- [Use the primary instance](how-to-guides-manage-instances-use-the-primary-instance) +- [Use instance command aliases](how-to-guides-manage-instances-use-instance-command-aliases) +- [Share data with an instance](how-to-guides-manage-instances-share-data-with-an-instance) +- [Remove an instance](how-to-guides-manage-instances-remove-an-instance) +- [Add a network to an existing instance](how-to-guides-manage-instances-add-a-network-to-an-existing-instance) +- [Configure static IPs](how-to-guides-manage-instances-configure-static-ips) +- {ref}`how-to-guides-manage-instances-use-a-blueprint` +- {ref}`how-to-guides-manage-instances-use-the-docker-blueprint` +- [Run a Docker container in Multipass](how-to-guides-manage-instances-run-a-docker-container-in-multipass) ```{toctree} :hidden: diff --git a/docs/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init.md b/docs/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init.md index aa2d91b9130..2044921c530 100644 --- a/docs/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init.md +++ b/docs/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init.md @@ -6,6 +6,7 @@ You can set up instances with a customized environment or configuration using th Below are some common examples of using `cloud-init` with Multipass to create customized instances. The `cloud-init` file is provided by the Multipass team, but users are free to create and use their own personal `cloud-init` configurations. ## 📦 anbox-cloud-appliance + Launch with: ```{code-block} text multipass launch \ @@ -16,8 +17,11 @@ multipass launch \ --timeout 900 \ --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-anbox.yaml ``` + ## ⚙️ charm-dev + Launch with: + ```{code-block} text multipass launch 24.04 \ --name charm-dev \ @@ -27,7 +31,9 @@ multipass launch 24.04 \ --timeout 1800 \ --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-charm-dev.yaml ``` + Health check: + ```{code-block} text multipass exec charm-dev -- bash -c " set -e @@ -38,8 +44,11 @@ multipass exec charm-dev -- bash -c " charmcraft pack " ``` + ## 🐳 docker + Launch with: + ```{code-block} text multipass launch 24.04 \ --name docker \ @@ -48,10 +57,13 @@ multipass launch 24.04 \ --disk 40G \ --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-docker.yaml ``` + Health check: + ```{code-block} text multipass exec docker -- bash -c "docker run hello-world" ``` + You can also optionally add aliases: ```{code-block} text @@ -61,10 +73,13 @@ multipass alias docker:docker-compose docker-compose multipass prefer default multipass aliases ``` -> See also: [`How to use command aliases`](/how-to-guides/manage-instances/use-instance-command-aliases) + +> See also: [`How to use command aliases`](how-to-guides-manage-instances-use-instance-command-aliases) ## 🎞️ jellyfin + Launch with: + ```{code-block} text multipass launch 22.04 \ --name jellyfin \ @@ -75,7 +90,9 @@ multipass launch 22.04 \ ``` ## ☸️ minikube + Launch with: + ```{code-block} text multipass launch \ --name minikube \ @@ -85,7 +102,9 @@ multipass launch \ --timeout 1800 \ --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-minikube.yaml ``` + Health check: + ```{code-block} text multipass exec minikube -- bash -c "set -e minikube status @@ -93,7 +112,9 @@ multipass exec minikube -- bash -c "set -e ``` ## 🤖 ros2-humble + Launch with: + ```{code-block} text multipass launch 22.04 \ --name ros2-humble \ @@ -103,7 +124,9 @@ multipass launch 22.04 \ --timeout 1800 \ --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-ros2-humble.yaml ``` + Heath check: + ```{code-block} text multipass exec ros2-humble -- bash -c " set -e @@ -116,8 +139,11 @@ multipass exec ros2-humble -- bash -c " ls /opt/ros/humble " ``` + ## 🤖 ros2-jazzy + Launch with: + ```{code-block} text multipass launch 24.04 \ --name ros2-jazzy \ @@ -127,7 +153,9 @@ multipass launch 24.04 \ --timeout 1800 \ --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-ros2-jazzy.yaml ``` + Health check: + ```{code-block} text multipass exec ros2-jazzy -- bash -c " set -e diff --git a/docs/how-to-guides/manage-instances/modify-an-instance.md b/docs/how-to-guides/manage-instances/modify-an-instance.md index 6eec11d2f41..d155943b2bf 100644 --- a/docs/how-to-guides/manage-instances/modify-an-instance.md +++ b/docs/how-to-guides/manage-instances/modify-an-instance.md @@ -1,18 +1,18 @@ (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/index) +> 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 customise an instance outside of the [`launch`](/reference/command-line-interface/launch) command using the Multipass [settings](/reference/settings/index). +This document shows further ways to customise an instance outside of the [`launch`](reference-command-line-interface-launch) command using the Multipass [settings](reference-settings-index). (set-the-cpu-ram-or-disk-of-an-instance)= ## Set the CPUs , RAM or disk space of an instance -> See also: [`local..cpus`](/reference/settings/local-instance-name-cpus), [`local..disk)`](/reference/settings/local-instance-name-disk), [`local..memory`](/reference/settings/local-instance-name-memory) +> See also: [`local..cpus`](reference-settings-local-instance-name-cpus), [`local..disk)`](reference-settings-local-instance-name-disk), [`local..memory`](reference-settings-local-instance-name-memory) You can set instance properties at `launch` time, but you can also update some of them after the instance has been created. Specifically, an instance’s memory, disk space, and the number of its CPUs are exposed via daemon settings: `local..(cpus|disk|memory)`. -To modify one of this properties, first stop the instance and then issue the [`set`](/reference/command-line-interface/set) command. For example: +To modify one of this properties, first stop the instance and then issue the [`set`](reference-command-line-interface-set) command. For example: ```{code-block} text multipass stop handsome-ling @@ -63,7 +63,7 @@ Modifying instance settings is not supported when using the Hyperkit driver, whi ## Set the status of an instance to primary -> See also: [client.primary-name](/reference/settings/client-primary-name) +> See also: [client.primary-name](reference-settings-client-primary-name) This section demonstrates how to set the status of an instance to primary. This is convenient because it makes this instance the default argument for several commands, such as `shell` , `start` , `stop` , `restart` and `suspend`, and also automatically mounts your $HOME directory into the instance. diff --git a/docs/how-to-guides/manage-instances/remove-an-instance.md b/docs/how-to-guides/manage-instances/remove-an-instance.md index 7fdc0b51045..38912805e1f 100644 --- a/docs/how-to-guides/manage-instances/remove-an-instance.md +++ b/docs/how-to-guides/manage-instances/remove-an-instance.md @@ -1,13 +1,13 @@ (how-to-guides-manage-instances-remove-an-instance)= # Remove an instance -> See also: [Instance](/explanation/instance) +> See also: [Instance](explanation-instance) This guide demonstrates how to remove an instance, either temporarily or permanently. ## Move an instance to the recycle bin -> See also: [`delete`](/reference/command-line-interface/launch), [`recover`](/reference/command-line-interface/recover) +> See also: [`delete`](reference-command-line-interface-delete), [`recover`](reference-command-line-interface-recover) To mark an instance as deleted, run: @@ -43,7 +43,7 @@ keen-yak STOPPED -- Ubuntu 18.04 LTS ## Remove an instance permanently -> See also: [`delete`](/reference/command-line-interface/launch), [`purge`](/reference/command-line-interface/purge) +> See also: [`delete`](reference-command-line-interface-delete), [`purge`](reference-command-line-interface-purge) If you want to get rid of all instances in `Deleted` status for good, you can purge them: diff --git a/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md b/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md index 0552ce1992a..760c765c317 100644 --- a/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md +++ b/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md @@ -1,7 +1,8 @@ (how-to-guides-manage-instances-run-a-docker-container-in-multipass)= # Run a Docker container in Multipass + ```{Warning} -Blueprints are deprecated and will be removed in a future release. You can achieve similar effects with cloud-init and other launch options. Find out more at: [Launch customized instances with Multipass and cloud-init](/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init) +Blueprints are deprecated and will be removed in a future release. You can achieve similar effects with cloud-init and other launch options. Find out more at: [Launch customized instances with Multipass and cloud-init](how-to-guides-manage-instances-launch-customized-instances-with-multipass-and-cloud-init) ``` @@ -36,7 +37,7 @@ In this tutorial, you will see how to get started with the Docker blueprint by c *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). +Let's start by installing Multipass on your machine, following the steps in [How to install Multipass](how-to-guides-install-multipass). * dnscrypt-proxy/dnscrypt-wrapper/cloudflared-proxy \ The default configuration binds to localhost port 53, clashing with Internet Sharing. * Another `dnsmasq` process bound to localhost port 53 -* Custom DHCP server bound to port 67? ("sudo lsof -iUDP:67 -n -P" should show launchd & bootpd only) +* Custom DHCP server bound to port 67? (`sudo lsof -iUDP:67 -n -P` should show `launchd` & `bootpd` only) * macOS updates can make changes to the firewall and leave instances in unknown state; see {ref}`troubleshoot-networking-issues-caused-by-macos-update` below. ### Problem class @@ -59,9 +59,9 @@ The default configuration binds to localhost port 53, clashing with Internet Sha 1. Is Firewall enabled? 1. If so it must not "Block all incoming connections" * Blocking all incoming connections prevents a DHCP server from running locally, to give an IP to the instance. - * It’s OK to block incoming connections to "multipassd" however. + * It’s OK to block incoming connections to `"multipassd"` however. 1. VPN -1. Little Snitch - defaults are good, it should permit mDNSResponder and bootpd access to BPF +1. Little Snitch - defaults are good, it should permit `mDNSResponder` and `bootpd` access to BPF If you're having trouble downloading images and/or see `Unknown error`s when trying to `multipass launch -vvv`, Little Snitch may be interfering with `multipassd`'s network access (ref. [#1169](https://github.com/canonical/multipass/issues/1169)) 1. Internet Sharing - doesn’t usually clash @@ -85,7 +85,7 @@ Maybe `-static` route helps? If using Cisco AnyConnect, try using OpenConnect (`brew install openconnect`) instead as it messes with routes less (but your company sysadmin/policy may not permit/authorise this). -* It monitors the routing table so may prevent any customisation. Here is [a very hacky workaround](https://unix.stackexchange.com/questions/106304/route-add-no-longer-works-when-i-connected-to-vpn-via-cisco-anyconnect-client/501094#501094). +* It monitors the routing table so may prevent any customisation. Here is [a very handy but non-standard workaround](https://unix.stackexchange.com/questions/106304/route-add-no-longer-works-when-i-connected-to-vpn-via-cisco-anyconnect-client/501094#501094). Does your VPN software provide a "split connection" option, where VPN sysadmin can designate a range of IP addresses to **not** be routed through the VPN? * Cisco does @@ -109,11 +109,11 @@ sudo pfctl -f /etc/pf.conf #### Configure Multipass to use a different subnet -Edit `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist` to change the "Shared_Net_Address" value to something other than `192.168.64.1 -`. -* it works if you edit the plist file and stay inside 192.168 range, as Multipass hardcoded for this +Edit `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist` to change the `"Shared_Net_Address"` value to something other than `192.168.64.1 -`. +* it works if you edit the `plist` file and stay inside 192.168 range, as Multipass hard-coded for this ```{note} -If you change the subnet and launch an instance, it will get an IP from that new subnet. But if you try changing it back, the change is reverted on next instance start. It appears that the DHCP server reads the last IP in `/var/db/dhcpd_leases`, decides the subnet from that, and updates Shared_Net_Address to match. So, the only way to really revert this change is to edit or delete `/var/db/dhcpd_leases`. +If you change the subnet and launch an instance, it will get an IP from that new subnet. But if you try changing it back, the change is reverted on next instance start. It appears that the DHCP server reads the last IP in `/var/db/dhcpd_leases`, decides the subnet from that, and updates `Shared_Net_Address` to match. So, the only way to really revert this change is to edit or delete `/var/db/dhcpd_leases`. ``` (troubleshoot-networking-dns-problems)= @@ -233,9 +233,9 @@ google.ie. 39 IN A 74.125.193.94 This implies the problem is with the macOS **Internet Sharing** feature---for some reason, its built-in DNS server is broken. -The built-in DNS server should be "mDNSResponder", which binds to localhost on port 53. +The built-in DNS server should be `"mDNSResponder"`, which binds to localhost on port 53. -If using Little Snitch or another per-process firewall, ensure mDNSResponder can establish outgoing connections. The macOS’s built-in firewall should not interfere with it. +If using Little Snitch or another per-process firewall, ensure `mDNSResponder` can establish outgoing connections. The macOS’s built-in firewall should not interfere with it. Check what is bound to that port on the host with: @@ -281,7 +281,7 @@ This means that applications that rely on additional IP addresses, such as [meta When upgrading macOS to 12.4 (this might happen however also when upgrading to other versions), macOS makes changes to the firewall. If the instances are not stopped before the update, it is possible the connection to the instances are blocked by the macOS firewall. We cannot know what is exactly the change introduced to the firewall, it seems the Apple's `bootpd` stops replying DHCP requests. -There are some procedures that can help to overcome this issue (see [issue #2387](https://github.com/canonical/multipass/issues/2387) on the Multipass GitHub repo for a discussion on this and some alternative solutions). First, you can try to: +There are some procedures that can help to overcome this issue (see [issue #2387](https://github.com/canonical/multipass/issues/2387) on the Multipass GitHub repository for a discussion on this and some alternative solutions). First, you can try to: * Reboot the computer. * Disable and then re-enable Internet sharing and/or the firewall. @@ -329,6 +329,26 @@ Using Administrator privileges, edit the file `C:\WINDOWS\System32\drivers\etc\h Anti-virus and network security software are not necessarily virtualisation-aware. If you’re having issues with connectivity, temporarily disabling this software to test can result in a positive outcome. Examples of this software are Symantec, ESET, Kaspersky and Malware Bytes. + +#### Wi-Fi upload speed degrading when using external switch with Hyper-V + +If you're using Multipass on Windows and have created an External Switch connected to your Wi-Fi adapter in Hyper-V, you may notice your upload speeds degrade severely, often dropping to around 1 Mbit/s. This issue is due to a long-standing limitation in Windows networking, where certain offload features interfere with Hyper-V’s virtual networking performance. Fortunately, there’s a reliable workaround to restore your original speeds. + +##### Workaround + +The following steps will help you disable the Large Send Offload feature for the Hyper-V virtual ethernet adapter, which should resolve the upload speed issue: + +1. Open Device Manager. +2. Expand Network Adapters. +3. Find the entry named Hyper-V Virtual Ethernet Adapter #N (Where “N” is the one connected to Wi-Fi). +4. Right-click > Properties. +5. Go to the Advanced tab. +6. Locate and disable both of the following: + * Large Send Offload v2 (IPv4) + * Large Send Offload v2 (IPv6) +7. Click OK and restart your networking or your machine if needed + + diff --git a/docs/images/multipass-reference-architecture.jpg b/docs/images/multipass-reference-architecture.jpg new file mode 100644 index 00000000000..4c0d636ac85 Binary files /dev/null and b/docs/images/multipass-reference-architecture.jpg differ diff --git a/docs/index.md b/docs/index.md index 298d2b7b713..ef45caf6a5e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,11 +22,76 @@ Developers can use Multipass to prototype cloud deployments and to create fresh, ## In this documentation -| | | -|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| -| [Tutorial](/tutorial/index)
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 | +### Basics +Start here to install and launch your first Multipass instance. + +- Tutorial: [Getting stated with Multipass](tutorial-index) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) + +### Using Multipass + +Learn the complete lifecycle of a virtual machine. + +- **Instance management:** [Create an instance](how-to-guides-manage-instances-create-an-instance) • [Use an instance](how-to-guides-manage-instances-use-an-instance) • [Modify an instance](how-to-guides-manage-instances-modify-an-instance) • [Use the primary instance](how-to-guides-manage-instances-use-the-primary-instance) • [Use instance command aliases](how-to-guides-manage-instances-use-instance-command-aliases) • [Remove an instance](how-to-guides-manage-instances-remove-an-instance) + +- **Instance customization:** [`cloud-init`](how-to-guides-manage-instances-launch-customized-instances-with-multipass-and-cloud-init) • [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) • +[Run a Docker container in Multipass](how-to-guides-manage-instances-run-a-docker-container-in-multipass) + +- **Interfaces (CLI/GUI):** [Command-line interface](reference-command-line-interface-index) • [GUI client](reference-gui-client) • [Use a different terminal from the system icon](how-to-guides-customise-multipass-use-a-different-terminal-from-the-system-icon) • [How to integrate with Windows Terminal](how-to-guides-customise-multipass-integrate-with-windows-terminal) + +- **Troubleshooting:** [Access logs](how-to-guides-troubleshoot-access-logs) • [Troubleshoot launch/start issues](how-to-guides-troubleshoot-troubleshoot-launch-start-issues) + +### Understanding Multipass + +- **Core concepts:** [Instance](explanation-instance) • [Image](explanation-image) • [Snapshot](explanation-snapshot) • [Alias](explanation-alias) • [Service](explanation-service) • [Multipass exec and shells](explanation-multipass-exec-and-shells) • [ID mapping](explanation-id-mapping) • [Reference architecture](explanation-reference-architecture) + +- **Virtualization:** [Driver](explanation-driver) • [How to 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) • [Platform](explanation-platform) • [Host](explanation-host) + +- **Configuration:** [Settings](reference-settings-index) • [Settings keys and values](explanation-settings-keys-values) • [Logging levels](reference-logging-levels) • [Configure Multipass's default logging level](how-to-guides-customise-multipass-configure-multipass-default-logging-level) • [Instance name format](reference-instance-name-format) • [Instance states](reference-instance-states) + +### Resources and networking + +- **Storage:** [Share data with an instance](how-to-guides-manage-instances-share-data-with-an-instance) • [Configure where Multipass stores external data](how-to-guides-customise-multipass-configure-where-multipass-stores-external-data) • [Mount](explanation-mount) • [Mount an encrypted home folder](how-to-guides-troubleshoot-mount-an-encrypted-home-folder) + +- **Networking:** [Add a network to an existing instance](how-to-guides-manage-instances-add-a-network-to-an-existing-instance) • [Configure static IPs](how-to-guides-manage-instances-configure-static-ips) • [Troubleshoot networking](how-to-guides-troubleshoot-troubleshoot-networking) + +### Security and performance + +- **Security:** [Authenticate users with the Multipass service](how-to-guides-customise-multipass-authenticate-users-with-the-multipass-service) • [Authentication](explanation-authentication) • [About security](explanation-about-security) + +- **Performance:** [About performance](explanation-about-performance) + + +## How this documentation is organized + +````{grid} 1 1 2 2 + +```{grid-item-card} [Tutorial](tutorial/index) + +**Get started:** a hands-on introduction to Multipass for new users +``` + +```{grid-item-card} [How-to guides](how-to-guides/index) + +**Step-by-step guides** covering key operations and common tasks +``` + +```` + +````{grid} 1 1 2 2 +:reverse: + +```{grid-item-card} [Reference](reference/index) + +**Technical information** - specifications, APIs, architecture +``` + +```{grid-item-card} [Explanation](explanation/index) + +**Concepts** - discussion and clarification of key topics +``` + +```` --- ## Project and community @@ -34,7 +99,7 @@ Developers can use Multipass to prototype cloud deployments and to create fresh, We value your input and contributions! Here are some ways you can join our community or get help with your Multipass questions: * Read our [Code of Conduct](https://ubuntu.com/community/code-of-conduct) -* Read our quick guide: [Contribute to Multipass docs](./contribute-to-multipass-docs) +* Read our quick guide: {ref}`contribute-to-multipass-docs` * Join the [Discourse forum](https://discourse.ubuntu.com/c/project/multipass/21/) * Report an issue or contribute to the code on [GitHub](https://github.com/canonical/multipass/issues) @@ -49,5 +114,6 @@ tutorial/index how-to-guides/index reference/index explanation/index +reference/release-notes/index contribute-to-multipass-docs ``` diff --git a/docs/reference/command-line-interface/alias.md b/docs/reference/command-line-interface/alias.md index f2d1d7214cf..225e446d595 100644 --- a/docs/reference/command-line-interface/alias.md +++ b/docs/reference/command-line-interface/alias.md @@ -1,7 +1,7 @@ (reference-command-line-interface-alias)= # alias -> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases). +> See also: [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: diff --git a/docs/reference/command-line-interface/aliases.md b/docs/reference/command-line-interface/aliases.md index 9dc06e3ae3d..d50984e304f 100644 --- a/docs/reference/command-line-interface/aliases.md +++ b/docs/reference/command-line-interface/aliases.md @@ -1,7 +1,7 @@ (reference-command-line-interface-aliases)= # aliases -> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) +> See also: [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. diff --git a/docs/reference/command-line-interface/authenticate.md b/docs/reference/command-line-interface/authenticate.md index ac954eee31a..c6599a52ee4 100644 --- a/docs/reference/command-line-interface/authenticate.md +++ b/docs/reference/command-line-interface/authenticate.md @@ -1,9 +1,9 @@ (reference-command-line-interface-authenticate)= # 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) +> See also: [Authentication](/explanation/authentication), [How to authenticate users with the Multipass service](how-to-guides-customise-multipass-authenticate-users-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. +The `authenticate` command is used to authenticate a user with the Multipass service. Once authenticated, the user 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: diff --git a/docs/reference/command-line-interface/prefer.md b/docs/reference/command-line-interface/prefer.md index 288ec7f2c7e..27ae4a7e162 100644 --- a/docs/reference/command-line-interface/prefer.md +++ b/docs/reference/command-line-interface/prefer.md @@ -1,7 +1,7 @@ (reference-command-line-interface-prefer)= # prefer -> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) +> See also: [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) The `prefer` command, introduced in Multipass release 1.11.0, is used to switch alias contexts. It accepts a single argument, specifying the name of the context to switch to. diff --git a/docs/reference/command-line-interface/unalias.md b/docs/reference/command-line-interface/unalias.md index 29bca5094b3..a5f2101cd17 100644 --- a/docs/reference/command-line-interface/unalias.md +++ b/docs/reference/command-line-interface/unalias.md @@ -1,7 +1,7 @@ (reference-command-line-interface-unalias)= # unalias -> See also: [`alias`](/reference/command-line-interface/alias), [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) +> See also: [`alias`](/reference/command-line-interface/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases) The `multipass unalias` command removes a previously defined alias. diff --git a/docs/reference/release-notes/1.16.0.md b/docs/reference/release-notes/1.16.0.md new file mode 100644 index 00000000000..84f8bb955b7 --- /dev/null +++ b/docs/reference/release-notes/1.16.0.md @@ -0,0 +1,61 @@ +--- +orphan: true +--- + +(1.16.0)= +# 1.16.0 + +These release notes cover new features and changes in Multipass 1.16.0. + +We're pleased to announce Multipass 1.16.0, where the entire code base became fully open source! This is a consolidation release, bringing a ton of improvements to our GUI, fixes to the Multipass daemon/service, as well as important security enhancements. + +## New features and improvements + +### Fully open source + +Previously proprietary bits for Windows and macOS are now unified within [canonical/multipass](https://github.com/canonical/multipass). + +### Custom image launch + +Custom image launch is now supported on macOS and Windows too (with `file://` or `https://` URLs). + +### GUI improvements + +* Facilitate reusing launch configurations with a button to "Launch and configure next" +* Support zoom in the terminal (use Ctrl or ⌘ together with +, -, or 0) +* Start VMs with the "Open shell" button +* Remember window size + better default sizes + +### Other improvements + +* Support the QEMU driver on ARM Linux hosts +* Improve copy-paste support +* Improve gRPC security with standard mTLS +* Update almost all our dependencies and move some more to vcpkg +* {ref}`index` documentation has been migrated to ReadTheDocs and included in [this repository](https://github.com/canonical/multipass/tree/main/docs). + +## Deprecations + +* LXD and libvirt drivers are being deprecated, along with [blueprints](explanation-blueprint). The plan is to remove them in the next feature release. +* This is also likely to be the last release that will support macOS 13. + +## Bug fixes + +* Fix 5 different crash conditions ([#3978](https://github.com/canonical/multipass/pull/3978), [#4004](https://github.com/canonical/multipass/pull/4004), [#4006](https://github.com/canonical/multipass/pull/4006), [#4010](https://github.com/canonical/multipass/pull/4010), [#4016](https://github.com/canonical/multipass/pull/4016)) +* Fix issues with mounts, file transfer, and SSH ([#3902](https://github.com/canonical/multipass/pull/3902), [#3971](https://github.com/canonical/multipass/pull/3971), [#3959](https://github.com/canonical/multipass/pull/3959), [#4007](https://github.com/canonical/multipass/pull/4007)) + +## New contributors + +Special thanks to our new contributors :wink: + +* @Artem-OSSRevival made their first contribution in https://github.com/canonical/multipass/pull/4138 +* [@didrocks](https://github.com/didrocks) made their first contribution in https://github.com/canonical/multipass/pull/3931 +* [@xmkg](https://github.com/xmkg) made their first contribution in https://github.com/canonical/multipass/pull/4058 +* [@network-charles](https://github.com/network-charles) made their first contribution in https://github.com/canonical/multipass/pull/4051 +* [@ntorresalberto](https://github.com/ntorresalberto) made their first contribution in https://github.com/canonical/multipass/pull/3904 +* [@rico33631](https://github.com/rico33631) made their first contribution in https://github.com/canonical/multipass/pull/3880 +* [@rshrj](https://github.com/rshrj) made their first contribution in https://github.com/canonical/multipass/pull/4012 + +## Feedback + +Please file issues on the [Multipass GitHub](https://github.com/canonical/multipass/issues/new/choose) for problems and feature requests, or join the [Multipass Discourse forum](https://discourse.ubuntu.com/c/project/multipass) to chat. You can also find us in the [Multipass room on Matrix](https://matrix.to/#/#multipass:ubuntu.com). diff --git a/docs/reference/release-notes/1.16.1.md b/docs/reference/release-notes/1.16.1.md new file mode 100644 index 00000000000..a7b04769b57 --- /dev/null +++ b/docs/reference/release-notes/1.16.1.md @@ -0,0 +1,22 @@ +--- +orphan: true +--- + +(1.16.1)= +# 1.16.1 + +A patch release fixing issues with certificates and external directories, as well as in mounts: + + +## New features & improvements + +- [multipassd] regenerate gRPC server certificate on root ca mismatch ([#4218](https://github.com/canonical/multipass/pull/4218)) +- Certificates inaccessible when MULTIPASS_STORAGE is set ([#4246](https://github.com/canonical/multipass/pull/4246)) +- [sshfs-mount] make `chown` return 0 on Windows ([#4288](https://github.com/canonical/multipass/pull/4288)) + +See also the [v1.16.1](https://github.com/canonical/multipass/milestone/34?closed=1) milestone and the full diff: https://github.com/canonical/multipass/compare/v1.16.0...v1.16.1 + + +## Feedback + +Please file issues on the [Multipass GitHub](https://github.com/canonical/multipass/issues/new/choose) for problems and feature requests, or join the [Multipass Discourse forum](https://discourse.ubuntu.com/c/project/multipass) to chat. You can also find us in the [Multipass room on Matrix](https://matrix.to/#/#multipass:ubuntu.com). diff --git a/docs/reference/release-notes/index.md b/docs/reference/release-notes/index.md new file mode 100644 index 00000000000..8ae7b6dd0d1 --- /dev/null +++ b/docs/reference/release-notes/index.md @@ -0,0 +1,81 @@ +(reference-release-notes)= +# Release notes + +This page outlines the release notes of all versions of Multipass. If you're interested in getting notified for the latest Multipass releases, subscribe to the [Multipass category](https://discourse.ubuntu.com/c/project/multipass/21/none) on the Ubuntu discourse. + +For detailed release information, see the [Multipass releases page](https://github.com/canonical/multipass/releases) on GitHub. + +## Recent releases + +```{admonition} Support for Multipass releases +:class: note +Only the most recent release of Multipass is actively supported. Users are encouraged to [upgrade](how-to-guides-install-multipass-upgrade) to the latest version to receive new features, security updates and bug fixes. +``` + +| Release date | Release notes | +|----|----| +| August 27, 2025 | [Multipass 1.16.1](./1.16.1) | +| July 10, 2025 | [Multipass 1.16.0](./1.16.0) | + + +### What's new in 1.16.x? + +Along with bug fixes and general improvements, Multipass 1.16.x includes: + +* Enhanced networking capabilities +* Improved instance management +* Performance optimizations +* Updated cloud-init support +* Bug fixes and stability improvements + + +## Release and support policy + +Multipass follows a defined release cycle with regular releases. + +Minor releases +: A new minor release of Multipass is released approximately every 6 months. It includes new features and bug fixes. + +Patch releases +: A patch release for Multipass is released as needed and includes critical bug fixes and security updates. + +To ensure that you receive the latest security updates and bug fixes, you should upgrade to a new release of Multipass shortly after it is released. + + +
Click to view earlier release notes + +| Release date | Release notes | +|----|----| +| February 26, 2025 | [Multipass 1.15.1](https://github.com/canonical/multipass/releases/tag/v1.15.1) | +| December 11, 2024 | [Multipass 1.15.0](https://github.com/canonical/multipass/releases/tag/v1.15.0) | +| October 17, 2024 | [Multipass 1.14.1](https://github.com/canonical/multipass/releases/tag/v1.14.1) | +| July 24, 2024 | [Multipass 1.14.0](https://github.com/canonical/multipass/releases/tag/v1.14.0) | +| February 12, 2024 | [Multipass 1.13.1](https://github.com/canonical/multipass/releases/tag/v1.13.1) | +| April 2, 2025 | [Multipass 1.13.0](https://github.com/canonical/multipass/releases/tag/v1.13.0) | +| October 1, 2024 | [Multipass 1.12.2](https://github.com/canonical/multipass/releases/tag/v1.12.2) | +| April 25, 2024 | [Multipass 1.12.1](https://github.com/canonical/multipass/releases/tag/v1.12.1) | +| February 23, 2024 | [Multipass 1.12.0](https://github.com/canonical/multipass/releases/tag/v1.12.0) | +| November 6, 2023 | [Multipass 1.11.1](https://github.com/canonical/multipass/releases/tag/v1.11.1) | +| August 29, 2023 | [Multipass 1.11.0](https://github.com/canonical/multipass/releases/tag/v1.11.0) | +| March 17, 2023 | [Multipass 1.10.1](https://github.com/canonical/multipass/releases/tag/v1.10.1) | +| September 30, 2022 | [Multipass 1.10.0](https://github.com/canonical/multipass/releases/tag/v1.10.0) | +| July 22, 2022 | [Multipass 1.9.2](https://github.com/canonical/multipass/releases/tag/v1.9.2) | +| June 7, 2022 | [Multipass 1.9.1](https://github.com/canonical/multipass/releases/tag/v1.9.1) | +| May 26, 2022 | [Multipass 1.9.0](https://github.com/canonical/multipass/releases/tag/v1.9.0) | +| March 4, 2022 | [Multipass 1.8.1](https://github.com/canonical/multipass/releases/tag/v1.8.1) | +| December 21, 2021 | [Multipass 1.8.0](https://github.com/canonical/multipass/releases/tag/v1.8.0) | +| September 22, 2021 | [Multipass 1.7.2](https://github.com/canonical/multipass/releases/tag/v1.7.2) | +| September 13, 2021 | [Multipass 1.7.1](https://github.com/canonical/multipass/releases/tag/v1.7.1) | +| August 3, 2021 | [Multipass 1.7.0](https://github.com/canonical/multipass/releases/tag/v1.7.0) | +| May 7, 2021 | [Multipass 1.6.2](https://github.com/canonical/multipass/releases/tag/v1.6.2) | +| March 11, 2021 | [Multipass 1.6.1](https://github.com/canonical/multipass/releases/tag/v1.6.1) | +| February 12, 2021 | [Multipass 1.6.0](https://github.com/canonical/multipass/releases/tag/v1.6.0) | +| December 18, 2020 | [Multipass 1.5.0](https://github.com/canonical/multipass/releases/tag/v1.5.0) | +| September 18, 2020 | [Multipass 1.4.0](https://github.com/canonical/multipass/releases/tag/v1.4.0) | +| July 31, 2020 | [Multipass 1.3.0](https://github.com/canonical/multipass/releases/tag/v1.3.0) | +| April 22, 2020 | [Multipass 1.2.1](https://github.com/canonical/multipass/releases/tag/v1.2.1) | +| April 3, 2020 | [Multipass 1.2.0](https://github.com/canonical/multipass/releases/tag/v1.2.0) | +| March 13, 2020 | [Multipass 1.1.0](https://github.com/canonical/multipass/releases/tag/v1.1.0) | +| January 17, 2020 | [Multipass 1.0.0](https://github.com/canonical/multipass/releases/tag/v1.0.0) | + +
diff --git a/docs/reference/release-notes/release-notes-templates.md b/docs/reference/release-notes/release-notes-templates.md new file mode 100644 index 00000000000..2fd3ff720ae --- /dev/null +++ b/docs/reference/release-notes/release-notes-templates.md @@ -0,0 +1,36 @@ +--- +orphan: true +--- +# < Release version > + +These release notes cover new features and changes in Multipass < version >. + +< Include a brief description of the release here. Mention if it's a minor or patch release, and highlight key changes or themes of the release. > + +## New features & improvements + +< List features here as sub sections> + +## Removed functionality + +< List features that were part of Multipass so far or that were on the deprecation path for a while and have been removed for the current release > + +## Deprecations + +< List deprecated features. Provide an alternative, if any, for the users to use instead of the deprecated features > + +## Known issues + +< List known issues with the current release. Include plans to fix it, if known. > + +## Bug fixes + +< Describe bug fixes in 1-2 lines. Include links to relevant PRs or issues, if any. > + +## New contributors + +< Acknowledge new contributors to the project. Include their GitHub handles and links to their first contributions/PRs. > + +## Feedback + +Please file issues on the [Multipass GitHub](https://github.com/canonical/multipass/issues/new/choose) for problems and feature requests, or join the [Multipass Discourse forum](https://discourse.ubuntu.com/c/project/multipass) to chat. You can also find us in the [Multipass room on Matrix](https://matrix.to/#/#multipass:ubuntu.com). diff --git a/docs/reference/settings/local-passphrase.md b/docs/reference/settings/local-passphrase.md index 5d9380d4274..93a502c749b 100644 --- a/docs/reference/settings/local-passphrase.md +++ b/docs/reference/settings/local-passphrase.md @@ -9,7 +9,7 @@ ## Description -Passphrase used by clients requesting access to the Multipass service via the [`authenticate`](/reference/command-line-interface/authenticate) command. +Passphrase to authenticate users with the Multipass service, via the [`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. diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index f0de52dec38..cb65a435ea2 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -17,9 +17,10 @@ Select the tab corresponding to your operating system (e.g. Linux) to display th ## Create and use a basic instance -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux Start Multipass from the application launcher. In Ubuntu, press the super key and type "Multipass", or find Multipass in the Applications panel on the lower left of the desktop. @@ -127,7 +128,8 @@ This folder could be a great place to keep files that need to be accessed by bot ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS Start Multipass from the application launcher. In macOS, open the application launcher, type "Multipass", and launch the application. @@ -221,7 +223,8 @@ ubuntu@primary:~/Home/Multipass_Files$ ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows Start Multipass from the application launcher. Press the Windows key and type "Multipass", then launch the application. @@ -359,9 +362,10 @@ minikube latest minikube is local Launch an instance running Ubuntu 22.10 ("Kinetic Kudu") by typing the `multipass launch kinetic` command. -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". @@ -395,7 +399,8 @@ You can now launch the type of instance you need by running this command: ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "breezy-liger". @@ -429,7 +434,8 @@ You can now launch the type of instance you need by running this command: ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "decorous-skate". @@ -469,9 +475,10 @@ You can now launch the type of instance you need by running this command: You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux ```{code-block} text $ multipass info ltsInstance @@ -508,7 +515,8 @@ ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS ```{code-block} text $ multipass info ltsInstance @@ -545,7 +553,8 @@ ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows ```{code-block} text C:\WINDOWS\system32> multipass info ltsInstance @@ -610,9 +619,10 @@ sudo apt install apache2 Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage. -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux ```{figure} /images/tutorial/mp-linux-4.png :width: 720px @@ -625,7 +635,8 @@ Open a browser and type in the IP address of your instance into the address bar. ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS ```{figure} /images/tutorial/mp-macos-5.png :width: 720px @@ -638,7 +649,8 @@ Open a browser and type in the IP address of your instance into the address bar. ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows ```{figure} /images/tutorial/mp-windows-12.png :width: 720px @@ -668,9 +680,10 @@ You can launch an instance using the Docker Blueprint by running `multipass laun Once that's done, run `multipass info docker-dev` to note down the IP of the new instance. -`````{tabs} +`````{tab-set} -````{group-tab} Linux +````{tab-item} Linux +:sync: Linux ```{code-block} text $ multipass launch docker --name docker-dev @@ -735,7 +748,8 @@ From the Portainer dashboard, you can see the ports available on nginx. To verif ```` -````{group-tab} macOS +````{tab-item} macOS +:sync: macOS ```{code-block} text $ multipass launch docker --name docker-dev @@ -800,7 +814,8 @@ From the Portainer dashboard, you can see the ports available on nginx. To verif ```` -````{group-tab} Windows +````{tab-item} Windows +:sync: Windows ```{code-block} text C:\WINDOWS\system32> multipass launch docker --name docker-dev