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

Use extlinks extension

Browse source 
Provides an easy way to link to Github issues, Forum topics, Qubes website
and Wikipedia articles.
This commit is contained in:
parulin 2025-07-27 12:47:41 -04:00
parent ba609d123e
commit e17e04a1bb
No known key found for this signature in database
GPG key ID: BC3830B42F4BF1F5
90 changed files with 330 additions and 318 deletions
Download patch file Download diff file Expand all files Collapse all files

12
conf.py
View file

@ -33,6 +33,7 @@ release = '4.3'
html_static_path = ['attachment/doc']
extensions = [
'sphinx.ext.autosectionlabel',
'sphinx.ext.extlinks',
'sphinxnotes.strike',
'sphinx_reredirects'
]
@ -46,6 +47,17 @@ redirects = {
"developer/general/how-to-edit-the-documentation":"https://www.qubes-os.org/doc/how-to-edit-the-documentation/"
}
extlinks = {'issue': ('https://github.com/QubesOS/qubes-issues/issues/%s',
'issue #%s'),
'topic': ('https://forum.qubes-os.org/t/%s',
'forum topic #%s'),
'website': ('https://www.qubes-os.org/%s',
None),
'wikipedia': ('https://en.wikipedia.org/wiki/%s',
'%s'),
}
extlinks_detect_hardcoded_links = True
autosectionlabel_prefix_document = True
source_suffix = {

2
developer/building/qubes-builder.rst
View file

@ -9,7 +9,7 @@ Qubes builder
**Note: See** :doc:`ISO building instructions </developer/building/qubes-iso-building>` **for a streamlined overview on how to use the build system.**
We have a fully automated build system for Qubes, that downloads, builds and packages all the Qubes components, and finally should spit out a ready-to-use installation ISO, all in a `secure <https://www.qubes-os.org/news/2016/05/30/build-security/>`__ way.
We have a fully automated build system for Qubes, that downloads, builds and packages all the Qubes components, and finally should spit out a ready-to-use installation ISO, all in a :website:`secure <news/2016/05/30/build-security/>` way.
In order to use it, you should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed:

4
developer/building/qubes-iso-building.rst
View file

@ -113,7 +113,7 @@ Continue the build process with:
When building the Whonix templates, you will often need to add/update the ``WHONIX_TBB_VERSION`` variable in ``builder.conf`` at this stage to specify the currently shipping Tor Browser version. See the related note under `Extra Whonix Build Options <https://forum.qubes-os.org/t/18981>`__.
When building the Whonix templates, you will often need to add/update the ``WHONIX_TBB_VERSION`` variable in ``builder.conf`` at this stage to specify the currently shipping Tor Browser version. See the related note under :topic:`Extra Whonix Build Options <18981>`.
You may also want to add ``COMPONENTS := $(filter-out gcc,$(COMPONENTS))`` to bypass a multiple hour compile step. See :ref:`QubesBuilder <developer/building/qubes-builder:use pre-built qubes packages>` for more detail.
@ -202,7 +202,7 @@ Continue the build process with:
When building the Whonix templates, you will often need to add/update the ``WHONIX_TBB_VERSION`` variable at this stage to specify the currently shipping Tor Browser version. See the related note under `Extra Whonix Build Options <https://forum.qubes-os.org/t/18981>`__.
When building the Whonix templates, you will often need to add/update the ``WHONIX_TBB_VERSION`` variable at this stage to specify the currently shipping Tor Browser version. See the related note under :topic:`Extra Whonix Build Options <18981>`.
Finally, if you are making a test build, use:

2
developer/debugging/automated-tests.rst
View file

@ -7,7 +7,7 @@ Unit and Integration Tests
--------------------------
Starting with Qubes R3 we use `python unittest <https://docs.python.org/3/library/unittest.html>`__ to perform automatic tests of Qubes OS. Despite the name, we use it for both `unit tests <https://en.wikipedia.org/wiki/Unit_tests>`__ and `integration tests <https://en.wikipedia.org/wiki/Integration_tests>`__. The main purpose is, of course, to deliver much more stable releases.
Starting with Qubes R3 we use `python unittest <https://docs.python.org/3/library/unittest.html>`__ to perform automatic tests of Qubes OS. Despite the name, we use it for both :wikipedia:`unit tests <Unit_tests>` and :wikipedia:`integration tests <Integration_tests>`. The main purpose is, of course, to deliver much more stable releases.
The integration tests must be run in dom0, but some unit tests can run inside a VM as well.

2
developer/debugging/mount-lvm-image.rst
View file

@ -55,4 +55,4 @@ References
----------
Please consult this issue’s `comment <https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625>`__.
Please consult this issue’s :issue:`comment <4687#issuecomment-451626625>`.

2
developer/debugging/test-bench.rst
View file

@ -17,7 +17,7 @@ Install ISO
^^^^^^^^^^^
First, do a clean install from the ``.iso`` :doc:`you built </developer/building/qubes-iso-building>` or grabbed elsewhere (for example `here <https://forum.qubes-os.org/t/qubesos-4-1-alpha-signed-weekly-builds/3601>`__).
First, do a clean install from the ``.iso`` :doc:`you built </developer/building/qubes-iso-building>` or grabbed elsewhere (for example :topic:`here <qubesos-4-1-alpha-signed-weekly-builds/3601>`).
Enabling Network Access in Dom0
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2
developer/general/continuous-integration.rst
View file

@ -3,7 +3,7 @@ Continuous integration (CI)
===========================
This page explains the `continuous integration (CI) <https://en.wikipedia.org/wiki/Continuous_integration>`__ infrastructure that the Qubes OS Project uses.
This page explains the :wikipedia:`continuous integration (CI) <Continuous_integration>` infrastructure that the Qubes OS Project uses.
Website and documentation
-------------------------

60
developer/general/gsoc.rst
View file

@ -7,7 +7,7 @@ Information for Students
------------------------
Thank you for your interest in participating in the `Google Summer of Code program <https://summerofcode.withgoogle.com/>`__ with the `Qubes OS team <https://www.qubes-os.org/team/>`__. You can read more about the Google Summer of Code program at the `official website <https://summerofcode.withgoogle.com/>`__ and the `official FAQ <https://developers.google.com/open-source/gsoc/faq>`__.
Thank you for your interest in participating in the `Google Summer of Code program <https://summerofcode.withgoogle.com/>`__ with the :website:`Qubes OS team <team/>`. You can read more about the Google Summer of Code program at the `official website <https://summerofcode.withgoogle.com/>`__ and the `official FAQ <https://developers.google.com/open-source/gsoc/faq>`__.
Being accepted as a Google Summer of Code contributor is quite competitive. If you are interested in participating in the Summer of Code please be aware that you must be able to produce code for Qubes OS for 3-5 months. Your mentors, Qubes developers, will dedicate a portion of their time towards mentoring you. Therefore, we seek candidates who are committed to helping Qubes long-term and are willing to do quality work and be proactive in communicating with your mentor.
@ -149,7 +149,7 @@ Qubes as a Vagrant provider
**Size of the project**: 350 hours
**Mentor**: `Wojtek Porczyk <https://www.qubes-os.org/team/>`__, `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Wojtek Porczyk <team/>`, :website:`Marek Marczykowski-Górecki <team/>`
System health monitor
^^^^^^^^^^^^^^^^^^^^^
@ -157,7 +157,7 @@ System health monitor
**Project**: System health monitor
**Brief explanation**: A tool that informs the user about common system and configuration issues. Some of this is already available, but scattered across different places. See related issues: `6663 <https://github.com/QubesOS/qubes-issues/issues/6663>`__, `2134 <https://github.com/QubesOS/qubes-issues/issues/2134>`__
**Brief explanation**: A tool that informs the user about common system and configuration issues. Some of this is already available, but scattered across different places. See related issues: :issue:`6663`, :issue:`2134`
**Expected results**:
@ -193,7 +193,7 @@ System health monitor
**Size of the project**: 350 hours
**Mentor**: `Marta Marczykowska-Górecka <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marta Marczykowska-Górecka <team/>`
Mechanism for maintaining in-VM configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -225,7 +225,7 @@ Mechanism for maintaining in-VM configuration
**Size of the project**: 175 hours
**Mentor**: `Frédéric Pierret <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Frédéric Pierret <team/>`
Qubes Live USB
^^^^^^^^^^^^^^
@ -233,7 +233,7 @@ Qubes Live USB
**Project**: Revive Qubes Live USB, integrate it with installer
**Brief explanation**: Qubes Live USB is based on Fedora tools to build live distributions. But for Qubes we need some adjustments: starting Xen instead of Linux kernel, smarter copy-on-write handling (we run there multiple VMs, so a lot more data to save) and few more. Additionally in Qubes 3.2 we have so many default VMs that default installation does not fit in 16GB image (default value) - some subset of those VMs should be chosen. Ideally we’d like to have just one image being both live system and installation image. More details: `#1552 <https://github.com/QubesOS/qubes-issues/issues/1552>`__, `#1965 <https://github.com/QubesOS/qubes-issues/issues/1965>`__.
**Brief explanation**: Qubes Live USB is based on Fedora tools to build live distributions. But for Qubes we need some adjustments: starting Xen instead of Linux kernel, smarter copy-on-write handling (we run there multiple VMs, so a lot more data to save) and few more. Additionally in Qubes 3.2 we have so many default VMs that default installation does not fit in 16GB image (default value) - some subset of those VMs should be chosen. Ideally we’d like to have just one image being both live system and installation image. More details: :issue:`1552`, :issue:`1965`.
**Expected results**:
@ -263,7 +263,7 @@ Qubes Live USB
**Size of the project**: 350 hours
**Mentor**: `Frédéric Pierret <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Frédéric Pierret <team/>`
LogVM(s)
^^^^^^^^
@ -271,7 +271,7 @@ LogVM(s)
**Project**: LogVM(s)
**Brief explanation**: Qubes AppVMs do not have persistent /var (on purpose). It would be useful to send logs generated by various VMs to a dedicated log-collecting VM. This way logs will not only survive VM shutdown, but also be immune to altering past entries. See `#830 <https://github.com/QubesOS/qubes-issues/issues/830>`__ for details.
**Brief explanation**: Qubes AppVMs do not have persistent /var (on purpose). It would be useful to send logs generated by various VMs to a dedicated log-collecting VM. This way logs will not only survive VM shutdown, but also be immune to altering past entries. See :issue:`830` for details.
**Expected results**:
@ -301,7 +301,7 @@ LogVM(s)
**Size of the project**: 175 hours
**Mentor**: `Frédéric Pierret <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Frédéric Pierret <team/>`
Whonix IPv6 and nftables support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -339,7 +339,7 @@ Whonix IPv6 and nftables support
**Size of the project**: 175 hours
**Mentor**: `Patrick Schleizer <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Patrick Schleizer <team/>`
GUI agent for Windows 8/10
^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -347,7 +347,7 @@ GUI agent for Windows 8/10
**Project**: GUI agent for Windows 8/10
**Brief explanation**: Add support for Windows 8+ to the Qubes GUI agent and video driver. Starting from Windows 8, Microsoft requires all video drivers to conform to the WDDM display driver model which is incompatible with the current Qubes video driver. Unfortunately the WDDM model is much more complex than the old XPDM one and officially *requires* a physical GPU device (which may be emulated). Some progress has been made to create a full WDDM driver that *doesn’t* require a GPU device, but the driver isn’t working correctly yet. Alternatively, WDDM model supports display-only drivers which are much simpler but don’t have access to system video memory and rendering surfaces (a key feature that would simplify seamless GUI mode). `#1861 <https://github.com/QubesOS/qubes-issues/issues/1861>`__
**Brief explanation**: Add support for Windows 8+ to the Qubes GUI agent and video driver. Starting from Windows 8, Microsoft requires all video drivers to conform to the WDDM display driver model which is incompatible with the current Qubes video driver. Unfortunately the WDDM model is much more complex than the old XPDM one and officially *requires* a physical GPU device (which may be emulated). Some progress has been made to create a full WDDM driver that *doesn’t* require a GPU device, but the driver isn’t working correctly yet. Alternatively, WDDM model supports display-only drivers which are much simpler but don’t have access to system video memory and rendering surfaces (a key feature that would simplify seamless GUI mode). :issue:`1861`
**Expected results**: Working display-only WDDM video driver or significant progress towards making the full WDDM driver work correctly.
@ -357,7 +357,7 @@ GUI agent for Windows 8/10
**Size of the project**: 175 hours
**Mentor**: `Rafał Wojdyła <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Rafał Wojdyła <team/>`
GNOME support in dom0 / GUI VM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -373,7 +373,7 @@ GNOME support in dom0 / GUI VM
- adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place)
- More info: `#1806 <https://github.com/QubesOS/qubes-issues/issues/1806>`__
- More info: :issue:`1806`
@ -409,7 +409,7 @@ GNOME support in dom0 / GUI VM
**Size of the project**: 175 hours
**Mentor**: `Frédéric Pierret <https://www.qubes-os.org/team/>`__, `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Frédéric Pierret <team/>`, :website:`Marek Marczykowski-Górecki <team/>`
Generalize the Qubes PDF Converter to other types of files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -437,7 +437,7 @@ Progress towards reproducible builds
**Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See:
- “`Security challenges for the Qubes build process <https://www.qubes-os.org/news/2016/05/30/build-security/>`__”
- “:website:`Security challenges for the Qubes build process <news/2016/05/30/build-security/>`”
- `This mailing list post <https://groups.google.com/d/msg/qubes-devel/gq-wb9wTQV8/mdliS4P2BQAJ>`__
@ -455,7 +455,7 @@ for more information and qubes-specific background.
**Size of the project**: 350 hours
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`
Porting Qubes to ARM/aarch64
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -469,9 +469,9 @@ Qubes currently only supports the x86_64 CPU architecture. Xen currently has add
Some related discussion:
- `#4318 <https://github.com/QubesOS/qubes-issues/issues/4318>`__ on porting to ppc64.
- :issue:`4318` on porting to ppc64.
- `#3894 <https://github.com/QubesOS/qubes-issues/issues/3894>`__ on porting to L4 microkernel.
- :issue:`3894` on porting to L4 microkernel.
@ -501,7 +501,7 @@ Some related discussion:
**Size of the project**: 350 hours
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`
Android development in Qubes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -509,7 +509,7 @@ Android development in Qubes
**Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio
**Brief explanation**: The goal is to enable Android development (and testing!) on Qubes OS. Currently it’s only possible using qemu-emulated Android for ARM. Since it’s software emulation it’s rather slow. Details, reference: `#2233 <https://github.com/QubesOS/qubes-issues/issues/2233>`__
**Brief explanation**: The goal is to enable Android development (and testing!) on Qubes OS. Currently it’s only possible using qemu-emulated Android for ARM. Since it’s software emulation it’s rather slow. Details, reference: :issue:`2233`
**Expected results**:
@ -533,11 +533,11 @@ Admin API Fuzzer
^^^^^^^^^^^^^^^^
**Project**: Develop a `Fuzzer <https://en.wikipedia.org/wiki/Fuzzing>`__ for the :doc:`Qubes OS Admin API </developer/services/admin-api>`.
**Project**: Develop a :wikipedia:`Fuzzer <Fuzzing>` for the :doc:`Qubes OS Admin API </developer/services/admin-api>`.
**Brief explanation**: The :doc:`Qubes OS Admin API </developer/services/admin-api>` enables VMs to execute privileged actions on other VMs or dom0 - if allowed by the Qubes OS RPC policy. Programming errors in the Admin API however may cause these access rights to be more permissive than anticipated by the programmer.
Since the Admin API is continuously growing and changing, continuous security assessments are required. A `Fuzzer <https://en.wikipedia.org/wiki/Fuzzing>`__ would help to automate part of these assessments.
Since the Admin API is continuously growing and changing, continuous security assessments are required. A :wikipedia:`Fuzzer <Fuzzing>` would help to automate part of these assessments.
**Expected results**:
@ -569,7 +569,7 @@ Secure Boot support
**Project**: Add support for protecting boot binaries with Secure Boot technology, using user-generated keys.
**Brief explanation**: Since recently, Xen supports “unified EFI boot” which allows to sign not only Xen binary itself, but also dom0 kernel and their parameters. While the base technology is there, enabling it is a painful and complex process. The goal of this project is to integrate configuration of this feature into Qubes, automating as much as possible. See discussion in `issue #4371 <https://github.com/QubesOS/qubes-issues/issues/4371>`__
**Brief explanation**: Since recently, Xen supports “unified EFI boot” which allows to sign not only Xen binary itself, but also dom0 kernel and their parameters. While the base technology is there, enabling it is a painful and complex process. The goal of this project is to integrate configuration of this feature into Qubes, automating as much as possible. See discussion in :issue:`4371`
**Expected results**:
@ -593,7 +593,7 @@ Secure Boot support
**Size of the project**: 175 hours
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`
Reduce logging of Disposable VMs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -601,7 +601,7 @@ Reduce logging of Disposable VMs
**Project**: Reduce logging of Disposable VMs
**Brief explanation**: Partial metadata of a DisposableVM is stored in the dom0 filesystem. This applies to various logs, GUI status files etc. There should be an option to hide as much of that as possible - including bypassing some logging, and removing various state files, or at the very least obfuscating any hints what is running inside DisposableVM. More details at `issue #4972 <https://github.com/QubesOS/qubes-issues/issues/4972>`__
**Brief explanation**: Partial metadata of a DisposableVM is stored in the dom0 filesystem. This applies to various logs, GUI status files etc. There should be an option to hide as much of that as possible - including bypassing some logging, and removing various state files, or at the very least obfuscating any hints what is running inside DisposableVM. More details at :issue:`4972`
**Expected results**: A DisposableVM should not leave logs hinting what was running inside.
@ -617,7 +617,7 @@ Reduce logging of Disposable VMs
**Size of the project**: 350 hours
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`
Past Projects
-------------
@ -633,7 +633,7 @@ Template manager, new template distribution mechanism
**Project**: Template manager, new template distribution mechanism
**Brief explanation**: Template VMs currently are distributed using RPM packages. There are multiple problems with that, mostly related to static nature of RPM package (what files belong to the package). This means such Template VM cannot be renamed, migrated to another storage (like LVM), etc. Also we don’t want RPM to automatically update template package itself (which would override all the user changes there). More details: `#2064 <https://github.com/QubesOS/qubes-issues/issues/2064>`__, `#2534 <https://github.com/QubesOS/qubes-issues/issues/2534>`__, `#3573 <https://github.com/QubesOS/qubes-issues/issues/3573>`__.
**Brief explanation**: Template VMs currently are distributed using RPM packages. There are multiple problems with that, mostly related to static nature of RPM package (what files belong to the package). This means such Template VM cannot be renamed, migrated to another storage (like LVM), etc. Also we don’t want RPM to automatically update template package itself (which would override all the user changes there). More details: :issue:`2064`, :issue:`2534`, :issue:`3573`.
**Expected results**:
@ -647,7 +647,7 @@ Template manager, new template distribution mechanism
- template metadata, templates repository - enable the user to browse available templates (probably should be done in dedicated VM, or DisposableVM)
- manual template removal by users (without it, see problems such as `#5509 <https://github.com/QubesOS/qubes-issues/issues/5509>`__
- manual template removal by users (without it, see problems such as :issue:`5509`
@ -657,7 +657,7 @@ Template manager, new template distribution mechanism
- tool to browse templates repository - both CLI and GUI (preferably integrated with existing Template Manager tool)
- integrate both tools - user should be able to choose some template to be installed from repository browsing tool - see `#1705 <https://github.com/QubesOS/qubes-issues/issues/1705>`__ for some idea (this one lacks integrity verification, but a similar service could be developed with that added)
- integrate both tools - user should be able to choose some template to be installed from repository browsing tool - see :issue:`1705` for some idea (this one lacks integrity verification, but a similar service could be developed with that added)
@ -683,7 +683,7 @@ Template manager, new template distribution mechanism
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`
----

14
developer/general/gsod.rst
View file

@ -3,7 +3,7 @@ Google Season of Docs (GSoD)
============================
Thank you for your interest in participating in the `2024 Google Season of Docs <https://developers.google.com/season-of-docs/>`__ program with the `Qubes OS team <https://www.qubes-os.org/team/>`__. This page details our 2024 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official `guides <https://developers.google.com/season-of-docs/docs/>`__ and `FAQ <https://developers.google.com/season-of-docs/docs/faq>`__.
Thank you for your interest in participating in the `2024 Google Season of Docs <https://developers.google.com/season-of-docs/>`__ program with the :website:`Qubes OS team <team/>`. This page details our 2024 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official `guides <https://developers.google.com/season-of-docs/docs/>`__ and `FAQ <https://developers.google.com/season-of-docs/docs/faq>`__.
Update and Expand How-To Guides – Qubes OS
------------------------------------------
@ -15,7 +15,7 @@ About the Qubes OS Project
Qubes OS is a security-focused operating system that allows you to organize your digital life into compartments called “qubes.” If one qube is compromised, the others remain safe, so a single cyberattack can no longer take down your entire digital life in one fell swoop. You can think of using Qubes OS as having many different computers on your desk for different activities but with the convenience of a single physical machine, a single unified desktop environment, and a set of tools for using qubes together securely as parts of a unified system.
Qubes OS was launched in 2011 and has `received praise from security experts and organizations <https://www.qubes-os.org/endorsements/>`__ like Edward Snowden, the Freedom of the Press Foundation, Micah Lee, and Let’s Encrypt. Qubes has :doc:`over 40,000 active users </introduction/statistics>`. From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done safely.
Qubes OS was launched in 2011 and has :website:`received praise from security experts and organizations <endorsements/>` like Edward Snowden, the Freedom of the Press Foundation, Micah Lee, and Let’s Encrypt. Qubes has :doc:`over 40,000 active users </introduction/statistics>`. From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done safely.
The project's problem
^^^^^^^^^^^^^^^^^^^^^
@ -262,7 +262,7 @@ Consolidate troubleshooting guides
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`
Improve Getting Started page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -270,7 +270,7 @@ Improve Getting Started page
**Project**: Improve Getting Started page
**Brief explanation**: The :doc:`Getting Started page </introduction/getting-started>` is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the `offline documentation <https://github.com/QubesOS/qubes-issues/issues/1019>`__ or the firstboot guide.
**Brief explanation**: The :doc:`Getting Started page </introduction/getting-started>` is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the :issue:`offline documentation <1019>` or the firstboot guide.
**Expected results**:
@ -288,7 +288,7 @@ Improve Getting Started page
**Mentor**: `Michael Carbone <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Michael Carbone <team/>`
Rewrite qrexec documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -300,7 +300,7 @@ Rewrite qrexec documentation
**Expected results**:
- Review existing :doc:`qrexec documentation </developer/services/qrexec>` and an `issue about it <https://github.com/QubesOS/qubes-issues/issues/1392>`__
- Review existing :doc:`qrexec documentation </developer/services/qrexec>` and an :issue:`issue about it <1392>`
- Propose updated, consolidated admin documentation (policy writing, adding services)
@ -314,4 +314,4 @@ Rewrite qrexec documentation
**Mentor**: `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/>`__
**Mentor**: :website:`Marek Marczykowski-Górecki <team/>`

10
developer/general/research.rst
View file

@ -57,10 +57,10 @@ Compartmentalization, Isolation, and Separation
The Qubes Architecture
======================
- `Qubes virtual mini-summit 2021 <https://www.qubes-os.org/news/2021/07/30/minisummit-agenda/>`__ by 3mdeb and the Qubes team, August 2021
- `Qubes Air: Generalizing the Qubes Architecture <https://www.qubes-os.org/news/2018/01/22/qubes-air/>`__ by Joanna Rutkowska, January 2018
- `Introducing the Next Generation Qubes Core Stack <https://www.qubes-os.org/news/2017/10/03/core3/>`__ by Joanna Rutkowska, October 2017
- `Introducing the Qubes Admin API <https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/>`__ by Joanna Rutkowska, June 2017
- `Qubes OS Architecture Spec v0.3 <https://www.qubes-os.org/attachment/doc/arch-spec-0.3.pdf>`__ by Joanna Rutkowska and Rafal Wojtczuk, January 2010
- :website:`Qubes virtual mini-summit 2021 <news/2021/07/30/minisummit-agenda/>` by 3mdeb and the Qubes team, August 2021
- :website:`Qubes Air: Generalizing the Qubes Architecture <news/2018/01/22/qubes-air/>` by Joanna Rutkowska, January 2018
- :website:`Introducing the Next Generation Qubes Core Stack <news/2017/10/03/core3/>` by Joanna Rutkowska, October 2017
- :website:`Introducing the Qubes Admin API <news/2017/06/27/qubes-admin-api/>` by Joanna Rutkowska, June 2017
- :website:`Qubes OS Architecture Spec v0.3 <attachment/doc/arch-spec-0.3.pdf>` by Joanna Rutkowska and Rafal Wojtczuk, January 2010

6
developer/general/usability-ux.rst
View file

@ -5,7 +5,7 @@ Usability & UX
Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority!
We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review `our visual style guide <https://www.qubes-os.org/doc/visual-style-guide/>`__ for other design related information.
We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review :website:`our visual style guide <doc/visual-style-guide/>` for other design related information.
----
@ -43,7 +43,7 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura
In making software easy to use, it is crucial to be mindful of `cognitive load <https://en.wikipedia.org/wiki/Cognitive_load>`__ which dictates that *“humans are generally able to hold only seven +/- two units of information in short-term memory.”* Making sure your interfaces don’t pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
In making software easy to use, it is crucial to be mindful of :wikipedia:`cognitive load <Cognitive_load>` which dictates that *“humans are generally able to hold only seven +/- two units of information in short-term memory.”* Making sure your interfaces don’t pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
----
@ -269,7 +269,7 @@ The desktop GUIs that QubesOS versions 1 - 4.1 offer are `KDE <https://kde.org>`
This change means you should use `GTK <https://gtk.org/>`__ rather than Qt for new GUIs.
All three of these mentioned desktop environments have their own `human interface guidelines <https://en.wikipedia.org/wiki/Human_interface_guidelines>`__, and we suggest you familiarize yourself with the platform you developing for.
All three of these mentioned desktop environments have their own :wikipedia:`human interface guidelines <Human_interface_guidelines>`, and we suggest you familiarize yourself with the platform you developing for.
- `GNOME Human Interface Guidelines <https://developer.gnome.org/hig/>`__

2
developer/releases/1_0/release-notes.rst
View file

@ -32,7 +32,7 @@ Downloads
---------
See `Qubes Downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`Qubes Downloads <downloads/>`.
Installation instructions
-------------------------

2
developer/releases/2_0/release-notes.rst
View file

@ -61,7 +61,7 @@ Downloads
---------
See `Qubes Downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`Qubes Downloads <downloads/>`.
Installation instructions
-------------------------

2
developer/releases/3_0/release-notes.rst
View file

@ -53,7 +53,7 @@ Downloads
^^^^^^^^^
See `Qubes Downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`Qubes Downloads <downloads/>`.
Installation instructions
^^^^^^^^^^^^^^^^^^^^^^^^^

2
developer/releases/3_1/release-notes.rst
View file

@ -53,7 +53,7 @@ Downloads
---------
See `Qubes Downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`Qubes Downloads <downloads/>`.
Installation instructions
-------------------------

8
developer/releases/3_2/release-notes.rst
View file

@ -21,7 +21,7 @@ New features since 3.1
- Tiling window managers support: awesome, :doc:`i3 </user/advanced-topics/i3>`
- More flexible Qubes RPC services - `related ticket <https://github.com/QubesOS/qubes-issues/issues/1876>`__, :ref:`documentation <developer/services/qrexec:service policies with arguments>`
- More flexible Qubes RPC services - :issue:`related ticket <1876>`, :ref:`documentation <developer/services/qrexec:service policies with arguments>`
@ -31,7 +31,7 @@ Known issues
------------
- `Fedora 23 reached EOL in December 2016 <https://fedoraproject.org/wiki/End_of_life>`__. There is a `manual procedure to upgrade your VMs <https://www.qubes-os.org/news/2018/01/06/fedora-26-upgrade/>`__.
- `Fedora 23 reached EOL in December 2016 <https://fedoraproject.org/wiki/End_of_life>`__. There is a :website:`manual procedure to upgrade your VMs <news/2018/01/06/fedora-26-upgrade/>`.
- Windows Tools: ``qvm-block`` does not work
@ -47,13 +47,13 @@ Downloads
---------
See `Qubes Downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`Qubes Downloads <downloads/>`.
Installation instructions
-------------------------
See :doc:`Installation Guide </user/downloading-installing-upgrading/installation-guide>`. After installation, `manually upgrade to Fedora 26 <https://www.qubes-os.org/news/2018/01/06/fedora-26-upgrade/>`__.
See :doc:`Installation Guide </user/downloading-installing-upgrading/installation-guide>`. After installation, :website:`manually upgrade to Fedora 26 <news/2018/01/06/fedora-26-upgrade/>`.
Upgrading
---------

30
developer/releases/4_0/release-notes.rst
View file

@ -9,37 +9,37 @@ New features since 3.2
- Core management scripts rewrite with better structure and extensibility, `current API documentation <https://dev.qubes-os.org/projects/core-admin/en/latest/>`__ and the documentation API index as a `webarchive <https://web.archive.org/web/20230128102821/https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/>`__
- `Admin API <https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/>`__ allowing strictly controlled managing from non-dom0
- :website:`Admin API <news/2017/06/27/qubes-admin-api/>` allowing strictly controlled managing from non-dom0
- All ``qvm-*`` command-line tools rewritten, some options have changed
- Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM
- Use `PVH <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt>`__ and `HVM <https://github.com/QubesOS/qubes-issues/issues/2185>`__ by default to `mitigate Meltdown & Spectre <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt>`__ and lower the `attack surface on Xen <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt>`__
- Use `PVH <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt>`__ and :issue:`HVM <2185>` by default to `mitigate Meltdown & Spectre <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt>`__ and lower the `attack surface on Xen <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt>`__
- Create USB VM by default
- `Multiple DisposableVMs templates support <https://github.com/QubesOS/qubes-issues/issues/2253>`__
- :issue:`Multiple DisposableVMs templates support <2253>`
- New :doc:`backup format </user/how-to-guides/backup-emergency-restore-v4>` using scrypt key-derivation function
- Non-encrypted backups no longer supported
- `split VM packages <https://github.com/QubesOS/qubes-issues/issues/2771>`__, for better support minimal, specialized templates
- :issue:`split VM packages <2771>`, for better support minimal, specialized templates
- `Qubes Manager decomposition <https://github.com/QubesOS/qubes-issues/issues/2132>`__ - domains and devices widgets instead of full Qubes Manager; devices widget support also USB
- :issue:`Qubes Manager decomposition <2132>` - domains and devices widgets instead of full Qubes Manager; devices widget support also USB
- :doc:`More flexible firewall interface </developer/debugging/vm-interface>` for ease unikernel integration
- Template VMs do not have network interface by default, `qrexec-based updates proxy <https://github.com/QubesOS/qubes-issues/issues/1854>`__ is used instead
- Template VMs do not have network interface by default, :issue:`qrexec-based updates proxy <1854>` is used instead
- More flexible IP addressing for VMs - `custom IP <https://github.com/QubesOS/qubes-issues/issues/1477>`__, `hidden from the IP <https://github.com/QubesOS/qubes-issues/issues/1143>`__
- More flexible IP addressing for VMs - :issue:`custom IP <1477>`, :issue:`hidden from the IP <1143>`
- More flexible Qubes RPC policy - `related ticket <https://github.com/QubesOS/qubes-issues/issues/865>`__, :ref:`documentation <developer/services/qrexec:specifying vms: tags, types, targets, etc.>`
- More flexible Qubes RPC policy - :issue:`related ticket <865>`, :ref:`documentation <developer/services/qrexec:specifying vms: tags, types, targets, etc.>`
- `New Qubes RPC confirmation window <https://github.com/QubesOS/qubes-issues/issues/910>`__, including option to specify destination VM
- :issue:`New Qubes RPC confirmation window <910>`, including option to specify destination VM
- `New storage subsystem design <https://github.com/QubesOS/qubes-issues/issues/1842>`__
- :issue:`New storage subsystem design <1842>`
- Dom0 update to Fedora 25 for better hardware support
@ -55,7 +55,7 @@ Security Notes
- PV VMs migrated from 3.2 to 4.0-rc4 or later are automatically set to PVH mode in order to protect against Meltdown (see `QSB #37 <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt>`__). However, PV VMs migrated from any earlier 4.0 release candidate (RC1, RC2, or RC3) are not automatically set to PVH mode. These must be set manually.
- The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see `#3737 <https://github.com/QubesOS/qubes-issues/issues/3737>`__).
- The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see :issue:`3737`).
Steps for dom0 updates:
1. Open the Qubes Menu by clicking on the “Q” icon in the top-left corner of the screen.
@ -110,15 +110,15 @@ Known issues
------------
- Locale using coma as decimal separator `crashes qubesd <https://github.com/QubesOS/qubes-issues/issues/3753>`__. Either install with different locale (English (United States) for example), or manually apply fix explained in that issue.
- Locale using coma as decimal separator :issue:`crashes qubesd <3753>`. Either install with different locale (English (United States) for example), or manually apply fix explained in that issue.
- In the middle of installation, `keyboard layout reset to US <https://github.com/QubesOS/qubes-issues/issues/3352>`__. Be careful what is the current layout while setting default user password (see upper right screen corner).
- In the middle of installation, :issue:`keyboard layout reset to US <3352>`. Be careful what is the current layout while setting default user password (see upper right screen corner).
- On some laptops (for example Librem 15v2), touchpad do not work directly after installation. Reboot the system to fix the issue.
- List of USB devices may contain device identifiers instead of name
- With R4.0.1, which ships kernel-4.19, you may never reach the anaconda startup and be block on an idle black screen with blinking cursor. You can try to add ``plymouth.ignore-serial-consoles`` in the grub installer boot menu right after ``quiet rhgb``. With legacy mode, you can do it directly when booting the DVD or USB key. In UEFI mode, follow the same procedure described for :ref:`disabling <user/troubleshooting/uefi-troubleshooting:installation freezes before displaying installer>` ``nouveau`` module (related `solved issue <https://github.com/QubesOS/qubes-issues/issues/3849>`__ in further version of Qubes).
- With R4.0.1, which ships kernel-4.19, you may never reach the anaconda startup and be block on an idle black screen with blinking cursor. You can try to add ``plymouth.ignore-serial-consoles`` in the grub installer boot menu right after ``quiet rhgb``. With legacy mode, you can do it directly when booting the DVD or USB key. In UEFI mode, follow the same procedure described for :ref:`disabling <user/troubleshooting/uefi-troubleshooting:installation freezes before displaying installer>` ``nouveau`` module (related :issue:`solved issue <3849>` in further version of Qubes).
- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+4.0%22+label%3Abug>`__
@ -130,7 +130,7 @@ Downloads
---------
See `Qubes Downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`Qubes Downloads <downloads/>`.
Installation instructions
-------------------------

