Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-06 05:34:27 -04:00
Code Issues Projects Releases Packages Wiki Activity

Minor changes in how-to-install-software

Browse source
This commit is contained in:
unman 2025-05-15 11:07:17 +00:00
commit aa62d0b296
No known key found for this signature in database
GPG key ID: BB52274595B71262
45 changed files with 1498 additions and 553 deletions
Download patch file Download diff file Expand all files Collapse all files

4
user/templates/debian/debian.md
View file

@ -60,7 +60,9 @@ This section contains notes about specific Debian releases.
### Debian 12
If you want to use a Debian 12 template for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded.
The Debian-12 templates that ship with release 4.2.4 cannot be used for salting Fedora templates. You must change the template used by `default-mgmt-dvm` to a Fedora template. You can do this in the Qubes Template Switcher tool, or at the command line using `qvm-prefs default-mgmt-dvm template`.
If you have a Debian template from an earlier release that you want to use for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded.
Do this by marking these packages on hold *before* updating the template.
```

73
user/templates/minimal-templates.md
View file

@ -55,7 +55,6 @@ Minimal templates of the following distros are available:
- Fedora
- Debian
- CentOS
- Gentoo
A list of all available templates can also be obtained with the [Template Manager](/doc/template-manager/) tool.
@ -305,75 +304,3 @@ Documentation on all of these can be found in the [docs](/doc/).
You could, of course, use `qubes-vm-recommended` to automatically install many
of these, but in that case you are well on the way to a standard Debian
template.
### CentOS
The following list provides an overview of which packages are needed for which
purpose. As usual, the required packages are to be installed in the running
template with the following command (replace `packages` with a space-delimited
list of packages to be installed):
```
[user@your-new-clone ~]$ sudo yum install packages
```
- Commonly used utilities: `pciutils` `vim-minimal` `less` `psmisc`
`gnome-keyring`
- Audio: `pulseaudio-qubes`.
- Networking: `qubes-core-agent-networking`, and whatever network tools
you want. N.B. minimal templates do not include any browser.
- [FirewallVM](/doc/firewall/), such as the template for `sys-firewall`: at
least `qubes-core-agent-networking`, and also `qubes-core-agent-dom0-updates`
if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking`
`qubes-core-agent-network-manager` `NetworkManager-wifi`
`network-manager-applet` `notification-daemon`
`gnome-keyring`. If your network devices need extra packages for a network
VM, use the `lspci` command to identify the devices, then find the package
that provides necessary firnware and install it. If you need utilities for
debugging and analyzing network connections, install the following packages:
`tcpdump` `telnet` `nmap` `nmap-ncat`
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`:
`qubes-usb-proxy` to provide USB devices to other Qubes and
`qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- [VPN
qube](https://forum.qubes-os.org/t/19061):
You may need to install network-manager VPN packages, depending on the VPN
technology you'll be using. After creating a machine based on this template,
follow the [VPN
howto](https://forum.qubes-os.org/t/19061#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
to configure it.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be
needed to make the customized minimal template work properly. These packages
are:
- `qubes-core-agent-nautilus`: This package provides integration with the
Nautilus file manager (without it, items like "copy to VM/open in disposable"
will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar
file manager (without it, items like "copy to VM/open in disposable" will not
be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates.
Any template on which the qube responsible for 'dom0' updates (e.g.
`sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop
experience.
Also, there are packages to provide additional services:
- `qubes-gpg-split`: For implementing split GPG.
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-img-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
- `qubes-mgmt-salt-vm-connector`: If you want to use salt management on the
template and qubes.
Documentation on all of these can be found in the [docs](/doc/).
You could, of course, use `qubes-vm-recommended` to automatically install many
of these, but in that case you are well on the way to a standard Debian
template.

77
user/templates/templates.md
View file

@ -78,10 +78,15 @@ developers do not test them.
* [Whonix](/doc/templates/whonix/)
* [Ubuntu](/doc/templates/ubuntu/)
* [Arch Linux](/doc/building-archlinux-template/)
* [CentOS](/doc/templates/centos/)
* [CentOS Minimal](/doc/templates/minimal/)
* [Gentoo](/doc/templates/gentoo/)
* [Gentoo Minimal](/doc/templates/minimal/)
* [CentOS*](/doc/templates/centos)
*\* The CentOS version used by this template reached
[End-of-Life in June 2024](https://en.wikipedia.org/wiki/CentOS_Stream#Release_history)
and is no longer receiving updates. Due to a lack of specific interest
at this time a proposal to create a new CentOS 10 template was
[declined](https://github.com/QubesOS/qubes-issues/issues/9716).*
## Windows
@ -153,68 +158,21 @@ Please see [How to Install Software](/doc/how-to-install-software).
## Uninstalling
If you want to remove a template you must make sure that it is not being used.
You should check that the template is not being used by any qubes,
and also that it is not set as the default template.
The procedure for uninstalling a template depends on how it was created.
If the template was originaly created by cloning another template, then you can
delete it the same way as you would any other qube. In the Qube Manager,
right-click on the template and select **Delete qube**. (If you're not sure,
you can safely try this method first to see if it works.)
If, on the other hand, the template came pre-installed or was installed by
installing a template package in dom0, per the instructions
[above](#installing), then you must execute the following type of command in
dom0 in order to uninstall it:
To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal. If no issues are found, a dialog box will request the template's name be typed as a final confirmation. Upon completion, the template will be deleted.
Alternatively, to remove a template via the command line in dom0:
```
$ qvm-template remove qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
$ qvm-template remove <TEMPLATE_NAME>
```
`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>` is the name of the desired
template package.
You may see warning messages like the following:
\<TEMPLATE_NAME> is the first column from the output of:
```
warning: file /var/lib/qubes/vm-templates/fedora-XX/whitelisted-appmenus.list: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/vm-whitelisted-appmenus.list: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.04: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.03: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.02: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.01: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.00: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/netvm-whitelisted-appmenus.list: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/icon.png: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/clean-volatile.img.tar: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.templates: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.tempicons: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps: remove failed: No such file or directory
warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file or directory
$ qvm-template list --installed
```
These are normal and expected. Nothing is wrong, and no action is required to
address these warnings.
In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. "Global property default_template" requires [switching](#switching) the default_template property to another template. "Template for" can be resolved by [switching](#switching) the dependent qubes' template. Once the issues are addressed, attempt the removal again.
If the uninstallation command doesn't work, pay close attention to
any error message: it may tell you what qube is using the template,
or if the template is default. In other cases, please see [VM Troubleshooting](/doc/vm-troubleshooting/).
If the Applications Menu entry doesn't go away after you uninstall a template,
execute the following type of command in dom0:
```
$ rm ~/.local/share/applications/<TEMPLATE_NAME>
```
Applications Menu entries for backups of removed qubes can also be found in
`/usr/local/share/applications/` of dom0.
```
$ rm /usr/local/share/applications/<TEMPLATE_NAME>
```
If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts).
## Reinstalling
@ -429,8 +387,9 @@ this context: the same as their template filesystem, of course.
* Some templates are available in ready-to-use binary form, but some of them
are available only as source code, which can be built using the [Qubes
Builder](/doc/qubes-builder/). In particular, some template "flavors" are
available in source code form only. For the technical details of the template
Builder](https://github.com/QubesOS/qubes-builderv2/). In particular, some
template "flavors" are available in source code form only. For the
technical details of the template
system, please see [Template Implementation](/doc/template-implementation/).
Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for
Take a look at the [Qubes Builder](/doc/qubes-builder-v2/) documentation for
instructions on how to compile them.

31
user/templates/windows/windows-qubes-4-1.md
View file

@ -146,18 +146,17 @@ These parameters are set for the following reasons:
- Install on first disk.
- **For Windows 11 only**: Windows 11 requires TPM 2.0, which currently is not supported from Xen. In Order to install Windows 11 under Qubes, the check for TPM in the Windows installer has to be disabled:
- When you start setup without having a TPM, you get an error message like *This PC does not fulfil the minimum requirements for Windows 11*.
- Typing Shift-F10 then opens a console window.
- When the window allowing you to select a Windows version is displayed, **do not select a version and close this window**, but instead type Shift-F10 to open a console window.
- Here you type `regedit` to start the registry editor.
- There you position to the key `HKEY_LOCAL_MACHINE\SYSTEM\Setup`.
- Now create the key `LabConfig`.
- Position to this key and create 3 DWORD values called `BypassTPMCheck`, `BypassSecureBootCheck` and `BypassRAMCheck` and set each value to `1`.
- Close the registry editor and console windows.
- In the setup window, hit the left arrow in the left upper corner. You will then return into the setup, which will continue normally and install Windows 11 without TPM 2.0.
- You will then return to the setup, which will continue normally and install Windows 11 without TPM 2.0.
:warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft some time.
:warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working.
The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft:
The installation of Windows 11 may require an internet connection to grab a Microsoft ID. Previously, this was true only for the home edition, but since version 24H2, it extends to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that works for version 21H2 but may be blocked for newer versions:
- When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.
- Here you type `taskmgr` to start the Task Manager window so you can see all running processes.
@ -172,6 +171,17 @@ These parameters are set for the following reasons:
- Click `Next`. A screen appears saying "Who's going to use this device?" This is the local account creation screen.
- Enter the username you want to use and click `Next`.
- Enter a password and click `Next`. You can leave the field blank but it's not recommended.
For Windows 11 version 24H2, the following sequence of actions to use a local account instead of a Microsoft account has been proved working:
For version 24H2, the following actions allow you to install Windows 11 with a local account, if the VM is defined, at least temporarily, without a netVM:
- After some reboots, the VM will show a window allowing the selection of an installation country. In this window, type Shift-F10 to open a console window.
- In this window, type `oobe\bypassnro`. The VM will then reboot and return to the country selection window. The network connection window will now show an option "I don't have internet", allowing you to define a local account.
In new preview builds of Windows (26120 and beyond, and eventually the next release version), the `oobe\bypassnro` command has been erased and no longer works. Instead, there's a new command called start `ms-chx:localonly` that does something similar. In this case, proceed as follows:
- Follow the Windows 11 install process until you get to the Sign in screen. Here, type Shift-F10 to open a console window.
- Enter start `ms-cxh:localonly` at the command prompt.
- A "Create a user for this PC" dialog window appears, allowing you to define a local account.
- On systems shipped with a Windows license, the product key may be read from flash via root in dom0:
@ -231,7 +241,16 @@ For additional information on configuring a Windows qube, see the [Customizing W
## Windows as a template
As described above Windows 7, 8.1, 10 and 11 can be installed as TemplateVM. To have the user data stored in AppVMs depending on this template, the option `Move User Profiles` has to be selected on installation of Qubes Windows Tools. For Windows 7, before installing QWT, the private disk `D:` has to be renamed to `Q:`, see the QWT installation documentation in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1).
As described above Windows 7, 8.1, 10, and 11 can be installed as TemplateVM. To have the user data stored in AppVMs depending on this template, the user data have to be stored on a private disk named `Q:`. If there is already a disk for user data, possibly called `D:`, it has to be renamed to `Q:`. Otherwise, this disk has to be created via the Windows `diskpart` utility, or the Disk Management administrative function by formatting the qube's private volume and associating the letter `Q:` with it. The volume name is of no importance.
Moving the user data is not directly possible under Windows, because the directory `C:\Users` is permanently open and thus locked. Qubes Windows Tools provides a function to move these data on Windows reboot when the directory is not yet locked. To use this function, a working version of QWT has to be used (see the documentation on QWT installation). For Qubes R4.2, this is currently the version 4.1.69. There are two possibilities to move the user data to this volume `Q:`.
- If Qubes Windows Tools is installed, the option `Move User Profiles` has to be selected on the installation. In this case, the user files are moved to the new disk during the reboot at the end of the installation.
- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the `REG_MULTI_SZ` value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once.
If the user data have been moved to `Q:`, be sure not to user the option `Move User Profeiles`on subsequent installations of Qubes Windows tools.
AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
~~~

10
user/templates/xfce-templates.md
View file

@ -13,7 +13,13 @@ title: Xfce templates
---
If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/), or [Gentoo](/doc/templates/gentoo/).
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [Gentoo](/doc/templates/gentoo/) or [CentOS*](/doc/templates/centos/).
*\* The CentOS version used by this template reached
[End-of-Life in June 2024](https://en.wikipedia.org/wiki/CentOS_Stream#Release_history)
and is no longer receiving updates. Due to a lack of specific interest
at this time a proposal to create a new CentOS 10 template was
[declined](https://github.com/QubesOS/qubes-issues/issues/9716).*
## Installation
@ -30,7 +36,7 @@ You may wish to try again with the testing repository enabled:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-X-xfce
```
If you would like to install a community distribution, like CentOS or Gentoo, try the install command by enabling the community repository:
If you would like to install a community distribution such as Gentoo, try the install command by enabling the community repository:
```
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce