Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-07 14:12:18 -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/advanced-topics/config-files.md
View file

@ -18,7 +18,7 @@ That way, they can be used to customize a single VM instead of all VMs based on
The scripts here all run as root.
- `/rw/config/rc.local` - script runs at VM startup.
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc.
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. The script need to have the executable permission set to be executed.
Example usage:
~~~
@ -32,6 +32,8 @@ The scripts here all run as root.
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
- `/rw/config/rc.local.d/*.rc` - scripts run at VM startup just before `/rw/config/rc.local`
- `/rw/config/rc.local-early.d/*.rc`, `/rw/config/rc.local-early` - scripts similar to `/rw/config/rc.local`, but running earlier in the system startup sequence - just before `sysinit.target`, and setting up the network.
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- In ProxyVMs (or app qubes with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.

4
user/advanced-topics/secondary-storage.md
View file

@ -65,10 +65,12 @@ In theory, you can still use file-based disk images ("file" pool driver), but it
Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
```
sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
sudo cryptsetup luksFormat --sector-size=512 /dev/sdb
sudo blkid /dev/sdb
```
(The `--sector-size=512` argument can sometimes work around an incompatibility of storage hardware with LVM thin pools on Qubes. If this does not apply to your hardware, the argument will make no difference.)
Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
```

50
user/advanced-topics/standalones-and-hvms.md
View file

@ -50,6 +50,21 @@ is about the virtualization mode. In practice, however, it is most common for
standalones to be HVMs and for HVMs to be standalones. Hence, this page covers
both topics.
## Understanding Virtualization Modes
PVH has both better performance and better security than either PV or HVM:
PVH has less attack surface than PV, as it relies on Second Level Address Translation (SLAT) hardware. Guests modify their own page tables natively, without hypervisor involvement. Xen does not need to perform complex checks to ensure that a guest cannot obtain write access to its own page tables, as is necessary for PV. Flaws in these checks have been a source of no fewer than four guest ⇒ host escapes: XSA-148, XSA-182, XSA-212, and XSA-213.
PVH also has less attack surface than HVM, as it does not require QEMU to provide device emulation services. While QEMU is confined in a stubdomain, and again in a seccomp based sandbox, the stubdomain has significant attack surface against the hypervisor. Not only does it have the full attack surface of a PV domain, it also has access to additional hypercalls that allow it to control the guest it is providing emulation services for. XSA-109 was a vulnerability in one of these hypercalls.
PVH has better performance than HVM, as the stubdomain iin HVM consumes resources (both memory and a small amount of CPU). There is little difference in the I/O path at runtime, as both PVH and HVM guests usually use paravirtualized I/O protocols.
Surprisingly, PVH often has better performance than PV. This is because PVH does not require hypercalls for page table updates, which are expensive. SLAT does raise the cost of TLB misses, but this is somewhat mitigated by a second-level TLB in recent hardware.
## Creating a standalone
You can create a standalone in the Qube Manager by selecting the "Type" of
@ -176,9 +191,40 @@ seen, e.g., in the Qube Manager in the qube's properties:
Alternatively, one can use the `qvm-ls -n` command to obtain the same
information (IP/netmask/gateway).
The Qube Settimgs shows a netmask of 255.255.255.255.
This is not suitable for most standalones, and you will need to use a different value.
The DNS IP addresses are `10.139.1.1` and `10.139.1.2`. There is [opt-in
support](/doc/networking/#ipv6) for IPv6 forwarding.
In Qubes, the IP address is usually in range 10.137.0.0/16, with disposables in range 10.138.0.0/16, and DNS set to `10.139.1.1` and `10.139.1.2`.
The simplest solution is to set the netmask to 255.0.0.0 - standard for a class A network.
If you want a more restricted solution you could use 255.252.0.0, or 255.255.255.0
There is [opt-in support](/doc/networking/#ipv6) for IPv6 forwarding.
### An example of setting up a network - Network Manager on KDE
Every guest operating system has its own way of handling networking, and the user is
referred to the documentation that comes with that operating system. However,
Network Manager is widely used on Linux systems, and so a worked example will
prove useful. This example is for an HVM running EndeavourOS.
![Image of Qube Settings](/attachment/doc/EndeavourOS_Network.png "Qube Settings")
In this example, Network Manager on KDE, the network had the following values:
1. IPv4 networking
2. IP address 10.137.0.17
3. Netmask - qube settings showed 255.255.255.255, but we decided to use 255.255.255.0
4. Gateway 10.138.24.248
5. Virtual DNS 10.139.1.1 and 10.139.1.2
![Image of Network Manager, annotated by numbers for reference below](/attachment/doc/Network Manager.png "Annotated image of KDE Network Manager")
The network was set up by entering Network Manager, selecting the Wi-Fi & Networking tab, clicking on the Wired Ethernet
item, and selecting tab IPv4 (1).
The Manual method was selected (2), which revealed areas for data entry.
The DNS Servers section takes a comma-separated list, here 10.139.1.1,10.1.139.2 (3).
At the bottom of the tab (4), the '+ Add' button was selected, and the IP address of 10.137.0.17 entered in the 'Address' column, the Netmask of 255.255.255.0 entered in the 'Netmask' column, and the Gateway of 10.138.24.248 under 'Gateway'.
Selecting the "Apply" button stored these changes
## Using template-based HVMs

2
user/downloading-installing-upgrading/supported-releases.md
View file

@ -57,7 +57,7 @@ It is the responsibility of each distribution to clearly notify its users in adv
| Qubes OS | Fedora | Debian |
| ----------- | ------ | ------ |
| Release 4.2 | 40, 41 | 12 |
| Release 4.2 | 41 | 12 |
### Note on Debian support

2
user/downloading-installing-upgrading/testing.md
View file

@ -17,7 +17,7 @@ How to test upcoming Qubes OS releases:
- Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).)
- Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).)
- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself.
- Use [qubes-builder](/doc/qubes-builder-v2/) to build the latest release yourself.
- (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
Please make sure to [report any bugs you encounter](/doc/issue-tracking/).

78
user/hardware/certified-hardware.md → user/hardware/certified-hardware/certified-hardware.md
View file

@ -25,71 +25,19 @@ Qubes-certified computers are certified for a [major release](/doc/version-schem
The current Qubes-certified models are listed below in reverse chronological order of certification.
### NovaCustom V54 Series 14.0 inch coreboot laptop
[![Photo of the NovaCustom V54 Series 14.0 inch coreboot laptop](/attachment/site/novacustom-v54-series.png)](https://novacustom.com/product/v54-series/)
The [NovaCustom V54 Series 14.0 inch coreboot laptop](https://novacustom.com/product/v54-series/) is certified for Qubes OS Release 4.
### NitroPad V56
[![Photo of the NitroPad V56](/attachment/site/nitropad-v56.png)](https://shop.nitrokey.com/shop/nitropad-v56-684)
The [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) is certified for Qubes OS Release 4.
### NovaCustom V56 Series 16.0 inch coreboot laptop
[![Photo of the NovaCustom V56 Series 16.0 inch coreboot laptop](/attachment/site/novacustom-v56-series.png)](https://novacustom.com/product/v56-series/)
The [NovaCustom V56 Series 16.0 inch coreboot laptop](https://novacustom.com/product/v56-series/) is certified for Qubes OS Release 4.
### NitroPC Pro 2
[![Photo of the NitroPC Pro 2](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/nitropc-pro-2-523)
The [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) is a desktop based on the MSI PRO Z790-P DDR5 motherboard. It is certified for Qubes OS Release 4.
### Star Labs StarBook
[![Photo of the Star Labs StarBook](/attachment/site/starlabs-starbook.png)](https://starlabs.systems/pages/starbook)
The [Star Labs StarBook](https://starlabs.systems/pages/starbook) is a 14-inch laptop. It is certified for Qubes OS Release 4.
### NitroPC Pro
[![Photo of the NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523)
The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is a desktop based on the MSI PRO Z690-A DDR5 motherboard. It is certified for Qubes OS Release 4.
### NovaCustom NV41 Series
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://novacustom.com/product/nv41-series/)
The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS Release 4.
### Dasharo FidelisGuard Z690
[![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS Release 4.
### NitroPad T430
[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS Release 4.
### NitroPad X230
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS Release 4.
### Insurgo PrivacyBeast X230
[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS Release 4.
| Brand | Model | Certification details |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [NovaCustom](https://novacustom.com/) | [V54 Series](https://novacustom.com/product/v54-series/) | [Certification details](/doc/certified-hardware/novacustom-v54-series/) |
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) | [Certification details](/doc/certified-hardware/nitropad-v56/) |
| [NovaCustom](https://novacustom.com/) | [V56 Series](https://novacustom.com/product/v56-series/) | [Certification details](/doc/certified-hardware/novacustom-v56-series/) |
| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) | [Certification details](/doc/certified-hardware/nitropc-pro-2/) |
| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook) | [Certification details](/doc/certified-hardware/starlabs-starbook/) |
| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) | [Certification details](/doc/certified-hardware/nitropc-pro/) |
| [NovaCustom](https://novacustom.com/) | [NV41 Series](https://novacustom.com/product/nv41-series/) | [Certification details](/doc/certified-hardware/novacustom-nv41-series/) |
| [3mdeb](https://3mdeb.com/) | [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) |
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) | [Certification details](/doc/certified-hardware/nitropad-t430/) |
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) | [Certification details](/doc/certified-hardware/nitropad-x230/) |
| [Insurgo](https://insurgo.ca/) | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) |
## Become hardware certified

38
user/hardware/certified-hardware/dasharo-fidelisguard-z690.md Normal file
View file

@ -0,0 +1,38 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/dasharo-fidelisguard-z690/
title: Dasharo FidelisGuard Z690
image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg
---
The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
| Part | Model Name |
|------------- | -------------------------------------------------------------- |
| CPU | Intel Core i5-12600K, 3.7GHz |
| Cooling | Noctua CPU NH-U12S Redux |
| RAM | Kingston Fury Beast, DDR4, 4x8GB (32 GB Total), 3600 MHz, CL17 |
| Power Supply | Seasonic Focus PX 750W 80 Plus Platinum |
| Storage | SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe |
| Enclosure | SilentiumPC Armis AR1 |
[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_2.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
This computer comes with a "Dasharo Supporters Entrance Subscription," which includes the following:
- Full access to [Dasharo Tools Suite (DTS)](https://docs.dasharo.com/dasharo-tools-suite/overview/)
- The latest Dasharo releases issued by the Dasharo Team
- Special Dasharo updates for supporters
- Dasharo Premier Support through an invite-only Matrix channel
- Influence on the Dasharo feature roadmap
[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_3.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
For further details, please see the [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page.
[![Photo of the outside of the Dasharo FidelisGuard Z690](/attachment/posts/dasharo-fidelisguard-z690_4.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)

26
user/hardware/certified-hardware/insurgo-privacybeast-x230.md Normal file
View file

@ -0,0 +1,26 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/insurgo-privacybeast-x230/
title: Insurgo PrivacyBeast X230
image: /attachment/site/insurgo-privacybeast-x230.png
---
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> The CPU in this computer no longer receives microcode updates from Intel. Without microcode updates, Qubes OS cannot ensure that this computer is secure against CPU vulnerabilities. While this computer remains certified for Qubes OS Release 4, we recommend that prospective buyers consider a newer Qubes-certified computer instead.
</div>
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a custom refurbished [ThinkPad X230](https://www.thinkwiki.org/wiki/Category:X230) that includes the following features:
- [coreboot](https://www.coreboot.org/) initialization for the x230 is binary-blob-free, including native graphic initialization. Built with the [Heads](https://github.com/osresearch/heads/) payload, it delivers an [Anti Evil Maid (AEM)](/doc/anti-evil-maid/)-like solution built into the firmware. (Even though our [requirements](/doc/certified-hardware/#hardware-certification-requirements) provide an exception for CPU-vendor-provided blobs for silicon and memory initialization, Insurgo exceeds our requirements by insisting that these be absent from its machines.)
- [Intel ME](https://libreboot.org/faq.html#intelme) is neutered through the AltMeDisable bit, while all modules other than ROMP and BUP, which are required to initialize main CPU, have been [deleted](https://github.com/linuxboot/heads-wiki/blob/master/Installing-and-Configuring/Flashing-Guides/Clean-the-ME-firmware.md#how-to-disabledeactive-most-of-it).
- A re-ownership process that allows it to ship pre-installed with Qubes OS, including full-disk encryption already in place, but where the final disk encryption key is regenerated only when the machine is first powered on by the user, so that the OEM doesn't know it.
- [Heads](https://github.com/osresearch/heads/) provisioned pre-delivery to protect against malicious [interdiction](https://en.wikipedia.org/wiki/Interdiction).

30
user/hardware/certified-hardware/nitropad-t430.md Normal file
View file

@ -0,0 +1,30 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/nitropad-t430/
title: NitroPad T430
image: /attachment/site/nitropad-t430.jpg
---
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> The CPU in this computer no longer receives microcode updates from Intel. Without microcode updates, Qubes OS cannot ensure that this computer is secure against CPU vulnerabilities. While this computer remains certified for Qubes OS Release 4, we recommend that prospective buyers consider a newer Qubes-certified computer instead.
</div>
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Please be advised that the i7-3632QM option is <b>not</b> compatible with Qubes OS, as it does not support VT-d. The option specifically tested by the Qubes team is the i5-3320M.
</div>
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
Key features of the [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) include:
- Tamper detection through measured boot with [coreboot](https://www.coreboot.org/), [Heads](https://github.com/osresearch/heads/), and Nitrokey USB hardware, including support for [Anti Evil Maid (AEM)](/doc/anti-evil-maid/)
- Deactivated [Intel Management Engine](https://libreboot.org/faq.html#intelme)
- User-replaceable cryptographic keys
- Included Nitrokey USB key
- Professional ThinkPad hardware based on the [ThinkPad T430](https://www.thinkwiki.org/wiki/Category:T430)
- Security-conscious shipping to mitigate against third-party [interdiction](https://en.wikipedia.org/wiki/Interdiction)

82
user/hardware/certified-hardware/nitropad-v56.md Normal file
View file

@ -0,0 +1,82 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/nitropad-v56/
title: NitroPad V56
image: /attachment/site/nitropad-v56.png
---
The [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the NitroPad V56](/attachment/site/nitropad-v56.png)](https://shop.nitrokey.com/shop/nitropad-v56-684)
## Qubes-certified options
The configuration options required for Qubes certification are detailed below.
### Processor and graphics card
- Certified: Intel Core Ultra 5 Processor 125H, Intel Arc iGPU with AI Boost
- Certified: Intel Core Ultra 7 Processor 155H, Intel Arc iGPU with AI Boost
- The Nvidia GPU options are not currently certified.
### Memory (RAM) DDR5, 5600 MHz
- Certified: All options 16 GB (2x8 GB) and higher
### 1st Hard Disk SSD NVMe PCIe 4.0 x4
- Certified: Any of the available options in this section
### 2nd Hard Disk SSD NVMe PCIe 4.0 x4
- Certified: Any of the available options in this section
### Keyboard
- Certified: Any of the available options in this section
### Wireless interfaces
- Certified: Wi-Fi 6E + Bluetooth 5.3, Intel AX-210/211 (non vPro) WLAN module 2.4 Gbps, 802.11ax
- Certified: Wi-Fi 7 + Bluetooth 5.42, Intel BE200 (non vPro) WLAN module 5.8 Gbps, 802.11be
- Certified: No wireless
### Webcam and microphone
- Certified: Any of the available options in this section
### Type
- Certified: Any of the available options in this section
### Firmware
- Certified: Dasharo TianoCore UEFI without Measured boot, without Nitrokey
- The option "Dasharo HEADS with Measured Boot, requires Nitrokey!" is not yet certified.
### Operating system
- Certified: Qubes OS 4.2.3 or newer (within Release 4).
- Releases older than 4.2.3 are not certified.
- You may choose either to have Nitrokey preinstall Qubes OS for you, or you may choose to install Qubes OS yourself. This choice does not affect certification.
### Nitrokey
- Certified: None -- for TianoCore only!
- The Nitrokey options are currently not applicable to Qubes hardware certification. (See the Firmware section above.)
### Shipment of Nitrokey
- This section does not affect Qubes hardware certification.
### Tamper-evident packaging
- This section does not affect Qubes hardware certification.
## Disclaimers
- In order for Wi-Fi to function properly, `sys-net` must currently be based on a Fedora template. The firmware package in Debian templates is currently too old for the certified Wi-Fi cards.
- Currently requires `kernel-latest`: If you install Qubes OS yourself, you must select the `Install Qubes OS RX using kernel-latest` option on the GRUB menu when booting the installer. This non-default kernel option is currently required for the NitroPad V56 to function properly.
- Due to a [known bug](https://github.com/Dasharo/dasharo-issues/issues/976), the bottom-right USB-C port is currently limited to USB 2.0 speeds.

25
user/hardware/certified-hardware/nitropad-x230.md Normal file
View file

@ -0,0 +1,25 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/nitropad-x230/
title: NitroPad X230
image: /attachment/site/nitropad-x230.jpg
---
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> The CPU in this computer no longer receives microcode updates from Intel. Without microcode updates, Qubes OS cannot ensure that this computer is secure against CPU vulnerabilities. While this computer remains certified for Qubes OS Release 4, we recommend that prospective buyers consider a newer Qubes-certified computer instead.
</div>
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) offers users unprecedented control over the security of their hardware. Key features include:
- Tamper detection through measured boot with [coreboot](https://www.coreboot.org/), [Heads](https://github.com/osresearch/heads/), and Nitrokey USB hardware, including support for [Anti Evil Maid (AEM)](/doc/anti-evil-maid/)
- Deactivated [Intel Management Engine](https://libreboot.org/faq.html#intelme)
- User-replaceable cryptographic keys
- Included Nitrokey USB key
- Professional ThinkPad hardware based on the [ThinkPad X230](https://www.thinkwiki.org/wiki/Category:X230)
- Security-conscious shipping to mitigate against third-party [interdiction](https://en.wikipedia.org/wiki/Interdiction)

47
user/hardware/certified-hardware/nitropc-pro-2.md Normal file
View file

@ -0,0 +1,47 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/nitropc-pro-2/
title: NitroPC Pro 2
image: /attachment/posts/nitropc-pro.jpg
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> When configuring your NitroPC Pro 2 on the Nitrokey website, there is an option for a discrete graphics card (e.g., Nvidia GeForce RTX 4070 or 4090) in addition to integrated graphics (e.g., Intel UHD 770, which is always included because it is physically built into the CPU). NitroPC Pro 2 configurations that include discrete graphics cards are <em>not</em> Qubes-certified. The only NitroPC Pro 2 configurations that are Qubes-certified are those that contain <em>only</em> integrated graphics.
</div>
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Only the "Dasharo TianoCore UEFI without Measured Boot, without Nitrokey" firmware option is certified. The "HEADS with Measured Boot, requires Nitrokey!" firmware option is <em>not</em> certified.
</div>
The [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of NitroPC Pro 2](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/nitropc-pro-2-523)
Here's a summary of the main component options available for this mid-tower desktop PC:
| Component | Options |
|----------------------------- | -------------------------------------------------------- |
| Motherboard | MSI PRO Z790-P DDR5 (Wi-Fi optional) |
| Processor | 14th Generation Intel Core i5-14600K or i9-14900K |
| Memory | 16 GB to 128 GB DDR5 |
| NVMe storage (optional) | Up to two NVMe PCIe 4.0 x4 SSDs, up to 2 TB each |
| SATA storage (optional) | Up to two SATA SSDs, up to 7.68 TB each |
| Wireless (optional) | Wi-Fi 6E, 2400 Mbps, 802.11/a/b/g/n/ac/ax, Bluetooth 5.2 |
| Operating system (optional) | Qubes OS 4.2 or Ubuntu 22.04 LTS |
Of special note for Qubes users, the NitroPC Pro 2 features a combined PS/2 port that supports both a PS/2 keyboard and a PS/2 mouse simultaneously with a Y-cable (not included). This allows for full control of dom0 without the need for USB keyboard or mouse passthrough. Nitrokey also offers a special tamper-evident shipping method for an additional fee. With this option, the case screws will be individually sealed and photographed, and the NitroPC Pro 2 will be packed inside a sealed bag. Photographs of the seals will be sent to you by email, which you can use to determine whether the case was opened during transit.
The NitroPC Pro 2 also comes with a "Dasharo Entry Subscription," which includes the following:
- Accesses to the latest firmware releases
- Exclusive newsletter
- Special updates, including early access to updates enhancing privacy, security, performance, and compatibility
- Early access to new firmware releases for [newly-supported desktop platforms](https://docs.dasharo.com/variants/overview/#desktop) (please see the [roadmap](https://github.com/Dasharo/presentations/blob/main/dasharo_roadmap.md#dasharo-desktop-roadmap))
- Access to the Dasharo Premier Support invite-only live chat channel on the Matrix network, allowing direct access to the Dasharo Team and fellow subscribers with personalized and priority assistance
- Insider's view and influence on the Dasharo feature roadmap for a real impact on Dasharo development
- [Dasharo Tools Suite Entry Subscription](https://docs.dasharo.com/osf-trivia-list/dts/#what-is-dasharo-tools-suite-supporters-entrance) keys
For further product details, please see the official [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) page.

47
user/hardware/certified-hardware/nitropc-pro.md Normal file
View file

@ -0,0 +1,47 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/nitropc-pro/
title: NitroPC Pro
image: /attachment/posts/nitropc-pro.jpg
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> When configuring your NitroPC Pro 2 on the Nitrokey website, there is an option for a discrete graphics card (e.g., Nvidia GeForce RTX 4070 or 4090) in addition to integrated graphics (e.g., Intel UHD 770, which is always included because it is physically built into the CPU). NitroPC Pro 2 configurations that include discrete graphics cards are <em>not</em> Qubes-certified. The only NitroPC Pro 2 configurations that are Qubes-certified are those that contain <em>only</em> integrated graphics.
</div>
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Only the "Dasharo TianoCore UEFI without Measured Boot, without Nitrokey" firmware option is certified. The "HEADS with Measured Boot, requires Nitrokey!" firmware option is <em>not</em> certified.
</div>
The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523)
Here's a summary of the main component options available for this mid-tower desktop PC:
| Component | Options |
|----------------------------- | -------------------------------------------------------- |
| Motherboard | MSI PRO Z690-A DDR5 (Wi-Fi optional) |
| Processor | 12th Generation Intel Core i5-12600K or i9-12900K |
| Memory | 16 GB to 128 GB DDR5 |
| NVMe storage (optional) | Up to two NVMe PCIe 4.0 x4 SSDs, up to 2 TB each |
| SATA storage (optional) | Up to two SATA SSDs, up to 7.68 TB each |
| Wireless (optional) | Wi-Fi 6E, 2400 Mbps, 802.11/a/b/g/n/ac/ax, Bluetooth 5.2 |
| Operating system (optional) | Qubes OS 4.1 or Ubuntu 22.04 LTS |
Of special note for Qubes users, the NitroPC Pro features a combined PS/2 port that supports both a PS/2 keyboard and a PS/2 mouse simultaneously with a Y-cable (not included). This allows for full control of dom0 without the need for USB keyboard or mouse passthrough. Nitrokey also offers a special tamper-evident shipping method for an additional fee. With this option, the case screws will be individually sealed and photographed, and the NitroPC Pro will be packed inside a sealed bag. Photographs of the seals will be sent to you by email, which you can use to determine whether the case was opened during transit.
The NitroPC Pro also comes with a "Dasharo Entry Subscription," which includes the following:
- Accesses to the latest firmware releases
- Exclusive newsletter
- Special firmware updates, including early access to updates enhancing privacy, security, performance, and compatibility
- Early access to new firmware releases for [newly-supported desktop platforms](https://docs.dasharo.com/variants/overview/#desktop) (please see the [roadmap](https://github.com/Dasharo/presentations/blob/main/dug2_dasharo_roadmap.md#dasharo-desktop-roadmap))
- Access to the Dasharo Premier Support invite-only live chat channel on the Matrix network, allowing direct access to the Dasharo Team and fellow subscribers with personalized and priority assistance
- Insider's view and influence on the Dasharo feature roadmap for a real impact on Dasharo development
- [Dasharo Tools Suite Entry Subscription](https://docs.dasharo.com/osf-trivia-list/dts/#what-is-dasharo-tools-suite-supporters-entrance) keys
For further product details, please see the official [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) page.

42
user/hardware/certified-hardware/novacustom-nv41-series.md Normal file
View file

@ -0,0 +1,42 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/novacustom-nv41-series/
title: NovaCustom NV41 Series
image: /attachment/site/novacustom-nv41-series.png
---
The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://novacustom.com/product/nv41-series/)
## Qubes-certified configurations
The following configuration options are certified for Qubes OS Release 4:
Processor:
- Intel Core i5-1240P processor
- Intel Core i7-1260P processor
Memory:
- 2 x 16 GB Kingston DDR4 SODIMM 3200 MHz (32 GB total)
- 1 x 32 GB Kingston DDR4 SODIMM 3200 MHz (32 GB total)
- 2 x 32 GB Kingston DDR4 SODIMM 3200 MHz (64 GB total)
M.2 storage chip:
- Samsung 980 SSD (all capacities)
- Samsung 980 Pro SSD (all capacities)
Wi-Fi and Bluetooth:
- Intel AX-200/201 Wi-Fi module 2976 Mbps, 802.11ax/Wi-Fi 6 + Bluetooth 5.2
- Killer (Intel) Wireless-AX 1675x M.2 Wi-Fi module 802.11ax/Wi-Fi 6E + Bluetooth 5.3
- Blob-free: Qualcomm Atheros QCNFA222 Wi-Fi 802.11a/b/g/n + Bluetooth 4.0
- No Wi-Fi/Bluetooth chip
### Notes on Wi-Fi and Bluetooth options
- When viewed in a Linux environment with `lspci`, the "Killer (Intel) Wireless-AX 1675x M.2 Wi-Fi module 802.11ax/Wi-Fi 6E + Bluetooth 5.3" device displays the model number "AX210." However, according to its [Intel Ark entry](https://ark.intel.com/content/www/us/en/ark/products/211485/intel-killer-wifi-6e-ax1675-xw.html) (in the "Product Brief" file), they are actually the same Wi-Fi module.
- Similarly, when viewed in a Linux environment with `lspci`, the "Blob-free: Qualcomm Atheros QCNFA222 Wi-Fi 802.11a/b/g/n + Bluetooth 4.0" device displays the model number "AR9462," which seems to be just the Wi-Fi chip model number, whereas "QCNFA222" seems to be the model number of the whole device (which include Bluetooth). Meanwhile, the Bluetooth device presents itself as "IMC Networks Device 3487."
- The term "blob-free" is used in different ways. In practice, being "blob-free" generally does *not* mean that the device does not use any closed-source firmware "blobs." Rather, it means that the device comes with firmware *preinstalled* so that it does not have to be loaded from the operating system. In theory, the preinstalled firmware could be open-source, but as far as we know, that is not the case with this particular Atheros Wi-Fi/Bluetooth module. (Qualcomm has published firmware source code in the past, but only for other device models, as far as we are aware.) Meanwhile, the Free Software Foundation (FSF) [considers](https://www.gnu.org/philosophy/free-hardware-designs.en.html#boundary) unmodifiable preinstalled firmware to be part of the hardware, hence they regard such hardware as "blob-free" from a software perspective. While common usage of the term "blob-free" often follows the FSF's interpretation, it is worthwhile for Qubes users who are concerned about closed-source firmware to understand the nuance.

69
user/hardware/certified-hardware/novacustom-v54-series.md Normal file
View file

@ -0,0 +1,69 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/novacustom-v54-series/
title: NovaCustom V54 Series
image: /attachment/site/novacustom-v54-series.png
---
The [NovaCustom V54 Series 14.0 inch coreboot laptop](https://novacustom.com/product/v54-series/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the NovaCustom V54 Series 14.0 inch coreboot laptop](/attachment/site/novacustom-v54-series.png)](https://novacustom.com/product/v54-series/)
## Qubes-certified options
The configuration options required for Qubes certification are detailed below.
### Screen size
- Certified: 14 inch
**Note:** The 14-inch model (V540TU) and the 16-inch model (V560TU) are two separate products. [The 16-inch model is also certified.](/doc/certified-hardware/novacustom-v56-series/)
### Screen resolution
- Certified: Full HD+ (1920 x 1200)
- Certified: 2.8K (2880 x 1800)
### Processor and graphics
- Certified: Intel Core Ultra 5 Processor 125H, Intel Arc iGPU with AI Boost
- Certified: Intel Core Ultra 7 Processor 155H, Intel Arc iGPU with AI Boost
- The Nvidia discrete GPU options are not currently certified.
### Memory
- Certified: Any configuration with at least 16 GB of memory
### Storage
- Certified: All of the available options in these sections
### Personalization
- This section is merely cosmetic and therefore does not affect certification.
### Firmware options
- Qubes OS does not currently support UEFI secure boot.
- The option to be kept up to date with firmware updates is merely an email notification service and therefore does not affect certification.
- The coreboot+Heads option is not currently certified. This option is a separate firmware variant. As such, it requires a separate certification process, which we expect to occur in the future.
- Disabling Intel Management Engine (HAP disabling) does not affect certification.
### Operating system
- Certified: Qubes OS 4.2.4 or newer (within Release 4).
- Releases older than 4.2.4 are not certified.
- You may choose either to have NovaCustom preinstall Qubes OS for you, or you may choose to install Qubes OS yourself. This choice does not affect certification.
### Wi-Fi and Bluetooth
- Certified: Intel AX-210/211 (non vPro) Wi-Fi module 2.4 Gbps, 802.11AX/Wi-Fi6E + Bluetooth 5.3
- Certified: Intel BE200 (non vPro) Wi-Fi module 5.8 Gbps, 802.11BE/Wi-Fi7 + Bluetooth 5.42
- Certified: No Wi-Fi chip -- no Bluetooth and Wi-Fi connection possible (only with USB adapter)
## Disclaimers
- In order for Wi-Fi to function properly, `sys-net` must currently be based on a Fedora template. The firmware package in Debian templates is currently too old for the certified Wi-Fi cards.
- Currently requires `kernel-latest`: If you install Qubes OS yourself, you must select the `Install Qubes OS RX using kernel-latest` option on the GRUB menu when booting the installer. This non-default kernel option is currently required for the NovaCustom V54 Series to function properly.
- Due to a [known bug](https://github.com/Dasharo/dasharo-issues/issues/976), the bottom-right USB-C port is currently limited to USB 2.0 speeds.

69
user/hardware/certified-hardware/novacustom-v56-series.md Normal file
View file

@ -0,0 +1,69 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/novacustom-v56-series/
title: NovaCustom V56 Series
image: /attachment/site/novacustom-v56-series.png
---
The [NovaCustom V56 Series 16.0 inch coreboot laptop](https://novacustom.com/product/v56-series/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
[![Photo of the NovaCustom V56 Series 16.0 inch coreboot laptop](/attachment/site/novacustom-v56-series.png)](https://novacustom.com/product/v56-series/)
## Qubes-certified options
The configuration options required for Qubes certification are detailed below.
### Screen size
- Certified: 16 inch
**Note:** The 16-inch model (V560TU) and the 14-inch model (V540TU) are two separate products. [The 14-inch model is also certified.](/doc/certified-hardware/novacustom-v54-series/)
### Screen resolution
- Certified: Full HD+ (1920 x 1200)
- Certified: Q-HD+ (2560 x 1600)
### Processor and graphics
- Certified: Intel Core Ultra 5 Processor 125H + Intel Arc iGPU with AI Boost
- Certified: Intel Core Ultra 7 Processor 155H + Intel Arc iGPU with AI Boost
- The Nvidia discrete GPU options are not currently certified.
### Memory
- Certified: Any configuration with at least 16 GB of memory
### Storage
- Certified: Any of the available options in this section
### Personalization
- This section is merely cosmetic and therefore does not affect certification.
### Firmware options
- Qubes OS does not currently support UEFI secure boot.
- Keeping up-to-date with firmware updates is merely an email notification service and therefore does not affect certification.
- The coreboot+Heads option is not currently certified. This option is a separate firmware variant. As such, it requires a separate certification process, which we expect to occur in the future.
- Disabling Intel Management Engine (HAP disabling) does not affect certification.
### Operating system
- Certified: Qubes OS 4.2.3 or newer (within Release 4).
- Releases older than 4.2.3 are not certified.
- You may choose either to have NovaCustom preinstall Qubes OS for you, or you may choose to install Qubes OS yourself. This choice does not affect certification.
### Wi-Fi and Bluetooth
- Certified: Intel AX-210/211 (non vPro) Wi-Fi module 2.4 Gbps, 802.11AX/Wi-Fi6E + Bluetooth 5.3
- Certified: Intel BE200 (non vPro) Wi-Fi module 5.8 Gbps, 802.11BE/Wi-Fi7 + Bluetooth 5.42
- Certified: No Wi-Fi chip - no Bluetooth and Wi-Fi connection possible (only with USB adapter)
## Disclaimers
- In order for Wi-Fi to function properly, `sys-net` must currently be based on a Fedora template. The firmware package in Debian templates is currently too old for the certified Wi-Fi cards.
- Currently requires `kernel-latest`: If you install Qubes OS yourself, you must select the `Install Qubes OS RX using kernel-latest` option on the GRUB menu when booting the installer. This non-default kernel option is currently required for the NovaCustom V56 Series to function properly.
- Due to a [known bug](https://github.com/Dasharo/dasharo-issues/issues/976), the bottom-right USB-C port is currently limited to USB 2.0 speeds.

35
user/hardware/certified-hardware/starlabs-starbook.md Normal file
View file

@ -0,0 +1,35 @@
---
lang: en
layout: doc
permalink: /doc/certified-hardware/starlabs-starbook/
title: Star Labs StarBook
image: /attachment/site/starlabs-starbook.png
---
The [Star Labs StarBook](https://starlabs.systems/pages/starbook) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
The [Star Labs StarBook](https://starlabs.systems/pages/starbook) is a 14-inch laptop featuring open-source coreboot and EDK II firmware.
[![Photo of Star Labs StarBook](/attachment/site/starlabs-starbook.png)](https://starlabs.systems/pages/starbook)
The Qubes developers have tested and certified the following StarBook configuration options for Qubes OS Release 4:
| Component | Qubes-certified options |
| ---------------- | ------------------------------------------------ |
| Processor | 13th Generation Intel Core i3-1315U or i7-1360P |
| Memory | 8 GB, 16 GB, 32 GB, or 64 GB RAM |
| Storage | 512 GB, 1 TB, or 2 TB SSD |
| Graphics | Intel (integrated graphics) |
| Networking | Intel Wi-Fi 6 AX210 (no built-in wired Ethernet) |
| Firmware | coreboot 8.97 (2023-10-03) |
| Operating system | Qubes OS (pre-installation optional) |
[![Photo of Star Labs StarBook](/attachment/posts/starlabs-starbook_top.png)](https://starlabs.systems/pages/starbook)
The StarBook features a true matte 14-inch IPS display at 1920x1080 full HD resolution with 400cd/m² of brightness, 178° viewing angles, and a 180° hinge. The backlit keyboard is available in US English, UK English, French, German, Nordic, and Spanish layouts.
[![Photo of Star Labs StarBook](/attachment/posts/starlabs-starbook_side.png)](https://starlabs.systems/pages/starbook)
The StarBook includes four USB ports (1x USB-C with Thunderbolt 4, 2x USB 3.0, and 1x USB 2.0), one HDMI port, a microSD slot, an audio input/output combo jack, and a DC jack for charging. For more information, see the official [Star Labs StarBook](https://starlabs.systems/pages/starbook) page.
[![Photo of Star Labs StarBook](/attachment/posts/starlabs-starbook_back.png)](https://starlabs.systems/pages/starbook)

24
user/hardware/system-requirements.md
View file

@ -114,16 +114,16 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
other security updates directly to users. By contrast, on AMD client (as
opposed to server) platforms, microcode updates are typically shipped only as
part of system firmware and generally cannot be loaded from the operating
system. This means that AMD users typically must wait for:
system [^1]. This means that AMD users typically must wait for:
1. AMD to distribute microcode updates to original equipment manufacturers
(OEMs), original design manufacturers (ODMs), and motherboard manufacturers
(MB); and
2. The user's OEM, ODM, or MB to provide a suitable BIOS or (U)EFI update for
the user's system.
Historically, AMD has often been slow to complete step (1), at least for its
client (as opposed to server) platforms. In some cases, AMD has made fixes
client (as opposed to server) platforms [^2]. In some cases, AMD has made fixes
available for its server platforms very shortly after a security embargo was
lifted, but it did not make fixes available for client platforms facing the
same vulnerability until weeks or months later. (A "security embargo" is the
@ -134,7 +134,7 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
Step (2) varies by vendor. Many vendors fail to complete step (2) at all,
while some others take a very long time to complete it.
The bottom line is that Qubes OS **can** run on AMD systems, and the Qubes and
Xen security teams do their best to provide security support for AMD systems.
However, without the ability to ship microcode updates, there is only so much
@ -163,3 +163,17 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
- You can check whether an Intel processor has VT-x and VT-d on
[ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
[^1]: There is an `amd-ucode-firmware` package, but it only contains
microcode for servers and outdated microcode for Chromebooks. Also,
the [AMD security website](https://www.amd.com/en/resources/product-security.html)
only lists microcode as a mitigation for data center CPUs.
[^2]: As shown on [the AMD page for Speculative Return Stack Overflow](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7005.html),
updated AGESA™ firmware for AMD Ryzen™ Threadripper™ 5000WX Processors
was not available until 2024-01-11, even though the vulnerability became
public on 2023-08-08. AMD did not provide updated firmware for other client
processors until a date between 2023-08-22 to 2023-08-25.
For Zenbleed, firmware was not available until 2024 for most client parts,
even though server parts got microcode on 2023-06-06.

176
user/how-to-guides/backup-emergency-restore-v4.md
View file

@ -12,13 +12,17 @@ title: Emergency backup recovery (v4)
This page describes how to perform an emergency restore of a backup created on
Qubes R4.X (which uses backup format version 4).
The Qubes backup system has been designed with emergency disaster recovery in
mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure.
The Qubes backup system is designed with emergency disaster recovery in mind. No
special Qubes-specific tools are required to access data backed up by Qubes. In
the event a Qubes system is unavailable, you can access your data on any
GNU/Linux system by following the instructions on this page.
Required `scrypt` Utility
-------------------------
**Important:** You may wish to store a copy of these instructions with your
Qubes backups. All Qubes documentation, including this page, is available in
plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git
repository.
## Required `scrypt` utility
In Qubes 4.X, backups are encrypted and integrity-protected with
[scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this
@ -34,8 +38,8 @@ easier scripting, which means you'll need to enter the passphrase for each file
separately, instead of using `echo ... | scrypt`.
Here are instructions for obtaining a compiled `scrypt` binary. This example
uses an RPM-based system (Fedora), but the same general procedure should work
on any GNU/Linux system.
uses an RPM-based system (Fedora), but the same general procedure should work on
any GNU/Linux system.
1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing
Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
@ -46,7 +50,7 @@ on any GNU/Linux system.
[user@restore ~]$ dnf download scrypt
or, if that doesn't work:
Or, if that doesn't work:
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
@ -62,60 +66,35 @@ on any GNU/Linux system.
[user@restore ~]$ sudo dnf install rpmdevtools
5. Extract the `scrypt` binary from the RPM.
5. Extract the `scrypt` binary from the RPM and make it conveniently
available.
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
6. (Optional) Create an alias for the new binary.
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
Emergency Recovery Instructions
-------------------------------
## Emergency recovery instructions
**Note:** In the following example, the backup file is both *encrypted* and
*compressed*.
1. Untar the main backup file.
1. Untar the backup metadata from the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
backup-header backup-header.hmac qubes.xml.000.enc
backup-header
backup-header.hmac
qubes.xml.000.enc
vm1/private.img.000.enc
vm1/private.img.001.enc
vm1/private.img.002.enc
vm1/icon.png.000.enc
vm1/firewall.xml.000.enc
vm1/whitelisted-appmenus.list.000.enc
dom0-home/dom0user.000.enc
**To extract only specific VMs:** Each VM in the backup file has its path
listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is
`password`.)
[user@restore ~]$ cat backup-header | grep backup-id
backup-id=20190128T123456-1234
[user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000
Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password
[user@restore ~]$ tar -i -xvf qubes.xml.000
Now that you have the decrypted `qubes.xml.000` file, search for the
`backup-path` property inside of it. With the `backup-path`, extract only
the files necessary for your VM (`vmX`).
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
backup-header backup-header.hmac vmX/
2. Set the backup passphrase environment variable. While this isn't strictly
required, it will be handy later and will avoid saving the passphrase in
the shell's history.
required, it will be handy later and will avoid saving the passphrase in the
shell's history.
[user@restore ~]$ read -r backup_pass
3. Verify the integrity of `backup-header`. For compatibility reasons,
`backup-header.hmac` is an encrypted *and integrity protected*
version of `backup-header`.
Type in your passphrase (it will be visible on screen!) and press Enter.
3. Verify the integrity of `backup-header` using `backup-header.hmac` (an
encrypted *and integrity protected* version of `backup-header`).
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
@ -123,34 +102,34 @@ Emergency Recovery Instructions
diff -qs backup-header backup-header.verified
Files backup-header and backup-header.verified are identical
**Note:** If this command fails, it may be that the backup was tampered
with or is in a different format. In the latter case, look inside
`backup-header` at the `version` field. If it contains a value other than
`version=4`, go to the instructions for that format version:
**Note:** If this command fails, it may be that the backup was tampered with
or is in a different format. In the latter case, look inside `backup-header`
at the `version` field. If it contains a value other than `version=4`, go to
the instructions for that format version:
- [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
- [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
4. Read `backup-header`:
4. Read `backup-header`.
[user@restore ~]$ cat backup-header
version=4
encrypted=True
compressed=True
compression-filter=gzip
backup_id=20161020T123455-1234
hmac-algorithm=scrypt
backup-id=20230405T123455-1234
5. Set `backup_id` to the value in the last line of `backup-header`:
5. Set `backup_id` to the value in the last line of `backup-header`. (Note that
there is a hyphen in `backup-id` in the file, whereas there is an underscore
in `backup_id` in the variable you're setting.)
[user@restore ~]$ backup_id=20161020T123455-1234
[user@restore ~]$ backup_id=20230405T123455-1234
6. Verify the integrity of your data, decrypt, decompress, and extract
`private.img`:
6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
done | gzip -d | tar -xv
vm1/private.img
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
qubes.xml
If this pipeline fails, it is likely that the backup is corrupted or has
been tampered with.
@ -158,23 +137,66 @@ Emergency Recovery Instructions
**Note:** If your backup was compressed with a program other than `gzip`,
you must substitute the correct compression program in the command above.
This information is contained in `backup-header` (see step 4). For example,
if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
command above.
if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
-d` in the command above. You might need to install a package of the same
name (in this example, `bzip2`) through your distribution's package manager.
7. Mount `private.img` and access your data.
7. Search inside of the `qubes.xml` file for the `backup-path` of the qube
whose data you wish to restore. If you install the `xmlstarlet` package, the
following command will convert `qubes.xml` to a friendlier listing for this
purpose:
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
This data has been successfully recovered!
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
-n qubes.xml
anon-whonix
debian-11
default-mgmt-dvm
disp2345
fedora-37
fedora-37-dvm
personal vm123/
sys-firewall
sys-net
sys-usb
sys-whonix
untrusted
vault vm321/
whonix-gw-16
whonix-ws-16
whonix-ws-16-dvm
work
8. Success! If you wish to recover data from more than one VM in your backup,
simply repeat steps 6 and 7 for each additional VM.
The example output above shows that the backup file includes a qube named
`personal` and a qube named `vault`, with `backup-path` values of `vm123/`
and `vm321/` respectively. (Every other listed qube was not selected to be
included in the backup file.) Use the corresponding value to untar the
necessary data files of the qube:
**Note:** You may wish to store a copy of these instructions with your
Qubes backups in the event that you fail to recall the above procedure
while this web page is inaccessible. All Qubes documentation, including
this page, is available in plain text format in the following Git
repository:
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
https://github.com/QubesOS/qubes-doc.git
8. Verify and decrypt the backed up data, decompress it, and extract it.
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
done | gzip -d | tar -xv
vm123/private.img
If this pipeline fails, it is likely that the backup is corrupted or has
been tampered with.
Also see the note in step 6 about substituting a different compression
program for `gzip`.
9. Mount `private.img` and access your data.
[user@restore ~]$ sudo mkdir /mnt/img
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
[user@restore ~]$ ls /mnt/img/home/user/
example_data_file.txt
...
Success! If you wish to recover data from more than one qube in your backup,
simply repeat steps 7, 8, and 9 for each additional qube.

6
user/how-to-guides/how-to-back-up-restore-and-migrate.md
View file

@ -160,6 +160,12 @@ out.
6. When you are ready, click **Next**. Qubes will proceed to restore from your
backup. Once the progress bar has completed, you may click **Finish**.
In case that applications are not shown, i.e. "No applications found", open the
settings of the qube -> select `Applications` -> click `Refresh applications`.
When a restored application qube refreshes, the application lists will open the template qubes on which it is based. In that case the template qube should also be restored, if it is missing the default qube will be assigned.
The updated list of the installed software can be seen on the left and adjusted accordingly to the user's needs.
**Note:** When restoring from a dom0 backup, a new directory will be created in
the current dom0 home directory, and the contents from the backup will be
placed inside this new directory. This is intentional, as it allows users to

2
user/how-to-guides/how-to-organize-your-qubes.md
View file

@ -89,7 +89,7 @@ the other. Alice's setup looks like this:
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
she doesn't want to get bogged down doing with all that and figures it
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
OS doesn't judge her this and just gives her the freedom to do things however
OS doesn't judge her for this and just gives her the freedom to do things however
she likes while keeping everything securely compartmentalized. At times like
these, she takes comfort in knowing that things can be messy and disorganized
*within* a qube while her overall digital life remains well-organized.

72
user/how-to-guides/how-to-update.md
View file

@ -17,6 +17,7 @@ Fully updating your Qubes OS system means updating:
- [dom0](/doc/glossary/#dom0)
- [templates](/doc/glossary/#template)
- [standalones](/doc/glossary/#standalone) (if you have any)
- [firmware](/doc/glossary/#firmware)
## Security updates
@ -65,10 +66,19 @@ If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal"
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Updating with direct commands such as <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
<b>Warning:</b> Updating with direct commands such as <code>dnf update</code> and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
</div>
Advanced users may wish to perform updates via the command-line interface. To update templates and standalones non-interactively, use the command `qubes-vm-update`, and to update dom0, use `qubes-dom0-update`. If you want to perform an update with more advanced user-configurable options (e.g., custom pre- or post-update scripts, custom workarounds), see: [update.qubes-dom0](/doc/salt/#updatequbes-dom0) and [update.qubes-vm](/doc/salt/#updatequbes-vm).
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
- If you are using Salt, one can use the following two Salt states.
- [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
- [update.qubes-vm](/doc/salt/#updatequbes-vm)
- Alternatively, use `qubes-dom0-update` to update dom0, and use `qubes-vm-update` to update domUs.
Using either of these methods has the same effect as updating via the Qubes Update tool.
Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
@ -83,3 +93,61 @@ In the case of Qubes OS itself, we will make an [announcement](/news/categories/
Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
## Microcode Updates
x86\_64 CPUs contain special low-level software called **microcode**, which
is used to implement certain instructions and runs on various processors that
are outside of Qubes OS's control. Most microcode is in an on-CPU ROM, but
CPU vendors provide patches that modify small parts of this microcode. These
patches can be loaded from the BIOS or by the OS.
The fixes for some QSBs require a microcode update to work. Furthermore,
microcode updates will sometimes fix vulnerabilities "silently". This means
that the vulnerability impacts the security of Qubes OS, but the Qubes OS
Security Team is not informed that a vulnerability exists, so no QSB is ever
issued. Therefore, it is critical to update microcode.
Intel provides microcode updates for all of their CPUs in a public Git
repository, and allows OS vendors (such as Qubes OS) to distribute the updates
free of charge. AMD, however, only provides microcode for server CPUs.
AMD client CPUs can only receive microcode updates via a system firmware
update. Worse, there is often a significant delay between when a vulnerability
becomes public and when firmware that includes updated microcode is available
to Qubes OS users. This is why Qubes OS recommends Intel CPUs instead of
AMD CPUs.
## Firmware updates
Modern computers have many processors other than those that run Qubes OS.
Furthermore, the main processor cores also run firmware, which is used to
boot the system and often provides some services at runtime. Both kinds
of firmware can have bugs and vulnerabilities, so it is critical to keep
them updated.
Some firmware is loaded by the OS at runtime.
Such firmware is provided by the `linux-firmware` package and can be updated the usual way.
Other devices have persistent firmware that must be updated manually.
Qubes OS supports updating system firmware in three different ways.
Which one to use depends on the device whose firmware is being updated.
- If a device is attached to a domU, it should be updated using **fwupd**.
fwupd is included in both Debian and Fedora repositories.
It requires Internet access to use, but you can use the updates proxy if you
need to update firmware from an offline VM. You can use either the
command-line `fwupdmgr` tool or any of the graphical interfaces to fwupd.
- If a device is attached to dom0, use the `qubes-fwupdmgr` command-line tool.
This tool uses fwupd internally, but it fetches firmware and metadata over
qrexec from the dom0 UpdateVM, rather than fetching them from the Internet.
Unfortunately, their is no graphical interface for this tool yet.
- System76 systems use a special update tool which is simpler than fwupd.
Support for this tool is currently in progress. Once it is finished,
users will be able to use the **system76-firmware-cli** command-line
tool to update the firmware.
Firmware updates are important on all systems, but they are especially
important on AMD client systems. These doesn't support loading microcode from
the OS, so firmware updates are the **only** way to obtain microcode updates.

59
user/how-to-guides/how-to-use-usb-devices.md
View file

@ -13,7 +13,7 @@ title: How to use USB devices
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/how-to-use-block-storage-devices/) page.
**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/).
**Note:** Attaching USB devices to qubes requires a [USB qube](/doc/usb-qubes/).
**Important security warning:** USB passthrough comes with many security implications.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**.
@ -28,15 +28,15 @@ Examples of valid cases for USB-passthrough:
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/ctap-proxy/).
But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
## Attaching And Detaching a USB Device
## Attaching and detaching a USB device
### With Qubes Device Manager
### With Qubes device manager
Click the device-manager-icon: ![device manager icon](/attachment/doc/media-removable.png)
A list of available devices appears.
USB-devices have a USB-icon to their right: ![usb icon](/attachment/doc/generic-usb.png)
Hover on one device to display a list of VMs you may attach it to.
Hover on one device to display a list of qubes you may attach it to.
Click one of those.
The USB device will be attached to it.
@ -44,11 +44,11 @@ You're done.
After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover on the attached device to display a list of running VMs.
Hover on the attached device to display a list of running qubes
The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it.
Click that and your device will be detached.
### With The Command Line Tool
### With the command line tool
In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
@ -74,7 +74,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
Now, you can use your USB device (camera in this case) in the `work` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
If you see the error `ERROR: qubes-usb-proxy not installed in the qube` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
When you finish, detach the device.
@ -87,20 +87,20 @@ sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
## Maintenance And Customisation
## Maintenance and customisation
### Creating And Using a USB qube
### Creating and using a USB qube
If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/).
### Installation Of `qubes-usb-proxy`
### Installation of `qubes-usb-proxy`
To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
If you receive this error: `ERROR: qubes-usb-proxy not installed in the qube`, you can install the `qubes-usb-proxy` with the package manager in the qube you want to attach the USB device to.
- Fedora:
```
@ -111,18 +111,19 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
sudo apt-get install qubes-usb-proxy
```
### Using USB Keyboards And Other Input Devices
### Using USB keyboards and other input devices
**Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing!
Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/).
### Finding The Right USB Controller
### Finding the right USB controller
Some USB devices are not compatible with the USB pass-through method Qubes employs.
In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it.
However, with this approach you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it.
You can find your controller and its BDF address using the method described below, using the command-line tools `lsusb` and `readlink`.
If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
@ -141,7 +142,7 @@ Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
(In this case, the device isn't fully identified)
The device is connected to USB bus \#3.
Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM.
Check which other devices are connected to the same bus, since *all* of them will be attached to the target qube.
To find the right controller, follow the usb bus:
@ -154,11 +155,29 @@ This should output something like:
```
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
```
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM.
For example, On R 4.0 the command would look something like
Now you see the path: the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the target qube, like this:
```
qvm-pci attach --persistent personal dom0:00_1a.0
```
It is possible that on some system configurations the readlink method produces output which is different from the example above,
For example, you might see output like this:
```
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
```
In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead.
### Identifying controllers using the Qube Manager
Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to.
Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices".
Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller".
They should look something like: `01:00.0 USB controller: Name of manufacturer`
The first part is the BDF address, in this example: `01:00.0`
If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation", while the added controller shows another manufacturer's name.
Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.

7
user/reference/glossary.md
View file

@ -88,6 +88,13 @@ domUs lack direct hardware access.
* Sometimes the term [VM](#vm) is used as a synonym for domU. This is
technically inaccurate, as [dom0](#dom0) is also a VM in Xen.
## firmware
Software that runs outside the control of the operating system.
Some firmware executes on the same CPU cores as Qubes OS does, but
all computers have many additional processors that the operating system
does not run on, and these computers also run firmware.
## HVM
Hardware-assisted Virtual Machine. Any fully virtualized, or hardware-assisted,

43
user/security-in-qubes/firewall.md
View file

@ -269,7 +269,8 @@ As an example we can take the use case of qube QubeDest running a web server lis
**1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
You can get this information using various methods, but only the first one can be used for `sys-net` outside world IP:
You can get this information using various methods.
Only the first method can be used for `sys-net` to find the external IP:
- by running this command in each qube: `ip -4 -br a | grep UP`
- using `qvm-ls -n`
@ -284,7 +285,12 @@ Note the IP addresses you will need, they will be required in the next steps.
For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, and that the IP address of sys-firewall is 10.137.1.z.
In the sys-net VM's Terminal, the first step is to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
When writing rules in sys-net, you can use `iif` or `iifname`.
`iif` is faster, but can change where interfaces are dynamically created and destroyed, eg. ppp0.
In that case use `iifname`, like this `iifname ens6`.
`iifname` can also match wildcards - `iifname "eth*"`
In the sys-net VM's Terminal, the first step is to define an nftables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
```
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@ -292,25 +298,24 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
> Note: the name `custom-dnat-qubeDST` is arbitrary
> Note: while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes
> Note: while we use a DNAT chain for a single qube, it's possible to have a single DNAT chain for multiple qubes
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
```
nft add rule qubes custom-dnat-qubeDEST iif == "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
nft add rule qubes custom-dnat-qubeDEST iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
```
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
```
nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
```
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
> If you want to expose the service on multiple interfaces, repeat steps 2 and 3 above, for each interface. Alternatively, you can leave out the interface completely.
> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
Verify the rules on the sys-net firewall correctly match the packets you want by looking at the counters: check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
```
nft list table ip qubes
@ -320,12 +325,12 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
```
chain custom-forward {
iif "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
}
chain custom-dnat-qubeDEST {
type nat hook prerouting priority filter + 1; policy accept;
iif "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
}
```
@ -351,18 +356,20 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-net`:
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iif == "ens6" saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
nft add rule qubes custom-dnat-qubeDEST iifname ens6 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
# allow forwarded traffic
nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
fi
~~~
**3. Route packets from the FirewallVM to the VM**
For the following example, we use the fact that the physical interface of sys-firewall, facing sys-net, is eth0. Furthermore, we assume that the target VM running the web server has the IP address 10.137.0.xx and that the IP address of sys-firewall is 10.137.1.z.
For the following example, we use the fact that the interface of sys-firewall facing sys-net, is eth0.
This is allocated to iifgroup 1.
Furthermore, we assume that the IP address of sys-firewall is 10.137.1.z, and the target VM running the web server has the IP address 10.137.0.xx.
In the sys-firewall VM's Terminal, add a DNAT chain that will contain routing rules:
In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
```
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@ -371,13 +378,13 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
```
nft add rule qubes custom-dnat-qubeDEST iif == "eth0" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
```
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
```
nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
```
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
@ -398,10 +405,10 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-firewall`:
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iif == "eth0" tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
# allow forwarded traffic
nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
fi
~~~

157
user/security-in-qubes/split-gpg-2.md Normal file
View file

@ -0,0 +1,157 @@
---
lang: en
layout: doc
permalink: /doc/split-gpg-2/
redirect_from:
- /en/doc/split-gpg-2/
- /doc/SplitGpg-2/
- /doc/UserDoc/SplitGpg-2/
- /doc/open-pgp-2/
- /en/doc/open-pgp-2/
- /doc/OpenPGP-2/
- /doc/UserDoc/OpenPGP-2/
ref: 568
title: Split GPG-2
---
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes app qube.
This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations -- such as encryption/decryption and signing -- to another, more trusted, network-isolated domain.
This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.
(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
[![split-gpg-diagram.png](/attachment/doc/split-gpg-diagram.png)](/attachment/doc/split-gpg-diagram.png)
This diagram presents an overview of the Split GPG architecture.
## Advantages of Split GPG vs. traditional GPG with a smart card
It is often thought that the use of smart cards for private key storage guarantees ultimate safety.
While this might be true (unless the attacker can find a usually-very-expensive-and-requiring-physical-presence way to extract the key from the smart card) but only with regards to the safety of the private key itself.
However, there is usually nothing that could stop the attacker from requesting the smart card to perform decryption of all the user documents the attacker has found or need to decrypt.
In other words, while protecting the user's private key is an important task, we should not forget that ultimately it is the user data that are to be protected and that the smart card chip has no way of knowing the requests to decrypt documents are now coming from the attacker's script and not from the user sitting in front of the monitor.
(Similarly the smart card doesn't make the process of digitally signing a document or a transaction in any way more secure -- the user cannot know what the chip is really signing.
Unfortunately this problem of signing reliability is not solvable by Split GPG.)
With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
This way it would be easy to spot unexpected requests to decrypt documents.
## Configuration
Create/Edit `/etc/qubes/policy.d/30-user-gpg2.policy` in dom0, and add a line like this:
```
qubes.Gpg2 + gpg-client-vm @default allow target=gpg-server-vm
```
Import/Generate your secret keys in the server domain.
For example:
```
gpg-server-vm$ gpg --import /path/to/my/secret-keys-export
gpg-server-vm$ gpg --import-ownertrust /path/to/my/ownertrust-export
```
or
```
gpg-server-vm$ gpg --gen-key
```
In dom0 enable the `split-gpg2-client` service in the client domain, for example via the command-line:
```shell
dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME> split-gpg2-client on
```
To verify if this was done correctly:
```shell
dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME>
```
Output should be:
```shell
split-gpg2-client on
```
Restart the client domain.
Export the **public** part of your keys and import them in the client domain.
Also import/set proper "ownertrust" values.
For example:
```
gpg-server-vm$ gpg --export > public-keys-export
gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
```
This should be enough to have it running:
```
gpg-client-vm$ gpg -K
/home/user/.gnupg/pubring.kbx
-----------------------------
sec# rsa2048 2019-12-18 [SC] [expires: 2021-12-17]
50C2035AF57B98CD6E4010F1B808E4BB07BA9EFB
uid [ultimate] test
ssb# rsa2048 2019-12-18 [E]
```
If you want change some server option copy `/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to `~/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix `.conf` in `~/.config/qubes-split-gpg2/conf.d/`.
If you have a passphrase on your keys and `gpg-agent` only shows the "keygrip" (something like the fingerprint of the private key) when asking for the passphrase, then make sure that you have imported the public key part in the server domain.
## Subkeys vs primary keys
split-gpg2 only knows a hash of the data being signed.
Therefore, it cannot differentiate between e.g. signatures of a piece of data or signatures of another key.
This means that a client can use split-gpg2 to sign other keys, which split-gpg1 did not allow.
To prevent this, split-gpg2 creates a new GnuPG home directory and imports the secret subkeys (**not** the primary key!) to it.
Clients will be able to use the secret parts of the subkeys, but not of the primary key.
If your primary key is able to sign data and certify other keys, and your only subkey can only perform encryption, this means that all signing will fail.
To make signing work again, generate a subkey that is capable of signing but **not** certification.
split-gpg2 does not generate this key for you, so you need to generate it yourself.
If you want to generate a key in software, use the `addkey` command of `gpg2 --edit-key`.
If you want to generate a key on a smartcard or other hardware token, use `addcardkey` instead.
## Advanced usage
There are a few option not described in this README.
See the comments in the example (config and the source code)[https://github.com/QubesOS/qubes-app-linux-split-gpg2/blob/main/qubes-split-gpg2.conf.example].
Similar to a smartcard, split-gpg2 only tries to protect the private key.
For advanced usages, consider if a specialized RPC service would be better.
It could do things like checking what data is singed, detailed logging, exposing the encrypted content only to a VM without network, etc.
Using split-gpg2 as the "backend" for split-gpg1 is known to work.
## Allow key generation
By setting `allow_keygen = yes` in `qubes-split-gpg2.conf` you can allow the client to generate new keys.
Normal usage should not need this.
**Warning**: This feature is new and not much tested.
Therefore it's not security supported!
## Copyright
Copyright (C) 2014 HW42 <hw42@ipsumj.de>\
Copyright (C) 2019 Marek Marczykowski-Górecki <marmarek@invisiblethingslab.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

6
user/security-in-qubes/split-gpg.md
View file

@ -16,6 +16,12 @@ ref: 168
title: Split GPG
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> This information concerns split-gpg.
The implementation has been updated to provide more features in split-gpg-2. Some incomplete information on split-gpg-2 is available <a href="https://www.qubes-os.org/doc/split-gpg-2/">here</a>
</div>
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes app qube.
This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations -- such as encryption/decryption and signing -- to another, more trusted, network-isolated domain.
This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.

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

19
user/troubleshooting/vpn-troubleshooting.md
View file

@ -30,4 +30,21 @@ After suspend/resume, OpenVPN may not automatically reconnect. In order to get i
After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected.
To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install.
To figure out the root of the problem, check the VPN logs in `/var/log/syslog` or use `journalctl`. The logs may reveal issues like missing OpenVPN libraries, which you can then install.
## `notify-send` induced failure
[Some VPN guides](https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061) use complex scripts that include a call to `notify-send`, yet some images may not contain this tool or may not have it working properly.
For instance calling `notify-send` on a `fedora-36` template VM gives:
```
Failed to execute child process “dbus-launch” (No such file or directory)
```
To check this tool is working properly run:
```bash
sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle
```
You should see the `info` message appear on the top of your screen.
If that is the case then `notify-send` is not the issue.
If it is not, and you have an error of some sort you can:
1. Remove all calls to `notify-send` from scripts you are using to start VPN
2. Use another template qube that has a working `notify-send` or find proper guide and make your current template run `notify-send` work properly.