16
developer/releases/4_1/release-notes.rst
View file

@ -7,9 +7,9 @@ New features and improvements since Qubes 4.0
---------------------------------------------
- Optional qubes-remote-support package now available from repositories (strictly opt-in, no package installed by default; no new ports or network connections open by default; requires explicit connection initiation by the user, then requires sharing a code word with the remote party before a connection can be established; see `#6364 <https://github.com/QubesOS/qubes-issues/issues/6364>`__ for more information)
- Optional qubes-remote-support package now available from repositories (strictly opt-in, no package installed by default; no new ports or network connections open by default; requires explicit connection initiation by the user, then requires sharing a code word with the remote party before a connection can be established; see :issue:`6364` for more information)
- Qubes firewall reworked to be more defensive (see `#5540 <https://github.com/QubesOS/qubes-issues/issues/5540>`__ for details)
- Qubes firewall reworked to be more defensive (see :issue:`5540` for details)
- Xen upgraded to version 4.14
@ -19,7 +19,7 @@ New features and improvements since Qubes 4.0
- Upgraded default template releases
- Experimental support for GUI running outside of dom0 (hybrid mode GUI domain without real GPU passthrough; see `#5662 <https://github.com/QubesOS/qubes-issues/issues/5662>`__ for details)
- Experimental support for GUI running outside of dom0 (hybrid mode GUI domain without real GPU passthrough; see :issue:`5662` for details)
- Experimental support for audio server running outside of dom0 (“Audio domain”)
@ -27,15 +27,15 @@ New features and improvements since Qubes 4.0
- UEFI boot now loads GRUB, which in turn loads Xen, making the boot path similar to legacy boot and allowing the user to modify boot parameters or choose an alternate boot menu entry
- New qrexec policy format (see `#4370 <https://github.com/QubesOS/qubes-issues/issues/4370>`__ for details)
- New qrexec policy format (see :issue:`4370` for details)
- qrexec protocol improvements (see `#4909 <https://github.com/QubesOS/qubes-issues/issues/4909>`__ for details)
- qrexec protocol improvements (see :issue:`4909` for details)
- New qrexec-policy daemon
- Simplified using in-qube kernels
- Windows USB and audio support courtesy of `tabit-pro <https://github.com/tabit-pro>`__ (see `#5802 <https://github.com/QubesOS/qubes-issues/issues/5802>`__ and `#2624 <https://github.com/QubesOS/qubes-issues/issues/2624>`__)
- Windows USB and audio support courtesy of `tabit-pro <https://github.com/tabit-pro>`__ (see :issue:`5802` and :issue:`2624`)
- Clarified disposable-related terminology and properties
@ -85,7 +85,7 @@ New features and improvements since Qubes 4.0
- ``qvm-run`` tool got ``--no-shell`` option to run a single command without using a shell inside the qube
- MAC Randomization for iwlwifi (see `#938 <https://github.com/QubesOS/qubes-issues/issues/938>`__)
- MAC Randomization for iwlwifi (see :issue:`938`)
@ -101,7 +101,7 @@ Download
--------
See `downloads <https://www.qubes-os.org/downloads/>`__.
See :website:`downloads <downloads/>`.
Installation instructions
-------------------------

34
developer/releases/4_2/release-notes.rst
View file

@ -7,43 +7,43 @@ New features and improvements since Qubes 4.1
---------------------------------------------
- Dom0 upgraded to Fedora 37 (`#6982 <https://github.com/QubesOS/qubes-issues/issues/6982>`__)
- Dom0 upgraded to Fedora 37 (:issue:`6982`)
- Xen upgraded to version 4.17
- Default Debian template upgraded to Debian 12
- Default Fedora and Debian templates use Xfce instead of GNOME (`#7784 <https://github.com/QubesOS/qubes-issues/issues/7784>`__)
- Default Fedora and Debian templates use Xfce instead of GNOME (:issue:`7784`)
- SELinux support in Fedora templates (`#4239 <https://github.com/QubesOS/qubes-issues/issues/4239>`__)
- SELinux support in Fedora templates (:issue:`4239`)
- Several GUI applications rewritten (screenshots below), including:
- Applications Menu (also available as preview in R4.1) (`#6665 <https://github.com/QubesOS/qubes-issues/issues/6665>`__), (`#5677 <https://github.com/QubesOS/qubes-issues/issues/5677>`__)
- Applications Menu (also available as preview in R4.1) (:issue:`6665`), (:issue:`5677`)
- Qubes Global Settings (`#6898 <https://github.com/QubesOS/qubes-issues/issues/6898>`__)
- Qubes Global Settings (:issue:`6898`)
- Create New Qube
- Qubes Update (`#7443 <https://github.com/QubesOS/qubes-issues/issues/7443>`__)
- Qubes Update (:issue:`7443`)
- New ``qubes-vm-update`` tool (`#7443 <https://github.com/QubesOS/qubes-issues/issues/7443>`__)
- New ``qubes-vm-update`` tool (:issue:`7443`)
- Unified ``grub.cfg`` location for both UEFI and legacy boot (`#7985 <https://github.com/QubesOS/qubes-issues/issues/7985>`__)
- Unified ``grub.cfg`` location for both UEFI and legacy boot (:issue:`7985`)
- PipeWire support (`#6358 <https://github.com/QubesOS/qubes-issues/issues/6358>`__)
- PipeWire support (:issue:`6358`)
- fwupd integration for firmware updates (`#4855 <https://github.com/QubesOS/qubes-issues/issues/4855>`__)
- fwupd integration for firmware updates (:issue:`4855`)
- Optional automatic clipboard clearing (`#3415 <https://github.com/QubesOS/qubes-issues/issues/3415>`__)
- Optional automatic clipboard clearing (:issue:`3415`)
- Official packages built using Qubes Builder v2 (`#6486 <https://github.com/QubesOS/qubes-issues/issues/6486>`__)
- Official packages built using Qubes Builder v2 (:issue:`6486`)
- Split GPG management in Qubes Global Settings
- Qrexec services use new qrexec policy format by default (but old format is still supported) (`#8000 <https://github.com/QubesOS/qubes-issues/issues/8000>`__)
- Qrexec services use new qrexec policy format by default (but old format is still supported) (:issue:`8000`)
- Improved keyboard layout switching
@ -67,9 +67,9 @@ Known issues
------------
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the ``custom-input`` and ``custom-forward`` chains. (For more information, see issues `#5031 <https://github.com/QubesOS/qubes-issues/issues/5031>`__ and `#6062 <https://github.com/QubesOS/qubes-issues/issues/6062>`__.)
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the ``custom-input`` and ``custom-forward`` chains. (For more information, see issues :issue:`5031` and :issue:`6062`.)
- Templates restored in 4.2 from a pre-4.2 backup continue to target their original Qubes OS release repos. If you are using fresh templates on a clean 4.2 installation, or if you performed an :ref:`in-place upgrade from 4.1 to 4.2 <user/downloading-installing-upgrading/upgrade/4_2:in-place upgrade>`, then this does not affect you. (For more information, see issue `#8701 <https://github.com/QubesOS/qubes-issues/issues/8701>`__.)
- Templates restored in 4.2 from a pre-4.2 backup continue to target their original Qubes OS release repos. If you are using fresh templates on a clean 4.2 installation, or if you performed an :ref:`in-place upgrade from 4.1 to 4.2 <user/downloading-installing-upgrading/upgrade/4_2:in-place upgrade>`, then this does not affect you. (For more information, see issue :issue:`8701`.)
@ -83,7 +83,7 @@ Notes
- Qubes 4.2 does not support Debian 11 templates (see :ref:`supported template releases <user/downloading-installing-upgrading/supported-releases:templates>`). Please :ref:`upgrade your Debian templates <user/templates/debian/debian:upgrading>` to Debian 12.
- Qubes 4.2.2 includes a fix for `#8332: File-copy qrexec service is overly restrictive <https://github.com/QubesOS/qubes-issues/issues/8332>`__. As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability.
- Qubes 4.2.2 includes a fix for :issue:`#8332: File-copy qrexec service is overly restrictive <8332>`. As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability.
- After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place.
@ -109,7 +109,7 @@ Download
--------
All Qubes ISOs and associated :doc:`verification files </project-security/verifying-signatures>` are available on the `downloads <https://www.qubes-os.org/downloads/>`__ page.
All Qubes ISOs and associated :doc:`verification files </project-security/verifying-signatures>` are available on the :website:`downloads <downloads/>` page.
Installation instructions
-------------------------

2
developer/services/admin-api.rst
View file

@ -2,7 +2,7 @@
Admin API
=========
*You may also be interested in the article* \ `Introducing the Qubes Admin API <https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/>`__\ *.*
*You may also be interested in the article* \ :website:`Introducing the Qubes Admin API <news/2017/06/27/qubes-admin-api/>`\ *.*
Goals
=====

6
developer/system/template-manager.rst
View file

@ -11,11 +11,11 @@ Motivation
This project was originally proposed in the 2020 Google Summer of Code program.
Previously, templates were distributed by RPM packages and managed by ``yum``/``dnf``. However, tracking inherently dynamic VM images with a package manager suited for static files creates some challenges. For example, users may accidentally update the images, overriding local changes (`#996 <https://github.com/QubesOS/qubes-issues/issues/996>`__, `#1647 <https://github.com/QubesOS/qubes-issues/issues/1647>`__). (Or in the case of `#2061 <https://github.com/QubesOS/qubes-issues/issues/2061>`__, want to specifically override the changes.) Other operations that work well on normal VMs are also somewhat inconsistent on RPM-managed templates. This includes actions such as renaming (`#839 <https://github.com/QubesOS/qubes-issues/issues/839>`__), removal (`#5509 <https://web.archive.org/web/20210526123932/https://github.com/QubesOS/qubes-issues/issues/5509>`__) and backup/restore (`#1385 <https://github.com/QubesOS/qubes-issues/issues/1385>`__, `#1453 <https://github.com/QubesOS/qubes-issues/issues/1453>`__, `discussion thread 1 <https://groups.google.com/forum/#!topic/qubes-devel/rwc2_miCNNE/discussion>`__, `discussion thread 2 <https://groups.google.com/forum/#!topic/qubes-users/uQEUpv4THsY/discussion>`__). In turn, this creates inconveniences and confusion for users (`#1403 <https://github.com/QubesOS/qubes-issues/issues/1403>`__, `#4518 <https://github.com/QubesOS/qubes-issues/issues/4518>`__).
Previously, templates were distributed by RPM packages and managed by ``yum``/``dnf``. However, tracking inherently dynamic VM images with a package manager suited for static files creates some challenges. For example, users may accidentally update the images, overriding local changes (:issue:`996`, :issue:`1647`). (Or in the case of :issue:`2061`, want to specifically override the changes.) Other operations that work well on normal VMs are also somewhat inconsistent on RPM-managed templates. This includes actions such as renaming (:issue:`839`), removal (`#5509 <https://web.archive.org/web/20210526123932/https://github.com/QubesOS/qubes-issues/issues/5509>`__) and backup/restore (:issue:`1385`, :issue:`1453`, `discussion thread 1 <https://groups.google.com/forum/#!topic/qubes-devel/rwc2_miCNNE/discussion>`__, `discussion thread 2 <https://groups.google.com/forum/#!topic/qubes-users/uQEUpv4THsY/discussion>`__). In turn, this creates inconveniences and confusion for users (:issue:`1403`, :issue:`4518`).
Also, the usage of RPM packages meant that installing a template results in arbitrary code execution, which is not ideal.
Besides distribution, users may also wish to have an integrated template management application (`#2062 <https://github.com/QubesOS/qubes-issues/issues/2062>`__, `#2064 <https://github.com/QubesOS/qubes-issues/issues/2064>`__, `#2534 <https://github.com/QubesOS/qubes-issues/issues/2534>`__, `#3040 <https://github.com/QubesOS/qubes-issues/issues/3040>`__), as opposed to the situation where multiple programs are required for different purposes, e.g., ``qubes-dom0-update``, ``dnf``, ``qvm-remove``, ``qubes-manager``.
Besides distribution, users may also wish to have an integrated template management application (:issue:`2062`, :issue:`2064`, :issue:`2534`, :issue:`3040`), as opposed to the situation where multiple programs are required for different purposes, e.g., ``qubes-dom0-update``, ``dnf``, ``qvm-remove``, ``qubes-manager``.
To tackle these issues, ``qvm-template`` was created. It strives to provide not only a better mechanism for handling template installation but also a consistent user-facing interface to deal with template management.
@ -61,7 +61,7 @@ Package format
--------------
The RPM package format is still used. However, the contents are manually extracted instead of installing the whole package. This allows us to take advantage of existing tools for things like repository management. We can also avoid the burden of dealing with verification, reducing the risk of issues like `QSB-028 <https://www.qubes-os.org/news/2016/12/19/qsb-28/>`__.
The RPM package format is still used. However, the contents are manually extracted instead of installing the whole package. This allows us to take advantage of existing tools for things like repository management. We can also avoid the burden of dealing with verification, reducing the risk of issues like :website:`QSB-028 <news/2016/12/19/qsb-28/>`.
The package name should be in the form ``qubes-template-<TEMPLATE_NAME>``.

4
introduction/code-of-conduct.rst
View file

