diff --git a/_dev/conf.py b/_dev/conf.py index 9f311f45..c643b145 100644 --- a/_dev/conf.py +++ b/_dev/conf.py @@ -186,7 +186,7 @@ htmlhelp_basename = 'QubesOSdev' # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - 'python': ('http://docs.python.org/', None), + 'python': ('https://docs.python.org/', None), # 'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None), } diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index 0146fe3a..dd72699a 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -15,7 +15,7 @@ A workflow for developing Qubes OS+ First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide assumes you're using qubes-builder to build Qubes. -# Repositories and committing Code +## Repositories and committing Code Qubes is split into a bunch of git repos. These are all contained in the `qubes-src` directory under qubes-builder. Subdirectories there are separate diff --git a/developer/debugging/profiling.md b/developer/debugging/profiling.md deleted file mode 100644 index 2932b4cb..00000000 --- a/developer/debugging/profiling.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -lang: en -layout: doc -permalink: /doc/profiling/ -redirect_from: -- /en/doc/profiling/ -- /doc/Profiling/ -- /wiki/Profiling/ -ref: 48 -title: Python profiling ---- - -This is a python profiling primer. - -For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats. - -## Requirements - -~~~ -yum install gprof2dot graphviz -git clone http://git.woju.eu/qubes/profiling.git -~~~ - -If you profile something in dom0, move `Upload.sh` from the repository to dom0: - -~~~ -mkdir -p ~/profiling -qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh -~~~ - -- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned. - -## Workflow - -### Identify function responsible for some slow action - -You have to select the area in which you suspect less than optimal performance. If you do not narrow the area, graphs may be unreadable. - -### Replace suspect function with probe - -Replace - -```python -def foo(self, bar): - # function content -``` - -with - -```python -def foo(self, *args, **kwargs): - profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(), - time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats')) - -def real_foo(self, bar): - # function content -``` - -### Run application - -Beware that some functions may be called often. For example `qubesmanager/main.py:update_table` gets run once per second. This will produce one pstat file per second. - -Remember to revert your changes to the application afterwards. - -### Upload statistics - -If you are in dom0: - -~~~ -cd ~/profiling -./Upload.sh -~~~ - -### Analyse - -~~~ -make -~~~ - -For every `${basename}.pstats` this will produce `${basename}.txt` and `${basename}.svg`. SVG files contain call graphs. Text files contain lists of all functions, sorted by cumulative execution time. You may also try `make all-png`. - -~~~ -make index.html -~~~ - -This creates `index.html` with all SVG graphics linked to TXT files, ready for upload. - -~~~ -make REMOTE=example.com:public_html/qubes/profiling/ upload -~~~ - -## Example - -This example is from `qubes-manager` (`qubesmanager/main.py`). - -!["update\_table-20140424-170010.svg"](//attachment/doc/update_table-20140424-170010.svg) - -It is apparent that the problem is around `get_disk_usage`, which calls something via `subprocess.call`. It does this 15 times, probably once per VM. diff --git a/developer/debugging/windows-debugging.md b/developer/debugging/windows-debugging.md index 852d1c67..87f22b5a 100644 --- a/developer/debugging/windows-debugging.md +++ b/developer/debugging/windows-debugging.md @@ -47,7 +47,7 @@ socat $tty1,raw $tty2,raw ...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0. - On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port. -- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port. +- On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port. - Reboot the *target* VM. - Run the above shell script in dom0. - If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that: @@ -57,7 +57,7 @@ socat $tty1,raw $tty2,raw Waiting to reconnect... Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE Kernel Debugger connection established. - Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols + Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols Executable search path is: ... Retry sending the same data packet for 64 times. The transport connection between host kernel debugger and target Windows seems lost. @@ -206,7 +206,7 @@ parse: > Waiting to reconnect... > Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE > Kernel Debugger connection established. -> Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols +> Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols > Executable search path is: > Windows 7 Kernel Version 7601 MP (1 procs) Free x64 > Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532 diff --git a/developer/general/devel-books.md b/developer/general/devel-books.md index d7ae9ae0..361648ba 100644 --- a/developer/general/devel-books.md +++ b/developer/general/devel-books.md @@ -26,6 +26,6 @@ Below is a list of various books that might be useful in learning some basics ne - _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online) - Useful books about Python: - - _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield - - _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield + - _[Programming in Python 3](https://www.qtrac.eu/py3book.html)_, by Mark Summerfield + - _[Rapid GUI Programming with Python and Qt](https://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield (Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.) diff --git a/developer/general/developing-gui-applications.md b/developer/general/developing-gui-applications.md new file mode 100644 index 00000000..1ff0387c --- /dev/null +++ b/developer/general/developing-gui-applications.md @@ -0,0 +1,102 @@ +--- +lang: en +layout: doc +permalink: /doc/developing-gui-applications/ +ref: 333 +title: Developing Qubes OS GUI tools +--- + +In order to avoid installing Qubes OS frontend tools you are working on in your own `dom0` or just to test them with less problems, you can use the mock Qubes object from the `qubesadmin` package. + +## Running programs using mock Qubes object + +Where you would normally provide the Qubes object, use the `qubesadmin.tests.mock_app` package and one of the mock Qubes objects from it. + +For example, the following code can be used to run the `qui-domains` tool using the mock Qubes object (this code would replace the initial part of the main function): + +```python +def main(): + ''' main function ''' + # qapp = qubesadmin.Qubes() + # dispatcher = qubesadmin.events.EventsDispatcher(qapp) + # stats_dispatcher = qubesadmin.events.EventsDispatcher(qapp, api_method='admin.vm.Stats') + + import qubesadmin.tests.mock_app as mock_app + qapp = mock_app.MockQubesComplete() + dispatcher = mock_app.MockDispatcher(qapp) + stats_dispatcher = mock_app.MockDispatcher( + qapp, api_method='admin.vm.Stats') + + # continue as normal +``` + +To run a mocked program without installing it in a qube, remember to extend PYTHONPATH appropriately, for example: + +```bash +~/qubes-sources/manager $ PYTHONPATH=../core-admin-client:. python3 qui/tray/domains.py +``` + +The mock object does not provide events (yet). + +Note: in order to see all qubes-relevant icons (like VM icons), install the `qubes-artwork` package. + +## How does it actually work + +The mock Qubes object has a collection of expected Qubes RPC calls and the responses that a real system would provide. Writing these calls manually is a bit tedious, given that most frontend tools query a lot of qube properties. For example, on a medium-sized system, initializing Qube Manager involves about 300 separate RPC calls. + +If you need more calls, you can add them to the mock object using the following syntax (the following example adds listing available vm kernels): + +```python + mock_app.expected_calls[('dom0', 'admin.pool.volume.List', 'linux-kernel', None)] = \ + b'0\x006.1.57-1.fc37\n6.1.43-1.fc37\ncustom_kernel\n' + +``` + +If error should be thrown, you need to provide the error code and name, for example: + +```python + mock_app.expected_calls[("vmname", "admin.vm.property.Get", "property_name", None)] = \ + b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00' +``` + +For details of particular calls, you can use [Extending the mock Qubes object]. + + +## Available mocks + +Three mocks are available in the `mock_app` file: + +* MockQubes, an extremely bare-bones Qubes testing instance, with just dom0, sys-net, and one template (fedora-36). +* MockQubesComplete, a more complex setup [![Qubes Manager running MockQubesComplete](/attachment/doc/doc-mock-app-ex1.png)](/attachment/doc/doc-mock-app-ex1.png) +* MockQubesWhonix, the setup above extended with several Whonix-related qubes + + +## Extending the mock Qubes object + +To collect information to modify this script, you can use the wrapper function to wrap and output all qubesd calls used by a program running on a live qubes instance. + +```python + qapp = qubesadmin.Qubes() + import qubesadmin.tests.mock_app as mock_app + qapp.qubesd_call = mock_app.wrapper(qapp.qubesd_call) + qapp._parse_qubesd_response = mock_app.wrapper(qapp._parse_qubesd_response) +``` + +## Writing tests + +The same mock Qubes can also be used to write tests. You can use the wrappers above to check which calls are made when certain actions are performed, and add them to the mock objects in the following way: + +```python +# this is an excerpt from tests for Qubes Global Config tool + clockvm_combo.set_active_id('test-blue') + + mock_qapp.expected_calls[('dom0', 'admin.property.Set', + 'clockvm', b'test-blue')] = b'0\x00' + basics_handler.save() + +``` + +If the call is made correctly, the test will continue successfully; if an unexpected call is made, the test will fail. + +Caution: the mock Qubes object does not react to changes like a normal Qubes object does. Further queries to the test object will continue to return initial values. + diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index 9e4adad3..e49d66d9 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -259,7 +259,7 @@ REMOVED as of January 2020: work is being done on this **Project**: Unikernel based firewallvm with Qubes firewall settings support -**Brief explanation**: [blog post](http://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall) +**Brief explanation**: [blog post](https://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall) **Expected results**: A firewall implemented as a unikernel which supports all the networking-related functionality as the default sys-firewall VM, including configuration via Qubes Manager. Other duties currently assigned to sys-firewall such as the update proxy may need to be appropriately migrated first. diff --git a/developer/releases/4_2/release-notes.md b/developer/releases/4_2/release-notes.md index cc3111ec..7b4dbc58 100644 --- a/developer/releases/4_2/release-notes.md +++ b/developer/releases/4_2/release-notes.md @@ -1,43 +1,54 @@ --- layout: doc -title: Qubes OS 4.2 release notes +title: Qubes OS 4.2.0 release notes permalink: /doc/releases/4.2/release-notes/ --- -_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._ - ## New features and improvements since Qubes 4.1 -- dom0 updated to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982)) -- Xen updated to 4.17 +- Dom0 upgraded to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/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)) - SELinux support in Fedora templates ([#4239](https://github.com/QubesOS/qubes-issues/issues/4239)) -- several GUI applications rewritten, including: - - applications menu (available as preview in R4.1 too) ([#6665](https://github.com/QubesOS/qubes-issues/issues/6665)), ([#5677](https://github.com/QubesOS/qubes-issues/issues/5677)) - - global settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898)) - - new qube dialog - - system updater ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443)) -- grub.cfg stored in /boot/grub2/grub.cfg in UEFI boot to ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985)) -- pipewire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358)) -- fwupd integration to allow firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855)) -- optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415)) -- official packages built using rewritten qubes-builder (qubes-builderv2) ([#6486](https://github.com/QubesOS/qubes-issues/issues/6486)) -- Split GPG and Split SSH management in Qubes Global Settings +- 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)) + - Qubes Global Settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898)) + - Create New Qube + - Qubes Update ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443)) +- Unified `grub.cfg` location for both UEFI and legacy boot ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985)) +- PipeWire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358)) +- fwupd integration for firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855)) +- Optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415)) +- Official packages built using Qubes Builder v2 ([#6486](https://github.com/QubesOS/qubes-issues/issues/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)) +- Improved keyboard layout switching -For a full list, including more detailed descriptions, please see -[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed). +For a full list, including more detailed descriptions, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed). Below are some screenshots of the new and improved Qubes GUI tools. + +The new Qubes OS Update tool: + +[![Screenshot of the Qubes OS Update tool](/attachment/site/4-2_update.png)](/attachment/site/4-2_update.png) + +The new Qubes OS Global Config tool: + +[![Screenshot of the Qubes OS Global Config tool](/attachment/site/4-2_global-config_1.png)](/attachment/site/4-2_global-config_1.png) +[![Screenshot of the Qubes OS Global Config tool](/attachment/site/4-2_global-config_2.png)](/attachment/site/4-2_global-config_2.png) + +The new Qubes OS Policy Editor tool: + +[![Screenshot of the Qubes OS Policy Editor tool](/attachment/site/4-2_policy-editor.png)](/attachment/site/4-2_policy-editor.png) ## Known issues - DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062)) -For a full list of known 4.2 issues with open bug reports, please see -[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+4.2%22+label%3A%22T%3A+bug%22). -We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately -after installation in order to apply any and all available bug fixes. +For a full list of open bug reports affecting 4.2, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen). We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply any and all available bug fixes. ## Download -See [downloads](/downloads/). +All Qubes ISOs and associated [verification files](/security/verifying-signatures/) are available on the [downloads](/downloads/) page. ## Installation instructions @@ -45,8 +56,4 @@ See the [installation guide](/doc/installation-guide/). ## Upgrading -The in-place upgrade procedure is not ready yet ([#7832](https://github.com/QubesOS/qubes-issues/issues/7832)). Currently, R4.2 can be tested by performing a clean installation. - -``` -TODO: Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/). -``` +Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/). diff --git a/developer/releases/4_2/schedule.md b/developer/releases/4_2/schedule.md index 54fb6900..bf06452a 100644 --- a/developer/releases/4_2/schedule.md +++ b/developer/releases/4_2/schedule.md @@ -15,4 +15,6 @@ policy](/doc/version-scheme/#release-schedule). | Date | Stage | | ----------:| ----------------------------------------- | | 2023-06-02 | 4.2.0-rc1 release | -| TODO | current-testing freeze before 4.2.0-rc2 | +| 2023-08-28 | 4.2.0-rc2 release | +| 2023-09-03 | 4.2.0-rc3 release | +| 2023-10-13 | 4.2.0-rc4 release | diff --git a/developer/releases/version-scheme.md b/developer/releases/version-scheme.md index 6f503f37..a96f9ca6 100644 --- a/developer/releases/version-scheme.md +++ b/developer/releases/version-scheme.md @@ -27,6 +27,13 @@ notable exception, as upstream OSes almost always have their own release schedules.) Bug fixes are allowed in all releases, and backward-compatible changes are allowed in all major and minor releases. +Qubes OS minor releases generally include new features, new templates, and +occasionally new defaults, but they are still backward-compatible in the sense +that qubes and features that worked in the previous release still function, +though the UI may be different in some cases. In general, deprecated features +are removed only in major releases, and in-place upgrades between major versions +are not guaranteed. + Following standard practice, **version** refers to any build that has been assigned a version name or number, e.g., `3.2-rc2`, `4.0.4`, `4.1-beta1`. By contrast, **release** refers to any version that is intended for consumption by @@ -52,47 +59,48 @@ Qubes OS. Another remix may have its own version series. ## Release versioning -Qubes OS as a whole is released from time to time. When preparing a new -release, we decide on the `.` numbers (e.g., `3.0`). We then -publish the first release candidate, `3.0-rc1`. When we feel that enough -progress has been made, we'll release `3.0-rc2` and so on. All these versions -(not yet releases) are considered unstable and not for production use. You are -welcome to [help us test](/doc/testing/) these versions. +Qubes OS as a whole is released from time to time. When preparing a new release, +we decide on the `.` numbers (e.g., `3.0`, which is short for +`3.0.0`). We then publish the first release candidate, e.g., `3.0.0-rc1`. When +we feel that enough progress has been made, we'll release `3.0.0-rc2` and so on. +All these versions (which are not yet releases) are considered unstable and are +not intended for production use. You are welcome to [help us +test](/doc/testing/) these versions. When enough progress has been made, we announce the first stable release, e.g. -`3.0.0`. This not only a version but an actual release. It is considered stable -and we commit to supporting it according to our [support +`3.0.0`. This is not only a version but an actual release. It is considered +stable, and we commit to supporting it according to our [support schedule](/doc/supported-releases/). Core components are branched at this -moment and bug fixes are backported from the master branch. Please see [help, +moment, and bug fixes are backported from the master branch. Please see [help, support, mailing lists, and forum](/support/) for places to ask questions about -stable releases. No major features and interface incompatibilities are to be +stable releases. No major features or interface incompatibilities are to be included in this release. We release bug fixes as patch releases (`3.0.1`, `3.0.2`, and so on), while backward-compatible enhancements and new features are introduced in the next minor release (e.g., `3.1`). Any backward-incompatible changes are introduced in the next major release (e.g., `4.0`). -Issues in our [issue tracker](/doc/issue-tracking/) are sorted by release -[milestones](/doc/issue-tracking/#milestones). +Please see [issue tracking](/doc/issue-tracking/) for information about how +releases are handled in the issue tracker. ## Release schedule -There is no specific schedule for releases other that more general roadmap. -When time comes, Supreme Committee declares feature freeze and tags `-rc1` and -releases ISO image. From this time on, no new features are accepted. Also a -strict time schedule kicks in. +There is no specific schedule for releases other than a general roadmap. +When the time comes, we declare a feature freeze, tag `-rc1`, and +release an ISO. From this point on, no new features are accepted, and our +schedule begins. -Each release candidate period is as follows. For the first two weeks we accept -and assign bug reports to be fixed before next release candidate. For the next -two weeks we generally focus on fixing assigned bug reports, so issues -discovered during this time may be postponed until later RC. Finally after that -there is one week of current-testing freeze, during which time no new packages -are released, in hope that they will be installed by wider user base and -tested. +Each release candidate period is as follows: For the first two weeks, we accept +and assign bug reports to be fixed before the next release candidate. For the +next two weeks, we generally focus on fixing assigned bug reports, so issues +discovered during this period may be postponed until a later RC. Finally, +there is a one week current-testing freeze, during which time no new packages +are released, in the hope that they will be installed and tested by wider user +base. -The next RC is released five weeks after the former. All packets are published -in `current` repository and the cycle starts over. There should always be at -least one release candidate before the final release. +The next RC is released five weeks after the former. All packages are published +in the `current` repository, and the cycle starts over. There should always be +at least one release candidate before the final release. | Stage | Duration | | ------------------------ | --------- | @@ -100,11 +108,11 @@ least one release candidate before the final release. | bug fixing | two weeks | | `current-testing` freeze | one week | -Starting with second cycle (that is, after `-rc1`) two weeks into the cycle -(after primary bug-reporting period) the Supreme Committee decides whether -there should be another RC. If, based on remaining issues, the Committee -decides to release final, then the Committee agrees upon the release date, -which should be no later than a week after. +Starting with the second cycle (that is, after `-rc1`), two weeks into the cycle +(after the primary bug-reporting period), we decide whether there should be +another RC. If, based on the bugs that have been reported, we decide that the +latest RC will be designated as the stable release, then we decide on its +release date, which should be no more than one week later. [![Release cycle](/attachment/doc/release-cycle.svg)](/attachment/doc/release-cycle.svg) diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index aa42efba..dc8039da 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -86,25 +86,27 @@ Additionally, disposable VMs are tightly integrated -- RPC to a DisposableVM is ### Policy files -The dom0 directory `/etc/qubes-rpc/policy/` contains a file for each available RPC action that a VM might call. -Together the contents of these files make up the RPC access policy database. +The dom0 directory `/etc/qubes/policy.d/` contains files that set policy for each available RPC action that a VM might call. +For example, `/etc/qubes/policy.d/90-default.policy` contains the default policy settings. +When making changes to existing policies it is recommended that you create a *new* policy file starting with a lower number, like `/etc/qubes/policy.d/30-user.policy`. +You may keep your custom policies in one file like `/etc/qubes/policy.d/30-user.policy`, or you may choose to have multiple files, like `/etc/qubes/policy.d/10-copy.policy`, `/etc/qubes/policy.d/10-open.policy`. +Together the contents of these files make up the RPC access policy database: the files are merged, with policies in lower number files overriding policies in higher numbered files. + Policies are defined in lines with the following format: ``` -srcvm destvm (allow|deny|ask[,default_target=default_target_VM])[,user=user_to_run_as][,target=VM_to_redirect_to] +service-name|* +argument|* source destination action [options] ``` -You can specify srcvm and destvm by name or by one of the reserved keywords such as `@anyvm`, `@dispvm`, or `dom0`. -(Of these three, only `@anyvm` keyword makes sense in the srcvm field. +You can specify the source and destination by name or by one of the reserved keywords such as `*`, `@dispvm`, or `dom0`. +(Of these three, only `*` keyword makes sense in the source field. Service calls from dom0 are currently always allowed, and `@dispvm` means "new VM created for this particular request," so it is never a source of request.) Other methods using *tags* and *types* are also available (and discussed below). -Whenever a RPC request for an action is received, the domain checks the first matching line of the relevant file in `/etc/qubes-rpc/policy/` to determine access: +Whenever a RPC request for an action is received, the domain checks the first matching line of the files in `/etc/qubes/policy.d/` to determine access: whether to allow the request, what VM to redirect the execution to, and what user account the program should run under. Note that if the request is redirected (`target=` parameter), policy action remains the same -- even if there is another rule which would otherwise deny such request. If no policy rule is matched, the action is denied. -If the policy file does not exist, the user is prompted to create one. -If there is still no policy file after prompting, the action is denied. In the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself -- in which case it must have executable permission set (`chmod +x`): - `/etc/qubes-rpc/RPC_ACTION_NAME` when you make it in the template qube; @@ -145,14 +147,14 @@ For DisposableVMs, `@dispvm:DISP_VM` is very similar to `@dispvm` but forces usi For example: ``` -anon-whonix @dispvm:anon-whonix-dvm allow +* * anon-whonix @dispvm:anon-whonix-dvm allow ``` Adding such policy itself will not force usage of this particular `DISP_VM` - it will only allow it when specified by the caller. But `@dispvm:DISP_VM` can also be used as target in request redirection, so _it is possible_ to force particular `DISP_VM` usage, when caller didn't specify it: ``` -anon-whonix @dispvm allow,target=@dispvm:anon-whonix-dvm +* * anon-whonix @dispvm allow target=@dispvm:anon-whonix-dvm ``` Note that without redirection, this rule would allow using default Disposable VM (`default_dispvm` VM property, which itself defaults to global `default_dispvm` property). @@ -166,15 +168,15 @@ By default no VM is selected, even if the caller provided some, but policy can s For example: ``` -work-mail work-archive allow -work-mail @tag:work ask,default_target=work-files -work-mail @default ask,default_target=work-files +* * work-mail work-archive allow +* * work-mail @tag:work ask default_target=work-files +* * work-mail @default ask default_target=work-files ``` -The first rule allow call from `work-mail` to `work-archive`, without any confirmation. +The first rule allows calls from `work-mail` to `work-archive`, without any confirmation. The second rule will ask the user about calls from `work-mail` VM to any VM with tag `work`. And the confirmation dialog will have `work-files` VM chosen by default, regardless of the VM specified by the caller (`work-mail` VM). -The third rule allow the caller to not specify target VM at all and let the user choose, still - from VMs with tag `work` (and `work-archive`, regardless of tag), and with `work-files` as default. +The third rule allows the caller to not specify target VM at all and let the user choose, still - from VMs with tag `work` (and `work-archive`, regardless of tag), and with `work-files` as default. ### RPC services and security @@ -213,9 +215,16 @@ With arguments, it is easier to write more precise policies using the "allow" an (Writing too many "ask" policies offloads additional decisions to the user. Generally, the fewer choices the user must make, the lower the chance to make a mistake.) -Each specific argument that we want to use needs its own policy in dom0 at a path like `/etc/qubes-rpc/policy/RPC_ACTION_NAME+ARGUMENT`. -So for instance, we might have policies called `test.Device`, `test.Device+device1` and `test.Device+device2`. -If the policy for the specific argument is not set (that is, if no file exists for `RPC_ACTION_NAME+ARGUMENT`), then dom0 uses the default policy with no argument for this service. +The argument is specified in the second column of the policy line, as +ARGUMENT. +If the policy uses "\*" as an argument, then it will match any argument (including no argument). +As rules are processed in order, any lines with a specific argument below the line with the wildcard argument will be ignored. +So for instance, we might have policies which are different depending on the argument: + +``` +Device +device1 * * allow +Device +device2 * * deny +Device * * * ask +``` When calling a service that takes an argument, just add the argument to the service name separated with `+`. @@ -265,10 +274,10 @@ ln -s /usr/bin/our_test_add_server /etc/qubes-rpc/test.Add ``` The administrative domain will direct traffic based on the current RPC policies. -In dom0, create a file at `/etc/qubes-rpc/policy/test.Add` containing the following: +In dom0, create a file at `/etc/qubes/policy.d/30-test.policy` containing the following: ``` -@anyvm @anyvm ask +test.Add * * * ask ``` This will allow our client and server to communicate. @@ -312,17 +321,15 @@ Make sure the file is executable! (The service argument is already sanitized by qrexec framework. It is guaranteed to not contain any spaces or slashes, so there should be no need for additional path sanitization.) -Now we create three policy files in dom0. -See the table below for details. +Now we create the policy file in dom0, at `/etc/qubes/policy.d/30-test.policy`. +The contents of the file are below. Replace "source_vm1" and others with the names of your own chosen domains. -|------------------------------------------------------------------------| -| Path to file in dom0 | Policy contents | -|-------------------------------------------+----------------------------| -| /etc/qubes-rpc/policy/test.File | @anyvm @anyvm deny | -| /etc/qubes-rpc/policy/test.File+testfile1 | source_vm1 target_vm allow | -| /etc/qubes-rpc/policy/test.File+testfile2 | source_vm2 target_vm allow | -|------------------------------------------------------------------------| +``` +test.File +testfile1 source_vm1 target_vm allow +test.File +testfile2 source_vm2 target_vm allow +test.File * * * deny +``` With this done, we can run some tests. Invoke RPC from `source_vm1` via @@ -332,11 +339,12 @@ Invoke RPC from `source_vm1` via ``` We should get the contents of `/home/user/testfile1` printed to the terminal. -Invoking the service from `source_vm2` should work the same, and `testfile2` should also work. +Invoking the service from `source_vm2` should result in a denial, but `testfile2` should work. ``` [user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile1 +Request refused [user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile2 ``` -But when invoked with other arguments or from a different VM, it should be denied. +And when invoked with other arguments or from a different VM, it should also be denied. diff --git a/developer/system/template-implementation.md b/developer/system/template-implementation.md index 50353f3b..4feb91fb 100644 --- a/developer/system/template-implementation.md +++ b/developer/system/template-implementation.md @@ -10,6 +10,8 @@ ref: 58 title: Template implementation --- +## Block devices of a VM + Every VM has 4 block devices connected: - **xvda** – base root device (/) – details described below @@ -17,7 +19,7 @@ Every VM has 4 block devices connected: - **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below) - **xvdd** – modules.img – kernel modules and firmware -## private.img (xvdb) +### private.img (xvdb) This is mounted as /rw and here is placed all VM private data. This includes: @@ -27,7 +29,7 @@ This is mounted as /rw and here is placed all VM private data. This includes: **Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM [are *not* copied to the child TemplateBasedVM's `/home`](/doc/templates/#inheritance-and-persistence). The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM. -## modules.img (xvdd) +### modules.img (xvdd) As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files: @@ -39,7 +41,7 @@ Normally kernel "package" is common for many VMs (can be set using qvm-prefs). O There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. -# Qubes TemplateVM implementation +## Qubes TemplateVM implementation TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs: @@ -50,7 +52,7 @@ There are two layers of the device-mapper snapshot device; the first one enables ![TemplateSharing2.png](/attachment/doc/TemplateSharing2.png) -## Snapshot device in Dom0 +### Snapshot device in Dom0 This device consists of: @@ -61,7 +63,7 @@ The above is achieved through creating device-mapper snapshots for each version When an AppVM is stopped the xen hotplug script checks whether the device is still in use – if it is not, the script removes the snapshot and frees the loop device. -### Changes to template filesystem +#### Changes to template filesystem In order for the full potential of the snapshot device to be realized, every change in root.img must save the original version of the modified block in root-cow.img. This is achieved by a snapshot-origin device. @@ -69,7 +71,7 @@ When TemplateVM is started, it receives the snapshot-origin device connected as When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.old and creates a new one (using the `qvm-template-commit` tool). The snapshot device will remain untouched due to the loop device, which uses an actual file on the disk (by inode, not by name). Linux kernel frees the old root-cow.img files as soon as they are unused by all snapshot devices (to be exact, loop devices). The new root-cow.img file will get a new inode number, and so new AppVMs will get new snapshot devices (with different names). -### Rollback template changes +#### Rollback template changes There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch". @@ -85,7 +87,7 @@ Steps performed by **qvm-revert-template-changes**: 6. Cleanup snapshot device (if nobody uses it at the moment). 7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). -## Snapshot device in AppVM +### Snapshot device in AppVM Root device is exposed to AppVM in read-only mode. AppVM can write only in: @@ -99,7 +101,7 @@ volatile.img is divided into two partitions: Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart. -## StandaloneVM +### StandaloneVM Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*. diff --git a/external/os-guides/windows/windows-tools.md b/external/os-guides/windows/windows-tools.md deleted file mode 100644 index 0efce90d..00000000 --- a/external/os-guides/windows/windows-tools.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -lang: en -layout: doc -redirect_from: -- /doc/windows-tools/ -- /doc/windows-appvms/ -- /en/doc/windows-appvms/ -- /doc/WindowsAppVms/ -- /wiki/WindowsAppVms/ -- /doc/windows-tools-3/ -- /en/doc/windows-tools-3/ -- /doc/WindowsTools3/ -- /doc/WindowsTools/ -- /wiki/WindowsTools/ -redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md -ref: 86 -title: Qubes Windows tools ---- diff --git a/external/os-guides/windows/windows-vm.md b/external/os-guides/windows/windows-vm.md deleted file mode 100644 index 1b5e50e9..00000000 --- a/external/os-guides/windows/windows-vm.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -lang: en -layout: doc -redirect_from: -- /doc/windows-vm/ -redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md -ref: 85 -title: Installing a Windows qube ---- diff --git a/external/os-guides/windows/windows.md b/external/os-guides/windows/windows.md deleted file mode 100644 index 3a913b99..00000000 --- a/external/os-guides/windows/windows.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -lang: en -layout: doc -redirect_from: -- /doc/windows/ -redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md -ref: 129 -title: Windows qubes ---- diff --git a/introduction/issue-tracking.md b/introduction/issue-tracking.md index 973b58dc..e550ac40 100644 --- a/introduction/issue-tracking.md +++ b/introduction/issue-tracking.md @@ -16,11 +16,7 @@ ref: 121 title: 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 [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). ## How to open a new issue @@ -28,314 +24,157 @@ First, let's make sure the issue tracker is the right place. ### I need help, have a question, or want to discuss something. -We're happy to help, answer questions, and have discussions, but the issue -tracker is not the right place for these activities. Instead, please see [Help, -Support, Mailing Lists, and Forum](/support/). +We're happy to help, answer questions, and have discussions, but the issue tracker is not the right place for these activities. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/). ### 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](/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 [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. -Thank you! If the vulnerability is confidential, please do not report it in our -public issue tracker. Instead, please see [Reporting Security Issues in Qubes -OS](/security/#reporting-security-issues-in-qubes-os). +Thank you! If the vulnerability is confidential, please do not report it in our public issue tracker. Instead, please see [Reporting Security Issues in Qubes OS](/security/#reporting-security-issues-in-qubes-os). ### I still want to open an issue. -Great! Thank you for taking the time and effort to help improve Qubes! To -ensure the process is efficient and productive for everyone involved, please -follow these steps: +Great! Thank you for taking the time and effort to help improve Qubes! To ensure the process is efficient and productive for everyone involved, please follow these steps: - 1. Carefully read our issue tracking [guidelines](#guidelines). If your issue - would violate any of the guidelines, **stop**. Please do not submit it. - 2. [Search through the existing issues](#search-tips), both open and closed, - to see if your issue already exists. If it does, **stop**. [Do not open a - duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues) - Instead, comment on the existing issue. + 1. Carefully read our issue tracking [guidelines](#guidelines). If your issue would violate any of the guidelines, **stop**. Please do not submit it. + 2. [Search through the existing issues](#search-tips), both open and closed, to see if your issue already exists. If it does, **stop**. [Do not open a duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues) Instead, comment on the existing issue. 3. Go [here](https://github.com/QubesOS/qubes-issues/issues/new/choose). 4. Select the [type](#type) of issue you want to open. 5. Enter a descriptive title. - 6. Do not delete the provided issue template. Fill out every applicable - section. - 7. Make sure to mention any relevant documentation and other issues you've - already seen. We don't know what you've seen unless you tell us. If you - don't list it, we'll assume you haven't seen it. - 8. If any sections of the issue template are *truly* not applicable, you may - remove them. + 6. Do not delete the provided issue template. Fill out every applicable section. + 7. Make sure to mention any relevant documentation and other issues you've already seen. We don't know what you've seen unless you tell us. If you don't list it, we'll assume you haven't seen it. + 8. If any sections of the issue template are *truly* not applicable, you may remove them. 9. Submit your issue. -10. Respond to any questions the official team asks. For example, you may be - asked to provide specific logs or other additional information. +10. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information. -Eventually, your issue may be closed. See [how issues get -closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, -why, and how this occurs. +Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs. -## Labels, milestones, and projects +## Labels and projects -Labels, milestones, and projects are features of GitHub's issue tracking system -that we use to keep -[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized. +Labels and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized. ### Labels -When an issue is first created, certain labels may automatically be applied to -it based on the type of issue the reporter selected. For example, if someone -selects the "Bug report" template, then the `T: bug` label will automatically -be applied to that issue. After that, only Qubes team members have permission -to modify [labels](https://github.com/QubesOS/qubes-issues/labels) and -[milestones](https://github.com/QubesOS/qubes-issues/milestones). Many labels -and milestones have descriptions on them that can be viewed either in their -respective lists or by hovering over them. Let's go over some of the most -important ones. +When an issue is first created, certain [labels](https://github.com/QubesOS/qubes-issues/labels) may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones. #### Type There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`. -- `T: bug` --- Type: bug report. A problem or defect resulting in unintended - behavior in something that exists. -- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist - **or** improvement of existing functionality. -- `T: task` --- Type: task. An action item that is neither a bug nor an - enhancement. +- `T: bug` --- Type: bug report. A problem or defect resulting in unintended behavior in something that exists. +- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality. +- `T: task` --- Type: task. An action item that is neither a bug nor an enhancement. -Every open issue should have **exactly one** type. An open issue should not -have more than one type, and it should not lack a type entirely. Bug reports -are for problems in things that already exist. If something doesn't exist yet, -but you think it ought to exist, then use `T: enhancement` instead. If -something already exists, but you think it could be improved in some way, you -should again use `T: enhancement`. `T: task` is for issues that fall under -under neither `T: bug` nor `T: enhancement`. +Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under under neither `T: bug` nor `T: enhancement`. #### Priority -There are several issue **priority** levels ranging from `P: minor` to `P: -blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for -the full list). Every open issue should have **exactly one** priority. An open -issue should not have more than one priority, and it should not lack a priority -entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how -the developers use these priorities. +There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have **exactly one** priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities. #### Component -There are many **component** labels, each beginning with `C:` (see -[here](https://github.com/QubesOS/qubes-issues/labels?page=2&q=C%3A) for the -full list). Every open issue should have **at least one** component. An open -issue may have more than one component, but it should not lack a component -entirely. When no other component applies, use `C: other`. +There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`. #### Affected release -A label of the form `affects-` indicates that an issue affects -the corresponding Qubes OS release. An issue can have more than one of these -labels if it affects multiple releases. - -### Milestones - -The issue tracker has several -[milestones](https://github.com/QubesOS/qubes-issues/milestones). Individual -issues can be assigned to milestones. The issue tracker does not allow an issue -to be assigned to more than one milestone. If an issue is already assigned to a -milestone, assigning it to a different one will *replace* the existing -milestone assignment. Each milestone has a progress indicator showing how close -that milestone is to completion. - -Most milestones correspond to specific Qubes OS releases. The Qubes developers -decide which issues will be assigned to specific milestones. The general idea -is that each milestone's progress indicator should provide a rough idea of how -much progress has been made on that milestone and how much work remains until -the milestone is complete. Most issues will not be assigned to any milestone at -all until a Qubes developer manually assigns it to one. While anyone is free to -open an issue, this does not create an obligation on the Qubes developers to -act on that issue. Every open issue should be understood to be merely "under -consideration" unless or until a Qubes developer decides to assign it to a -milestone. Issues that are assigned to a milestone are issues that either the -Qubes developers or another contributor plans to complete *for* that milestone. -The Qubes developers reserve the right to modify or remove milestones at any -time at their discretion. +A label of the form `affects-` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases. ### Projects -The issue tracker has several -[projects](https://github.com/QubesOS/qubes-issues/projects). A project is a -way to create a group of multiple related issues. This is the preferred method -of grouping issues, whereas trying to use normal issues as "meta-issues" or -"epics" is discouraged. +The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). A project is a way to create a group of multiple related issues. This is the preferred method of grouping issues, whereas trying to use normal issues as "meta-issues" or "epics" is discouraged. ## Search tips -[Search both open and closed -issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) -For example, you may be experiencing a bug that was just fixed, in which case -the report for that bug is probably closed. In this case, it would be useful to -view [all bug reports, both open and closed, with the most recently updated -sorted to the -top](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc). +- [Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3A%22T%3A+bug%22+sort%3Aupdated-desc). -[Search using labels.](https://github.com/QubesOS/qubes-issues/labels) For -example, you can search issues by priority -([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), -[critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), -[major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and -by component -([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), -[manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), -[Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), -etc.). +- [Search with labels.](https://github.com/QubesOS/qubes-issues/labels) For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.). -You can also try searching by -[milestone](https://github.com/QubesOS/qubes-issues/milestones) and by -[project](https://github.com/QubesOS/qubes-issues/projects). +- Search by closure reason: [`reason:complete`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3Acompleted) and [`reason:"not planned"`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3A%22not+planned%22). + +- [Search by project](https://github.com/QubesOS/qubes-issues/projects). ## Guidelines ### The issue tracker is not a discussion forum -The issue tracker is a tool to help the developers be more productive and -efficient in their work. It is not a place for discussion. If you wish to -discuss something in the issue tracker, please do so on the forum or mailing -lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can -simply link to the relevant issue in your discussion post. +The issue tracker is a tool to help the developers be more productive and efficient in their work. It is not a place for discussion. If you wish to discuss something in the issue tracker, please do so on the forum or mailing lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can simply link to the relevant issue in your discussion post. -This guideline is important for keeping issues focused on *actionable -information*, which helps the developers to stay focused on their work. When -developers come back to an issue to work on it, we do not want them to have to -sift through a large number of unnecessary comments before they can get -started. In many cases, an issue that gets "too big" essentially becomes more -trouble than it's worth, and no developer will touch it (also see [every issue -must be about a single, actionable -thing](#every-issue-must-be-about-a-single-actionable-thing)). In these cases, -we sometimes have to close the issue and open a new one. This is a waste of -energy for everyone involved, so we ask that everyone help to avoid repeating -this pattern. +This guideline is important for keeping issues focused on *actionable information*, which helps the developers to stay focused on their work. When developers come back to an issue to work on it, we do not want them to have to sift through a large number of unnecessary comments before they can get started. In many cases, an issue that gets "too big" essentially becomes more trouble than it's worth, and no developer will touch it (also see [every issue must be about a single, actionable thing](#every-issue-must-be-about-a-single-actionable-thing)). In these cases, we sometimes have to close the issue and open a new one. This is a waste of energy for everyone involved, so we ask that everyone help to avoid repeating this pattern. ### Do not submit questions -[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place -to ask questions. This includes, but is not limited to, troubleshooting -questions and questions about how to do things with Qubes. Instead, see [Help, -Support, Mailing Lists, and Forum](/support/) for appropriate place to ask -questions. By contrast, -[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for -tracking more general bugs, enhancements, and tasks that affect a broad range -of Qubes users. +[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place to ask questions. This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes. Instead, see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate place to ask questions. By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users. ### Use the issue template -When you open a new issue, an issue template is provided for you. Please use -it. Do not delete it. The issue template is carefully designed to elicit -important information. Without this information, the issue is likely to be -incomplete. (If certain sections are not applicable, you may remove them, but -please do so only sparingly and only if they are *truly* not applicable.) +When you open a new issue, an issue template is provided for you. Please use it. Do not delete it. The issue template is carefully designed to elicit important information. Without this information, the issue is likely to be incomplete. (If certain sections are not applicable, you may remove them, but please do so only sparingly and only if they are *truly* not applicable.) -It is also important to note the placement and content of the HTML comments in -the issue template. These help us to have issues with a consistent format. +It is also important to note the placement and content of the HTML comments in the issue template. These help us to have issues with a consistent format. ### Every issue must be about a single, actionable thing -If your issue is not actionable, please see [Help, Support, Mailing Lists, and -Forum](/support/) for the appropriate place to post it. If your issue would be -about more than one thing, file them as separate issues instead. This means we -should generally not try to use a single issue as a "meta" or "epic" issue that -exists only to group, contain, or track other issues. Instead, when there is a -need to group multiple related issues together, use -[projects](https://github.com/QubesOS/qubes-issues/projects). +If your issue is not actionable, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to post it. If your issue would be about more than one thing, file them as separate issues instead. This means we should generally not try to use a single issue as a "meta" or "epic" issue that exists only to group, contain, or track other issues. Instead, when there is a need to group multiple related issues together, use [projects](https://github.com/QubesOS/qubes-issues/projects). -This guideline is extremely important for making the issue tracker a useful -tool for the developers. When an issue is too big and composite, it becomes -intractable and drastically increases the likelihood that nothing will get -done. Such issues also tend to encourage an excessive amount of general -discussion that is simply not appropriate for a technical issue tracker (see -[the issue tracker is not a discussion -forum](#the-issue-tracker-is-not-a-discussion-forum)). +This guideline is extremely important for making the issue tracker a useful tool for the developers. When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see [the issue tracker is not a discussion forum](#the-issue-tracker-is-not-a-discussion-forum)). ### New issues should not be duplicates of existing issues -Before you submit an issue, check to see whether it has already been reported. -Search through the existing issues -- both open and closed -- by typing your -key words in the **Filters** box. If you find an issue that seems to be similar -to yours, read through it. If you find an issue that is the same as or subsumes -yours, leave a comment on the existing issue rather than filing a new one, even -if the existing issue is closed. If an issue affects more than one Qubes -version, we usually keep only one issue for all versions. The Qubes team will -see your comment and reopen the issue, if appropriate. For example, you can -leave a comment with additional information to help the maintainer debug it. -Adding a comment will subscribe you to email notifications, which can be -helpful in getting important updates regarding the issue. If you don't have -anything to add but still want to receive email updates, you can click the -"Subscribe" button at the side or bottom of the comments. +Before you submit an issue, check to see whether it has already been reported. Search through the existing issues -- both open and closed -- by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it. If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed. If an issue affects more than one Qubes version, we usually keep only one issue for all versions. The Qubes team will see your comment and reopen the issue, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don't have anything to add but still want to receive email updates, you can click the "Subscribe" button at the side or bottom of the comments. ### Every issue must be of a single type -Every issue must be exactly one of the following types: a bug report (`bug`), a -feature or improvement request (`enhancement`), or a task (`task`). Do not file -multi-typed issues. Instead, file multiple issues of distinct types. The Qubes -team will classify your issue according to its type. +Every issue must be exactly one of the following types: a bug report (`bug`), a feature or improvement request (`enhancement`), or a task (`task`). Do not file multi-typed issues. Instead, file multiple issues of distinct types. The Qubes team will classify your issue according to its type. ### New issues should include all relevant information -When you file a new issue, you should be sure to include the version of Qubes -you're using, as well as versions of related software packages ([how to copy -information out of dom0](/doc/how-to-copy-from-dom0/)). If your issue is -related to hardware, provide as many details as possible about the hardware. A -great way to do this is by [generating and submitting a Hardware Compatibility -List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), -then linking to it in your issue. You may also need to use command-line tools -such as `lspci`. If you're reporting a bug in a package that is in a -[testing](/doc/testing/) repository, please reference the appropriate issue in -the [updates-status](https://github.com/QubesOS/updates-status/issues) -repository. Project maintainers really appreciate thorough explanations. It -usually helps them address the problem more quickly, so everyone wins! +When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages ([how to copy information out of dom0](/doc/how-to-copy-from-dom0/)). If your issue is related to hardware, provide as many details as possible about the hardware. A great way to do this is by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then linking to it in your issue. You may also need to use command-line tools such as `lspci`. If you're reporting a bug in a package that is in a [testing](/doc/testing/) repository, please reference the appropriate issue in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository. Project maintainers really appreciate thorough explanations. It usually helps them address the problem more quickly, so everyone wins! ### There are no guarantees that your issue will be addressed -Keep in mind that -[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is an issue -tracker, not a support system. Creating a new issue is simply a way for you to -submit an item for the Qubes team's consideration. It is up to the Qubes team -to decide whether or how to address your issue, which may include closing the -issue without taking any action on it. Even if your issue is kept open, -however, you should not expect it to be addressed within any particular time -frame, or at all. At the time of this writing, there are well over one thousand -open issues in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues). -The Qubes team has its own roadmap and priorities, which will govern the manner -and order in which open issues are addressed. +Keep in mind that [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is an issue tracker, not a support system. Creating a new issue is simply a way for you to submit an item for the Qubes team's consideration. It is up to the Qubes team to decide whether or how to address your issue, which may include closing the issue without taking any action on it. Even if your issue is kept open, however, you should not expect it to be addressed within any particular time frame, or at all. At the time of this writing, there are well over one thousand open issues in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues). The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed. + +### Issues and comments must be written in English + +If English is not your native language, you may post a machine translation. If you wish, you may also include the original non-English text in a [collapsible section](#use-collapsible-sections-for-long-nonessential-content). + +### Use collapsible sections for long, nonessential content + +On GitHub, create collapsible sections in Markdown like so: + +``` +
+Summary goes here. This line is optional. + +Long, nonessential content goes here. You can put a code block here, but make sure to leave empty lines before and after the fence lines (```). + +
+``` + +**Tip:** Use the "Preview" tab to make sure it renders correctly before posting. ## How issues get closed -If the Qubes developers make a code change that resolves an issue, then the -issue will typically be [closed from the relevant commit or merged pull request -(PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue). +If the Qubes developers make a code change that resolves an issue, then the issue will typically be [closed from the relevant commit or merged pull request (PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue). ### Bug reports -In the case of bugs, the package containing the change will move to the -appropriate [testing](/doc/testing/) repository, then to the appropriate stable -repository. If you so choose, you can test the fix while it's in the -[testing](/doc/testing/) repository, or you can wait for it to land in the -stable repository. If, after testing the fix, you find that it does not really -fix the reported bug, please leave a comment on the issue explaining the -situation. When you do, we will receive a notification and respond on the issue -or reopen it (or both). Please **do not** create a duplicate issue or attempt -to contact the developers individually about a problem. +In the case of bugs, the package containing the change will move to the appropriate [testing](/doc/testing/) repository, then to the appropriate stable repository. If you so choose, you can test the fix while it's in the [testing](/doc/testing/) repository, or you can wait for it to land in the stable repository. If, after testing the fix, you find that it does not really fix the reported bug, please leave a comment on the issue explaining the situation. When you do, we will receive a notification and respond on the issue or reopen it (or both). Please **do not** create a duplicate issue or attempt to contact the developers individually about a problem. ### Resolution -In other cases, an issue may be closed with a specific resolution, such as `R: -invalid`, `R: duplicate`, or `R: won't fix`. Each of these labels has a -description that explains the label. We'll also leave a comment explaining why -we're closing the issue with one of these specific resolutions. If the issue is -closed without one of these specific resolutions, then it means, by default, -that the reported bug was fixed or the requested enhancement was implemented. +In GitHub, an issue can be [closed as either `completed` or `not planned`](https://github.blog/changelog/2022-03-10-the-new-github-issues-march-10th-update/#%F0%9F%95%B5%F0%9F%8F%BD%E2%99%80%EF%B8%8F-issue-closed-reasons). + +Being closed as `completed` means that the issue has been fixed (in the case of bugs) or done (in the case of enhancements and tasks). More precisely, it means that a commit containing the relevant work has been pushed. It takes time for this work to make its way into a package, which must then go through the [testing](/doc/testing/) process before finally landing in the relevant stable repository. Automated comments on the issue will announce when key events in this process occur. + +Being closed as `not planned` means that the issue will *not* be fixed (in the case of bugs) or done (in the case of enhancements and tasks). When an issue is closed as `not planned`, we add a **resolution** label starting with `R:` that specifies the reason for the closure, such as `R: duplicate` or `R: cannot reproduce`. Each of these labels has a description that briefly explains the label. We also leave a comment containing a longer explanation for why the issue is being closed along with general information. + +While issues that are closed as `not planned` get a more specific resolution label, issues that are closed as `completed` do not always get one, since the linked PRs, commits, automated messages, and the `completed` reason itself are often sufficient to convey all relevant information. For information about using closure reasons in searches, see [Search tips](#search-tips). ### Backports -Issues in GitHub can only be open or closed, but, when it comes to bugs that -affect multiple versions of Qubes OS, there are several possible states: +Issues in GitHub can only be open or closed, but when it comes to bugs that affect multiple versions of Qubes OS, there are several possible states: 1. Not fixed yet 2. Fix developed but not yet committed (PR open) @@ -345,20 +184,12 @@ affect multiple versions of Qubes OS, there are several possible states: 6. Update backported to stable version(s) and pushed to the testing repo 7. Update pushed to stable repo of stable version(s) -We close issues at step 3. Then, as updates are released, the issue -automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and -`stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to -select issues waiting for step 6 (see [issues by -release](https://github.com/QubesOS/qubes-issues#issues-by-release)). +We close issues at step 3. Then, as updates are released, the issue automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and `stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to select issues waiting for step 6 (see [issues by release](https://github.com/QubesOS/qubes-issues#issues-by-release)). -Therefore, if you see that an issue is closed, but the fix is not yet available -to you, be aware that it may be at an intermediate stage of this process -between issue closure and the update being available in whichever repos you -have enabled in whichever version of Qubes you're using. +Therefore, if you see that an issue is closed, but the fix is not yet available to you, be aware that it may be at an intermediate stage of this process between issue closure and the update being available in whichever repos you have enabled in whichever version of Qubes you're using. -In order to assist with this, we have a label called [backport -pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending), -which means, "The fix has been released for the testing release but is pending -backport to the stable release." Our infrastructure will attempt to apply this -label automatically, when appropriate, but it is not perfect, and the -developers may be need to adjust it manually. +In order to assist with this, we have a label called [backport pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending), which means, "The fix has been released for the testing release but is pending backport to the stable release." Our infrastructure will attempt to apply this label automatically, when appropriate, but it is not perfect, and the developers may be need to adjust it manually. + +### Understanding open and closed issues + +Every issue is always in one of two states: open or closed, with open being the default. The **open** and **closed** states mean that, according to our available information at present, the issue in question either **is** or **is not** (respectively) actionable for the Qubes team. The open and closed states do not mean anything more than this, and it's important not to read anything else into them. It's also important to understand that closing an issue is, in effect, nothing more than changing a virtual tag on an issue. Closing an issue is never "final" in any sense, and it does not affect the issue itself in any other way. Issues can be opened and closed instantly with a single button press an unlimited number of times at no cost. In fact, since the open and closed states reflect our available information at present, one should expect these states to change back and forth as new information becomes available. Closed issues are fully searchable, just like open issues, and we explicitly instruct all users of the issue tracker to search *both* open *and* closed issues, which GitHub makes easy. diff --git a/introduction/support.md b/introduction/support.md index 6f495938..ef073184 100644 --- a/introduction/support.md +++ b/introduction/support.md @@ -176,7 +176,7 @@ information in your message. A great way to provide your hardware details is by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then linking to it in your message. [Ask questions the smart -way.](http://www.catb.org/esr/faqs/smart-questions.html) +way.](https://www.catb.org/esr/faqs/smart-questions.html) ### Be patient @@ -309,7 +309,7 @@ account is in no way required, expected, or encouraged. Many discussants [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](http://www.mutt.org/). +[Thunderbird](https://www.thunderbird.net/) and [Mutt](https://www.mutt.org/). The Google Groups service is just free infrastructure, and we [distrust the infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure). This is why, for example, we encourage discussants to use [Split diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 9a2df42c..5be0d0b3 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -171,26 +171,61 @@ 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. Every PGP -key has a fingerprint that uniquely identifies it among all PGP keys (viewable -with `gpg2 --fingerprint `). Therefore, if you know the genuine QMSK +Perhaps the most common route is to rely on the key's fingerprint, which is a +string of 40 alphanumeric characters, like this: + +``` +427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 +``` + +Every PGP key has one of these fingerprints, which uniquely identifies it among +all PGP keys. (On the command line, you can view a key's fingerprint with the +`gpg2 --fingerprint ` command.) Therefore, if you know the genuine QMSK fingerprint, then you always have an easy way to confirm whether any purported copy of it is authentic, simply by comparing the fingerprints. -For example, here is the QMSK fingerprint: - -```shell_session -pub 4096R/36879494 2010-04-01 - Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 -uid Qubes Master Signing Key -``` - -But how do you know that this is the real fingerprint? After all, [this website +But how do you know which fingerprint is the real one? After all, [this website could be compromised](/faq/#should-i-trust-this-website), so the fingerprint you see here may not be genuine. That's why we strongly suggest obtaining the -fingerprint from *multiple independent sources in several different ways*. +fingerprint from *multiple independent sources in several different ways*, then +comparing the strings of letters and numbers to make sure they match. -Here are some ideas for how to do that: +When it comes to PGP fingerprints, spaces and capitalization don't matter. In +other words, all of these fingerprints are considered the same: + +``` +427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 +427f 11fd 0faa 4b08 0123 f01c ddfa 1a3e 3687 9494 +427F11FD0FAA4B080123F01CDDFA1A3E36879494 +427f11fd0faa4b080123f01cddfa1a3e36879494 +``` + +Instead, what matters is that *all* the characters are present in *exactly* the +same order. If even one character is different, the fingerprints do not match. +Even if two fingerprints have all the same characters, if any of those +characters are in a different order, sequence, or position, then the +fingerprints do not match. + +You may also sometimes see the entire fingerprint prefixed with `0x`, as in: + +``` +0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 +0x427f11fd0faa4b080123f01cddfa1a3e36879494 +``` + +The `0x` prefix is sometimes used to indicate that the string following it is a +hexadecimal value, and some PGP-related tools may require this prefix. For the +purpose of comparing fingerprints as described here, you may safely ignore the +`0x` prefix, as it is not part of the fingerprint. As long as the 40-character +string after the `0x` matches exactly, the fingerprint is the same. + +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), @@ -204,10 +239,10 @@ Here are some ideas for how to do that: 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)). -- Download old Qubes ISOs from different sources and check the included Qubes - Master Signing Key. - Ask people to post the fingerprint on various mailing lists, forums, and chat rooms. +- Download old Qubes ISOs from different sources and check the included Qubes + Master Signing Key. - Repeat the above over Tor. - Repeat the above over various VPNs and proxy servers. - Repeat the above on different networks (work, school, internet cafe, etc.). @@ -215,11 +250,11 @@ Here are some ideas for how to do that: confirm the fingerprint. - Repeat the above from different computers and devices. -Once you've obtained the fingerprint from enough independent sources in enough -different ways that you feel confident that you know the genuine fingerprint, -keep it in a safe place. Every time you need to check whether a key claiming to -be the QMSK is authentic, compare that key's fingerprint to your trusted copy -and confirm they match. +Once you've observed enough matching fingerprints from enough independent +sources in enough different ways that you feel confident that you have the +genuine fingerprint, keep it in a safe place. Every time you need to check +whether a key claiming to be the QMSK is authentic, compare that key's +fingerprint to your trusted copy and confirm they match. Now that you've imported the authentic QMSK, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the QMSK diff --git a/user/advanced-topics/bind-dirs.md b/user/advanced-topics/bind-dirs.md index 2266d91e..c1ecb418 100644 --- a/user/advanced-topics/bind-dirs.md +++ b/user/advanced-topics/bind-dirs.md @@ -24,19 +24,21 @@ In this way sys-whonix can benefit from the Tor anonymity feature 'persistent To ## How to use bind-dirs.sh? ## -In this example, we want to make `/var/lib/tor` persistent. +In this example, we want to make `/var/lib/tor` persistent. Enter all of the following commands in your app qube. -Inside the app qube. - -1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists. +1. Make sure the directory `/rw/config/qubes-bind-dirs.d` exists. ``` sudo mkdir -p /rw/config/qubes-bind-dirs.d ``` -2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights. +2. Create the file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root permissions, if it doesn't already exist. -3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable. + ``` + sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf + ``` + +3. Add a line to `/rw/config/qubes-bind-dirs.d/50_user.conf` that appends a folder or file to the `binds` variable. ``` binds+=( '/var/lib/tor' ) @@ -44,14 +46,22 @@ Inside the app qube. 4. Save. -5. Reboot the app qube. +5. If the directory you wish to make persistent doesn't exist in the template on which the app qube is based, you'll need to create the directory (with its full path) under `/rw/bind-dirs` in the app qube. For example, if `/var/lib/tor` didn't exist in the template, then you would execute the following command in your app qube: -6. Done. + ``` + sudo mkdir -p /rw/bind-dirs/var/lib/tor + ``` -From now on any files within the `/var/lib/tor` folder will persist across reboots. +6. (optional) If the directory you want to persist across reboots (`/var/lib/tor` in this case) needs special ownership and permissions, make sure the directory you created just under `/rw/bind-dirs/` has the same ones (using the commands `chown` and `chmod`, respectively). -You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line. -For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots. +7. Reboot the app qube. + +8. Done. + +From now on, all files in the `/var/lib/tor` directory will persist across reboots. + +You can make make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line. +For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file would also persist across reboots. ``` binds+=( '/var/lib/tor' ) diff --git a/user/downloading-installing-upgrading/supported-releases.md b/user/downloading-installing-upgrading/supported-releases.md index 588cccd8..3d7d1b7d 100644 --- a/user/downloading-installing-upgrading/supported-releases.md +++ b/user/downloading-installing-upgrading/supported-releases.md @@ -19,17 +19,17 @@ release and past major releases are always available on the [Downloads](/downloads/) page, while all ISOs, including past minor releases, are available from our [download mirrors](/downloads/#mirrors). -| Qubes OS | Start Date | End Date | Status | -| ----------- | ---------- | ---------- | --------------------- | -| Release 1 | 2012-09-03 | 2015-03-26 | Unsupported | -| Release 2 | 2014-09-26 | 2016-04-01 | Unsupported | -| Release 3.0 | 2015-10-01 | 2016-09-09 | Unsupported | -| Release 3.1 | 2016-03-09 | 2017-03-29 | Unsupported | -| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported | -| Release 4.0 | 2018-03-28 | 2022-08-04 | Unsupported | -| Release 4.1 | 2022-02-04 | TBA | Supported | -| Release 4.2 | TBA | TBA | [In testing](https://github.com/QubesOS/qubes-issues/milestone/26) | -| Release 4.3 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/milestone/28) | +| Qubes OS | Start Date | End Date | Status | +| ----------- | ---------- | ---------- | -------------- | +| Release 1 | 2012-09-03 | 2015-03-26 | Unsupported | +| Release 2 | 2014-09-26 | 2016-04-01 | Unsupported | +| Release 3.0 | 2015-10-01 | 2016-09-09 | Unsupported | +| Release 3.1 | 2016-03-09 | 2017-03-29 | Unsupported | +| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported | +| Release 4.0 | 2018-03-28 | 2022-08-04 | Unsupported | +| Release 4.1 | 2022-02-04 | 2024-06-18 | Supported | +| Release 4.2 | 2023-12-18 | TBA | Supported | +| Release 4.3 | TBA | TBA | In development | ### Note on patch releases @@ -91,10 +91,10 @@ upstream release on the upstream distribution's website (see [Fedora EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian Releases](https://wiki.debian.org/DebianReleases)). -| Qubes OS | Fedora | Debian | Whonix | -| ----------- | ------ | -------------------------- | ------ | -| Release 4.1 | 37, 38 | 10 (Buster), 11 (Bullseye) | 16 | -| Release 4.2 | 37, 38 | 11 (Bullseye) | 17 | +| Qubes OS | Fedora | Debian | Whonix | +| ----------- | ------ | ------ | ------ | +| Release 4.1 | 38 | 11, 12 | 16 | +| Release 4.2 | 38 | 12 | 17 | ### Note on Debian support @@ -108,23 +108,6 @@ chart that illustrates this. Qubes support ends at the *regular* EOL date, [Whonix](https://www.whonix.org/wiki/Qubes) templates are supported by our partner, the [Whonix Project](https://www.whonix.org/). The Whonix Project has -set its own support policy for Whonix templates in Qubes. - -This policy requires Whonix template users to stay reasonably close to the -cutting edge by upgrading to new stable releases of Qubes OS and Whonix -templates within a month of their respective releases. To be precise: - -* One month after a new stable version of Qubes OS is released, Whonix - templates will no longer be supported on any older release of Qubes OS. This - means that users who wish to continue using Whonix templates on Qubes must - always upgrade to the latest stable Qubes OS release within one month of its - release. - -* One month after new stable versions of Whonix templates are released, older - releases of Whonix templates will no longer be supported. This means that - users who wish to continue using Whonix templates on Qubes must always - upgrade to the latest stable Whonix template releases within one month of - their release. - -We aim to announce both types of events one month in advance in order to remind -users to upgrade. +set its own support policy for Whonix templates in Qubes. Please see the +[Qubes-Whonix version support policy](https://www.whonix.org/wiki/About#Qubes_Hosts) +for details. diff --git a/user/downloading-installing-upgrading/testing.md b/user/downloading-installing-upgrading/testing.md index a500a7c6..d6e6339d 100644 --- a/user/downloading-installing-upgrading/testing.md +++ b/user/downloading-installing-upgrading/testing.md @@ -7,102 +7,52 @@ ref: 147 title: Testing new releases and updates --- -Testing new Qubes OS releases and updates is one of the most helpful ways in -which you can [contribute](/doc/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 [contribute](/doc/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. -**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! +**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! ## Releases How to test upcoming Qubes OS releases: -* Use [qubes-builder](/doc/qubes-builder/) to build the latest release. -* Test the latest release candidate (RC), if one is currently available. -* 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).) -* (No support) Experiment with devel alpha ISOs found from time to time at - [Qubes OpenQA](https://openqa.qubes-os.org/). +- Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).) +- Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).) +- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself. +- (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/). Please make sure to [report any bugs you encounter](/doc/issue-tracking/). -See [Version Scheme](/doc/version-scheme/) for details about release versions -and schedules. See [Release Checklist](/doc/releases/todo/) for details about -the RC process. +See [Version scheme](/doc/version-scheme/) for details about release versions and schedules. See [Release checklist](/doc/releases/todo/) for details about the RC process. ## Updates How to test updates: -* Enable [dom0 testing - repositories](/doc/how-to-install-software-in-dom0/#testing-repositories). -* Enable [template testing - repositories](/doc/how-to-install-software/#testing-repositories). +- Enable [dom0 testing repositories](/doc/how-to-install-software-in-dom0/#testing-repositories). +- Enable [template testing repositories](/doc/how-to-install-software/#testing-repositories). -Every new update is first uploaded to the `security-testing` repository if it -is a security update or `current-testing` if it is a normal update. The update -remains in `security-testing` or `current-testing` for a minimum of one week. -On occasion, an exception is made for a particularly critical security update, -which is immediately pushed to the `current` stable repository. In general, -however, security updates remain in `security-testing` for two weeks before -migrating to `current`. Normal updates generally remain in `current-testing` -until they have been sufficiently tested by the community, which can last weeks -or even months, depending on the amount of feedback received (see [Providing -feedback](#providing-feedback)). +Every new update is first uploaded to the `security-testing` repository if it is a security update or `current-testing` if it is a normal update. The update remains in `security-testing` or `current-testing` for a minimum of one week. On occasion, an exception is made for a particularly critical security update, which is immediately pushed to the `current` stable repository. In general, however, security updates remain in `security-testing` for two weeks before migrating to `current`. Normal updates generally remain in `current-testing` until they have been sufficiently tested by the community, which can last weeks or even months, depending on the amount of feedback received (see [Providing feedback](#providing-feedback)). -"Sufficient testing" is, in practice, a fluid term that is up the developers' -judgment. In general, it means either that no negative feedback and at least -one piece of positive feedback has been received or that the package has been -in `current-testing` for long enough, depending on the component and the -complexity of the changes. +"Sufficient testing" is, in practice, a fluid term that is up the developers' judgment. In general, it means either that no negative feedback and at least one piece of positive feedback has been received or that the package has been in `current-testing` for long enough, depending on the component and the complexity of the changes. -A limitation of the current testing setup is that it is only possible to -migrate the *most recent version* of a package from `current-testing` to -`current`. This means that, if a newer version of a package is uploaded to -`current-testing`, it will no longer be possible to migrate any older versions -of that same package from `current-testing` to `current`, even if one of those -older versions has been deemed stable enough. While this limitation can be -inconvenient, the benefits outweigh the costs, since it greatly simplifies the -testing and reporting process. +A limitation of the current testing setup is that it is only possible to migrate the *most recent version* of a package from `current-testing` to `current`. This means that, if a newer version of a package is uploaded to `current-testing`, it will no longer be possible to migrate any older versions of that same package from `current-testing` to `current`, even if one of those older versions has been deemed stable enough. While this limitation can be inconvenient, the benefits outweigh the costs, since it greatly simplifies the testing and reporting process. ## Templates How to test [templates](/doc/templates/): -* For official templates, enable the `qubes-templates-itl-testing` repository, - then [install](/doc/templates/#installing) the desired template. -* For community templates, enable the `qubes-templates-community-testing` - repository, then [install](/doc/templates/#installing) the desired template. +- For official templates, enable the `qubes-templates-itl-testing` repository, then [install](/doc/templates/#installing) the desired template. +- For community templates, enable the `qubes-templates-community-testing` repository, then [install](/doc/templates/#installing) the desired template. + +To temporarily enable any of these repos, use the `--enablerepo=` option. Example commands: -To temporarily enable any of these repos, use the `--enablerepo=` -option. Example commands: ``` qvm-template --enablerepo=qubes-templates-itl-testing list --available qvm-template --enablerepo=qubes-templates-itl-testing install ``` -To enable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/qubes/repo-templates`. -To disable any of these repos permanently, change the corresponding `enabled` value to `0`. + +To enable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/qubes/repo-templates`. To disable any of these repos permanently, change the corresponding `enabled` value to `0`. ## Providing feedback -Since the whole point of testing software is to discover and fix bugs, your -feedback is an essential part of this process. - -We use an [automated build -process](https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md). -For every package that is uploaded to a testing repository, a GitHub issue is -created in the -[updates-status](https://github.com/QubesOS/updates-status/issues) repository -for tracking purposes. We welcome any kind of feedback on any package in any -testing repository. Even a simple or on -the package's associated issue would help us to decide whether the package is -ready to be migrated to a stable repository. If you [report a -bug](/doc/issue-tracking/) in a package that is in a testing repository, please -reference the appropriate issue in -[updates-status](https://github.com/QubesOS/updates-status/issues). +Since the whole point of testing software is to discover and fix bugs, your feedback is an essential part of this process. We use an [automated build process](https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md). For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository for tracking purposes. We welcome any kind of feedback on any package in any testing repository. Even a simple "thumbs up" or "thumbs down" reaction on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository. If you [report a bug](/doc/issue-tracking/) in a package that is in a testing repository, please reference the appropriate issue in [updates-status](https://github.com/QubesOS/updates-status/issues). diff --git a/user/downloading-installing-upgrading/upgrade/4_2.md b/user/downloading-installing-upgrading/upgrade/4_2.md new file mode 100644 index 00000000..48da7b58 --- /dev/null +++ b/user/downloading-installing-upgrading/upgrade/4_2.md @@ -0,0 +1,109 @@ +--- +lang: en +layout: doc +permalink: /doc/upgrade/4.2/ +title: How to upgrade to Qubes 4.2 +--- + +This page explains how to upgrade from Qubes 4.1 to Qubes 4.2. There are two +ways to upgrade: a clean installation or an in-place upgrade. In general, a +clean installation is simpler and less error-prone, but an in-place upgrade +allows you to preserve your customizations. + +## Back up + +Before attempting either an in-place upgrade or a clean installation, we +strongly recommend that you first [back up your +system](/doc/how-to-back-up-restore-and-migrate/) so that you don't lose any +data. + +## Clean installation + +If you would prefer to perform a clean installation rather than upgrading +in-place: + +1. Create a + [backup](/doc/how-to-back-up-restore-and-migrate/#creating-a-backup) of your + current installation. +2. [Download](/downloads/) the latest 4.2 release. +3. Follow the [installation guide](/doc/installation-guide/) to install Qubes + 4.2. +4. [Restore from your + backup](/doc/how-to-back-up-restore-and-migrate/#restoring-from-a-backup) on + your new 4.2 installation. + +## In-place upgrade + +**Warning:** It is not possible to upgrade directly from releases earlier than +4.1. If you're still on an earlier release, please either perform a [clean +installation of 4.2](#clean-installation) or [upgrade to +4.1](/doc/upgrade/4.1/) first. + +The upgrade may take several hours, and will download several gigabytes of +data. + +In place upgrade is a complex operation. For this reason, we provide a +`qubes-dist-upgrade` tool to handle all the necessary steps automatically. You +can install it with the following command in the dom0 terminal: + + sudo qubes-dom0-update -y qubes-dist-upgrade + +The upgrade consists of six stages --- three before restarting the system --- +labeled "STAGE 1" through "STAGE 3" in the options list below, and three after restarting the system --- labeled as "STAGE 4" through "STAGE 6" below. + +Full list of options can be obtained with `qubes-dist-upgrade --help`: + + Usage: qubes-dist-upgrade [OPTIONS]... + + This script is used for updating current QubesOS R4.1 to R4.2. + + Options: + --update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM. + --release-upgrade, -r (STAGE 2) Update 'qubes-release' for Qubes R4.2. + --dist-upgrade, -s (STAGE 3) Upgrade to Qubes R4.2 and Fedora 37 repositories. + --template-standalone-upgrade, -l (STAGE 4) Upgrade templates and standalone VMs to R4.2 repository. + --finalize, -x (STAGE 5) Finalize upgrade. It does: + - resync applications and features + - cleanup salt states + --convert-policy, -p (STAGE 6) Convert qrexec policy in /etc/qubes-rpc/policy + to the new format in /etc/qubes/policy.d. + --all-pre-reboot Execute stages 1 to 3 + --all-post-reboot Execute stages 4 to 6 + + --assumeyes, -y Automatically answer yes for all questions. + --usbvm, -u Current UsbVM defined (default 'sys-usb'). + --netvm, -n Current NetVM defined (default 'sys-net'). + --updatevm, -f Current UpdateVM defined (default 'sys-firewall'). + --skip-template-upgrade, -j Don't upgrade TemplateVM to R4.2 repositories. + --skip-standalone-upgrade, -k Don't upgrade StandaloneVM to R4.2 repositories. + --only-update Apply STAGE 4 and resync appmenus only to + selected qubes (comma separated list). + --keep-running List of extra VMs to keep running during update (comma separated list). + Can be useful if multiple updates proxy VMs are configured. + --max-concurrency How many TemplateVM/StandaloneVM to update in parallel in STAGE 1 + (default 4). + +After installing the tool, before-reboot stages can be performed at once with: + + sudo qubes-dist-upgrade --all-pre-reboot + +Optionally, an `--assumeyes` (or `-y`) option can be used to automatically +accept all the actions without confirmation. + +Alternatively, each upgrade stage can be started separately (see the list of +options above). + +After completing "STAGE 1" through "STAGE 3", restart the system. Then perform +the final steps: + + sudo qubes-dist-upgrade --all-post-reboot + +After performing those steps, it's recommended to restart the system one last time. + +When this completes, you can start using Qubes OS 4.2. + + +## Update + +After upgrading or performing a clean installation, we strongly recommend +[updating your system](/doc/how-to-update/). diff --git a/user/downloading-installing-upgrading/upgrade/upgrade.md b/user/downloading-installing-upgrading/upgrade/upgrade.md index 0c6c5b82..aad189ad 100644 --- a/user/downloading-installing-upgrading/upgrade/upgrade.md +++ b/user/downloading-installing-upgrading/upgrade/upgrade.md @@ -19,3 +19,4 @@ see [how to update](/doc/how-to-update/). * [Upgrade from 3.1 to 3.2](/doc/upgrade/3.2/) * [Upgrade from 3.2 to 4.0](/doc/upgrade/4.0/) * [Upgrade from 4.0 to 4.1](/doc/upgrade/4.1/) +* [Upgrade from 4.1 to 4.2](/doc/upgrade/4.2/) diff --git a/user/hardware/certified-hardware.md b/user/hardware/certified-hardware.md index db604cf7..d06be86e 100644 --- a/user/hardware/certified-hardware.md +++ b/user/hardware/certified-hardware.md @@ -10,211 +10,96 @@ ref: 144 title: Certified hardware --- -The Qubes OS Project aims to partner with a select few computer vendors to -ensure that Qubes users have reliable hardware purchasing options. We aim for -these vendors to be as diverse as possible in terms of geography, cost, and -availability. +The Qubes OS Project aims to partner with a select few computer vendors to ensure that Qubes users have reliable hardware purchasing options. We aim for these vendors to be as diverse as possible in terms of geography, cost, and availability. -You may also be interested in the [community-recommended -hardware](https://forum.qubes-os.org/t/5560) list and the [hardware -compatibility list (HCL)](/hcl/). +You may also be interested in the [community-recommended hardware](https://forum.qubes-os.org/t/5560) list and the [hardware compatibility list (HCL)](/hcl/). ## Qubes-certified computers -Qubes-certified computers are certified for a [major -release](/doc/version-scheme/) and regularly tested by the Qubes developers to -ensure compatibility with all of Qubes' features within that major release. The -developers test all new updates within that major release to ensure that no -regressions are introduced. +Qubes-certified computers are certified for a [major release](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major release. The developers test all new updates within that major release to ensure that no regressions are introduced. -The current Qubes-certified models are listed below in chronological order of -certification. +The current Qubes-certified models are listed below in chronological order of certification. ### Insurgo PrivacyBeast X230 [![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) -The [Insurgo PrivacyBeast -X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) -is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read -our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) -for details. +The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) for details. ### NitroPad X230 [![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67) -The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is -a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our -[announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) for -details. +The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) for details. ### NitroPad T430 [![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119) -The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) -is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.X. Read -our [announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) for -details. +The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.X. Read our [announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) for details. ### Dasharo FidelisGuard Z690 [![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) -The [Dasharo FidelisGuard -Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) -is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for -Qubes OS 4.X. Read our -[announcement](/news/2023/03/15/dasharo-fidelisguard-z690-first-qubes-certified-desktop/) -for details. +The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/03/15/dasharo-fidelisguard-z690-first-qubes-certified-desktop/) for details. ### NovaCustom NV41 Series -[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://configurelaptop.eu/nv41-series/) +[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://novacustom.com/product/nv41-series/) -The [NovaCustom NV41 Series](https://configurelaptop.eu/nv41-series/) is a -14-inch custom laptop. It is certified for Qubes OS 4.X. Read our -[announcement](/news/2023/05/03/novacustom-nv41-series-qubes-certified/) for -details. +The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/05/03/novacustom-nv41-series-qubes-certified/) for details. + +### NitroPC Pro + +[![Photo of the NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523) + +The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is a desktop based on the MSI PRO Z690-A DDR5 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/09/06/nitropc-pro-qubes-certified/) for details. ## Become hardware certified -If you are a hardware vendor, you can have your hardware certified as -compatible with Qubes OS. The benefits of hardware certification include: +If you are a hardware vendor, you can have your hardware certified as compatible with Qubes OS. The benefits of hardware certification include: -- Your customers can purchase with confidence, knowing that they can take full - advantage of Qubes OS on your hardware for a specific major version. -- We will continue testing your hardware to ensure compatibility with the - supported major version. In the course of this testing, we will also test - your hardware against upcoming versions, which can help with future planning. -- Your hardware will continue to be compatible with Qubes OS as it further - develops within that major version, and we will work with you toward - preserving compatibility and certification in future releases. +- Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware for a specific major version. +- We will continue testing your hardware to ensure compatibility with the supported major version. In the course of this testing, we will also test your hardware against upcoming versions, which can help with future planning. +- Your hardware will continue to be compatible with Qubes OS as it further develops within that major version, and we will work with you toward preserving compatibility and certification in future releases. - You can support the development of Qubes OS. ## Hardware certification requirements -**Note:** This section describes the requirements for hardware *certification*, -*not* the requirements for *running* Qubes OS. For the latter, please see the -[system requirements](/doc/system-requirements/). A brief list of the -requirements described in this section is available -[here](/doc/system-requirements/#qubes-certified-hardware). +**Note:** This section describes the requirements for hardware *certification*, *not* the requirements for *running* Qubes OS. For the latter, please see the [system requirements](/doc/system-requirements/). A brief list of the requirements described in this section is available [here](/doc/system-requirements/#qubes-certified-hardware). -A basic requirement is that all Qubes-certified devices must be 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. +A basic requirement is that all Qubes-certified devices must be 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 ([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. -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. +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. -While we -[recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the -potential problems that proprietary CPU-vendor code can cause, we are also -pragmatic enough to realize that we need to take smaller steps first, before we -can implement even stronger countermeasures such as a [stateless -laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf). A -switch to open source boot firmware is one such important step. To be -compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and -SLAT functionality that the underlying hardware offers (and which we require). -Among other things, this implies **proper DMAR ACPI table** construction. +While we [recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf). A switch to open source boot firmware is one such important step. To be compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and SLAT functionality that the underlying hardware offers (and which we require). Among other things, this implies **proper DMAR ACPI table** construction. -Most laptops use PS/2 connections internally for their input devices (i.e., -keyboard and touchpad). On most desktops, however, USB-connected keyboards -and mice have become standard. This presents a dilemma when the computer has -only one USB controller. If that single USB controller is dedicated solely to -the input devices, then no untrusted USB devices can be used. Conversely, if -the sole USB controller is completely untrusted, then there is no way for the -user to physically control the system in a secure way. In practice, Qubes users -on such hardware systems are generally forced to use a single USB controller -for both trusted and untrusted purposes --- [an unfortunate security -trade-off](/doc/device-handling-security/#security-warning-on-usb-input-devices). -For this reason, we require that every Qubes-certified non-laptop device -**either** (1) supports non-USB input devices (e.g., via PS/2) **or** (2) has a -separate USB controller that is only for input devices. +Most laptops use PS/2 connections internally for their input devices (i.e., keyboard and touchpad). On most desktops, however, USB-connected keyboards and mice have become standard. This presents a dilemma when the computer has only one USB controller. If that single USB controller is dedicated solely to the input devices, then no untrusted USB devices can be used. Conversely, if the sole USB controller is completely untrusted, then there is no way for the user to physically control the system in a secure way. In practice, Qubes users on such hardware systems are generally forced to use a single USB controller for both trusted and untrusted purposes --- [an unfortunate security trade-off](/doc/device-handling-security/#security-warning-on-usb-input-devices). For this reason, we require that every Qubes-certified non-laptop device **either** (1) supports non-USB input devices (e.g., via PS/2) **or** (2) has a separate USB controller that is only for input devices. -Finally, we require that Qubes-certified hardware does not have any built-in -_USB-connected_ microphones (e.g. as part of a USB-connected built-in camera) -that cannot be easily physically disabled by the user, e.g. via a convenient -mechanical switch. Thankfully, the majority of laptops on the market that we -have seen already satisfy this condition out-of-the-box, because their built-in -microphones are typically connected to the internal audio device, which itself -is a type of PCIe device. This is important, because such PCIe audio devices -are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through -our carefully designed protocol only to select app qubes when the user -explicitly chooses to do so. The rest of the time, they should be outside the -reach of malware. +Finally, we require that Qubes-certified hardware does not have any built-in _USB-connected_ microphones (e.g. as part of a USB-connected built-in camera) that cannot be easily physically disabled by the user, e.g. via a convenient mechanical switch. Thankfully, the majority of laptops on the market that we have seen already satisfy this condition out-of-the-box, because their built-in microphones are typically connected to the internal audio device, which itself is a type of PCIe device. This is important, because such PCIe audio devices are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through our carefully designed protocol only to select app qubes when the user explicitly chooses to do so. The rest of the time, they should be outside the reach of malware. -While we also recommend a physical kill switch on the built-in camera (or, if -possible, not to have a built-in camera), we also recognize this isn't a -critical requirement, because users who are concerned about it can easily cover -it a piece of tape (something that, regrettably, is far less effective on a -microphone). +While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone). -Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth -devices to be mandatory. Users who plan on using Qubes in an air-gap scenario -would do best if they manually remove all such devices persistently (as well as -the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely -on easy-to-flip-by-mistake switches, while others should benefit from the Qubes -default sandboxing of all networking devices in dedicated VMs. +Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth devices to be mandatory. Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs. -We hope these hardware requirements will encourage the development of more -secure and trustworthy devices. +We hope these hardware requirements will encourage the development of more secure and trustworthy devices. ## Hardware certification process To have hardware certified, the vendor must: -1. Send the Qubes team two (2) units for testing (non-returnable) for each - configuration the vendor wishes to be offering. -2. Offer to customers the very same configuration (same motherboard, same - screen, same BIOS version, same Wi-Fi module, etc.) for at least one year. -3. Pay the Qubes team a flat monthly rate, to be agreed upon between the - hardware vendor and the Qubes team. +1. Send the Qubes team two (2) units for testing (non-returnable) for each configuration the vendor wishes to be offering. +2. Offer to customers the very same configuration (same motherboard, same screen, same BIOS version, same Wi-Fi module, etc.) for at least one year. +3. Pay the Qubes team a flat monthly rate, to be agreed upon between the hardware vendor and the Qubes team. -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](/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 [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). +If you are interested in having your hardware certified, please [contact us](mailto:business@qubes-os.org). diff --git a/user/how-to-guides/how-to-organize-your-qubes.md b/user/how-to-guides/how-to-organize-your-qubes.md index e5c9891b..e905476a 100644 --- a/user/how-to-guides/how-to-organize-your-qubes.md +++ b/user/how-to-guides/how-to-organize-your-qubes.md @@ -317,7 +317,7 @@ her setup looks like this: to these generally doesn't allow spending or withdrawing any money. So, even the worst case scenario here wouldn't be catastrophic, unlike with her bank and brokerage accounts. Third, she's not too worried about any of her credit - card company websites being used to attach each other or her qube (As long as + card company websites being used to attack each other or her qube. (As long as it's contained to a single qube, she's fine with that level of risk.) Last, but not least: She has way too many credit cards! While Carol is very frugal, she likes to collect the sign-up bonuses that are offered for opening new diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md index 9150909a..2462bafb 100644 --- a/user/how-to-guides/how-to-update.md +++ b/user/how-to-guides/how-to-update.md @@ -8,14 +8,9 @@ ref: 200 title: How to update --- -*This page is about updating your system while staying on the same [supported -version of Qubes OS](/doc/supported-releases/#qubes-os). If you're instead -looking to upgrade from your current version of Qubes OS to a newer version, -see the [Upgrade Guides](/doc/upgrade/).* +*This page is about updating your system while staying on the same [supported version of Qubes OS](/doc/supported-releases/#qubes-os). If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see [Upgrade guides](/doc/upgrade/).* -It is important to keep your Qubes OS system up-to-date to ensure you have the -latest security updates, as well as the latest non-security enhancements and bug -fixes. +It is important to keep your Qubes OS system up-to-date to ensure you have the latest security updates, as well as the latest non-security enhancements and bug fixes. Fully updating your Qubes OS system means updating: @@ -25,124 +20,69 @@ Fully updating your Qubes OS system means updating: ## 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)](/security/qsb/) via the [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. +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)](/security/qsb/) via the [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 -By default, the **Qubes Update** tool will appear as an icon in the Notification -Area when updates are available. +By default, the **Qubes Update** tool will appear as an icon in the Notification Area when updates are available. [![Qube Updates Available](/attachment/doc/r4.0-qube-updates-available.png)](/attachment/doc/r4.0-qube-updates-available.png) -However, you can also start the tool manually by selecting it in the -Applications Menu under "Qubes Tools." Even if no updates have been detected, -you can use this tool to check for updates manually at any time by selecting -"Enable updates for qubes without known available updates," then selecting all -desired items from the list and clicking "Next." +However, you can also start the tool manually by selecting it in the Applications Menu under "Qubes Tools." Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting "Enable updates for qubes without known available updates," then selecting all desired items from the list and clicking "Next." -By default, most qubes that are connected to the internet will periodically -check for updates for their parent templates. If updates are available, you -will receive a notification as described above. However, if you have any -templates that do *not* have any online child qubes, you will *not* receive -update notifications for them. Therefore, you should regularly update such -templates manually instead. +By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. If updates are available, you will receive a notification as described above. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. Therefore, you should regularly update such templates manually instead. ## Installing updates -The standard way to install updates is with the **Qubes Update** tool. (However, -you can also perform the same action via the [command-line -interface](#command-line-interface).) +The standard way to install updates is with the **Qubes Update** tool. (However, you can also perform the same action via the [command-line interface](#command-line-interface).) [![Qubes Update](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png) -Simply follow the on-screen instructions, and the tool will download and install -all available updates for you. Note that if you are downloading updates over Tor -(`sys-whonix`), this can take a very long time, especially if there are a lot of -updates available. +Simply follow the on-screen instructions, and the tool will download and install all available updates for you. Note that if you are downloading updates over Tor (`sys-whonix`), this can take a very long time, especially if there are a lot of updates available. ## Restarting after updating -Certain updates require certain components to be restarted in order for the -updates to take effect: +Certain updates require certain components to be restarted in order for the updates to take effect: - QSBs may instruct you to restart certain components after installing updates. -- Dom0 should be restarted after any **Xen** or **kernel** updates. -- After updating a template, first shut down the template, then restart all - running qubes based on that template. +- Dom0 should be restarted after all **Xen** and **kernel** updates. +- On Intel systems, dom0 should be restarted after all `microcode_ctl` updates. +- On AMD systems, dom0 should be restarted after all `linux-firmware` updates. +- After updating a template, first shut down the template, then restart all running qubes based on that template. + +## AEM resealing after updating + +If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal" after certain updates. It's common for QSBs to contain instructions to this effect. See the relevant QSB and the [AEM `README`](https://github.com/QubesOS/qubes-antievilmaid/blob/main/README) for details. ## Command-line interface -Advanced users may wish to perform updates via the command-line interface. The -recommended way to do this is by applying the following two Salt states. -**Applying these two Salt states is the same as updating via the Qubes Update -tool.** +Advanced users may wish to perform updates via the command-line interface. The recommended way to do this is by applying the following two Salt states. **Applying these two Salt states is the same as updating via the Qubes Update tool.** - [update.qubes-dom0](/doc/salt/#updatequbes-dom0) - [update.qubes-vm](/doc/salt/#updatequbes-vm) -In your update qube, a terminal window opens that displays the progress of -operations and output as it is logged. At the end of the process, logs are sent -back to dom0. You answer any yes/no prompts in your dom0 terminal window. +In your update qube, a terminal window opens that displays the progress of operations and output as it is logged. At the end of the process, logs are sent back to dom0. You answer any yes/no prompts in your dom0 terminal window. -Advanced users may also be interested in learning [how to enable the -testing repos](/doc/testing/). +Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/). ## Upgrading to avoid EOL -The above covers updating *within* a given operating system (OS) release. -Eventually, however, most OS releases will reach **end-of-life (EOL)**, after -which point they will no longer be supported. This applies to Qubes OS itself -as well as OSes used in [templates](/doc/templates/) (and -[standalones](/doc/standalones-and-hvms/), if you have any). +The above covers updating *within* a given operating system (OS) release. Eventually, however, most OS releases will reach **end-of-life (EOL)**, after which point they will no longer be supported. This applies to Qubes OS itself as well as OSes used in [templates](/doc/templates/) (and [standalones](/doc/standalones-and-hvms/), if you have any). -**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 the [supported -releases](/doc/supported-releases/) page. +**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 [Supported releases](/doc/supported-releases/). -In the case of Qubes OS itself, we will make an -[announcement](/news/categories/#releases) when a supported Qubes OS release is -approaching EOL and another when it has actually reached EOL, and we will -provide [instructions for upgrading to the next stable supported Qubes OS -release](/doc/upgrade/). +In the case of Qubes OS itself, we will make an [announcement](/news/categories/#releases) when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/). -Periodic upgrades are also important for templates. For example, you might be -using a [Fedora template](/doc/templates/fedora/). The [Fedora -Project](https://getfedora.org/) is independent of the Qubes OS Project. They -set their own -[schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) -for when each Fedora release reaches EOL. You can always find out when an OS -reaches EOL from the upstream project that maintains it. We also pass along any -EOL notices we receive for official template OSes as a convenience to Qubes -users (see [supported template releases](/doc/supported-releases/#templates)). +Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)). -The one exception to all this is the specific release used for dom0 (not to be -confused with Qubes OS as a whole), which [doesn't have to be -upgraded](/doc/supported-releases/#note-on-dom0-and-eol). +The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol). diff --git a/user/security-in-qubes/vm-sudo.md b/user/security-in-qubes/vm-sudo.md index 7a840ab9..7141102d 100644 --- a/user/security-in-qubes/vm-sudo.md +++ b/user/security-in-qubes/vm-sudo.md @@ -104,86 +104,14 @@ Replacing passwordless root access with Dom0 user prompt -------------------------------------------------------- While the Qubes developers support the statement above, some Qubes users may wish to enable user/root isolation in VMs anyway. -We do not support it in any of our packages, but of course nothing is preventing the user from modifying his or her own system. -A list of steps to do so is provided here **without any guarantee of safety, accuracy, or completeness. +We do not support this in any of our packages, but of course nothing is preventing a user from modifying his or her own system. +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.** -1. Adding Dom0 "VMAuth" service: - - ``` - [root@dom0 /]# echo "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth - [root@dom0 /]# echo "@anyvm dom0 ask,default_target=dom0" \ - >/etc/qubes-rpc/policy/qubes.VMAuth - [root@dom0 /]# chmod +x /etc/qubes-rpc/qubes.VMAuth - ``` - - (Note: any VMs you would like still to have passwordless root access (e.g. Templates) can be specified in the second file with "\ dom0 allow") - -2. Configuring Fedora template to prompt Dom0 for any authorization request: - - In `/etc/pam.d/system-auth`, replace all lines beginning with "auth" with these lines: - - ``` - auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$ - auth requisite pam_deny.so - auth required pam_permit.so - ``` - - - Require authentication for sudo. - Replace the first line of `/etc/sudoers.d/qubes` with: - - ``` - user ALL=(ALL) ALL - ``` - - - Disable PolKit's default-allow behavior: - - ``` - [root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules - [root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla - ``` - -3. Configuring Debian/Whonix template to prompt Dom0 for any authorization request: - - In `/etc/pam.d/common-auth`, replace all lines beginning with "auth" with these lines: - - ``` - auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$ - auth requisite pam_deny.so - auth required pam_permit.so - ``` - - - Require authentication for sudo. - Replace the first line of `/etc/sudoers.d/qubes` with: - - ``` - user ALL=(ALL) ALL - ``` - - - Disable PolKit's default-allow behavior: - - ``` - [root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules - [root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla - ``` - - - In `/etc/pam.d/su.qubes`, comment out this line near the bottom of the file: - - ``` - auth sufficient pam_permit.so - ``` - - - For Whonix, if prompts appear during boot, create `/etc/sudoers.d/zz99` and add these lines: - - ``` - ALL ALL=NOPASSWD: /usr/sbin/virt-what - ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck restart - ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck start - ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck stop - ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck status - ``` - Dom0 passwordless root access ----------------------------- There is also passwordless user->root access in dom0. -As stated in comment in sudo configuration there (different one than VMs one), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account. +As stated in the comment in sudo configuration there (which is different from the one in individual qubes), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account. diff --git a/user/templates/templates.md b/user/templates/templates.md index f3740dec..bab15cb9 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -83,6 +83,15 @@ developers do not test them. * [Gentoo](/doc/templates/gentoo/) * [Gentoo Minimal](/doc/templates/minimal/) +## Windows + +Windows templates are constructed differently from Linux-based templates as +Windows is a closed source system that can be modified only after installing. +So it is not possible to provide preconfigured Windows templates for Qubes. +The process of installing a Windows qube and connecting it to the Qubes +environment via installing Qubes Windows Tools (QWT) is described in several +chapters in [Windows qubes](/doc/templates/windows/). + ## Installing Certain templates come preinstalled with Qubes OS. However, there may be times diff --git a/user/templates/windows/migrate-to-4-1.md b/user/templates/windows/migrate-to-4-1.md new file mode 100644 index 00000000..d80f65d5 --- /dev/null +++ b/user/templates/windows/migrate-to-4-1.md @@ -0,0 +1,54 @@ +--- +lang: en +layout: doc +permalink: /doc/templates/windows/migrate-to-4-1/ +redirect_from: +- /doc/templates/windows/windows-migrate41/ +- /user/templates/windows/windows-migrate41/ +- /doc/windows-migrate41/ +title: Migrating Windows qubes to Qubes OS 4.1 +--- + +For Windows 7, 10 and 11, there is a way to migrate backups created under Qubes R4.0 to R4.1. For this, the version of Qubes Windows Tools (QWT) 4.1-68, available from [tabit-pro/qubes-windows-tools-cross](https://github.com/tabit-pro/qubes-windows-tools-cross/releases), has to be installed under Qubes R4.0, selecting the option to install the Xen PV disk driver, which emulates SCSI disks. For template VMs, the option to move user profiles may be selected, too. Then, the backup may be created, and this backup can be restored under Qubes R4.1, resulting in a VM well integrated into Qubes R4.1. If `qvm-features audio-model ich6` is set, Windows even will have audio, although for Windows 10 and 11 somewhat scratchy. + +While this is somewhat straightforward, things get difficult if QWT 4.0.1.3 was installed in the VM. Prior to installing version 4.1-68, the old version has to be removed, which can be quite tricky for Windows 10 and 11. + +## Preparation for Windows 7 + + - Uninstall QWT 4.0.1.3, using the standard procedure from the system control panel of Windows. This will most likely result in a crash. + - Restart Windows again, hitting the F8 key, select the restart menu, and there select a start in safe mode. + - The system will start gain, but in a rather useless way. Just shut it down, and reboot again. + - Now Windows will start normally. Check in the control panel, if there are any Xen drivers left. If so, uninstall them. + - In the Windows device manager, check if there is still a (probably non working) Xen PV disk device. If so, uninstall it. Otherwise, QWT 4.1-68 will not install. + - In the control panel, check again, if the Xen drivers are removed. A Xen Bus Package (version 8.2.1.8) may remain and cannot be removed, but does no harm. Any other Xen drivers should have disappeared. + - There probably will be a drive `D:` containing the private user data. For Qubes, R4.1, QWT will expect this drive to be called `Q:`, so it has to be renamed: + - Start the command prompt as administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator" + - In the command prompt type `diskmgmt.msc` + - In the disk manager, select the volume `Private (D:)` + - Select the option `Change Drive Letter and Path` + - Select option `Change...` + - Select the letter `Q` + - Click `OK` in all still open windows of the disk manager and terminate it. + +## Preparation for Windows 10 and 11 + +If there is a drive `D:` from this earlier installation of Qubes Windows Tools, it will probably contain incomplete private data; especially the folder `AppData` containing program configuration data will be missing. In this situation, it may be better to perform a new Windows installation, because repair may be difficult and trouble-prone. +- First, be sure that the automatic repair function is disabled. In a command window, execute `bcdedit /set recoveryenabled NO`, and check that this worked by issuing the command `bcdedit`, without parameters, again. +- Now, uninstall QWT 4.0.1.3, using the Apps and Features function of Windows. This will most likely result in a crash. +- Restart Windows again, possibly two or three times, until repair options are offered. By hitting the F8 key, select the restart menu, and there select a start in safe mode (in German, it's option number 4). +- The system will start gain, but in a rather useless way. Just shut it down, and reboot again. +- Now Windows will start normally. Check in the Apps and Features display, if there are any Xen drivers left. If so, uninstall them. +- In the Windows device manager, check if there is still a (probably non working) Xen PV disk device. If so, uninstall it. Otherwise, QWT 4.1-68 will not install. +- In the Apps and Features display, check again, if the Xen drivers are removed. A Xen Bus Package (version 8.2.1.8) may remain and cannot be removed, but does no harm. Any other Xen drivers should have disappeared. + +## Transferring the Windows Qube + +- Now, finally, after one additional reboot, Qubes Windows Tools 4.1-68 can be installed. The option `Move user profiles` should be used **if and only if** there was **no** separate drive `D:` in the earlier Windows installation. +- After one more reboot, the backup for R4.1 may be created. +- This backup can be installed in Qubes R4.1 and will (probably) work. + +The PV disk drivers used for migration can be removed after successful installation of the VM under Qubes R4.1. For this, the QWT installation has to be started, the option Change has to be selected, and the PV disk driver must be unselected. After completion, the VM has to be rebooted. For Windows 10 and 11, the VM will crash with the error INACCESSIBLE BOOT DEVICE, which can be repaired as described above. + +After successful uninstallation of the PV disk drivers, the disks will appear as QEMU ATA disks. + +:warning: **Caution:** This change may lead Windows to declare that the hardware has changed and that in consequence, the activation is no longer valid, possibly complaining that the use of the software is no longer lawful. It should be possible to reactivate the software if a valid product key is provided. diff --git a/user/templates/windows/qubes-windows-tools-4-0.md b/user/templates/windows/qubes-windows-tools-4-0.md new file mode 100644 index 00000000..0c4e2443 --- /dev/null +++ b/user/templates/windows/qubes-windows-tools-4-0.md @@ -0,0 +1,358 @@ +--- +lang: en +layout: doc +permalink: /doc/templates/windows/qubes-windows-tools-4-0/ +redirect_from: +- /doc/templates/windows/windows-tools/ +- /user/templates/windows/windows-tools/ +- /doc/windows-tools/ +- /doc/windows-appvms/ +- /en/doc/windows-appvms/ +- /doc/WindowsAppVms/ +- /wiki/WindowsAppVms/ +- /doc/windows-tools-3/ +- /en/doc/windows-tools-3/ +- /doc/WindowsTools3/ +- /doc/WindowsTools/ +- /wiki/WindowsTools/ +title: Qubes Windows Tools (QWT) in Qubes OS 4.0 +--- + +**Warning:** *The content below describes Qubes Windows Tools installation in Qubes R4.0. The text has been updated to reflect the newer R4.1 release and QWT recent development. Please see [this updated document](/doc/templates/windows/qubes-windows-tools-4-1) for instructions for Qubes R4.1 and the updated version of Qubes Windows Tools.* + +Qubes Windows Tools are a set of programs and drivers that provide integration of Windows AppVMs with the rest of the Qubes system. Currently the following features are available for Windows VMs after installation of those tools: + +- **Qubes Video Driver** - provides for the Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop +- **File sender/receiver** - Support for [secure clipboard copy/paste](/doc/copy-paste/) between the Windows VM and other AppVMs +- **File sender/receiver** - Support for [secure file exchange](/doc/copying-files/) between the Windows VM and other AppVMs +- **Copy/Edit in Disposable VM** - Support for editing files in DisposableVMs as well as for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM) +- **Xen PV drivers** for Windows that increase performance compared to qemu emulated devices + +Below is a breakdown of the feature availability depending on the windows version: + +| Feature | Windows 7 x64 | Windows 10 x64 | +| ------------------------------------ | :------------: | :------------: | +| Qubes Video Driver | + | - | +| Qubes Network Setup | + | + | +| Private Volume Setup (move profiles) | + | + | +| File sender/receiver | + | + | +| Clipboard Copy/Paste | + | + | +| Application shortcuts | + | + | +| Copy/Edit in Disposable VM | + | + | +| Block device | + | + | +| USB device | + | + | +| Audio | - | - | + +Qubes Windows Tools are open source and are distributed under a GPL license. + +**Notes:** + +- Qubes Windows Tools are currently unmaintained +- 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)). + +Installing Windows OS in a Qubes VM +----------------------------------- + +Please refer to [this page](/doc/templates/windows/windows-vm) for instructions on how to install Windows in a Qubes VM. + +**Note:** It is strongly suggested to enable autologon for any Windows HVMs that will have Qubes Tools installed. To do so, run `netplwiz` command from the `Win+R`/Start menu and uncheck the *Users must enter a user name and password to use this computer* option. + +Installing Qubes guest tools in Windows 10 VMs +---------------------------------------------- + +This will allow you to install the Qubes Windows Tools on Windows 10 both as a StandaloneVM as well as a Template VM and a corresponding AppVM. But some features are not available: + +**Note:** seamless mode is currently not available for windows. Please check the top of this document for the full feature availability breakdown. + + 1. In the Windows 10 VM, download from the [XEN website](https://xenproject.org/downloads/windows-pv-drivers/windows-pv-drivers-9-series/windows-pv-drivers-9-0-0/) the installation kits for Xen bus (`xenbus`) and storage drivers (`xenvbd`) Version 9.0.0 (two files`xenvbd.tar`and `xenbus.tar`). + + 2. Use an archive extractor like [7-zip](https://www.7-zip.org/) to extract the contents of the `.tar` files. + + 3. Install `xenvbd` and `xenbus` by starting the file `dpinst.exe` from the `x64` directories of the extracted tar-files. If during installation, the Xen driver requests a reboot, select "No" and let the installation continue. + + 4. After installation, reboot. + + 5. Download the Qubes Windows Tools (`qubes-tools-4.0.1.3.exe`) from [the qubes FTP server](https://ftp.qubes-os.org/qubes-windows-tools/) and move it to `C:\`. + + 6. Check the integrity of the file `qubes-tools-4.0.1.3.exe`by comparing its hash checksum. This can be done using the Windows command `certutil` on the windows command prompt (`cmd.exe`) and specifying an appropriate hash algorithm like: + + certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256 + + And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support. + + **Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken. + + 7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later. + + 8. Shut down Windows and wait until the VM is really stopped, i.e. Qubes shows no more activity. + + 9. On a `dom0` terminal write: *(where `` is the name of your Windows 10 VM)* + + qvm-features gui 1 + qvm-prefs qrexec_timeout 300 + + 10. Reboot Windows. If the VM starts, but does not show any window then shutdown Windows from the Qube manager, wait until it has really stopped, and reboot Windows once more. + + 11. Now the system should be up, with QWT running correctly. + + 12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `` is the name of your Windows 10 VM)* + + `qvm-prefs default_user ` + + **Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder + + C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\ + + If the target VM is an AppVM, this has the consequence that the files are stored in the corresponding TemplateVM and so are lost on AppVM shutdown. + + +Installing Qubes guest tools in Windows 7 VMs +--------------------------------------------- + +First, make sure that `qubes-windows-tools` is installed in your system: + +~~~ +sudo qubes-dom0-update qubes-windows-tools +~~~ + +(If the above command does not work, it could be that the Qubes Tools are not in the stable repo yet. Try installing from the testing repo instead.) + +You can also install the package from testing repositories, where we usually publish new versions first: + +~~~ +sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools +~~~ + +This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed. + +Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that: + +- Start command prompt as Administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator" +- In the command prompt type `bcdedit /set testsigning on` +- Reboot your Windows VM + +In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools. + +To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`: + +~~~ +qvm-start lab-win7 --install-windows-tools +~~~ + +Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory. + +After successful installation, the Windows VM must be shut down and started again, possibly a couple of times. + +Qubes will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command: + +~~~ +qvm-prefs +~~~ + +**Note:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0: + +~~~ +qvm-prefs qrexec_timeout 300 +~~~ + +Xen PV drivers and Qubes Windows Tools +-------------------------------------- + +Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Win7 VM are usually very stable). There are two ways of installing the drivers: + +1. installing the drivers independently, from Xen's [official site](https://www.xenproject.org/developers/teams/windows-pv-drivers.html) +2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers. + +Notes about using Xen's VBD (storage) PV driver: +- **Windows 7:** installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above). +- the option to install the storage PV driver is disabled by default in Qubes Windows Tools +- in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar). + +**Caution:** Installing the version 9.0.0 Xen drivers on Windows 7 (a system without QWT - QWT uninstalled) leads to an unbootable system. The drivers install without error, but after reboot, the system aborts the reboot saying `Missing driver xenbus.sys`. + +- **Windows 10:** The version 9.0.0 Xen drivers have to be installed before installing Qubes Windows Tools. Installing them on a system with QWT installed is likely to produce a system which crashes or has the tools in a non-functional state. Even if the tools were installed and then removed before installing the Xen drivers, they probably will not work as expected. + + +With Qubes Windows Tools installed the early graphical console provided in debugging mode isn't needed anymore since Qubes' display driver will be used instead of the default VGA driver: + +~~~ +qvm-prefs -s win7new debug false +~~~ + + +Using Windows AppVMs in seamless mode +------------------------------------- + +**Note:** This feature is only available for Windows 7 + +Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running): + +~~~ +qvm-run -a my-win7-appvm explorer.exe +~~~ + +[![windows-seamless-4.png](/attachment/doc/windows-seamless-4.png)](/attachment/doc/windows-seamless-4.png) +[![windows-seamless-1.png](/attachment/doc/windows-seamless-1.png)](/attachment/doc/windows-seamless-1.png) + +Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM: + +~~~ +[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx +~~~ + +~~~ +[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com +~~~ + +... just like in the case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked whether to allow or deny the operation. + +Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM. + +To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press Ctrl-Alt-Home while having any window of this VM in the foreground. + +[![windows-seamless-7.png](/attachment/doc/windows-seamless-7.png)](/attachment/doc/windows-seamless-7.png) + +Changing between seamless and full desktop mode +----------------------------------------------- + +You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default. + +Using template-based Windows AppVMs +----------------------------------- + +Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just as for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM). + +In order to create a HVM TemplateVM one can use the following command, suitably adapted: + +~~~ +qvm-create --class TemplateVM win-template --property virt_mode=HVM --property kernel='' -l green +~~~ + +... , set memory as appropriate, and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/). + +If you use this Template as it is, then any HVMs that use it will effectively be DisposableVMs - the User directory will be wiped when the HVN is closed down. + +If you want to retain the User directory between reboots, then it would make sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs. +This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically. +To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`. +It's a selectable feature of the installer, enabled by default, but working only for Windows 7. +If that feature is selected during installation, completion of the process requires two reboots: + +- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active. +- User profiles are moved to the private disk on the next reboot after the private disk is initialized. +Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there. +This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot. +That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after. + +For Windows 10, the user directories have to be moved manually, because the automatic transfer during QWT installation is bound to crash due to undocumented new features of NTFS, and a system having the directory `users`on another disk than `C:` will break on Windows update. So the following steps should be taken: + +- The Windows disk manager may be used to add the private volume as disk `D:`, and you may, using the documented Windows operations, move the user directories `C:\users\\Documents` to this new disk, allowing depending AppVMs to have their own private volumes. Moving the hidden application directories `AppData`, however, is likely to invite trouble - the same trouble that occurs if, during QWT installation, the option `Move user profiles` is selected. + +- Configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM. + +It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs. + +Once the template has been created and installed it is easy to create AppVMs based on it: + +~~~ +qvm-create --property virt_mode=hvm --template --label