@ -7,7 +7,7 @@ Introduction
------------
This Code of Conduct is a collaborative, evolving document that attempts to transparently set out a public set of standards regarding appropriate conduct in the Qubes OS Project. It is *not* intended to be a statement or endorsement, whether implicit or explicit, of any particular political or philosophical attitude, belief, or way of living. Rather, it is an attempt to find a reasonable middle ground among the inevitable disagreements regarding free expression that arise in a large, diverse community of people from around the world. It is intended to be a practical means of serving the best interests of our users, contributors, and the project itself. We welcome you to view the `history of changes <https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md>`__ to this document and the `discussion <https://github.com/QubesOS/qubes-issues/issues/2163>`__ leading to its creation.
This Code of Conduct is a collaborative, evolving document that attempts to transparently set out a public set of standards regarding appropriate conduct in the Qubes OS Project. It is *not* intended to be a statement or endorsement, whether implicit or explicit, of any particular political or philosophical attitude, belief, or way of living. Rather, it is an attempt to find a reasonable middle ground among the inevitable disagreements regarding free expression that arise in a large, diverse community of people from around the world. It is intended to be a practical means of serving the best interests of our users, contributors, and the project itself. We welcome you to view the `history of changes <https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md>`__ to this document and the :issue:`discussion <2163>` leading to its creation.
Our Pledge
----------
@ -69,7 +69,7 @@ Enforcement
-----------
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project CoC team at ``mods@qubes-os.org``. The project CoC team is the `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/#marek-marczykowski-g%C3%B3recki>`__, `Andrew David Wong <https://www.qubes-os.org/team/#andrew-david-wong>`__, and `Michael Carbone <https://www.qubes-os.org/team/#michael-carbone>`__. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident, and will ensure reporter, reported and all others impacted are regularly updated through the process. Further details of specific enforcement policies may be posted separately.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project CoC team at ``mods@qubes-os.org``. The project CoC team is the :website:`Marek Marczykowski-Górecki <team/#marek-marczykowski-g%C3%B3recki>`, :website:`Andrew David Wong <team/#andrew-david-wong>`, and :website:`Michael Carbone <team/#michael-carbone>`. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident, and will ensure reporter, reported and all others impacted are regularly updated through the process. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

10
introduction/contributing.rst
View file

@ -17,19 +17,19 @@ Thank you for your interest in contributing to Qubes! Here are some of the many
- :doc:`Test new releases and updates </user/downloading-installing-upgrading/testing>`
- Submit `HCL reports <https://www.qubes-os.org/hcl/>`__ for your hardware
- Submit :website:`HCL reports <hcl/>` for your hardware
- Record :doc:`video tours </introduction/video-tours>`
- Create `artwork <https://github.com/QubesOS/qubes-artwork>`__ (plymouth themes, installer themes, wallpapers, etc.)
- `Write and edit the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__
- :website:`Write and edit the documentation <doc/how-to-edit-the-documentation/>`
- `Donate <https://www.qubes-os.org/donate/>`__ to the project
- :website:`Donate <donate/>` to the project
- If you represent an organization, become a `Qubes partner <https://www.qubes-os.org/partners/>`__
- If you represent an organization, become a :website:`Qubes partner <partners/>`
- Add a `Qubes download mirror <https://www.qubes-os.org/downloads/mirrors/>`__
- Add a :website:`Qubes download mirror <downloads/mirrors/>`
- Answer questions and discuss Qubes on the :doc:`mailing lists </introduction/support>` and :ref:`forum <introduction/support:forum>`

30
introduction/faq.rst
View file

@ -19,7 +19,7 @@ Is Qubes OS free and open-source software?
There are two distinct senses of the word “free” when it comes to free software. The difference in commonly expressed by the phrases “free as in beer” and “free as in speech.”
The first senses is straightforward. Qubes OS is “free as in beer,” meaning that it is provided at no cost (*gratis*), though `donations <https://www.qubes-os.org/donate/>`__ are greatly appreciated.
The first senses is straightforward. Qubes OS is “free as in beer,” meaning that it is provided at no cost (*gratis*), though :website:`donations <donate/>` are greatly appreciated.
The second sense is more complicated. Qubes OS is *mostly* “free as in speech,” but not entirely. All the software created by the Qubes OS Project *itself* is `free (or “libre”) <https://www.gnu.org/philosophy/free-sw>`__ and `open-source <https://opensource.org/docs/definition.html>`__ software (`FOSS or FLOSS <https://www.gnu.org/philosophy/floss-and-foss.en.html>`__). This means that everyone is allowed to use, copy, study, and change the software in accordance with its :doc:`license </developer/code/license>`. It also means that the :doc:`source code </developer/code/source-code>` is `publicly available <https://github.com/QubesOS/>`__ so everyone can audit and contribute to it.
@ -155,7 +155,7 @@ Does Qubes use full disk encryption (FDE)?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, Qubes OS uses `LUKS <https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup>`__/`dm-crypt <https://en.wikipedia.org/wiki/Dm-crypt>`__ to encrypt everything except the ``/boot`` partition.
By default, Qubes OS uses :wikipedia:`LUKS <Linux_Unified_Key_Setup>`/:wikipedia:`dm-crypt <Dm-crypt>` to encrypt everything except the ``/boot`` partition.
What do all these terms mean?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -179,7 +179,7 @@ How is Qubes affected by Xen Security Advisories (XSAs)?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See the `XSA Tracker <https://www.qubes-os.org/security/xsa/>`__.
See the :website:`XSA Tracker <security/xsa/>`.
What about this other/new (micro)kernel/hypervisor?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -279,13 +279,13 @@ Do you recommend coreboot as an alternative to vendor BIOS?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes, where it is possible to use it an open source boot firmware ought to be more trustable than a closed source implementation. `coreboot <https://www.coreboot.org/>`__ is as a result a requirement for `Qubes Certified Hardware <https://www.qubes-os.org/news/2016/07/21/new-hw-certification-for-q4/>`__. The number of machines coreboot currently supports is limited and the use of some vendor supplied blobs is generally still required. Where coreboot does support your machine and is not already installed, you will generally need additional hardware to flash it. Please see the coreboot website / their IRC channel for further information.
Yes, where it is possible to use it an open source boot firmware ought to be more trustable than a closed source implementation. `coreboot <https://www.coreboot.org/>`__ is as a result a requirement for :website:`Qubes Certified Hardware <news/2016/07/21/new-hw-certification-for-q4/>`. The number of machines coreboot currently supports is limited and the use of some vendor supplied blobs is generally still required. Where coreboot does support your machine and is not already installed, you will generally need additional hardware to flash it. Please see the coreboot website / their IRC channel for further information.
How should I report documentation issues?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you can fix the problem yourself, please see `how to edit the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__. If not, please see :doc:`issue tracking </introduction/issue-tracking>`.
If you can fix the problem yourself, please see :website:`how to edit the documentation <doc/how-to-edit-the-documentation/>`. If not, please see :doc:`issue tracking </introduction/issue-tracking>`.
Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -303,7 +303,7 @@ Should I trust this website?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone `review <https://www.qubes-os.org/doc/how-to-edit-the-documentation/#security>`__), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was `intentionally written in Markdown so as to be readable as plain text for this very reason <https://www.qubes-os.org/doc/documentation-style-guide/#markdown-conventions>`__. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone :website:`review <doc/how-to-edit-the-documentation/#security>`), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was :website:`intentionally written in Markdown so as to be readable as plain text for this very reason <doc/documentation-style-guide/#markdown-conventions>`. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
What does it mean to "distrust the infrastructure"?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -321,7 +321,7 @@ Why do you use GitHub?
Three main reasons:
1. We `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__ including GitHub (though there are aspects we’re still `working on <https://github.com/QubesOS/qubes-issues/issues/3958>`__).
1. We `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__ including GitHub (though there are aspects we’re still :issue:`working on <3958>`).
2. It’s free (as in beer). We’d have to spend either time or money to implement a solution ourselves or pay someone to do so, and we can’t spare either one right now.
@ -391,7 +391,7 @@ Is Qubes a multi-user system?
No. Qubes does not pretend to be a multi-user system. Qubes assumes that the user who controls Dom0 controls the whole system. It is very difficult to **securely** implement multi-user support. See `here <https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06>`__ for details.
However, in Qubes 4.x we will be implementing management functionality. See `Admin API <https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/>`__ and `Core Stack <https://www.qubes-os.org/news/2017/10/03/core3/>`__ for more details.
However, in Qubes 4.x we will be implementing management functionality. See :website:`Admin API <news/2017/06/27/qubes-admin-api/>` and :website:`Core Stack <news/2017/10/03/core3/>` for more details.
What are the system requirements for Qubes OS?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -403,7 +403,7 @@ Is there a list of hardware that is compatible with Qubes OS?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See the `Hardware Compatibility List <https://www.qubes-os.org/hcl/>`__.
See the :website:`Hardware Compatibility List <hcl/>`.
Is there any certified hardware for Qubes OS?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -471,7 +471,7 @@ What is a terminal?
^^^^^^^^^^^^^^^^^^^
A `terminal emulator <https://en.wikipedia.org/wiki/Terminal_emulator>`__, nowadays often referred to as just a *terminal*, is a program which provides a text window. Inside that window, a `shell <https://en.wikipedia.org/wiki/Shell_(computing)>`__ is typically running in it. A shell provides a `command-line interface <https://en.wikipedia.org/wiki/Command-line_interface>`__ where the user can enter and run `commands <https://en.wikipedia.org/wiki/Command_(computing)>`__.
A :wikipedia:`terminal emulator <Terminal_emulator>`, nowadays often referred to as just a *terminal*, is a program which provides a text window. Inside that window, a :wikipedia:`shell <Shell_(computing)>` is typically running in it. A shell provides a :wikipedia:`command-line interface <Command-line_interface>` where the user can enter and run :wikipedia:`commands <Command_(computing)>`.
See introductions on Wikibooks: `here <https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics>`__, `here <https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix>`__ and `here <https://en.wikibooks.org/wiki/Bash_Shell_Scripting>`__.
@ -487,7 +487,7 @@ Can I install Qubes OS together with other operating system (dual-boot/multi-boo
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You shouldn’t do that, because it poses a security risk for your Qubes OS installation. But if you understand the risk and accept it, read `documentation on multibooting <https://forum.qubes-os.org/t/18988>`__. It begins with an explanation of the risks with such a setup.
You shouldn’t do that, because it poses a security risk for your Qubes OS installation. But if you understand the risk and accept it, read :topic:`documentation on multibooting <18988>`. It begins with an explanation of the risks with such a setup.
Which version of Qubes am I running?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -656,7 +656,7 @@ I have weird graphics glitches like the screen turning partially black.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If it seems like the issue described in `this thread <https://github.com/QubesOS/qubes-issues/issues/2399>`__, try disabling the window compositor:
If it seems like the issue described in :issue:`this thread <2399>`, try disabling the window compositor:
- Q → System Tools → Window Manager Tweaks → Compositor → uncheck “Enable display compositing”
@ -737,7 +737,7 @@ Yes. In general, the Qubes developers will not use a piece of software unless th
- If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust.
- If the software is security-sensitive and requires communication with the outside world, a “split” implementation is highly preferred (for examples, see :doc:`Split GPG </user/security-in-qubes/split-gpg>` and `Split Bitcoin <https://forum.qubes-os.org/t/19017>`__).
- If the software is security-sensitive and requires communication with the outside world, a “split” implementation is highly preferred (for examples, see :doc:`Split GPG </user/security-in-qubes/split-gpg>` and :topic:`Split Bitcoin <19017>`).
- If the software has dependencies, these should be packaged and available in repos for a :ref:`current, Qubes-supported version <user/downloading-installing-upgrading/supported-releases:templates>` of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a “split” implementation).
@ -775,7 +775,7 @@ What is Qubes' attitude toward changing guest distros?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In general, we try to respect each distro’s culture, but we reserve the right to make modifications that we deem appropriate. See the discussion on issue `#1014 <https://github.com/QubesOS/qubes-issues/issues/1014>`__ for an example.
In general, we try to respect each distro’s culture, but we reserve the right to make modifications that we deem appropriate. See the discussion on issue :issue:`1014` for an example.
The policy is there mostly to ease maintenance, on several levels:
@ -831,7 +831,7 @@ Is there a way to automate tasks for continuous integration or DevOps?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes, Qubes natively supports automation via :doc:`Salt (SaltStack) </user/advanced-topics/salt>`. There is also the unofficial `ansible-qubes toolkit <https://github.com/Rudd-O/ansible-qubes>`__. (**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, `allowing it to manage dom0 may be a security risk <https://forum.qubes-os.org/t/19075#dom0-precautions>`__.)
Yes, Qubes natively supports automation via :doc:`Salt (SaltStack) </user/advanced-topics/salt>`. There is also the unofficial `ansible-qubes toolkit <https://github.com/Rudd-O/ansible-qubes>`__. (**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, :topic:`allowing it to manage dom0 may be a security risk <19075#dom0-precautions>`.)
.. |checkmark| image:: /attachment/doc/checkmark.png
.. |redx| image:: /attachment/doc/red_x.png

14
introduction/getting-started.rst
View file

@ -3,7 +3,7 @@ Getting started
===============
After `downloading <https://www.qubes-os.org/downloads/>`__ and :doc:`installing </user/downloading-installing-upgrading/installation-guide>` Qubes OS, it’s time to dive in and get to work! (Already know your way around? Dive right in to :doc:`organizing your qubes </user/how-to-guides/how-to-organize-your-qubes>`.)
After :website:`downloading <downloads/>` and :doc:`installing </user/downloading-installing-upgrading/installation-guide>` Qubes OS, it’s time to dive in and get to work! (Already know your way around? Dive right in to :doc:`organizing your qubes </user/how-to-guides/how-to-organize-your-qubes>`.)
The Basics
----------
@ -13,9 +13,9 @@ Qubes OS is an operating system built out of securely-isolated compartments, or
Suppose you want to use your favorite web browser in several different qubes. You’d install the web browser in a template, then every qube based on that template would be able to run the web browser software (while still being forbidden from modifying the template and any other qubes). This way, you only have to install the web browser a single time, and updating the template updates all the qubes based on it. This elegant design saves time and space while enhancing security.
There are also some “helper” qubes in your system. Each qube that connects to the Internet does so through a network-providing :ref:`service qube <user/reference/glossary:service qube>`. If you need to access USB devices, another service qube will do that. There’s also a :ref:`management qube <user/reference/glossary:management qube>` that automatically handles a lot of background housekeeping. For the most part, you won’t have to worry about it, but it’s nice to know that it’s there. As with app qubes, service qubes and management qubes are also based on templates. Templates are usually named after their operating system (often a `Linux distribution <https://en.wikipedia.org/wiki/Linux_distribution>`__) and corresponding version number. There are many ready-to-use :doc:`templates </user/templates/templates>` to choose from, and you can download and have as many as you like.
There are also some “helper” qubes in your system. Each qube that connects to the Internet does so through a network-providing :ref:`service qube <user/reference/glossary:service qube>`. If you need to access USB devices, another service qube will do that. There’s also a :ref:`management qube <user/reference/glossary:management qube>` that automatically handles a lot of background housekeeping. For the most part, you won’t have to worry about it, but it’s nice to know that it’s there. As with app qubes, service qubes and management qubes are also based on templates. Templates are usually named after their operating system (often a :wikipedia:`Linux distribution <Linux_distribution>`) and corresponding version number. There are many ready-to-use :doc:`templates </user/templates/templates>` to choose from, and you can download and have as many as you like.
Last but not least, there’s a very special :ref:`admin qube <user/reference/glossary:admin qube>` used to administer your entire system. There’s only one admin qube, and it’s called :ref:`dom0 <user/reference/glossary:dom0>`. You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be “game over”- an effective compromise of the entire system. That’s why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn’t happen. Due to its overarching importance, dom0 has no network connectivity and is used only for running the `desktop environment <https://en.wikipedia.org/wiki/Desktop_environment>`__ and `window manager <https://en.wikipedia.org/wiki/Window_manager>`__. Dom0 should never be used for anything else. In particular, you should never run user applications in dom0. (That’s what your app qubes are for!) In short, be very careful when interacting with dom0.
Last but not least, there’s a very special :ref:`admin qube <user/reference/glossary:admin qube>` used to administer your entire system. There’s only one admin qube, and it’s called :ref:`dom0 <user/reference/glossary:dom0>`. You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be “game over”- an effective compromise of the entire system. That’s why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn’t happen. Due to its overarching importance, dom0 has no network connectivity and is used only for running the :wikipedia:`desktop environment <Desktop_environment>` and :wikipedia:`window manager <Window_manager>`. Dom0 should never be used for anything else. In particular, you should never run user applications in dom0. (That’s what your app qubes are for!) In short, be very careful when interacting with dom0.
Color & Security
^^^^^^^^^^^^^^^^
@ -41,7 +41,7 @@ The bar at the top of your screen in Qubes 4.2 includes the following XFCE compo
- The **Task Bar** where buttons for open and hidden windows live.
- **Spaces**, an interface for `virtual desktops <https://en.wikipedia.org/wiki/Virtual_desktop>`__. Virtual desktops do not have any inherent security isolation properties, but some users find them useful for organizing things.
- **Spaces**, an interface for :wikipedia:`virtual desktops <Virtual_desktop>`. Virtual desktops do not have any inherent security isolation properties, but some users find them useful for organizing things.
- The **Tray**, where many functional widgets live.
@ -177,19 +177,19 @@ Compatible Hardware
-------------------
Make sure your hardware satisfies the :doc:`system requirements </user/hardware/system-requirements>`, as Qubes OS cannot run on every type of computer. You may also want to check out :doc:`Qubes-certified Hardware </user/hardware/certified-hardware/certified-hardware>` and take a look at the `Hardware Compatibility List (HCL) <https://www.qubes-os.org/hcl/>`__.
Make sure your hardware satisfies the :doc:`system requirements </user/hardware/system-requirements>`, as Qubes OS cannot run on every type of computer. You may also want to check out :doc:`Qubes-certified Hardware </user/hardware/certified-hardware/certified-hardware>` and take a look at the :website:`Hardware Compatibility List (HCL) <hcl/>`.
Downloads
---------
`Download an ISO <https://www.qubes-os.org/downloads/>`__, learn how to :doc:`verify its authenticity </project-security/verifying-signatures>`, and follow our :doc:`guide to install Qubes OS </user/downloading-installing-upgrading/installation-guide>`. Looking for the :doc:`source code </developer/code/source-code>`? You’ll find it `on GitHub <https://github.com/QubesOS>`__.
:website:`Download an ISO <downloads/>`, learn how to :doc:`verify its authenticity </project-security/verifying-signatures>`, and follow our :doc:`guide to install Qubes OS </user/downloading-installing-upgrading/installation-guide>`. Looking for the :doc:`source code </developer/code/source-code>`? You’ll find it `on GitHub <https://github.com/QubesOS>`__.
Documentation
-------------
Browse our extensive library of :doc:`documentation </index>` for users and developers of Qubes OS. You can even `help us improve it <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__!
Browse our extensive library of :doc:`documentation </index>` for users and developers of Qubes OS. You can even :website:`help us improve it <doc/how-to-edit-the-documentation/>`!
.. |snapshot_41.png| image:: /attachment/doc/r4.1-snapshot_40.png

2
introduction/intro.rst
View file

@ -190,6 +190,6 @@ presentation.
- If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation </index>` and the :ref:`user FAQ <introduction/faq:users>`.
- If you’re a developer, there’s dedicated :ref:`developer documentation <index:developer documentation>` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.
- Ready to give Qubes a try? Head on over to the :website:`downloads page <downloads/>`, and read the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.
- Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum </introduction/support>`.

4
introduction/issue-tracking.rst
View file

@ -3,7 +3,7 @@ Issue tracking
==============
We use `GitHub Issues <https://docs.github.com/en/issues>`__ as our `issue tracking system <https://en.wikipedia.org/wiki/Issue_tracking_system>`__. All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as this website) are tracked in `qubes-issues <https://github.com/QubesOS/qubes-issues/issues>`__.
We use `GitHub Issues <https://docs.github.com/en/issues>`__ as our :wikipedia:`issue tracking system <Issue_tracking_system>`. All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as this website) are tracked in `qubes-issues <https://github.com/QubesOS/qubes-issues/issues>`__.
How to open a new issue
-----------------------
@ -21,7 +21,7 @@ I see something that should be changed in the documentation.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We encourage you to submit the change yourself! Please see the `how to edit the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__ for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue.
We encourage you to submit the change yourself! Please see the :website:`how to edit the documentation <doc/how-to-edit-the-documentation/>` for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue.
I would like to report a security vulnerability.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

4
introduction/privacy.rst
View file

@ -9,7 +9,7 @@ Website
-------
For the legally-required boilerplate, see `Website Privacy Policy <https://www.qubes-os.org/website-privacy-policy/>`__.
For the legally-required boilerplate, see :website:`Website Privacy Policy <website-privacy-policy/>`.
This is just a static website generated with Jekyll and hosted from GitHub Pages. We try to use as little JavaScript as possible. We host all resources locally (no third-party CDNs) so that you only have to connect to one domain. This site should be easy to browse using Tor Browser and with scripts blocked. We also have an `onion service <http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/>`__ (access is not logged). We even go out of our way to make it easy to download `this website’s git repo <https://github.com/QubesOS/qubesos.github.io>`__, including all the website source code, so that you can host this entire site from your own local machine offline. Better yet, we’ve specifically written all of the :doc:`documentation </index>` in Markdown so that the plain text can be enjoyed from the comfort of your terminal. Here’s the `repo <https://github.com/QubesOS/qubes-doc>`__. (By the way, Git tags on our repos are PGP-signed so you can :doc:`verify </project-security/verifying-signatures>` the authenticity of the content.) Obviously, we don’t use any ads or trackers, but this is still a public website, so man-in-the-middle attacks and such are always a possibility. Please be careful. See :ref:`FAQ: Should I trust this website? <introduction/faq:should i trust this website?>`
@ -35,7 +35,7 @@ Mirrors
-------
There are also other third-party mirrors hosted by volunteers. These are used both for `ISO downloads <https://www.qubes-os.org/downloads/#mirrors>`__ and `updates <#update-servers-and-repositories>`__. We have no control over what data these mirrors collect or with whom they share it. Please see the privacy policy of each respective mirror operator.
There are also other third-party mirrors hosted by volunteers. These are used both for :website:`ISO downloads <downloads/#mirrors>` and `updates <#update-servers-and-repositories>`__. We have no control over what data these mirrors collect or with whom they share it. Please see the privacy policy of each respective mirror operator.
Qubes OS
--------

24
introduction/support.rst
View file

@ -73,11 +73,11 @@ The Qubes mailing lists and forum are open to the public. The contents are crawl
The Qubes community includes people from all walks of life and from around the world. Individuals differ in areas of experience and technical expertise. You will come into contact with others whose views and agendas differ from your own. Everyone is free to write what they please, as long as it doesn’t violate our :doc:`Code of Conduct </introduction/code-of-conduct>`. Be friendly and open, but do not believe everything you read. Use good judgment, and be especially careful when following instructions (e.g., copying commands) given by others on the lists.
It’s always possible that a bad actor could try to impersonate any member of the `Qubes team <https://www.qubes-os.org/team/>`__ anywhere on the Internet. Please don’t assume that someone who claims to be an official Qubes team member really is one without an appropriate form of authentication, such as a :doc:`verified PGP-signed message </project-security/verifying-signatures>`. (But bear in mind that anyone can generate a key with any name on it and use it to PGP-sign a message, so the mere presence of a PGP signature does not indicate authority. Successful :doc:`verification </project-security/verifying-signatures>` is what counts.) All official `news <https://www.qubes-os.org/news/>`__ can be authenticated by :doc:`verifying the signatures </project-security/verifying-signatures>` on the relevant tags or commits in the `qubes-posts <https://github.com/QubesOS/qubes-posts>`__ repository.
It’s always possible that a bad actor could try to impersonate any member of the :website:`Qubes team <team/>` anywhere on the Internet. Please don’t assume that someone who claims to be an official Qubes team member really is one without an appropriate form of authentication, such as a :doc:`verified PGP-signed message </project-security/verifying-signatures>`. (But bear in mind that anyone can generate a key with any name on it and use it to PGP-sign a message, so the mere presence of a PGP signature does not indicate authority. Successful :doc:`verification </project-security/verifying-signatures>` is what counts.) All official :website:`news <news/>` can be authenticated by :doc:`verifying the signatures </project-security/verifying-signatures>` on the relevant tags or commits in the `qubes-posts <https://github.com/QubesOS/qubes-posts>`__ repository.
Given that there may be impostors and others trying to lead you astray, how should you sort the good advice from the bad? This is up to each individual to decide, but it helps to know that many members of our community have proven themselves knowledgeable through their :doc:`contributions </introduction/contributing>` to the project. Often, these individuals sign their messages with the same key as (or another key authenticated by) the one they use to :doc:`sign their contributions </developer/code/code-signing>`.
For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages </developer/general/package-contributions>` or `contributing to the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify </project-security/verifying-signatures>` that these came from the same keyholder.
For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages </developer/general/package-contributions>` or :website:`contributing to the documentation <doc/how-to-edit-the-documentation/>`. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify </project-security/verifying-signatures>` that these came from the same keyholder.
Discussion guidelines
---------------------
@ -121,7 +121,7 @@ Report issues and submit changes in the right places
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker </introduction/issue-tracking>` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum <introduction/issue-tracking:the issue tracker is not a discussion forum>`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, `submit the change <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__.
The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker </introduction/issue-tracking>` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum <introduction/issue-tracking:the issue tracker is not a discussion forum>`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, :website:`submit the change <doc/how-to-edit-the-documentation/>`.
Moderation
^^^^^^^^^^
@ -143,7 +143,7 @@ Do not top-post
^^^^^^^^^^^^^^^
`Top-posting <https://en.wikipedia.org/wiki/Posting_style#Top-posting>`__ is placing your reply above the quoted message to which you’re replying. Please refrain from doing this. Instead, either `interleave <https://en.wikipedia.org/wiki/Posting_style#Interleaved_style>`__ your reply by placing parts of your message immediately below each quoted portion to which it is replying, or `bottom-post <https://en.wikipedia.org/wiki/Posting_style#Bottom-posting>`__ by placing your entire reply below the quoted message to which you’re replying.
:wikipedia:`Top-posting <Posting_style#Top-posting>` is placing your reply above the quoted message to which you’re replying. Please refrain from doing this. Instead, either :wikipedia:`interleave <Posting_style#Interleaved_style>` your reply by placing parts of your message immediately below each quoted portion to which it is replying, or :wikipedia:`bottom-post <Posting_style#Bottom-posting>` by placing your entire reply below the quoted message to which you’re replying.
Use proper subject lines
^^^^^^^^^^^^^^^^^^^^^^^^
@ -185,19 +185,19 @@ Google Groups
^^^^^^^^^^^^^
While the mailing lists are implemented as Google Group web forums, a Google account is in no way required, expected, or encouraged. Many discussants (including most members of the Qubes team) treat these lists as conventional `mailing lists <https://en.wikipedia.org/wiki/Electronic_mailing_list>`__, interacting with them solely through plain text email with `MUAs <https://en.wikipedia.org/wiki/Email_client>`__ like `Thunderbird <https://www.thunderbird.net/>`__ and `Mutt <https://www.mutt.org/>`__. The Google Groups service is just free infrastructure, and we :ref:`distrust the infrastructure <introduction/faq:what does it mean to "distrust the infrastructure"?>`. This is why, for example, we encourage discussants to use :doc:`Split GPG </user/security-in-qubes/split-gpg>` to sign all of their messages to the lists, but we do not endorse the use of these Google Groups as web forums. For that, we have a separate, dedicated `forum <#forum>`__.
While the mailing lists are implemented as Google Group web forums, a Google account is in no way required, expected, or encouraged. Many discussants (including most members of the Qubes team) treat these lists as conventional :wikipedia:`mailing lists <Electronic_mailing_list>`, interacting with them solely through plain text email with :wikipedia:`MUAs <Email_client>` like `Thunderbird <https://www.thunderbird.net/>`__ and `Mutt <https://www.mutt.org/>`__. The Google Groups service is just free infrastructure, and we :ref:`distrust the infrastructure <introduction/faq:what does it mean to "distrust the infrastructure"?>`. This is why, for example, we encourage discussants to use :doc:`Split GPG </user/security-in-qubes/split-gpg>` to sign all of their messages to the lists, but we do not endorse the use of these Google Groups as web forums. For that, we have a separate, dedicated `forum <#forum>`__.
Mailing lists
-------------
This section covers each of our individual `mailing lists <https://en.wikipedia.org/wiki/Electronic_mailing_list>`__, with details about the purpose of each list and how to use it. A Google account is **not** required for any of these mailing lists.
This section covers each of our individual :wikipedia:`mailing lists <Electronic_mailing_list>`, with details about the purpose of each list and how to use it. A Google account is **not** required for any of these mailing lists.
qubes-announce
^^^^^^^^^^^^^^
This is a read-only list for those who wish to receive only very important, infrequent messages. Only the core Qubes team can post to this list. Only `Qubes Security Bulletins (QSBs) <https://www.qubes-os.org/security/qsb/>`__, new stable Qubes OS releases, and Qubes OS release end-of-life notices are announced here.
This is a read-only list for those who wish to receive only very important, infrequent messages. Only the core Qubes team can post to this list. Only :website:`Qubes Security Bulletins (QSBs) <security/qsb/>`, new stable Qubes OS releases, and Qubes OS release end-of-life notices are announced here.
To subscribe, send a blank email to ``qubes-announce+subscribe@googlegroups.com``. (**Note:** A Google account is **not** required. Any email address will work.) To unsubscribe, send a blank email to ``qubes-announce+unsubscribe@googlegroups.com``. This list also has a `traditional mail archive <https://www.mail-archive.com/qubes-announce@googlegroups.com/>`__ and an optional `Google Groups web interface <https://groups.google.com/group/qubes-announce>`__.
@ -207,7 +207,7 @@ qubes-users
This list is for helping users solve various daily problems with Qubes OS. Examples of topics or questions suitable for this list include:
- `HCL <https://www.qubes-os.org/hcl/>`__ reports
- :website:`HCL <hcl/>` reports
- Installation problems
@ -219,7 +219,7 @@ This list is for helping users solve various daily problems with Qubes OS. Examp
Please try searching both the Qubes website and the archives of the mailing lists before sending a question. In addition, please make sure that you have read and understood the following basic documentation prior to posting to the list:
- The :doc:`Installation Guide </user/downloading-installing-upgrading/installation-guide>`, :doc:`System Requirements </user/hardware/system-requirements>`, and `HCL <https://www.qubes-os.org/hcl/>`__ (for problems related to installing Qubes OS)
- The :doc:`Installation Guide </user/downloading-installing-upgrading/installation-guide>`, :doc:`System Requirements </user/hardware/system-requirements>`, and :website:`HCL <hcl/>` (for problems related to installing Qubes OS)
- The :ref:`User FAQ <introduction/faq:users>`
@ -305,7 +305,7 @@ Why was this forum created?
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Previously, the only option for a forum-like experience was to interact with our mailing lists via Google Groups, but we understand all too well that the privacy implications and user experience were unacceptable for many members of our community, especially with the recent addition of a sign-in requirement to view threads. Many of you value the lower barrier to entry, organization, ease-of-use, and modern social features that today’s forums support. Moreover, Discourse `features email integration <https://forum.qubes-os.org/t/using-the-forum-via-email/533>`__ for those who still prefer the traditional mailing list format.
Previously, the only option for a forum-like experience was to interact with our mailing lists via Google Groups, but we understand all too well that the privacy implications and user experience were unacceptable for many members of our community, especially with the recent addition of a sign-in requirement to view threads. Many of you value the lower barrier to entry, organization, ease-of-use, and modern social features that today’s forums support. Moreover, Discourse :topic:`features email integration <using-the-forum-via-email/533>` for those who still prefer the traditional mailing list format.
How is this different from our mailing lists?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -317,7 +317,7 @@ Does this split the community?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Many open-source projects (such as Fedora and Debian) have both mailing lists and forums (and additional discussion venues). In fact, the Qubes OS Project already had non-mailing-list discussion venues such as `Reddit <https://www.reddit.com/r/Qubes/>`__ before this forum was introduced. We believe that this additional venue fosters the continued growth of community participation and improves everyone’s experience. In addition, we fully expect that many community members – especially the most active ones – will choose to participate in both venues. (Again, for those who still prefer interacting via email, `Discourse supports that too <https://forum.qubes-os.org/t/using-the-forum-via-email/533>`__!)
Many open-source projects (such as Fedora and Debian) have both mailing lists and forums (and additional discussion venues). In fact, the Qubes OS Project already had non-mailing-list discussion venues such as `Reddit <https://www.reddit.com/r/Qubes/>`__ before this forum was introduced. We believe that this additional venue fosters the continued growth of community participation and improves everyone’s experience. In addition, we fully expect that many community members – especially the most active ones – will choose to participate in both venues. (Again, for those who still prefer interacting via email, :topic:`Discourse supports that too <using-the-forum-via-email/533>`!)
Social media
------------
@ -337,7 +337,7 @@ The Qubes OS Project has a presence on the following social media platforms:
Generally speaking, these are not intended to be primary support venues. (Those would be `qubes-users <#qubes-users>`__ and the `forum <#forum>`__.) Rather, these are primarily intended to be a way to more widely disseminate items published on the `news <https://www.qubes-os.org/news/>`__ page. If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news.
Generally speaking, these are not intended to be primary support venues. (Those would be `qubes-users <#qubes-users>`__ and the `forum <#forum>`__.) Rather, these are primarily intended to be a way to more widely disseminate items published on the :website:`news <news/>` page. If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news.
Chat
----

2
introduction/video-tours.rst
View file

@ -41,7 +41,7 @@ Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If
-----------------------------------------------------------------------------------------------
`Micah Lee <https://micahflee.com/>`__, a long-time Qubes `advocate <https://www.qubes-os.org/endorsements/>`__, presented `Qubes OS: The Operating System That Can Protect You Even If You Get Hacked <https://archive.org/details/QubesOSTheOperatingSystemThatCanProtectYouEvenIfYouGetHackedTalkByMicahLee>`__ at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.
`Micah Lee <https://micahflee.com/>`__, a long-time Qubes :website:`advocate <endorsements/>`, presented `Qubes OS: The Operating System That Can Protect You Even If You Get Hacked <https://archive.org/details/QubesOSTheOperatingSystemThatCanProtectYouEvenIfYouGetHackedTalkByMicahLee>`__ at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.
----

4
project-security/security-pack.rst
View file

@ -5,9 +5,9 @@ Qubes security pack (qubes-secpack)
The **Qubes security pack (qubes-secpack)** is a Git repository that contains:
- `Qubes security bulletins (QSBs) <https://www.qubes-os.org/security/qsb/>`__
- :website:`Qubes security bulletins (QSBs) <security/qsb/>`
- `Qubes canaries <https://www.qubes-os.org/security/canary/>`__
- :website:`Qubes canaries <security/canary/>`
- :ref:`Qubes ISO cryptographic hash values <project-security/verifying-signatures:how to verify the cryptographic hash values of qubes isos>`

20
project-security/security.rst
View file

@ -7,11 +7,11 @@ This page provides a central hub for topics pertaining to the security of the Qu
- :doc:`Qubes security pack (qubes-secpack) </project-security/security-pack>`
- `Qubes security bulletins (QSBs) <https://www.qubes-os.org/security/qsb/>`__
- :website:`Qubes security bulletins (QSBs) <security/qsb/>`
- `Qubes canaries <https://www.qubes-os.org/security/canary/>`__
- :website:`Qubes canaries <security/canary/>`
- `Xen security advisory (XSA) tracker <https://www.qubes-os.org/security/xsa/>`__
- :website:`Xen security advisory (XSA) tracker <security/xsa/>`
- :doc:`Verifying signatures </project-security/verifying-signatures>`
@ -29,7 +29,7 @@ Reporting security issues in Qubes OS
**Please note:** The Qubes security team email address is intended for **responsible disclosure** by security researchers and others who discover legitimate security vulnerabilities. It is **not** intended for everyone who suspects they’ve been hacked. Please do not attempt to contact the Qubes security team unless you can **demonstrate** an actual security vulnerability or unless the team will be able to take reasonable steps to verify your claims.
If you’ve discovered a security issue affecting Qubes OS, either directly or indirectly (e.g., the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! We promise to take all reported issues seriously. If our investigation confirms that an issue affects Qubes, we will patch it within a reasonable time and release a public `Qubes security bulletin (QSB) <https://www.qubes-os.org/security/qsb/>`__ that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer. Please use the `Qubes security team PGP key <https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc>`__ to encrypt your email to this address:
If you’ve discovered a security issue affecting Qubes OS, either directly or indirectly (e.g., the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! We promise to take all reported issues seriously. If our investigation confirms that an issue affects Qubes, we will patch it within a reasonable time and release a public :website:`Qubes security bulletin (QSB) <security/qsb/>` that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer. Please use the `Qubes security team PGP key <https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc>`__ to encrypt your email to this address:
.. code:: bash
@ -49,17 +49,17 @@ Qubes security team
-------------------
The **Qubes security team (QST)** is the subset of the `core team <https://www.qubes-os.org/team/#core-team>`__ that is responsible for ensuring the security of Qubes OS and the Qubes OS Project. In particular, the QST is responsible for:
The **Qubes security team (QST)** is the subset of the :website:`core team <team/#core-team>` that is responsible for ensuring the security of Qubes OS and the Qubes OS Project. In particular, the QST is responsible for:
- Responding to `reported security issues <#reporting-security-issues-in-qubes-os>`__
- Evaluating whether `XSAs <https://www.qubes-os.org/security/xsa/>`__ affect the security of Qubes OS
- Evaluating whether :website:`XSAs <security/xsa/>` affect the security of Qubes OS
- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
- Writing, signing, and publishing `Qubes security bulletins (QSBs) <https://www.qubes-os.org/security/qsb/>`__
- Writing, signing, and publishing :website:`Qubes security bulletins (QSBs) <security/qsb/>`
- Writing, signing, and publishing `Qubes canaries <https://www.qubes-os.org/security/canary/>`__
- Writing, signing, and publishing :website:`Qubes canaries <security/canary/>`
- Generating, safeguarding, and using the project’s `PGP keys <https://keys.qubes-os.org/keys/>`__
@ -71,8 +71,8 @@ Members of the security team
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- `Marek Marczykowski-Górecki <https://www.qubes-os.org/team/#marek-marczykowski-górecki>`__
- :website:`Marek Marczykowski-Górecki <team/#marek-marczykowski-górecki>`
- `Simon Gaiser (aka HW42) <https://www.qubes-os.org/team/#simon-gaiser-aka-hw42>`__
- :website:`Simon Gaiser (aka HW42) <team/#simon-gaiser-aka-hw42>`

22
project-security/verifying-signatures.rst
View file

@ -3,7 +3,7 @@ Verifying signatures
====================
The Qubes OS Project uses `digital signatures <https://en.wikipedia.org/wiki/Digital_signature>`__ to guarantee the authenticity and integrity of certain important assets. This page explains how to verify those signatures. It is extremely important for your security to understand and apply these practices.
The Qubes OS Project uses :wikipedia:`digital signatures <Digital_signature>` to guarantee the authenticity and integrity of certain important assets. This page explains how to verify those signatures. It is extremely important for your security to understand and apply these practices.
What digital signatures can and cannot prove
--------------------------------------------
@ -27,7 +27,7 @@ OpenPGP software
----------------
We use `PGP <https://en.wikipedia.org/wiki/Pretty_Good_Privacy>`__ (specifically, the `OpenPGP <https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP>`__ standard). Before we begin, you’ll need software that can manage PGP keys and verify PGP signatures. Any program that complies with the OpenPGP standard will do, but here are some examples for popular operating systems:
We use :wikipedia:`PGP <Pretty_Good_Privacy>` (specifically, the :wikipedia:`OpenPGP <Pretty_Good_Privacy#OpenPGP>` standard). Before we begin, you’ll need software that can manage PGP keys and verify PGP signatures. Any program that complies with the OpenPGP standard will do, but here are some examples for popular operating systems:
**Linux:** `GnuPG <https://gnupg.org/download/index.html>`__ (`documentation <https://www.gnupg.org/documentation/>`__). Open a terminal and use the ``gpg2`` command. If you don’t already have GnuPG installed, install it via your distro’s package manager or from the GnuPG website.
@ -49,7 +49,7 @@ Before we proceed, you must first complete the prerequisite step of `installing
Once you have appropriate OpenPGP software installed, there are several ways to get the QMSK.
- If you’re on Qubes OS, it’s available in every qube (`except dom0 <https://github.com/QubesOS/qubes-issues/issues/2544>`__):
- If you’re on Qubes OS, it’s available in every qube (:issue:`except dom0 <2544>`):
.. code:: bash
@ -73,7 +73,7 @@ Once you have appropriate OpenPGP software installed, there are several ways to
$ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
- Get it from a public `keyserver <https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples>`__ (specified on first use with ``--keyserver <URI>`` along with keyserver options to include key signatures), e.g.:
- Get it from a public :wikipedia:`keyserver <Key_server_%28cryptographic%29#Keyserver_examples>` (specified on first use with ``--keyserver <URI>`` along with keyserver options to include key signatures), e.g.:
.. code:: bash
@ -103,7 +103,7 @@ Once you have appropriate OpenPGP software installed, there are several ways to
Once you’ve obtained the QMSK, you must verify that it’s authentic rather than a forgery. Anyone can create a PGP key with the name “Qubes Master Signing Key” and the short key ID ``0x36879494``, so you cannot rely on these alone. You also should not rely on any single website, not even over HTTPS.
So, what *should* you do? One option is to use the PGP `Web of Trust <https://en.wikipedia.org/wiki/Web_of_trust>`__. In addition, some operating systems include the means to acquire the QMSK securely. For example, on Fedora, ``dnf install distribution-gpg-keys`` will get you the QMSK along with several other Qubes keys. On Debian, your keyring may already contain the necessary keys.
So, what *should* you do? One option is to use the PGP :wikipedia:`Web of Trust <Web_of_trust>`. In addition, some operating systems include the means to acquire the QMSK securely. For example, on Fedora, ``dnf install distribution-gpg-keys`` will get you the QMSK along with several other Qubes keys. On Debian, your keyring may already contain the necessary keys.
Perhaps the most common route is to rely on the key’s fingerprint, which is a string of 40 alphanumeric characters, like this:
@ -143,7 +143,7 @@ The ``0x`` prefix is sometimes used to indicate that the string following it is
The general idea of “comparing fingerprints” is to go out into the world (whether digitally, physically, or both) and find other 40-character strings purporting to be the QMSK fingerprint, then compare them to your own purported QMSK fingerprint to ensure that the sequence of alphanumeric characters is exactly the same (again, regardless of spaces or capitalization). If any of the characters do not match or are not in the same order, then at least one of the fingerprints is a forgery. Here are some ideas to get you started:
- Check the fingerprint on various websites (e.g., `mailing lists <https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ>`__, `discussion forums <https://forum.qubes-os.org/t/1441/9>`__, `social <https://twitter.com/rootkovska/status/496976187491876864>`__ `media <https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/>`__, `personal websites <https://andrewdavidwong.com/fingerprints.txt>`__).
- Check the fingerprint on various websites (e.g., `mailing lists <https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ>`__, :topic:`discussion forums <1441/9>`, `social <https://twitter.com/rootkovska/status/496976187491876864>`__ `media <https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/>`__, `personal websites <https://andrewdavidwong.com/fingerprints.txt>`__).
- Check against PDFs, photographs, and videos in which the fingerprint appears (e.g., `slides from a talk <https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf>`__, on a `T-shirt <https://twitter.com/legind/status/813847907858337793/photo/2>`__, or in the `recording of a presentation <https://youtu.be/S0TVw7U3MkE?t=2563>`__).
@ -254,7 +254,7 @@ After you have completed these two prerequisite steps, the next step is to obtai
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
- Download it as a file. You can find the RSK for your Qubes release on the `downloads <https://www.qubes-os.org/downloads/>`__ page. You can also download all the currently used developers’ signing keys, RSKs, and the Qubes Master Signing Key from the :doc:`Qubes security pack </project-security/security-pack>` and the `Qubes keyserver <https://keys.qubes-os.org/keys/>`__. Once you’ve downloaded your RSK, import it with GPG:
- Download it as a file. You can find the RSK for your Qubes release on the :website:`downloads <downloads/>` page. You can also download all the currently used developers’ signing keys, RSKs, and the Qubes Master Signing Key from the :doc:`Qubes security pack </project-security/security-pack>` and the `Qubes keyserver <https://keys.qubes-os.org/keys/>`__. Once you’ve downloaded your RSK, import it with GPG:
.. code:: bash
@ -313,11 +313,11 @@ Before we proceed, you must first complete the following prerequisite steps:
Each Qubes ISO is accompanied by a set of **cryptographic hash values** contained in a plain text file ending in ``.DIGESTS``, which can find on the `downloads <https://www.qubes-os.org/downloads/>`__ page alongside the ISO. This file contains the output of running several different cryptographic hash functions on the ISO (a process known as “hashing”) to obtain alphanumeric outputs known as “hash values” or “digests.”
Each Qubes ISO is accompanied by a set of **cryptographic hash values** contained in a plain text file ending in ``.DIGESTS``, which can find on the :website:`downloads <downloads/>` page alongside the ISO. This file contains the output of running several different cryptographic hash functions on the ISO (a process known as “hashing”) to obtain alphanumeric outputs known as “hash values” or “digests.”
One convenient property of hash values is that they can be generated on any computer. This means, for example, that you can download a Qubes ISO on one computer, hash it, then visually compare that hash value to the one you generated or have saved on a different computer.
In addition to the ``.DIGESTS`` files on the `downloads <https://www.qubes-os.org/downloads/>`__ page alongside each ISO, and you can always find all the digest files for every Qubes ISO in the :doc:`Qubes security pack </project-security/security-pack>`.
In addition to the ``.DIGESTS`` files on the :website:`downloads <downloads/>` page alongside each ISO, and you can always find all the digest files for every Qubes ISO in the :doc:`Qubes security pack </project-security/security-pack>`.
If the filename of your ISO is ``Qubes-RX-x86_64.iso``, then the name of the digest file for that ISO is ``Qubes-RX-x86_64.iso.DIGESTS``, where ``X`` is a specific release of Qubes. The digest filename is always the same as the ISO filename followed by ``.DIGESTS``. Since the digest file is a plain text file, you can open it with any text editor. Inside, you should find text that looks similar to this:
@ -419,7 +419,7 @@ Before we proceed, you must first complete the following prerequisite steps:
Every Qubes ISO is released with a **detached PGP signature** file, which you can find on the `downloads <https://www.qubes-os.org/downloads/>`__ page alongside the ISO. If the filename of your ISO is ``Qubes-RX-x86_64.iso``, then the name of the signature file for that ISO is ``Qubes-RX-x86_64.iso.asc``, where ``X`` is a specific release of Qubes. The signature filename is always the same as the ISO filename followed by ``.asc``.
Every Qubes ISO is released with a **detached PGP signature** file, which you can find on the :website:`downloads <downloads/>` page alongside the ISO. If the filename of your ISO is ``Qubes-RX-x86_64.iso``, then the name of the signature file for that ISO is ``Qubes-RX-x86_64.iso.asc``, where ``X`` is a specific release of Qubes. The signature filename is always the same as the ISO filename followed by ``.asc``.
Download both the ISO and its signature file. Put both of them in the same directory, then navigate to that directory. Now, you can verify the ISO by executing this GPG command in the directory that contains both files:
@ -470,7 +470,7 @@ Note that your actual SHA-256 hash value and byte number will depend on which Qu
Now, reading the number of bytes directly from the ISO is fine, but you may be concerned that a sufficiently sophisticated adversary may have compromised the machine on which you’re performing this re-verification and may therefore be capable of feeding you a false success result. After all, if your adversary knows the answer you’re looking for — namely, a match to the genuine ISO — and has access to that very ISO in the same re-verification environment, then there is little to prevent him from simply hashing the original ISO and feeding you that result (perhaps while also reading from the USB drive and piping it into ``/dev/null`` so that you see the light on the USB drive blinking to support the illusion that the data is being read from the USB drive).
Therefore, in order to make things a bit more difficult for your hypothetical adversary, you may instead wish to perform the re-verification in an environment that has never seen the original ISO, e.g., a separate offline computer or a fresh VM the storage space of which is too small to hold the ISO. (**Note:** If you’re doing this in Qubes, you can attach the block device from sys-usb to a separate new qube. You don’t have to perform the re-verification directly in sys-usb.) In that case, you’ll have to obtain the size of the ISO in bytes and enter it into the above command manually. You can, of course, obtain the size by simply using the ``stat -c %s /path/to/iso`` command from above on the machine that has the ISO. You can also obtain it from the Qubes website by hovering over any ISO download button on the `downloads page <https://www.qubes-os.org/downloads/>`__. (You can also view these values directly in the downloads page’s `source data <https://github.com/QubesOS/qubesos.github.io/blob/master/_data/downloads.yml>`__.) Once you have the exact size of the ISO in bytes, simply insert it into the same command, for example:
Therefore, in order to make things a bit more difficult for your hypothetical adversary, you may instead wish to perform the re-verification in an environment that has never seen the original ISO, e.g., a separate offline computer or a fresh VM the storage space of which is too small to hold the ISO. (**Note:** If you’re doing this in Qubes, you can attach the block device from sys-usb to a separate new qube. You don’t have to perform the re-verification directly in sys-usb.) In that case, you’ll have to obtain the size of the ISO in bytes and enter it into the above command manually. You can, of course, obtain the size by simply using the ``stat -c %s /path/to/iso`` command from above on the machine that has the ISO. You can also obtain it from the Qubes website by hovering over any ISO download button on the :website:`downloads page <downloads/>`. (You can also view these values directly in the downloads page’s `source data <https://github.com/QubesOS/qubesos.github.io/blob/master/_data/downloads.yml>`__.) Once you have the exact size of the ISO in bytes, simply insert it into the same command, for example:
.. code:: bash

20
user/advanced-topics/gui-domain.rst
View file

@ -6,7 +6,7 @@ GUI domain
This page is intended for advanced users.
On this page, we describe how to set up a `GUI domain <https://www.qubes-os.org/news/2020/03/18/gui-domain/>`__. In all the cases, the base underlying TemplateVM used is ``Fedora`` with ``XFCE`` flavor to match current desktop choice in ``dom0``. That can be adapted very easily for other desktops and templates. By default, the configured GUI domain is a management qube with global admin permissions ``rwx`` but can be adjusted to ``ro`` (see `Introducing the Qubes Admin API <https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/>`__) in pillar data of the corresponding GUI domain to setup. For example, pillar data for ``sys-gui`` located at ``/srv/pillar/base/qvm/sys-gui.sls``. Please note that each GUI domain has no ``NetVM``.
On this page, we describe how to set up a :website:`GUI domain <news/2020/03/18/gui-domain/>`. In all the cases, the base underlying TemplateVM used is ``Fedora`` with ``XFCE`` flavor to match current desktop choice in ``dom0``. That can be adapted very easily for other desktops and templates. By default, the configured GUI domain is a management qube with global admin permissions ``rwx`` but can be adjusted to ``ro`` (see :website:`Introducing the Qubes Admin API <news/2017/06/27/qubes-admin-api/>`) in pillar data of the corresponding GUI domain to setup. For example, pillar data for ``sys-gui`` located at ``/srv/pillar/base/qvm/sys-gui.sls``. Please note that each GUI domain has no ``NetVM``.
**Note:** The setup is done using ``SaltStack`` formulas with the ``qubesctl`` tool. When executing it, apply step can take time because it needs to download latest Fedora XFCE TemplateVM and install desktop dependencies.
@ -14,7 +14,7 @@ Hybrid GUI domain (``sys-gui``)
-------------------------------
Here, we describe how to setup ``sys-gui`` that we call *hybrid mode* or referenced as a *compromise solution* in `GUI domain <https://www.qubes-os.org/news/2020/03/18/gui-domain/>`__.
Here, we describe how to setup ``sys-gui`` that we call *hybrid mode* or referenced as a *compromise solution* in :website:`GUI domain <news/2020/03/18/gui-domain/>`.
|sys-gui|
@ -48,7 +48,7 @@ GPU GUI domain (``sys-gui-gpu``)
--------------------------------
Here, we describe how to setup ``sys-gui-gpu`` which is a GUI domain with *GPU passthrough* in `GUI domain <https://www.qubes-os.org/news/2020/03/18/gui-domain/>`__.
Here, we describe how to setup ``sys-gui-gpu`` which is a GUI domain with *GPU passthrough* in :website:`GUI domain <news/2020/03/18/gui-domain/>`.
**Note:** the purpose of ``sys-gui-gpu`` is to improve Qubes OS security by detaching the GPU from dom0, this is not intended to improve GPU related performance within qubes, and this will not improve performance.
@ -91,13 +91,13 @@ At this point, you need to reboot your Qubes OS machine in order to boot into ``
**Note:** For some platforms, it can be sufficient to shutdown all the running qubes and starting ``sys-gui-gpu``. Unfortunately, it has been observed that detaching and attaching some GPU cards from ``dom0`` to ``sys-gui-gpu`` can freeze computer. We encourage reboot to prevent any data loss.
Once, ``lightdm`` is started, you can log as ``user`` where ``user`` refers to the first ``dom0`` user in ``qubes`` group and with corresponding ``dom0`` password. A better approach for handling password is currently discussed in `QubesOS/qubes-issues#6740 <https://github.com/QubesOS/qubes-issues/issues/6740>`__.
Once, ``lightdm`` is started, you can log as ``user`` where ``user`` refers to the first ``dom0`` user in ``qubes`` group and with corresponding ``dom0`` password. A better approach for handling password is currently discussed in :issue:`QubesOS/qubes-issues#6740 <6740>`.
VNC GUI domain (``sys-gui-vnc``)
--------------------------------
Here, we describe how to setup ``sys-gui-vnc`` that we call a *remote* GUI domain or referenced as *with a virtual server* in `GUI domain <https://www.qubes-os.org/news/2020/03/18/gui-domain/>`__.
Here, we describe how to setup ``sys-gui-vnc`` that we call a *remote* GUI domain or referenced as *with a virtual server* in :website:`GUI domain <news/2020/03/18/gui-domain/>`.
|sys-gui-vnc|
@ -144,31 +144,31 @@ Application menu lacks qubes entries in a fresh GUI domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See `QubesOS/qubes-issues#5804 <https://github.com/QubesOS/qubes-issues/issues/5804>`__
See :issue:`QubesOS/qubes-issues#5804 <5804>`
Cannot update dom0 from sys-gui
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See `QubesOS/qubes-issues#8934 <https://github.com/QubesOS/qubes-issues/issues/8934>`__
See :issue:`QubesOS/qubes-issues#8934 <8934>`
GUI of HVM qubes not visible
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See `QubesOS/qubes-issues#9385 <https://github.com/QubesOS/qubes-issues/issues/9385>`__
See :issue:`QubesOS/qubes-issues#9385 <9385>`
Power saving/screensaver issues
-------------------------------
See `QubesOS/qubes-issues#9033 <https://github.com/QubesOS/qubes-issues/issues/9033>`__, `QubesOS/qubes-issues#9384 <https://github.com/QubesOS/qubes-issues/issues/9384>`__, `QubesOS/qubes-issues#7989 <https://github.com/QubesOS/qubes-issues/issues/7989>`__
See :issue:`QubesOS/qubes-issues#9033 <9033>`, :issue:`QubesOS/qubes-issues#9384 <9384>`, :issue:`QubesOS/qubes-issues#7989 <7989>`
Qube startup order (sys-usb and sys-gui)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See `QubesOS/qubes-issues#7954 <https://github.com/QubesOS/qubes-issues/issues/7954>`__
See :issue:`QubesOS/qubes-issues#7954 <7954>`
Other GUI domain issues
^^^^^^^^^^^^^^^^^^^^^^^

2
user/advanced-topics/how-to-install-software-in-dom0.rst
View file

@ -209,7 +209,7 @@ Updating over Tor
-----------------
Requires installed `Whonix <https://forum.qubes-os.org/t/19014>`__.
Requires installed :topic:`Whonix <19014>`.
Go to Qubes VM Manager -> System -> Global Settings. See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix.

4
user/advanced-topics/resize-disk-image.rst
View file

@ -25,7 +25,7 @@ There are several disk images which can be easily extended, but pay attention to
In case of standalone qubes and templates, just change the Disk Storage settings above. If the standalone fails to start, temporarily increase the ``qrexec_timeout``, `as described here <https://github.com/QubesOS/qubes-issues/issues/9251#issuecomment-2121596415>`__.
In case of standalone qubes and templates, just change the Disk Storage settings above. If the standalone fails to start, temporarily increase the ``qrexec_timeout``, :issue:`as described here <9251#issuecomment-2121596415>`.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube’s own settings, but the system root image is :doc:`inherited from the template </introduction/getting-started>`, and so it must be changed in the template settings. If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below. See also the OS-specific follow-up instructions below.
@ -122,4 +122,4 @@ Or you can take the risk of reducing the size of the disk. For example, to reduc
If you have a SSD see `here <https://forum.qubes-os.org/t/19054>`__ for information on using fstrim.
If you have a SSD see :topic:`here <19054>` for information on using fstrim.

2
user/advanced-topics/rpc-policy.rst
View file

@ -6,7 +6,7 @@ RPC policies
This page is intended for advanced users.
*Qubes OS 4.1 introduced a new qrexec policy system and policy format. Please see* `this article <https://www.qubes-os.org/news/2020/06/22/new-qrexec-policy-system/>`__ *for details.*
*Qubes OS 4.1 introduced a new qrexec policy system and policy format. Please see* :website:`this article <news/2020/06/22/new-qrexec-policy-system/>` *for details.*
This document explains the basics of RPC policies in Qubes. For more information, see :doc:`Qrexec: command execution in VMs </developer/services/qrexec>`.

2
user/advanced-topics/salt.rst
View file

@ -219,7 +219,7 @@ To apply a state to all templates, call ``qubesctl --templates state.apply``.
The actual configuration is applied using ``salt-ssh`` (running over ``qrexec`` instead of ``ssh``). Which means you don’t need to install anything special in a qube you want to manage. Additionally, for each target qube, ``salt-ssh`` is started from a temporary qube. This way dom0 doesn’t directly interact with potentially malicious target qubes; and in the case of a compromised Salt qube, because they are temporary, the compromise cannot spread from one qube to another.
Beginning with Qubes 4.0 and after `QSB #45 <https://www.qubes-os.org/news/2018/12/03/qsb-45/>`__, we implemented two changes:
Beginning with Qubes 4.0 and after :website:`QSB #45 <news/2018/12/03/qsb-45/>`, we implemented two changes:
1. Added the ``management_dispvm`` qube property, which specifies the disposable Template that should be used for management, such as Salt configuration. App qubes inherit this property from their parent templates. If the value is not set explicitly, the default is taken from the global ``management_dispvm`` property. The qube-specific property is set with the ``qvm-prefs`` command, while the global property is set with the ``qubes-prefs`` command.

4
user/advanced-topics/standalones-and-hvms.rst
View file

@ -18,7 +18,7 @@ Meanwhile, a :ref:`Hardware-assisted Virtual Machine (HVM) <user/reference/gloss
HVMs allow you to create qubes based on any OS for which you have an installation ISO, so you can easily have qubes running Windows, ``*BSD``, or any Linux distribution. You can also use HVMs to run “live” distros.
By default, every qube runs in PVH mode (which has security advantages over both PV and HVM), except for those with attached PCI devices, which run in HVM mode. See `here <https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html>`__ for a discussion of the switch from PV to HVM and `here <https://www.qubes-os.org/news/2018/01/11/qsb-37/>`__ for the announcement about the change to using PVH as default.
By default, every qube runs in PVH mode (which has security advantages over both PV and HVM), except for those with attached PCI devices, which run in HVM mode. See `here <https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html>`__ for a discussion of the switch from PV to HVM and :website:`here <news/2018/01/11/qsb-37/>` for the announcement about the change to using PVH as default.
The standalone/template distinction and the HVM/PV/PVH distinctions are orthogonal. The former is about root filesystem inheritance, whereas the latter 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.
@ -477,6 +477,6 @@ Other documents related to HVMs:
- `Windows VMs <https://forum.qubes-os.org/search?q=windows%20hvm%20%23guides>`__
- `Linux HVM Tips <https://forum.qubes-os.org/t/19008>`__
- :topic:`Linux HVM Tips <19008>`

6
user/downloading-installing-upgrading/download-mirrors.rst
View file

@ -9,7 +9,7 @@ List of Download Mirrors
------------------------
The full list of known Qubes download mirrors is available `here <https://www.qubes-os.org/downloads/#mirrors>`__.
The full list of known Qubes download mirrors is available :website:`here <downloads/#mirrors>`.
Instructions for Mirror Operators
---------------------------------
@ -21,8 +21,8 @@ If you are interested in offering a mirror for Qubes downloads, thank you! We gr
- Our preferred frequency is **once every 24 hours**, but anything up to once every 6-8 hours is fine.
- For technical accommodations, please contact `Wojtek <https://www.qubes-os.org/team/#wojtek-porczyk>`__ or `Marek <https://www.qubes-os.org/team/#marek-marczykowski-górecki>`__.
- For technical accommodations, please contact :website:`Wojtek <team/#wojtek-porczyk>` or :website:`Marek <team/#marek-marczykowski-górecki>`.
- For website updates and fixes, please contact `unman <https://www.qubes-os.org/team/#unman>`__.
- For website updates and fixes, please contact :website:`unman <team/#unman>`.

20
user/downloading-installing-upgrading/installation-guide-4.1.rst
View file

@ -17,9 +17,9 @@ Hardware requirements
**Warning:** Qubes has no control over what happens on your computer before you install it. No software can provide security if it is installed on compromised hardware. Do not install Qubes on a computer you don’t trust. See :doc:`installation security </user/downloading-installing-upgrading/install-security>` for more information.
Qubes OS has very specific :doc:`system requirements </user/hardware/system-requirements>`. To ensure compatibility, we strongly recommend using :doc:`Qubes-certified hardware </user/hardware/certified-hardware/certified-hardware>`. Other hardware may require you to perform significant troubleshooting. You may also find it helpful to consult the `Hardware Compatibility List <https://www.qubes-os.org/hcl/>`__.
Qubes OS has very specific :doc:`system requirements </user/hardware/system-requirements>`. To ensure compatibility, we strongly recommend using :doc:`Qubes-certified hardware </user/hardware/certified-hardware/certified-hardware>`. Other hardware may require you to perform significant troubleshooting. You may also find it helpful to consult the :website:`Hardware Compatibility List <hcl/>`.
Even on supported hardware, you must ensure that `IOMMU-based virtualization <https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization>`__ is activated in the BIOS or UEFI. Without it, Qubes OS won’t be able to enforce isolation. For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be activated in your computer’s BIOS or UEFI, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. This `external guide <https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html>`__ made for Intel-based boards can help you figure out how to enter your BIOS or UEFI to locate and activate those settings. If those settings are not nested under the Advanced tab, you might find them under the Security tab.
Even on supported hardware, you must ensure that :wikipedia:`IOMMU-based virtualization <Input%E2%80%93output_memory_management_unit#Virtualization>` is activated in the BIOS or UEFI. Without it, Qubes OS won’t be able to enforce isolation. For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be activated in your computer’s BIOS or UEFI, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. This `external guide <https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html>`__ made for Intel-based boards can help you figure out how to enter your BIOS or UEFI to locate and activate those settings. If those settings are not nested under the Advanced tab, you might find them under the Security tab.
.. warning::
@ -29,13 +29,13 @@ Copying the ISO onto the installation medium
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. `Download <https://www.qubes-os.org/downloads/>`__ a Qubes ISO.
Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. :website:`Download <downloads/>` a Qubes ISO.
.. DANGER::
**Warning:** Any file you download from the internet could be malicious, even if it appears to come from a trustworthy source. Our philosophy is to :ref:`distrust the infrastructure <introduction/faq:what does it mean to "distrust the infrastructure"?>` . Regardless of how you acquire your Qubes ISO, :doc:`verify its authenticity </project-security/verifying-signatures>` before continuing.
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a USB drive, dual-layer DVD, or Blu-ray disc. The size of each Qubes ISO is available on the `downloads <https://www.qubes-os.org/downloads/>`__ page by hovering over the download button. The instructions below assume you’ve chosen a USB drive as your medium. If you’ve chosen a different medium, please adapt the instructions accordingly.
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a USB drive, dual-layer DVD, or Blu-ray disc. The size of each Qubes ISO is available on the :website:`downloads <downloads/>` page by hovering over the download button. The instructions below assume you’ve chosen a USB drive as your medium. If you’ve chosen a different medium, please adapt the instructions accordingly.
.. warning::
@ -67,7 +67,7 @@ On Windows, you can use the `Rufus <https://rufus.akeo.ie/>`__ tool to write the
.. note::
**Note:** Using Rufus to create the installation medium means that you `won’t be able <https://github.com/QubesOS/qubes-issues/issues/2051>`__ to choose the “Test this media and install Qubes OS” option mentioned in the example below. Instead, choose the “Install Qubes OS” option.
**Note:** Using Rufus to create the installation medium means that you :issue:`won’t be able <2051>` to choose the “Test this media and install Qubes OS” option mentioned in the example below. Instead, choose the “Install Qubes OS” option.
|Rufus menu|
@ -83,7 +83,7 @@ Getting to the boot screen
^^^^^^^^^^^^^^^^^^^^^^^^^^
“Booting” is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software is may be called the `“BIOS” <https://en.wikipedia.org/wiki/BIOS>`__ or `“UEFI” <https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface>`__.
“Booting” is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software is may be called the :wikipedia:`“BIOS” <BIOS>` or :wikipedia:`“UEFI” <Unified_Extensible_Firmware_Interface>`.
Since you’re installing Qubes OS, you’ll need to access your computer’s BIOS or UEFI menu so that you can tell it to boot from the USB drive to which you just copied the Qubes installer ISO.
@ -215,7 +215,7 @@ Installing an operating system onto a USB drive can be a convenient way to try Q
.. note::
**Did you know?** By default, Qubes OS uses `LUKS <https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup>`__ /`dm-crypt <https://en.wikipedia.org/wiki/Dm-crypt>`__ to encrypt everything except the ``/boot`` partition.
**Did you know?** By default, Qubes OS uses :wikipedia:`LUKS <Linux_Unified_Key_Setup>` /:wikipedia:`dm-crypt <Dm-crypt>` to encrypt everything except the ``/boot`` partition.
As soon as you press **Done**, the installer will ask you to enter a passphrase for disk encryption. The passphrase should be complex. Make sure that your keyboard layout reflects what keyboard you are actually using. When you’re finished, press **Done**.
@ -315,9 +315,9 @@ Security
^^^^^^^^
The Qubes OS Project occasionally issues `Qubes Security Bulletins (QSBs) <https://www.qubes-os.org/security/qsb/>`__ as part of the :doc:`Qubes Security Pack (qubes-secpack) </project-security/security-pack>`. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While `updating <#updating>`__ will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce <introduction/support:qubes-announce>` mailing list.
The Qubes OS Project occasionally issues :website:`Qubes Security Bulletins (QSBs) <security/qsb/>` as part of the :doc:`Qubes Security Pack (qubes-secpack) </project-security/security-pack>`. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While `updating <#updating>`__ will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce <introduction/support:qubes-announce>` mailing list.
In addition to QSBs, the Qubes OS Project also publishes `Canaries <https://www.qubes-os.org/security/canary/>`__, XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to :ref:`qubes-announce <introduction/support:qubes-announce>` in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the `Qubes News RSS feed <https://www.qubes-os.org/feed.xml>`__ or join one of our other :doc:`venues </introduction/support>`, where these news items are also announced.
In addition to QSBs, the Qubes OS Project also publishes :website:`Canaries <security/canary/>`, XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to :ref:`qubes-announce <introduction/support:qubes-announce>` in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the :website:`Qubes News RSS feed <feed.xml>` or join one of our other :doc:`venues </introduction/support>`, where these news items are also announced.
For more information about Qubes OS Project security, please see the :doc:`security center </project-security/security>`.
@ -343,7 +343,7 @@ Getting help
------------
- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in `improving <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__ it!)
- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in :website:`improving <doc/how-to-edit-the-documentation/>` it!)
- If issues arise during installation, see the :doc:`Installation Troubleshooting </user/troubleshooting/installation-troubleshooting>` guide.

20
user/downloading-installing-upgrading/installation-guide.rst
View file

@ -17,9 +17,9 @@ Hardware requirements
**Warning:** Qubes has no control over what happens on your computer before you install it. No software can provide security if it is installed on compromised hardware. Do not install Qubes on a computer you don’t trust. See :doc:`installation security </user/downloading-installing-upgrading/install-security>` for more information.
Qubes OS has very specific :doc:`system requirements </user/hardware/system-requirements>`. To ensure compatibility, we strongly recommend using :doc:`Qubes-certified hardware </user/hardware/certified-hardware/certified-hardware>`. Other hardware may require you to perform significant troubleshooting. You may also find it helpful to consult the `Hardware Compatibility List <https://www.qubes-os.org/hcl/>`__.
Qubes OS has very specific :doc:`system requirements </user/hardware/system-requirements>`. To ensure compatibility, we strongly recommend using :doc:`Qubes-certified hardware </user/hardware/certified-hardware/certified-hardware>`. Other hardware may require you to perform significant troubleshooting. You may also find it helpful to consult the :website:`Hardware Compatibility List <hcl/>`.
Even on supported hardware, you must ensure that `IOMMU-based virtualization <https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization>`__ is activated in the BIOS or UEFI. Without it, Qubes OS won’t be able to enforce isolation. For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be activated in your computer’s BIOS or UEFI, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. This `external guide <https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html>`__ made for Intel-based boards can help you figure out how to enter your BIOS or UEFI to locate and activate those settings. If those settings are not nested under the Advanced tab, you might find them under the Security tab.
Even on supported hardware, you must ensure that :wikipedia:`IOMMU-based virtualization <Input%E2%80%93output_memory_management_unit#Virtualization>` is activated in the BIOS or UEFI. Without it, Qubes OS won’t be able to enforce isolation. For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be activated in your computer’s BIOS or UEFI, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. This `external guide <https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html>`__ made for Intel-based boards can help you figure out how to enter your BIOS or UEFI to locate and activate those settings. If those settings are not nested under the Advanced tab, you might find them under the Security tab.
.. warning::
@ -29,13 +29,13 @@ Copying the ISO onto the installation medium
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. `Download <https://www.qubes-os.org/downloads/>`__ a Qubes ISO. If your Internet connection is unstable and the download is interrupted, you could resume the partial download with ``wget --continue`` in case you are currently using wget for downloading or use a download-manager with resume capability. Alternatively you can download installation ISO via BitTorrent that sometimes enables higher download speeds and more reliable downloads of large files.
Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. :website:`Download <downloads/>` a Qubes ISO. If your Internet connection is unstable and the download is interrupted, you could resume the partial download with ``wget --continue`` in case you are currently using wget for downloading or use a download-manager with resume capability. Alternatively you can download installation ISO via BitTorrent that sometimes enables higher download speeds and more reliable downloads of large files.
.. DANGER::
**Warning:** Any file you download from the internet could be malicious, even if it appears to come from a trustworthy source. Our philosophy is to :ref:`distrust the infrastructure <introduction/faq:what does it mean to "distrust the infrastructure"?>` . Regardless of how you acquire your Qubes ISO, :doc:`verify its authenticity </project-security/verifying-signatures>` before continuing.
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a USB drive, dual-layer DVD, or Blu-ray disc. The size of each Qubes ISO is available on the `downloads <https://www.qubes-os.org/downloads/>`__ page by hovering over the download button. The instructions below assume you’ve chosen a USB drive as your medium. If you’ve chosen a different medium, please adapt the instructions accordingly.
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a USB drive, dual-layer DVD, or Blu-ray disc. The size of each Qubes ISO is available on the :website:`downloads <downloads/>` page by hovering over the download button. The instructions below assume you’ve chosen a USB drive as your medium. If you’ve chosen a different medium, please adapt the instructions accordingly.
.. warning::
@ -67,7 +67,7 @@ On Windows, you can use the `Rufus <https://rufus.ie/>`__ tool to write the ISO
.. note::
**Note:** Using Rufus to create the installation medium means that you `won’t be able <https://github.com/QubesOS/qubes-issues/issues/2051>`__ to choose the “Test this media and install Qubes OS” option mentioned in the example below. Instead, choose the “Install Qubes OS” option.
**Note:** Using Rufus to create the installation medium means that you :issue:`won’t be able <2051>` to choose the “Test this media and install Qubes OS” option mentioned in the example below. Instead, choose the “Install Qubes OS” option.
|Rufus menu|
@ -83,7 +83,7 @@ Getting to the boot screen
^^^^^^^^^^^^^^^^^^^^^^^^^^
“Booting” is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software may be called the `“BIOS” <https://en.wikipedia.org/wiki/BIOS>`__ or `“UEFI” <https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface>`__.
“Booting” is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software may be called the :wikipedia:`“BIOS” <BIOS>` or :wikipedia:`“UEFI” <Unified_Extensible_Firmware_Interface>`.
Since you’re installing Qubes OS, you’ll need to access your computer’s BIOS or UEFI menu so that you can tell it to boot from the USB drive to which you just copied the Qubes installer ISO.
@ -199,7 +199,7 @@ Installing an operating system onto a USB drive can be a convenient way to try Q
.. note::
**Did you know?** By default, Qubes OS uses `LUKS <https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup>`__ /`dm-crypt <https://en.wikipedia.org/wiki/Dm-crypt>`__ to encrypt everything except the ``/boot`` partition.
**Did you know?** By default, Qubes OS uses :wikipedia:`LUKS <Linux_Unified_Key_Setup>` /:wikipedia:`dm-crypt <Dm-crypt>` to encrypt everything except the ``/boot`` partition.
As soon as you press **Done**, the installer will ask you to enter a passphrase for disk encryption. The passphrase should be complex. Make sure that your keyboard layout reflects what keyboard you are actually using. When you’re finished, press **Done**.
@ -306,9 +306,9 @@ Security
^^^^^^^^
The Qubes OS Project occasionally issues `Qubes Security Bulletins (QSBs) <https://www.qubes-os.org/security/qsb/>`__ as part of the :doc:`Qubes Security Pack (qubes-secpack) </project-security/security-pack>`. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While `updating <#updating>`__ will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce <introduction/support:qubes-announce>` mailing list.
The Qubes OS Project occasionally issues :website:`Qubes Security Bulletins (QSBs) <security/qsb/>` as part of the :doc:`Qubes Security Pack (qubes-secpack) </project-security/security-pack>`. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While `updating <#updating>`__ will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce <introduction/support:qubes-announce>` mailing list.
In addition to QSBs, the Qubes OS Project also publishes `Canaries <https://www.qubes-os.org/security/canary/>`__, XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to :ref:`qubes-announce <introduction/support:qubes-announce>` in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the `Qubes News RSS feed <https://www.qubes-os.org/feed.xml>`__ or join one of our other :doc:`venues </introduction/support>`, where these news items are also announced.
In addition to QSBs, the Qubes OS Project also publishes :website:`Canaries <security/canary/>`, XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to :ref:`qubes-announce <introduction/support:qubes-announce>` in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the :website:`Qubes News RSS feed <feed.xml>` or join one of our other :doc:`venues </introduction/support>`, where these news items are also announced.
For more information about Qubes OS Project security, please see the :doc:`security center </project-security/security>`.
@ -334,7 +334,7 @@ Getting help
------------
- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in `improving <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__ it!)
- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in :website:`improving <doc/how-to-edit-the-documentation/>` it!)
- If issues arise during installation, see the :doc:`Installation Troubleshooting </user/troubleshooting/installation-troubleshooting>` guide.

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

@ -9,7 +9,7 @@ Qubes OS
--------
Qubes OS releases are supported for **six months** after each subsequent major or minor release (see :doc:`Version Scheme </developer/releases/version-scheme>`). The current release and past major releases are always available on the `Downloads <https://www.qubes-os.org/downloads/>`__ page, while all ISOs, including past minor releases, are available from our `download mirrors <https://www.qubes-os.org/downloads/#mirrors>`__.
Qubes OS releases are supported for **six months** after each subsequent major or minor release (see :doc:`Version Scheme </developer/releases/version-scheme>`). The current release and past major releases are always available on the :website:`Downloads <downloads/>` page, while all ISOs, including past minor releases, are available from our :website:`download mirrors <downloads/#mirrors>`.
.. list-table::
:widths: 11 11 11 11

6
user/downloading-installing-upgrading/testing.rst
View file

@ -6,7 +6,7 @@ Testing new releases and updates
This page is intended for advanced users.
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can :doc:`contribute </introduction/contributing>` to the Qubes OS Project. If you’re interested in helping with this, please `join the testing team <https://forum.qubes-os.org/t/joining-the-testing-team/5190>`__. There are several different types of testing, which we’ll cover below.
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can :doc:`contribute </introduction/contributing>` to the Qubes OS Project. If you’re interested in helping with this, please :topic:`join the testing team <joining-the-testing-team/5190>`. There are several different types of testing, which we’ll cover below.
**Warning:** Software testing is intended for advanced users and developers. You should only attempt to do this if you know what you’re doing. Never rely on code that is in testing for critical work!
@ -16,9 +16,9 @@ Releases
How to test upcoming Qubes OS releases:
- Test the latest release candidate (RC) on the `downloads <https://www.qubes-os.org/downloads/>`__ page, if one is currently available. (Or try an older RC from our `FTP server <https://ftp.qubes-os.org/iso/>`__.)
- Test the latest release candidate (RC) on the :website:`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>`__.)
- Try the `signed weekly builds <https://qubes.notset.fr/iso/>`__. (:topic:`Learn more <16929>` and `track their status <https://github.com/fepitre/updates-status-iso/issues>`__.)
- Use :doc:`qubes-builder </developer/building/qubes-builder-v2>` to build the latest release yourself.

4
user/downloading-installing-upgrading/upgrade/4_0.rst
View file

@ -11,7 +11,7 @@ Preparation
-----------
1. Go to `downloads <https://www.qubes-os.org/downloads/>`__ and prepare a USB drive or DVD with the R4.0 installer.
1. Go to :website:`downloads <downloads/>` and prepare a USB drive or DVD with the R4.0 installer.
2. If this is your only computer, and you do not have a R3.2 installer, you should also create a separate R3.2 USB drive or DVD installer at this time.
@ -73,7 +73,7 @@ Restore from your backup
4. Go to **Qubes menu -> System Tools -> Qubes Manager** to start it.
5. Follow the **Restoring from a Backup** section in the :doc:`Backup, Restoration, and Migration </user/how-to-guides/how-to-back-up-restore-and-migrate>` guide. We recommend that you restore only your :ref:`app qubes <user/reference/glossary:app qube>` and :ref:`standalones <user/reference/glossary:standalone>` from R3.2. Using :doc:`templates </user/templates/templates>` and :ref:`service qubes <user/reference/glossary:service qube>` from R3.2 is not fully supported (see `#3514 <https://github.com/QubesOS/qubes-issues/issues/3514>`__). Instead, we recommend using the templates that were created specifically for R4.0, which you can :doc:`customize </user/how-to-guides/how-to-install-software>` according to your needs. For the template OS versions supported in R4.0, see :ref:`supported releases <user/downloading-installing-upgrading/supported-releases:templates>`. If the restore tool complains about missing templates, you can select the option to restore the app qubes anyway, then change them afterward to use one of the default R4.0 templates.
5. Follow the **Restoring from a Backup** section in the :doc:`Backup, Restoration, and Migration </user/how-to-guides/how-to-back-up-restore-and-migrate>` guide. We recommend that you restore only your :ref:`app qubes <user/reference/glossary:app qube>` and :ref:`standalones <user/reference/glossary:standalone>` from R3.2. Using :doc:`templates </user/templates/templates>` and :ref:`service qubes <user/reference/glossary:service qube>` from R3.2 is not fully supported (see :issue:`3514`). Instead, we recommend using the templates that were created specifically for R4.0, which you can :doc:`customize </user/how-to-guides/how-to-install-software>` according to your needs. For the template OS versions supported in R4.0, see :ref:`supported releases <user/downloading-installing-upgrading/supported-releases:templates>`. If the restore tool complains about missing templates, you can select the option to restore the app qubes anyway, then change them afterward to use one of the default R4.0 templates.

2
user/downloading-installing-upgrading/upgrade/4_1.rst
View file

@ -19,7 +19,7 @@ If you would prefer to perform a clean installation rather than upgrading in-pla
1. Create a :ref:`backup <user/how-to-guides/how-to-back-up-restore-and-migrate:creating a backup>` of your current installation.
2. `Download <https://www.qubes-os.org/downloads/>`__ the latest 4.1 release.
2. :website:`Download <downloads/>` the latest 4.1 release.
3. Follow the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>` to install Qubes 4.1.

2
user/downloading-installing-upgrading/upgrade/4_2.rst
View file

@ -38,7 +38,7 @@ If you would prefer to perform a clean installation rather than upgrading in-pla
4. Create a :ref:`backup <user/how-to-guides/how-to-back-up-restore-and-migrate:creating a backup>` of your current installation.
5. `Download <https://www.qubes-os.org/downloads/>`__ the latest 4.2 release.
5. :website:`Download <downloads/>` the latest 4.2 release.
6. Follow the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>` to install Qubes 4.2.

6
user/hardware/certified-hardware/certified-hardware.rst
View file

@ -9,7 +9,7 @@ The Qubes OS Project aims to partner with a select few computer vendors to ensur
**Warning:** The Qubes OS Project certifies only that a particular hardware *configuration* is *supported* by Qubes OS and is available to purchase with Qubes OS preinstalled. We take no responsibility for any vendor’s manufacturing, shipping, payment, or other practices; nor can we control whether physical hardware is modified (whether maliciously or otherwise) *en route* to the user.
You may also be interested in the `community-recommended hardware <https://forum.qubes-os.org/t/5560>`__ list and the `hardware compatibility list (HCL) <https://www.qubes-os.org/hcl/>`__.
You may also be interested in the :topic:`community-recommended hardware <5560>` list and the :website:`hardware compatibility list (HCL) <hcl/>`.
Qubes-certified computers
-------------------------
@ -87,7 +87,7 @@ Hardware certification requirements
A basic requirement is that all Qubes-certified devices must be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation (`SLAT <https://en.wikipedia.org/wiki/Second_Level_Address_Translation>`__), also known as `EPT <https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile>`__ in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach. We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous `XSA-148 <https://xenbits.xen.org/xsa/advisory-148.html>`__, which — unlike many other major Xen bugs — regrettably did `affect <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt>`__ Qubes OS. Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation (:wikipedia:`SLAT <Second_Level_Address_Translation>`), also known as `EPT <https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile>`__ in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach. We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous `XSA-148 <https://xenbits.xen.org/xsa/advisory-148.html>`__, which — unlike many other major Xen bugs — regrettably did `affect <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt>`__ Qubes OS. Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka “the BIOS”), such as `coreboot <https://www.coreboot.org/>`__. The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see `Intel FSP <https://firmware.intel.com/learn/fsp/about-intel-fsp>`__) as well as other internal operations (see `Intel ME <https://www.apress.com/9781430265719>`__). However, we specifically require all code used for and dealing with the System Management Mode (SMM) to be open-source.
@ -117,6 +117,6 @@ To have hardware certified, the vendor must:
It is the vendor’s responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version. This could be done by consulting the `Hardware Compatibility List <https://www.qubes-os.org/hcl/>`__ or trying to install it themselves before shipping any units to us. While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
It is the vendor’s responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version. This could be done by consulting the :website:`Hardware Compatibility List <hcl/>` or trying to install it themselves before shipping any units to us. While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
If you are interested in having your hardware certified, please `contact us <mailto:business@qubes-os.org>`__.

2
user/hardware/certified-hardware/insurgo-privacybeast-x230.rst
View file

@ -19,7 +19,7 @@ The `Insurgo PrivacyBeast X230 <https://insurgo.ca/produit/qubesos-certified-pri
- 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>`__.
- `Heads <https://github.com/osresearch/heads/>`__ provisioned pre-delivery to protect against malicious :wikipedia:`interdiction <Interdiction>`.

2
user/hardware/certified-hardware/nitropad-t430.rst
View file

@ -27,7 +27,7 @@ Key features of the `NitroPad T430 <https://shop.nitrokey.com/shop/product/nitro
- 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>`__
- Security-conscious shipping to mitigate against third-party :wikipedia:`interdiction <Interdiction>`

2
user/hardware/certified-hardware/nitropad-x230.rst
View file

@ -23,7 +23,7 @@ The `NitroPad X230 <https://shop.nitrokey.com/shop/product/nitropad-x230-67>`__
- 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>`__
- Security-conscious shipping to mitigate against third-party :wikipedia:`interdiction <Interdiction>`

2
user/hardware/how-to-use-the-hcl.rst
View file

@ -3,7 +3,7 @@ How to use the hardware compatibility list (HCL)
================================================
The `HCL <https://www.qubes-os.org/hcl/>`__ is a compilation of reports generated and submitted by users across various Qubes versions about their hardware’s compatibility with Qubes.
The :website:`HCL <hcl/>` is a compilation of reports generated and submitted by users across various Qubes versions about their hardware’s compatibility with Qubes.
**Note:** Except in the case of developer-reported entries, the Qubes team has not independently verified the accuracy of these reports. Please first consult the data sheets (CPU, chipset, motherboard) prior to buying new hardware for Qubes. Make sure it meets the :doc:`System Requirements </user/hardware/system-requirements>` and search in particular for support of:

14
user/hardware/system-requirements.rst
View file

@ -13,9 +13,9 @@ Minimum
- **CPU:** 64-bit Intel or AMD processor (also known as ``x86_64``, ``x64``, and ``AMD64``)
- `Intel VT-x <https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29>`__ with `EPT <https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables>`__ or `AMD-V <https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29>`__ with `RVI <https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing>`__
- :wikipedia:`Intel VT-x <X86_virtualization#Intel_virtualization_.28VT-x.29>` with :wikipedia:`EPT <Second_Level_Address_Translation#Extended_Page_Tables>` or :wikipedia:`AMD-V <X86_virtualization#AMD_virtualization_.28AMD-V.29>` with :wikipedia:`RVI <Second_Level_Address_Translation#Rapid_Virtualization_Indexing>`
- `Intel VT-d <https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d>`__ or `AMD-Vi (also known as AMD IOMMU) <https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29>`__
- :wikipedia:`Intel VT-d <X86_virtualization#Intel-VT-d>` or :wikipedia:`AMD-Vi (also known as AMD IOMMU) <X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29>`
@ -31,9 +31,9 @@ Recommended
- **CPU:** 64-bit Intel processor (also known as ``x86_64``, ``x64``, and ``Intel 64``)
- `Intel VT-x <https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29>`__ with `EPT <https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables>`__
- :wikipedia:`Intel VT-x <X86_virtualization#Intel_virtualization_.28VT-x.29>` with :wikipedia:`EPT <Second_Level_Address_Translation#Extended_Page_Tables>`
- `Intel VT-d <https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d>`__
- :wikipedia:`Intel VT-d <X86_virtualization#Intel-VT-d>`
- For security, we recommend processors that are recent enough to still be receiving microcode updates (see `below <#important-notes>`__ for details).
@ -51,7 +51,7 @@ Recommended
- **Graphics:** Intel integrated graphics processor (IGP) strongly recommended
- Nvidia GPUs may require significant `troubleshooting <https://forum.qubes-os.org/t/18987>`__.
- Nvidia GPUs may require significant :topic:`troubleshooting <18987>`.
- AMD GPUs have not been formally tested, but Radeons (especially RX580 and earlier) generally work well.
@ -85,9 +85,9 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
- :doc:`Certified hardware </user/hardware/certified-hardware/certified-hardware>` — Qubes developer certified, officially recommended
- `Community-recommended hardware <https://forum.qubes-os.org/t/5560>`__ — list curated and maintained by the community, unofficially recommended
- :topic:`Community-recommended hardware <5560>` — list curated and maintained by the community, unofficially recommended
- `Hardware compatibility list (HCL) <https://www.qubes-os.org/hcl/>`__ — community test results, neither recommended nor disrecommended
- :website:`Hardware compatibility list (HCL) <hcl/>` — community test results, neither recommended nor disrecommended

4
user/how-to-guides/how-to-back-up-restore-and-migrate.rst
View file

@ -85,7 +85,7 @@ Restoring from a backup
2. **ignore username mismatch**: This option applies only to the restoration of dom0’s home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See `issue #3498 <https://github.com/QubesOS/qubes-issues/issues/3498>`__ for more details.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See :issue:`3498` for more details.
@ -130,7 +130,7 @@ Migrating between two physical machines
---------------------------------------
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, `install Qubes <https://www.qubes-os.org/downloads/>`__ on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved!
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, :website:`install Qubes <downloads/>` on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved!
Choosing a backup passphrase
----------------------------

2
user/how-to-guides/how-to-install-software.rst
View file

@ -5,7 +5,7 @@ How to install software
When you wish to install software in Qubes OS, you should generally install it in a :ref:`template <user/reference/glossary:template>`. For installing templates themselves, see :ref:`how to install a template <user/templates/templates:installing>`. Advanced users may also be interested in learning how to install software in :doc:`standalones </user/advanced-topics/standalones-and-hvms>` and :doc:`dom0 </user/advanced-topics/how-to-install-software-in-dom0>`.
Qubes OS is effectively a “meta” operating system (OS) that can run almost any arbitrary OS inside of itself. For example, the way software is normally installed in a Linux distribution (“distro”) is quite different from the way software is normally installed in Windows. This isn’t up to Qubes. Qubes is just the framework in which you’re running these other OSes. Therefore, if you want to install software in a Linux template, for example, you should do so in whatever way is normal for that Linux distro. Most Linux software is distributed via `packages <https://en.wikipedia.org/wiki/Package_format>`__, which are stored in `software repositories <https://en.wikipedia.org/wiki/Software_repository>`__ (“repos”). `Package managers <https://en.wikipedia.org/wiki/Package_manager>`__ handle downloading, installing, updating, and removing packages. (Again, none of this is Qubes-specific.) If you’re not familiar with how software is normally installed in Linux distros via package managers or the software you want doesn’t seem to be available in your distro’s repos (or you’re in another situation not covered on this page), please read this `community guide to installing software in Qubes <https://forum.qubes-os.org/t/9991/>`__.
Qubes OS is effectively a “meta” operating system (OS) that can run almost any arbitrary OS inside of itself. For example, the way software is normally installed in a Linux distribution (“distro”) is quite different from the way software is normally installed in Windows. This isn’t up to Qubes. Qubes is just the framework in which you’re running these other OSes. Therefore, if you want to install software in a Linux template, for example, you should do so in whatever way is normal for that Linux distro. Most Linux software is distributed via :wikipedia:`packages <Package_format>`, which are stored in :wikipedia:`software repositories <Software_repository>` (“repos”). :wikipedia:`Package managers <Package_manager>` handle downloading, installing, updating, and removing packages. (Again, none of this is Qubes-specific.) If you’re not familiar with how software is normally installed in Linux distros via package managers or the software you want doesn’t seem to be available in your distro’s repos (or you’re in another situation not covered on this page), please read this :topic:`community guide to installing software in Qubes <9991/>`.
The following instructions explain how to permanently install new software in a template. There are different instructions for software from the default repositories and all other software. (If you’re not sure, try the default repositories first.)

8
user/how-to-guides/how-to-organize-your-qubes.rst
View file

@ -40,7 +40,7 @@ This helps her keep groups of qubes organized in a set. Some of her qubes are ba
|Alice’s system: diagram 2|
- **Several email qubes.** Since Alice is a command-line aficionado, she likes to use a terminal-based email client, so both her work and personal email qubes are based on a template with `Mutt <https://forum.qubes-os.org/t/18989>`__ installed. The email qubes where she sends and receives PGP-signed and encrypted email securely accesses the private keys in her PGP backend qube (more on that below). To guard against malicious attachments, she configured Mutt to open all attachment files in :doc:`disposable qubes </user/how-to-guides/how-to-use-disposables>`.
- **Several email qubes.** Since Alice is a command-line aficionado, she likes to use a terminal-based email client, so both her work and personal email qubes are based on a template with :topic:`Mutt <18989>` installed. The email qubes where she sends and receives PGP-signed and encrypted email securely accesses the private keys in her PGP backend qube (more on that below). To guard against malicious attachments, she configured Mutt to open all attachment files in :doc:`disposable qubes </user/how-to-guides/how-to-use-disposables>`.
- **Several qubes for communication tools,** like Signal, Slack, Zoom, Telegram, IRC, and Discord. This is where she teleconferences and chats with clients. She uses :doc:`USB passthrough </user/how-to-guides/how-to-use-usb-devices>` to attach her webcam to each qube as needed and detaches it afterward. Likewise, she gives each qube access to her microphone while it’s needed, then removes access afterward. This way, she doesn’t have to trust any given video chat program’s mute button and doesn’t have to worry about being spied on when she’s not on a call. She also has a qube for social media platforms like Twitter, Reddit, and Hacker News for networking and keeping up with new developments (or so she claims; in reality, it’s mostly for feuds over programming language superiority, Vim vs. Emacs wars, and tabs vs. spaces crusades).
@ -70,11 +70,11 @@ Bob isn’t a super technical guy. He prefers to keep his tools simple so he can
- **Whonix qubes.** He has the standard ``sys-whonix`` service qube for providing Torified network access, and he uses disposable ``anon-workstation`` app qubes for using Tor Browser to do research on stories he’s writing. Since the topic is often of a sensitive nature and might implicate powerful individuals, it’s important that he be able to conduct this research with a degree of anonymity. He doesn’t want the subjects of his investigation to know that he’s looking into them. He also doesn’t want his network requests being traced back to his work or home IP addresses. Whonix helps with both of these concerns. He also has another Whonix-based disposable template for receiving tips anonymously via Tor, since some high-risk whistleblowers he’s interacted with have said that they can’t take a chance with any other form of communication.
- **Two qubes for** `Signal <https://forum.qubes-os.org/t/19073>`__ **.** Bob has two Signal app qubes (both on the same template in which the Signal desktop app is installed). One is linked to his own mobile number for communicating with co-workers and other known, trusted contacts. The other is a public number that serves as an additional way for sources to reach him confidentially. This is especially useful for individuals who don’t use Tor but for whom unencrypted communication could be dangerous.
- **Two qubes for** :topic:`Signal <19073>` **.** Bob has two Signal app qubes (both on the same template in which the Signal desktop app is installed). One is linked to his own mobile number for communicating with co-workers and other known, trusted contacts. The other is a public number that serves as an additional way for sources to reach him confidentially. This is especially useful for individuals who don’t use Tor but for whom unencrypted communication could be dangerous.
- **Several data vaults.** When someone sends Bob material that turns out to be useful, or when he comes across useful material while doing his own research, he stores a copy in a completely offline, network-isolated vault qube. Most of these files are PDFs and images, though some are audio files, videos, and text files. Since most of them are from unknown or untrusted sources, Bob isn’t sure if it would be safe to put them all in the same vault, so he makes different vaults (usually one for each story or topic) just in case. This has the side benefit of helping to keep things organized.
- **A** `VPN qube <https://forum.qubes-os.org/t/19061>`__ **and associated qubes for accessing work resources.** The servers at work can only be accessed from the organization’s network, so Bob has certain qubes that are connected to a VPN qube so that he can upload his work and access anything he needs on the local network when he’s not physically there.
- **A** :topic:`VPN qube <19061>` **and associated qubes for accessing work resources.** The servers at work can only be accessed from the organization’s network, so Bob has certain qubes that are connected to a VPN qube so that he can upload his work and access anything he needs on the local network when he’s not physically there.
- **A password manager vault.** Bob stores all of his login credentials in the default password manager that came with his offline vault qube. He :doc:`securely copies and pastes </user/how-to-guides/how-to-copy-and-paste-text>` them into other qubes as needed.
@ -124,7 +124,7 @@ The vast majority of Carol’s assets are in broad-based, low-cost, passively-ma
Carol has added the following to her Qubes setup:
- **A standalone qube for running Bitcoin Core and an offline wallet vault.** Carol finds the design and security properties of Bitcoin very interesting, so she’s experimenting with running a full node. She also created a network-isolated vault in order to try running a copy of Bitcoin Core completely offline as a “cold storage” wallet. She’s still trying to figure out how this compares to an actual hardware wallet, paper wallet, or physically air-gapped machine, but she’s figures they all have different security properties. She also recently heard about using `Electrum as a “split” wallet in Qubes <https://forum.qubes-os.org/t/19017>`__ and is interested in exploring that further.
- **A standalone qube for running Bitcoin Core and an offline wallet vault.** Carol finds the design and security properties of Bitcoin very interesting, so she’s experimenting with running a full node. She also created a network-isolated vault in order to try running a copy of Bitcoin Core completely offline as a “cold storage” wallet. She’s still trying to figure out how this compares to an actual hardware wallet, paper wallet, or physically air-gapped machine, but she’s figures they all have different security properties. She also recently heard about using :topic:`Electrum as a “split” wallet in Qubes <19017>` and is interested in exploring that further.
- **Whonix qubes.** Carol read somewhere that Bitcoin nodes should be run over Tor for privacy and security. She found it very convenient that Whonix is already integrated into Qubes, so she simply set her Bitcoin Core “full node” qube to use ``sys-whonix`` as its networking qube.

4
user/how-to-guides/how-to-update.rst
View file

@ -23,7 +23,7 @@ Security updates
----------------
Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a `Qubes Security Bulletin (QSB) <https://www.qubes-os.org/security/qsb/>`__ via the `Qubes Security Pack (qubes-secpack) <https://www.qubes-os.org/security/pack/>`__. It is very important to read each new QSB and follow any user instructions it contains. Most of the time, simply updating your system normally, as described below, will be sufficient to obtain security updates. However, in some cases, special action may be required on your part, which will be explained in the QSB.
Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a :website:`Qubes Security Bulletin (QSB) <security/qsb/>` via the :website:`Qubes Security Pack (qubes-secpack) <security/pack/>`. It is very important to read each new QSB and follow any user instructions it contains. Most of the time, simply updating your system normally, as described below, will be sufficient to obtain security updates. However, in some cases, special action may be required on your part, which will be explained in the QSB.
Checking for updates
--------------------
@ -109,7 +109,7 @@ The above covers updating *within* a given operating system (OS) release. Eventu
**It’s very important that you use only supported releases so that you continue to receive security updates.** This means that you *must* periodically upgrade Qubes OS and your templates before they reach EOL. You can always see which versions of Qubes OS and select templates are supported on :doc:`Supported releases </user/downloading-installing-upgrading/supported-releases>`.
In the case of Qubes OS itself, we will make an `announcement <https://www.qubes-os.org/news/categories/>`__ when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide :doc:`instructions for upgrading to the next stable supported Qubes OS release </user/downloading-installing-upgrading/upgrade/upgrade>`.
In the case of Qubes OS itself, we will make an :website:`announcement <news/categories/>` when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide :doc:`instructions for upgrading to the next stable supported Qubes OS release </user/downloading-installing-upgrading/upgrade/upgrade>`.
Periodic upgrades are also important for templates. For example, you might be using a :doc:`Fedora template </user/templates/fedora/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 :ref:`supported template releases <user/downloading-installing-upgrading/supported-releases:templates>`).

8
user/how-to-guides/how-to-use-block-storage-devices.rst
View file

@ -11,7 +11,7 @@ Using the Devices Widget to Attach a Drive
------------------------------------------
(**Note:** In the present context, the term “USB drive” denotes any `USB mass storage device <https://en.wikipedia.org/wiki/USB_mass_storage_device_class>`__. In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
(**Note:** In the present context, the term “USB drive” denotes any :wikipedia:`USB mass storage device <USB_mass_storage_device_class>`. In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller.
@ -121,7 +121,7 @@ Recovering From Premature Device Destruction
--------------------------------------------
If you fail to detach the device before it’s destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), `there will be problems <https://github.com/QubesOS/qubes-issues/issues/1082>`__.
If you fail to detach the device before it’s destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), :issue:`there will be problems <1082>`.
To recover from this error state, in dom0 run
@ -139,7 +139,7 @@ What if I removed the device before detaching it from the VM?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Currently (until issue `1082 <https://github.com/QubesOS/qubes-issues/issues/1082>`__ gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, ``libvirtd``) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. If this isn’t an option, you can manually recover from the situation by following these steps:
Currently (until issue :issue:`1082` gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, ``libvirtd``) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. If this isn’t an option, you can manually recover from the situation by following these steps:
1. Physically connect the device back. You can use any device as long as it will be detected under the same name (for example, ``sdb``).
@ -219,7 +219,7 @@ Additional Attach Options
-------------------------
Attaching a block device through the command line offers additional customisation options, specifiable via the ``--option``/``-o`` option. (Yes, confusing wording, there’s an `issue for that <https://github.com/QubesOS/qubes-issues/issues/4530>`__.)
Attaching a block device through the command line offers additional customisation options, specifiable via the ``--option``/``-o`` option. (Yes, confusing wording, there’s an :issue:`issue for that <4530>`.)
frontend-dev
^^^^^^^^^^^^

2
user/how-to-guides/how-to-use-devices.rst
View file

@ -53,7 +53,7 @@ Attaching a Device to Several VMs
Only ``mic`` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the ``--persistent`` option), however, only one of them can be started at the same time.
But be careful: There is a `bug in <https://github.com/QubesOS/qubes-issues/issues/4692>`__ ``qvm-device block`` or ``qvm-block`` which will allow you to *attach* a block device to two running VMs. Don’t do that!
But be careful: There is a :issue:`bug in <4692>` ``qvm-device block`` or ``qvm-block`` which will allow you to *attach* a block device to two running VMs. Don’t do that!
General ``qvm-device`` Command Line Tool Behavior
-------------------------------------------------

4
user/how-to-guides/how-to-use-disposables.rst
View file

@ -164,7 +164,7 @@ Starting an arbitrary program in a disposable from an app qube
--------------------------------------------------------------
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). Starting an arbitrary program can be done from an app qube by running
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details :issue:`here <2581#issuecomment-272664009>`). Starting an arbitrary program can be done from an app qube by running
.. code:: bash
@ -178,7 +178,7 @@ Starting an arbitrary application in a disposable via command line from dom0
----------------------------------------------------------------------------
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details :issue:`here <2581#issuecomment-272664009>`). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
.. code:: bash

2
user/how-to-guides/how-to-use-optical-discs.rst
View file

@ -11,7 +11,7 @@ Currently, the only options for reading and recording optical discs (e.g., CDs,
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to a VM.
3. Use a SATA optical drive attached to dom0. (**Caution:** This option is `potentially dangerous <https://forum.qubes-os.org/t/19075#dom0-precautions>`__.)
3. Use a SATA optical drive attached to dom0. (**Caution:** This option is :topic:`potentially dangerous <19075#dom0-precautions>`.)

4
user/how-to-guides/how-to-use-pci-devices.rst
View file

@ -87,7 +87,7 @@ Additional Attach Options
-------------------------
Attaching a PCI device through the commandline offers additional options, specifiable via the ``--option``/``-o`` option. (Yes, confusing wording, there’s an `issue for that <https://github.com/QubesOS/qubes-issues/issues/4530>`__.)
Attaching a PCI device through the commandline offers additional options, specifiable via the ``--option``/``-o`` option. (Yes, confusing wording, there’s an :issue:`issue for that <4530>`.)
``qvm-pci`` exposes two additional options. Both are intended to fix device or driver specific issues, but both come with :ref:`heavy security implications <user/security-in-qubes/device-handling-security:pci security>`! **Make sure you understand them before continuing!**
@ -109,7 +109,7 @@ permissive
^^^^^^^^^^
Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of `side channel attacks <https://en.wikipedia.org/wiki/Side-channel_attack>`__.
Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of :wikipedia:`side channel attacks <Side-channel_attack>`.
usage example:

4
user/how-to-guides/how-to-use-usb-devices.rst
View file

@ -15,13 +15,13 @@ Examples of valid cases for USB-passthrough:
- `microcontroller programming <https://www.arduino.cc/en/Main/Howto>`__
- `external audio devices <https://forum.qubes-os.org/t/18984>`__
- :topic:`external audio devices <18984>`
- :doc:`optical drives </user/how-to-guides/how-to-use-optical-discs>` for recording
(If you are thinking to use a two-factor-authentication device, :doc:`there is an app for that </user/security-in-qubes/ctap-proxy>`. But it has some `issues <https://github.com/QubesOS/qubes-issues/issues/4661>`__.)
(If you are thinking to use a two-factor-authentication device, :doc:`there is an app for that </user/security-in-qubes/ctap-proxy>`. But it has some :issue:`issues <4661>`.)
Attaching and detaching a USB device
------------------------------------

4
user/security-in-qubes/anti-evil-maid.rst
View file

@ -35,9 +35,9 @@ Security Considerations
-----------------------
`Qubes security guidelines <https://forum.qubes-os.org/t/19075>`__ dictate that USB devices should never be attached directly to dom0, since this can result in the entire system being compromised. However, in its default configuration, installing and using AEM requires attaching a USB drive (i.e., `mass storage device <https://en.wikipedia.org/wiki/USB_mass_storage_device_class>`__) directly to dom0. (The other option is to install AEM to an internal disk. However, this carries significant security implications, as explained `here <https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html>`__.) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand. Given the practical feasibility of attacks like `BadUSB <https://web.archive.org/web/20160304013434/https://srlabs.de/badusb/>`__ and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision. New, factory-sealed USB drives cannot simply be assumed to be “clean” (e.g., to have non-malicious microcontroller firmware). Therefore, it is up to each individual Qubes user to evaluate the relative risk of each attack vector against his or her security model.
:topic:`Qubes security guidelines <19075>` dictate that USB devices should never be attached directly to dom0, since this can result in the entire system being compromised. However, in its default configuration, installing and using AEM requires attaching a USB drive (i.e., :wikipedia:`mass storage device <USB_mass_storage_device_class>`) directly to dom0. (The other option is to install AEM to an internal disk. However, this carries significant security implications, as explained `here <https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html>`__.) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand. Given the practical feasibility of attacks like `BadUSB <https://web.archive.org/web/20160304013434/https://srlabs.de/badusb/>`__ and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision. New, factory-sealed USB drives cannot simply be assumed to be “clean” (e.g., to have non-malicious microcontroller firmware). Therefore, it is up to each individual Qubes user to evaluate the relative risk of each attack vector against his or her security model.
For example, a user who frequently travels with a Qubes laptop holding sensitive data may be at a much higher risk of Evil Maid attacks than a home user with a stationary Qubes desktop. If the frequent traveler judges her risk of an Evil Maid attack to be higher than the risk of a malicious USB device, she might reasonably opt to install and use AEM. On the other hand, the home user might deem the probability of an Evil Maid attack occurring in her own home to be so low that there is a higher probability that any USB drive she purchases is already compromised, in which case she might reasonably opt never to attach any USB devices directly to dom0. (In either case, users can–and should–secure dom0 against further USB-related attacks through the use of a `USB VM <https://forum.qubes-os.org/t/19075#creating-and-using-a-usbvm>`__.)
For example, a user who frequently travels with a Qubes laptop holding sensitive data may be at a much higher risk of Evil Maid attacks than a home user with a stationary Qubes desktop. If the frequent traveler judges her risk of an Evil Maid attack to be higher than the risk of a malicious USB device, she might reasonably opt to install and use AEM. On the other hand, the home user might deem the probability of an Evil Maid attack occurring in her own home to be so low that there is a higher probability that any USB drive she purchases is already compromised, in which case she might reasonably opt never to attach any USB devices directly to dom0. (In either case, users can–and should–secure dom0 against further USB-related attacks through the use of a :topic:`USB VM <19075#creating-and-using-a-usbvm>`.)
For more information, please see `this discussion thread <https://groups.google.com/d/msg/qubes-devel/EBc4to5IBdg/n1hfsHSfbqsJ>`__.

6
user/security-in-qubes/ctap-proxy.rst
View file

@ -11,11 +11,11 @@ What is CTAP, U2F, FIDO2?
CTAP, U2F, and FIDO2 are all related to authentication protocols and standards developed by the FIDO Alliance. CTAP has two versions: CTAP1 and CTAP2:
1. `CTAP1/U2F <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`__ (Universal 2nd Factor): U2F is an earlier protocol developed by the FIDO Alliance as part of the FIDO U2F standard. It provides a strong second-factor authentication method using dedicated hardware security keys. U2F allows users to authenticate to online services by simply plugging in a U2F-compliant security key and pressing a button, providing a higher level of security compared to traditional passwords.
1. :wikipedia:`CTAP1/U2F <Universal_2nd_Factor>` (Universal 2nd Factor): U2F is an earlier protocol developed by the FIDO Alliance as part of the FIDO U2F standard. It provides a strong second-factor authentication method using dedicated hardware security keys. U2F allows users to authenticate to online services by simply plugging in a U2F-compliant security key and pressing a button, providing a higher level of security compared to traditional passwords.
2. `CTAP2 <https://en.wikipedia.org/wiki/Client_to_Authenticator_Protocol>`__ (Client to Authenticator Protocol): CTAP2 is a protocol within the FIDO2 framework that enables communication between a client device (e.g., a computer or smartphone) and an authenticator (e.g., a hardware device). CTAP allows for secure and convenient authentication using public key cryptography and strong authentication factors.
2. :wikipedia:`CTAP2 <Client_to_Authenticator_Protocol>` (Client to Authenticator Protocol): CTAP2 is a protocol within the FIDO2 framework that enables communication between a client device (e.g., a computer or smartphone) and an authenticator (e.g., a hardware device). CTAP allows for secure and convenient authentication using public key cryptography and strong authentication factors.
3. `FIDO2 <https://en.wikipedia.org/wiki/FIDO_Alliance>`__: FIDO2 is a set of standards and protocols developed by the FIDO Alliance for passwordless and strong authentication. It combines two main components: CTAP (Client to Authenticator Protocol) and WebAuthn (Web Authentication API). FIDO2 enables users to authenticate to online services using various authentication methods, such as biometrics, PINs, or hardware tokens, instead of relying on passwords.
3. :wikipedia:`FIDO2 <FIDO_Alliance>`: FIDO2 is a set of standards and protocols developed by the FIDO Alliance for passwordless and strong authentication. It combines two main components: CTAP (Client to Authenticator Protocol) and WebAuthn (Web Authentication API). FIDO2 enables users to authenticate to online services using various authentication methods, such as biometrics, PINs, or hardware tokens, instead of relying on passwords.

2
user/security-in-qubes/data-leaks.rst
View file

@ -15,7 +15,7 @@ For example, suppose you have an ``email`` app qube. You have set the firewall r
Note that physically air-gapped machines are not necessarily immune to this problem. Covert channels can potentially take many forms (e.g., sneakernet thumb drive, bluetooth, or even microphone and speakers).
For a further discussion of covert channels, see `this thread <https://groups.google.com/d/topic/qubes-users/AqZV65yZLuU/discussion>`__ and `#817 <https://github.com/QubesOS/qubes-issues/issues/817>`__.
For a further discussion of covert channels, see `this thread <https://groups.google.com/d/topic/qubes-users/AqZV65yZLuU/discussion>`__ and :issue:`817`.
Types of Data Leaks
-------------------

4
user/security-in-qubes/device-handling-security.rst
View file

@ -19,7 +19,7 @@ Some devices do not implement a reset option. In these cases, Qubes by default d
In case device reset is disabled for any reason, detaching the device should be considered a risk. Ideally, devices for which the ``no-strict-reset`` option is set are attached once to a VM which isn’t shut down until the system is shut down.
Additionally, Qubes restricts the config-space a VM may use to communicate with a PCI device. Only whitelisted registers are accessible. However, some devices or applications require full PCI access. In these cases, the whole config-space may be allowed. You’re potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit. This increases the VM’s ability to run a `side channel attack <https://en.wikipedia.org/wiki/Side-channel_attack>`__ and vulnerability to the same. See `Xen PCI Passthrough: PV guests and PCI quirks <https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks>`__ and `Software Attacks on Intel VT-d <https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf>`__ (page 7) for more details.
Additionally, Qubes restricts the config-space a VM may use to communicate with a PCI device. Only whitelisted registers are accessible. However, some devices or applications require full PCI access. In these cases, the whole config-space may be allowed. You’re potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit. This increases the VM’s ability to run a :wikipedia:`side channel attack <Side-channel_attack>` and vulnerability to the same. See `Xen PCI Passthrough: PV guests and PCI quirks <https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks>`__ and `Software Attacks on Intel VT-d <https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf>`__ (page 7) for more details.
USB Security
------------
@ -43,4 +43,4 @@ If you have only a USB mouse connected to a USB qube, but the keyboard is connec
If your keyboard is also connected to a USB qube, things are much harder. Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen. One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication). One way to achieve this is to use a :doc:`YubiKey </user/security-in-qubes/mfa>`, or some other hardware token, or even to manually enter a one-time password.
Support for `two factor authentication <https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/>`__ was recently added, though there are `issues <https://github.com/QubesOS/qubes-issues/issues/4661>`__.
Support for :website:`two factor authentication <news/2018/09/11/qubes-u2f-proxy/>` was recently added, though there are :issue:`issues <4661>`.

4
user/security-in-qubes/firewall.rst
View file

@ -101,7 +101,7 @@ Thereby sys-firewall-1 is only needed if you have other client qubes connected t
If you adopt this model, you should be aware that all traffic will arrive at the ``network service qube`` appearing to originate from the IP address of ``sys-firewall-2``.
For the VPN service please also look at the `VPN documentation <https://forum.qubes-os.org/t/19061>`__.
For the VPN service please also look at the :topic:`VPN documentation <19061>`.
Enabling networking between two qubes
-------------------------------------
@ -321,7 +321,7 @@ As an example we can take the use case of qube QubeDest running a web server lis
- **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running
- **Note:** `Issue #4028 <https://github.com/QubesOS/qubes-issues/issues/4028>`__ discusses adding a command to automate exposing the port.
- **Note:** :issue:`Issue #4028 <4028>` discusses adding a command to automate exposing the port.

6
user/security-in-qubes/firewall_4.1.rst
View file

@ -89,7 +89,7 @@ Thereby sys-firewall-1 is only needed if you have other client qubes connected t
If you adopt this model, you should be aware that all traffic will arrive at the ``network service qube`` appearing to originate from the IP address of ``sys-firewall-2``.
For the VPN service please also look at the `VPN documentation <https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061>`__.
For the VPN service please also look at the :topic:`VPN documentation <configuring-a-proxyvm-vpn-gateway/19061>`.
Enabling networking between two qubes
-------------------------------------
@ -311,7 +311,7 @@ As an example we can take the use case of a web server listening on port 443 tha
- **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running
- **Note:** `Issue #4028 <https://github.com/QubesOS/qubes-issues/issues/4028>`__ discusses adding a command to automate exposing the port.
- **Note:** :issue:`Issue #4028 <4028>` discusses adding a command to automate exposing the port.
@ -343,7 +343,7 @@ Code the appropriate new filtering firewall rule to allow new connections for th
- If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
- In Qubes R4, at the moment (`QubesOS/qubes-issues#3644 <https://github.com/QubesOS/qubes-issues/issues/3644>`__), nftables is also used which imply that additional rules need to be set in a ``qubes-firewall`` nft table with a forward chain.
- In Qubes R4, at the moment (:issue:`QubesOS/qubes-issues#3644 <3644>`), nftables is also used which imply that additional rules need to be set in a ``qubes-firewall`` nft table with a forward chain.

10
user/security-in-qubes/mfa.rst
View file

@ -19,7 +19,7 @@ Time-based One-time Password (TOTP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As the name implies, this generates authentication code that is time-dependent. You can save the TOTP secret in a mobile app like `FreeOTP <https://en.wikipedia.org/wiki/FreeOTP>`__ and then use it as an additional factor to login to your Qubes system.
As the name implies, this generates authentication code that is time-dependent. You can save the TOTP secret in a mobile app like :wikipedia:`FreeOTP <FreeOTP>` and then use it as an additional factor to login to your Qubes system.
**Warning**: remember to keep backup access codes.
@ -134,13 +134,13 @@ Login with a YubiKey / NitroKey3
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The YubiKey / NitroKey3 is a hardware authentication device manufactured by Yubico / NitroKey to protect access to computers, networks, and online services that supports one-time passwords (OTP), public-key cryptography, and authentication, and the Universal 2nd Factor `(U2F) <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`__ and FIDO2 protocols developed by the `FIDO Alliance <https://en.wikipedia.org/wiki/FIDO_Alliance>`__.
The YubiKey / NitroKey3 is a hardware authentication device manufactured by Yubico / NitroKey to protect access to computers, networks, and online services that supports one-time passwords (OTP), public-key cryptography, and authentication, and the Universal 2nd Factor :wikipedia:`(U2F) <Universal_2nd_Factor>` and FIDO2 protocols developed by the :wikipedia:`FIDO Alliance <FIDO_Alliance>`.
You can use a YubiKey / NitroKey3 to enhance the user authentication in Qubes. The following instructions explain how to setup the YubiKey / NitroKey3 as an *additional* way to login.
After setting it up, you can login by providing both - a password typed in via keyboard *and* the YubiKey / NitroKey3 plugged in. Someone eavesdropping your login attempt would not be able to login by only observing and remembering your password. Stealing your YubiKey / NitroKey3 would not suffice to login either. Only if an attacker has both, the password and the Yubikey / NitroKey3, it would be possible to login (it is thus called `Multi-factor authentication <https://en.wikipedia.org/wiki/Multi-factor_authentication>`__).
After setting it up, you can login by providing both - a password typed in via keyboard *and* the YubiKey / NitroKey3 plugged in. Someone eavesdropping your login attempt would not be able to login by only observing and remembering your password. Stealing your YubiKey / NitroKey3 would not suffice to login either. Only if an attacker has both, the password and the Yubikey / NitroKey3, it would be possible to login (it is thus called :wikipedia:`Multi-factor authentication <Multi-factor_authentication>`).
The following instructions keep your current login password untouched and recommends to define a new, additional password that is used in combination with the YubiKey / NitroKey3 only. This ensures that you a) do not accidentally lock yourself out during setup and b) you do not need to fear `shoulder surfing <https://en.wikipedia.org/wiki/Shoulder_surfing_(computer_security)>`__ so much (i.e. by not using your standard login password in public).
The following instructions keep your current login password untouched and recommends to define a new, additional password that is used in combination with the YubiKey / NitroKey3 only. This ensures that you a) do not accidentally lock yourself out during setup and b) you do not need to fear :wikipedia:`shoulder surfing <Shoulder_surfing_(computer_security)>` so much (i.e. by not using your standard login password in public).
Setup login with YubiKey / NitroKey3
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -150,7 +150,7 @@ To use the YubiKey / NitroKey3 for multi-factor authentication you need to
- install software for the YubiKey / NitroKey3,
- configure the YubiKey for the `Challenge-Response <https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication>`__ mode or the NitroKey3 for `HOTP <https://en.wikipedia.org/wiki/HMAC-based_one-time_password>`__ mode,
- configure the YubiKey for the :wikipedia:`Challenge-Response <Challenge%E2%80%93response_authentication>` mode or the NitroKey3 for :wikipedia:`HOTP <HMAC-based_one-time_password>` mode,
- store the password for YubiKey / NitroKey3 Login and the Challenge-Response / HOTP secret in dom0,

4
user/security-in-qubes/split-gpg.rst
View file

@ -364,7 +364,7 @@ Security Benefits
^^^^^^^^^^^^^^^^^
In the standard Split GPG setup, there are at least two ways in which the ``work-gpg`` VM might be compromised. First, an attacker who is capable of exploiting a hypothetical bug in ``work-email``’s `MUA <https://en.wikipedia.org/wiki/Mail_user_agent>`__ could gain control of the ``work-email`` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the ``work-gpg`` VM), giving the attacker control of the ``work-gpg`` VM. Second, a malicious public key file which is imported into the ``work-gpg`` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the ``work-gpg`` VM. In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the ``work-email`` VM or to another VM (e.g., the ``netvm``, which is always untrusted by default) via the Split GPG protocol or other :doc:`covert channels </user/security-in-qubes/data-leaks>`. Once the master secret key is in the ``work-email`` VM, the attacker could simply email it to himself (or to the world).
In the standard Split GPG setup, there are at least two ways in which the ``work-gpg`` VM might be compromised. First, an attacker who is capable of exploiting a hypothetical bug in ``work-email``’s :wikipedia:`MUA <Mail_user_agent>` could gain control of the ``work-email`` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the ``work-gpg`` VM), giving the attacker control of the ``work-gpg`` VM. Second, a malicious public key file which is imported into the ``work-gpg`` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the ``work-gpg`` VM. In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the ``work-email`` VM or to another VM (e.g., the ``netvm``, which is always untrusted by default) via the Split GPG protocol or other :doc:`covert channels </user/security-in-qubes/data-leaks>`. Once the master secret key is in the ``work-email`` VM, the attacker could simply email it to himself (or to the world).
In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the ``work-gpg`` VM will not be able to obtain the user’s master secret key since it is simply not there. Rather, the master secret key remains in the ``vault`` VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it. [1]_ The attacker might nonetheless be able to leak the secret subkeys from the ``work-gpg`` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place. (This is significantly less devastating than having to create a new *master* keypair.)
@ -388,7 +388,7 @@ Current limitations
-------------------
- Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket `#474 <https://github.com/QubesOS/qubes-issues/issues/474>`__ for more details and plans how to get around this problem, as well as the section on `using Split GPG with subkeys <#advanced-using-split-gpg-with-subkeys>`__.
- Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket :issue:`474` for more details and plans how to get around this problem, as well as the section on `using Split GPG with subkeys <#advanced-using-split-gpg-with-subkeys>`__.
- It doesn’t solve the problem of allowing the user to know what is to be signed before the operation gets approved. Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined.

2
user/security-in-qubes/vm-sudo.rst
View file

@ -78,7 +78,7 @@ Replacing passwordless root access with Dom0 user prompt
An alternative approach is to enable user/root isolation by using a dom0 generated prompt.
A list of steps to do so is provided in the `Qubes community guide, Replacing passwordless root with a dom0 prompt <https://forum.qubes-os.org/t/replacing-passwordless-root-with-a-dom0-prompt/19074>`__ **without any guarantee of safety, accuracy, or completeness. Proceed at your own risk. Do not rely on this for extra security.**
A list of steps to do so is provided in the :topic:`Qubes community guide, Replacing passwordless root with a dom0 prompt <replacing-passwordless-root-with-a-dom0-prompt/19074>` **without any guarantee of safety, accuracy, or completeness. Proceed at your own risk. Do not rely on this for extra security.**
Dom0 passwordless root access

6
user/templates/debian/debian-upgrade.rst
View file

@ -90,7 +90,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
7. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/templates:important notes>`, but it does not hurt. Some users have `reported <https://github.com/QubesOS/qubes-issues/issues/5055>`__ that it makes a difference.)
7. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/templates:important notes>`, but it does not hurt. Some users have :issue:`reported <5055>` that it makes a difference.)
.. code:: bash
@ -179,7 +179,7 @@ Relevant discussions:
- `Fixing sound in Debian Stretch <https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU>`__
- `User apt commands blocked on startup <https://github.com/QubesOS/qubes-issues/issues/2621>`__
- :issue:`User apt commands blocked on startup <2621>`
@ -201,7 +201,7 @@ Additional information
----------------------
- Please note that, if you installed packages from one of the :doc:`testing </user/downloading-installing-upgrading/testing>` repositories, you must make sure that the repository is enabled in ``/etc/apt/sources.list.d/qubes-r4.list`` before attempting the upgrade. Otherwise, your upgrade will `break <https://github.com/QubesOS/qubes-issues/issues/2418>`__.
- Please note that, if you installed packages from one of the :doc:`testing </user/downloading-installing-upgrading/testing>` repositories, you must make sure that the repository is enabled in ``/etc/apt/sources.list.d/qubes-r4.list`` before attempting the upgrade. Otherwise, your upgrade will :issue:`break <2418>`.
- By default, Qubes uses code names in the ``apt`` sources files, although the templates are referred to by release number. Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitions.

2
user/templates/debian/debian.rst
View file

@ -81,7 +81,7 @@ If you have a Debian template from an earlier release that you want to use for s
This is a `known bug <https://github.com/QubesOS/qubes-issues/issues/9129>`__ in Salt which affects version 3006-5.
This is a :issue:`known bug <9129>` in Salt which affects version 3006-5.
Starting services
^^^^^^^^^^^^^^^^^

4
user/templates/fedora/fedora-upgrade.rst
View file

@ -117,7 +117,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
5. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/templates:important notes>`, but it does not hurt. Some users have `reported <https://github.com/QubesOS/qubes-issues/issues/5055>`__ that it makes a difference.)
5. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/templates:important notes>`, but it does not hurt. Some users have :issue:`reported <5055>` that it makes a difference.)
.. code:: bash
@ -192,7 +192,7 @@ Release-specific notes
----------------------
See the `news <https://www.qubes-os.org/news/>`__ announcement for each specific template release for any important notices about that particular release.
See the :website:`news <news/>` announcement for each specific template release for any important notices about that particular release.
End-of-life (EOL) releases
^^^^^^^^^^^^^^^^^^^^^^^^^^

16
user/templates/minimal-templates.rst
View file

@ -12,9 +12,9 @@ Important
---------
1. `The minimal templates are intended only for advanced users. <https://forum.qubes-os.org/t/9717/15>`__ Most things will *not* work out-of-the-box, and you *will* have to fix them yourself. If you are not prepared to do a lot of reading, searching, learning, and troubleshooting, then you should instead stick to the standard templates, which are perfectly suitable for the vast majority of users. In particular, if you are new to Qubes, you should not attempt to use minimal templates until you have gained more experience.
1. :topic:`The minimal templates are intended only for advanced users. <9717/15>` Most things will *not* work out-of-the-box, and you *will* have to fix them yourself. If you are not prepared to do a lot of reading, searching, learning, and troubleshooting, then you should instead stick to the standard templates, which are perfectly suitable for the vast majority of users. In particular, if you are new to Qubes, you should not attempt to use minimal templates until you have gained more experience.
2. If something works with a standard template but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug. In such cases, please do *not* file a bug report. Instead, please see :doc:`Help, Support, Mailing Lists, and Forum </introduction/support>` for the appropriate place to ask for help. Once you have learned how to solve your problem, please `contribute what you learned to the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__.
2. If something works with a standard template but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug. In such cases, please do *not* file a bug report. Instead, please see :doc:`Help, Support, Mailing Lists, and Forum </introduction/support>` for the appropriate place to ask for help. Once you have learned how to solve your problem, please :website:`contribute what you learned to the documentation <doc/how-to-edit-the-documentation/>`.
3. The minimal templates are intentionally *minimal*. :ref:`Do not ask for your favorite package to be added to the minimal template by default. <introduction/faq:could you please make my preference the default?>`
@ -120,13 +120,13 @@ The following list provides an overview of which packages are needed for which p
- :doc:`USB qube </user/advanced-topics/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>`__: Use the ``dnf search "NetworkManager VPN plugin"`` command to look up the VPN packages you need, based on the VPN technology you’ll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the `VPN instructions <https://forum.qubes-os.org/t/19061#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager>`__ to configure it.
- :topic:`VPN qube <19061>`: Use the ``dnf search "NetworkManager VPN plugin"`` command to look up the VPN packages you need, based on the VPN technology you’ll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the :topic:`VPN instructions <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``.
To manage fedora-39-minimal templates with salt, you may need to install ``python3-urllib3`` in older versions of the template. (This package is already installed in recent builds: see `discussion <https://github.com/QubesOS/qubes-issues/issues/8806>`__.)
To manage fedora-39-minimal templates with salt, you may need to install ``python3-urllib3`` in older versions of the template. (This package is already installed in recent builds: see :issue:`discussion <8806>`.)
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:
@ -172,7 +172,7 @@ Also, there are packages to provide additional services:
You may also wish to consider additional packages from the ``qubes-core-agent`` suite.
See `here <https://forum.qubes-os.org/t/18999>`__ for further information on customizing ``fedora-minimal``.
See :topic:`here <18999>` for further information on customizing ``fedora-minimal``.
Logging
^^^^^^^
@ -196,7 +196,7 @@ The following list provides an overview of which packages are needed for which p
- Commonly used utilities: ``pciutils`` ``vim-minimal`` ``less`` ``psmisc`` ``gnome-keyring``
- The ``zenity`` package is required for interactive dialogs, e.g., file selection (`#5202 <https://github.com/QubesOS/qubes-issues/issues/5202>`__) and for using the Nautilus menu option to copy some files to other qubes (`#6801 <https://github.com/QubesOS/qubes-issues/issues/6801>`__).
- The ``zenity`` package is required for interactive dialogs, e.g., file selection (:issue:`5202`) and for using the Nautilus menu option to copy some files to other qubes (:issue:`6801`).
- Audio: ``pulseaudio-qubes``
@ -208,9 +208,9 @@ The following list provides an overview of which packages are needed for which p
- :doc:`USB qube </user/advanced-topics/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.
- Qubes to which USB devices are attached: ``libpam-systemd`` (Until `#7689 <https://github.com/QubesOS/qubes-issues/issues/7689>`__ is fixed, either pair it with ``qubes-core-agent-passwordless-root`` or manually activate the user session with ``loginctl activate <USER_SESSION_ID>``.)
- Qubes to which USB devices are attached: ``libpam-systemd`` (Until :issue:`7689` is fixed, either pair it with ``qubes-core-agent-passwordless-root`` or manually activate the user session with ``loginctl activate <USER_SESSION_ID>``.)
- `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.
- :topic:`VPN qube <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 :topic:`VPN howto <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``.

10
user/templates/templates.rst
View file

@ -61,13 +61,13 @@ These templates are supported by the Qubes community. Some of them are available
By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer. In addition, these templates may be somewhat less stable, since the Qubes developers do not test them.
- `Whonix <https://forum.qubes-os.org/t/19014>`__
- :topic:`Whonix <19014>`
- `Ubuntu <https://qubes.3isec.org>`__
- `Arch Linux <https://forum.qubes-os.org/t/19052>`__
- :topic:`Arch Linux <19052>`
- `Gentoo <https://forum.qubes-os.org/t/19007>`__
- :topic:`Gentoo <19007>`
- :doc:`Gentoo Minimal </user/templates/minimal-templates>`
@ -75,7 +75,7 @@ By installing these templates, you are trusting not only the Qubes developers an
\* *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>`__ *.*
\* *The CentOS version used by this template reached* :wikipedia:`End-of-Life in June 2024 <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* :issue:`declined <9716>` *.*
Windows
-------
@ -308,7 +308,7 @@ Important Notes
^^^^^^^^^^^^^^^
- ``qvm-trim-template`` is no longer necessary or available in Qubes 4.0 and higher. All qubes are created in a thin pool and trimming is handled automatically. No user action is required. See `Disk Trim <https://forum.qubes-os.org/t/19054>`__ for more information.
- ``qvm-trim-template`` is no longer necessary or available in Qubes 4.0 and higher. All qubes are created in a thin pool and trimming is handled automatically. No user action is required. See :topic:`Disk Trim <19054>` for more information.
- RPM-installed templates are “system managed” and therefore cannot be backed up using Qubes’ built-in backup function. In order to ensure the preservation of your custom settings and the availability of a “known-good” backup template, you may wish to clone the default system template and use your clone as the default template for your app qubes.

2
user/templates/windows/qubes-windows-tools-4-0.rst
View file

@ -70,7 +70,7 @@ Qubes Windows Tools are open source and are distributed under a GPL license.
- Currently only 64-bit versions of Windows 7 and Windows 10 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although `there has been reports <https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA>`__ on working GPU passthrough).
- **This page documents the process of installing Qubes Windows Tools on versions up to R3.2.**. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see `issue #3585 <https://github.com/QubesOS/qubes-issues/issues/3585>`__).
- **This page documents the process of installing Qubes Windows Tools on versions up to R3.2.**. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see :issue:`3585`).

2
user/templates/windows/qubes-windows-tools-4-1.rst
View file

@ -53,7 +53,7 @@ for Qubes R4.1.2, or
for Qubes R4.2.0, respectively, instead of the command listed in step 1 of the installation described below. This will provide the .iso file to be presented as an installation drive to the Windows qube in step 3 of the QWT installation.
If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version `4.1.68-1 <https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm>`__ for Qubes R4.1.2 and version `4.1.69-1 <https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm>`__ for Qubes R4.2.0). After downloading, copy the file to ``dom0`` as described in `How to copy from dom0 <https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0>`__ and install it via ``sudo dnf install /path/to/rpmfile``. Now you can proceed according to step 3 of the description below.
If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version `4.1.68-1 <https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm>`__ for Qubes R4.1.2 and version `4.1.69-1 <https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm>`__ for Qubes R4.2.0). After downloading, copy the file to ``dom0`` as described in :website:`How to copy from dom0 <doc/how-to-copy-from-dom0/#copying-to-dom0>` and install it via ``sudo dnf install /path/to/rpmfile``. Now you can proceed according to step 3 of the description below.
**Warning**: These older versions of Qubes Windows Tools will be replaced during the next dom0 update by the current dummy version 4.1.70-1. This can be inhibited by appending the line ``exclude=qubes-windows-tools`` to the file ``/etc/dnf/dnf.conf`` in dom0. But this will also stop any further QWT updates - so be sure to remove this line when - hopefully - a new functional version 4.1.71-1 of Qubes Windows Tools will be made available!!!

6
user/templates/windows/windows-qubes-4-0.rst
View file

@ -177,7 +177,7 @@ MS Windows versions considerations:
- The instructions *may* work on other versions than Windows 7 x64 but haven’t been tested.
- Qubes Windows Tools (QWT) only supports Windows 7 x64. Note that there are `known issues <https://github.com/QubesOS/qubes-issues/issues/3585>`__ with QWT on Qubes 4.x
- Qubes Windows Tools (QWT) only supports Windows 7 x64. Note that there are :issue:`known issues <3585>` with QWT on Qubes 4.x
- For Windows 10 under Qubes 4.0, a way to install QWT 4.0.1.3, which has worked in several instances, is described in :doc:`Qubes Windows Tools </user/templates/windows/qubes-windows-tools-4-0>`.
@ -349,7 +349,7 @@ Windows update
--------------
Depending on how old your installation media is, fully updating your Windows VM may take *hours* (this isn’t specific to Xen/Qubes) so make sure you clone your VM between the mandatory reboots in case something goes wrong. This `comment <https://github.com/QubesOS/qubes-issues/issues/3585#issuecomment-366471111>`__ provides useful links on updating a Windows 7 SP1 VM.
Depending on how old your installation media is, fully updating your Windows VM may take *hours* (this isn’t specific to Xen/Qubes) so make sure you clone your VM between the mandatory reboots in case something goes wrong. This :issue:`comment <3585#issuecomment-366471111>` provides useful links on updating a Windows 7 SP1 VM.
**Note:** if you already have Qubes Windows Tools installed the video adapter in Windows will be “Qubes video driver” and you won’t be able to see the Windows Update process when the VM is being powered off because Qubes services would have been stopped by then. Depending on the size of the Windows update packs it may take a bit of time until the VM shutdowns by itself, leaving one wondering if the VM has crashed or still finalizing the updates (in dom0 a changing CPU usage - eg. shown with ``xentop`` - usually indicates that the VM hasn’t crashed). To avoid guessing the VM’s state enable debugging (``qvm-prefs -s win7new debug true``) and in Windows’ device manager (My computer -> Manage / Device manager / Display adapters) temporarily re-enable the standard VGA adapter and disable “Qubes video driver”. You can disable debugging and revert to Qubes’ display once the VM is updated.
@ -357,4 +357,4 @@ Further customization
---------------------
Please see the `Customizing Windows 7 templates <https://forum.qubes-os.org/t/19005>`__ page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - ie. TemplateVM or StandaloneVM).
Please see the :topic:`Customizing Windows 7 templates <19005>` page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - ie. TemplateVM or StandaloneVM).

4
user/templates/windows/windows-qubes-4-1.rst
View file

@ -73,7 +73,7 @@ However, if you are an expert or want to do it manually you may continue below.
Have the Windows ISO image (preferrably the 64-bit version) downloaded in some qube.
Windows ISOs can be downloaded directly from Microsoft (eg. `here <https://www.microsoft.com/en-us/software-download/windows10ISO>`__ for Win10), or selected and downloaded via the `Windows Media Creation Tool <https://go.microsoft.com/fwlink/?LinkId=691209>`__. You should, however, regard the downloaded image to be untrustworthy, since there is no reliable way to check that the download was not somehow compromised (see the discussion in issue `Simplify Qubes Windows Tools Installation for R4.1 #7240 <https://github.com/QubesOS/qubes-issues/issues/7240>`__).
Windows ISOs can be downloaded directly from Microsoft (eg. `here <https://www.microsoft.com/en-us/software-download/windows10ISO>`__ for Win10), or selected and downloaded via the `Windows Media Creation Tool <https://go.microsoft.com/fwlink/?LinkId=691209>`__. You should, however, regard the downloaded image to be untrustworthy, since there is no reliable way to check that the download was not somehow compromised (see the discussion in issue :issue:`Simplify Qubes Windows Tools Installation for R4.1 #7240 <7240>`).
Unofficial “debloated” ISOs from projects like reviOS 18 or ameliorated 10 can be found on the net, although obviously you should consider them even “unsafer” than MS provided ISOs. Alternatively, one could download an official ISO and run scripts/apply patches before installation. Some of the “tweaks” might end up being too much depending on the qube’s planned usage though (eg. no appx functionality in ameliorated windows - so the installation of Windows Store apps is impossible, even with powershell).
@ -374,7 +374,7 @@ Optimize resources for use in virtual machine as “vanilla” version of Window
For additional information on configuring a Windows qube, see the `Customizing Windows 7 templates <https://forum.qubes-os.org/t/19005>`__ page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - i.e. TemplateVM or StandaloneVM).
For additional information on configuring a Windows qube, see the :topic:`Customizing Windows 7 templates <19005>` page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - i.e. TemplateVM or StandaloneVM).
Windows as a template
---------------------

2
user/templates/windows/windows.rst
View file

@ -13,7 +13,7 @@ For more information about Windows VMs in Qubes OS, please see the following ext
- :doc:`Installing and Using Qubes Windows Tools </user/templates/windows/qubes-windows-tools-4-1>`
- `Create a Gaming HVM in Qubes <https://forum.qubes-os.org/t/create-a-gaming-hvm/19000>`__
- :topic:`Create a Gaming HVM in Qubes <create-a-gaming-hvm/19000>`
- :doc:`Migrate backups of Windows VMs created under Qubes R4.0 to R4.1 </user/templates/windows/migrate-to-4-1>`

4
user/templates/xfce-templates.rst
View file

@ -3,9 +3,9 @@ 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 :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, `Gentoo <https://forum.qubes-os.org/t/19007>`__ or `CentOS* <https://forum.qubes-os.org/t/19006>`__.
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 :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, :topic:`Gentoo <19007>` or :topic:`CentOS* <19006>`.
\* *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>`__ *.*
\* *The CentOS version used by this template reached* :wikipedia:`End-of-Life in June 2024 <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* :issue:`declined <9716>` *.*
Installation
------------

2
user/troubleshooting/hardware-troubleshooting.rst
View file

@ -39,4 +39,4 @@ This generates the appropriate configuration in ``/etc/X11/xorg.conf.d/00-keyboa
Restarting ``xorg`` is required. The most straightforward way is to reboot the system.
More information in `this discussion <https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion>`__ and `this GitHub issue <https://github.com/QubesOS/qubes-issues/issues/1396>`__.
More information in `this discussion <https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion>`__ and :issue:`this GitHub issue <1396>`.

6
user/troubleshooting/installation-troubleshooting.rst
View file

@ -37,7 +37,7 @@ This error message is related to the faulty creation of the USB installation med
See `here <https://github.com/QubesOS/qubes-issues/issues/6447>`__ for a discussion of this error message.
See :issue:`here <6447>` for a discussion of this error message.
Boot screen does not appear / system does not detect your installation medium
-----------------------------------------------------------------------------
@ -77,13 +77,13 @@ If the above code doesn’t fix the problem, replace it with:
noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
For more information, look at the `Nvidia Troubleshooting guide <https://forum.qubes-os.org/t/19021#disabling-nouveau>`__.
For more information, look at the :topic:`Nvidia Troubleshooting guide <19021#disabling-nouveau>`.
Installation freezes at "Setting up Networking"
-----------------------------------------------
If you are facing this problem on an Apple computer, check out the `Macbook Troubleshooting guide <https://forum.qubes-os.org/t/19020>`__.
If you are facing this problem on an Apple computer, check out the :topic:`Macbook Troubleshooting guide <19020>`.
If you are installing Qubes 4.0 on an external storage device, you may have forgotten to disable ``sys-usb`` during the :ref:`initial setup <user/downloading-installing-upgrading/installation-guide:initial setup>`, which is generally required for that setup to work.

4
user/troubleshooting/pci-troubleshooting.rst
View file

@ -105,7 +105,7 @@ Domain […] has failed to start: internal error: Unable to reset PCI device [
This is a :ref:`PCI passthrough issue <user/troubleshooting/pci-troubleshooting:pci passthrough issues>`, which occurs when PCI arbitrator is too strict. There is a way to enable permissive mode for it. Sometimes, you may instead need to disable the FLR requirement on a device. Both can be achieved during attachment with ``qvm-pci`` as described below.
NOTE: The ``permissive`` flag increases attack surface and possibility of `side channel attacks <https://en.wikipedia.org/wiki/Side-channel_attack>`__. While using the ``no-strict-reset`` flag, do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent. Both ``permissive`` and ``no-strict-reset`` options may not be necessary and you should try one first, then the other, before using both.
NOTE: The ``permissive`` flag increases attack surface and possibility of :wikipedia:`side channel attacks <Side-channel_attack>`. While using the ``no-strict-reset`` flag, do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent. Both ``permissive`` and ``no-strict-reset`` options may not be necessary and you should try one first, then the other, before using both.
.. code:: bash
@ -133,7 +133,7 @@ Broadcom BCM43602 Wi-Fi card causes system freeze
-------------------------------------------------
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in `Macbook Troubleshooting <https://forum.qubes-os.org/t/19020#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card>`__.
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in :topic:`Macbook Troubleshooting <19020#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card>`.
For other non-Macbook machines, it is advisable to replace the Broadcom BCM43602 with one known to work on Qubes, such as the Atheros AR9462.

2
user/troubleshooting/resume-suspend-troubleshooting.rst
View file

@ -3,7 +3,7 @@ Suspend/resume troubleshooting
==============================
First check if there are any remarks for similar devices in the `Hardware Compatibility List (HCL) <https://www.qubes-os.org/hcl/>`__.
First check if there are any remarks for similar devices in the :website:`Hardware Compatibility List (HCL) <hcl/>`.
Network-Manager says "Device not ready" on suspend/resume
---------------------------------------------------------

2
user/troubleshooting/uefi-troubleshooting.rst
View file

@ -43,7 +43,7 @@ Installation freezes before displaying installer
------------------------------------------------
If you have an Nvidia card, see also `Nvidia Troubleshooting <https://forum.qubes-os.org/t/19021#disabling-nouveau>`__.
If you have an Nvidia card, see also :topic:`Nvidia Troubleshooting <19021#disabling-nouveau>`.
Installation from USB stick hangs on black screen
-------------------------------------------------

4
user/troubleshooting/usb-troubleshooting.rst
View file

@ -15,7 +15,7 @@ Can't attach a USB device / USB device not showing in qvm-usb
To successfully attach a USB device, you require a VM dedicated to handling the USB input and output. For guidance setting up a USB qube, see the :ref:`USB documentation <user/how-to-guides/how-to-use-usb-devices:creating and using a usb qube>`.
Currently (until issue `1082 <https://github.com/QubesOS/qubes-issues/issues/1082>`__ gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, ``libvirtd``) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. This may be characterized by VM manager crashes and the error message: ``Houston, we have a problem``. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. If this isn’t an option, you can manually recover from the situation by following the instructions at the :ref:`Block Devices documentation <user/how-to-guides/how-to-use-block-storage-devices:what if i removed the device before detaching it from the vm?>`.
Currently (until issue :issue:`1082` gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, ``libvirtd``) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. This may be characterized by VM manager crashes and the error message: ``Houston, we have a problem``. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. If this isn’t an option, you can manually recover from the situation by following the instructions at the :ref:`Block Devices documentation <user/how-to-guides/how-to-use-block-storage-devices:what if i removed the device before detaching it from the vm?>`.
"Device attach failed" error
----------------------------
@ -29,7 +29,7 @@ Attaching device to a qube works, but the device disconnects or disappears upon
After attaching a device to a qube, upon attempting to use the device results in the device disappearing or disconnecting. This may be observed by the device no longer existing in the Devices widget or the application within the attached qube indicating the device is no longer found.
As a first line of defense, increase the amount of memory given to the USB VM (sys-usb). High-bandwidth devices such as webcams have been `observed <https://github.com/QubesOS/qubes-issues/issues/6200>`__ to need more memory in sys-usb. If increasing the amount of memory does not resolve the issue, check kernel logs within sys-usb as well as the attached qube for errors before filing a bug report.
As a first line of defense, increase the amount of memory given to the USB VM (sys-usb). High-bandwidth devices such as webcams have been :issue:`observed <6200>` to need more memory in sys-usb. If increasing the amount of memory does not resolve the issue, check kernel logs within sys-usb as well as the attached qube for errors before filing a bug report.
USB VM does not boot after creating and assigning USB controllers to it
-----------------------------------------------------------------------

2
user/troubleshooting/vpn-troubleshooting.rst
View file

@ -43,7 +43,7 @@ To figure out the root of the problem, check the VPN logs in ``/var/log/syslog``
-------------------------------
`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:
:topic:`Some VPN guides <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:
.. code:: bash