From 98d89c5b13f396f71242815af26fa856472b3a99 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Tue, 16 Sep 2025 07:57:56 -0400 Subject: [PATCH 01/20] Replace all anchors links by ref roles * duplicate titles were removed * minor fixes for links like "below", etc. --- .../general/developing-gui-applications.rst | 2 +- developer/general/how-to-edit-the-website.rst | 4 +- developer/general/package-contributions.rst | 8 +-- developer/general/website-style-guide.rst | 4 +- developer/services/qrexec.rst | 4 +- developer/services/qrexec2.rst | 2 +- introduction/faq.rst | 22 +++--- introduction/issue-tracking.rst | 16 ++--- introduction/privacy.rst | 2 +- introduction/statistics.rst | 2 +- introduction/support.rst | 26 +++---- project-security/security-pack.rst | 2 +- project-security/security.rst | 2 +- project-security/verifying-signatures.rst | 72 +++++++++---------- user/advanced-topics/i3.rst | 2 +- user/advanced-topics/usb-qubes.rst | 14 ++-- .../installation-guide-4.1.rst | 4 +- .../installation-guide.rst | 4 +- .../testing.rst | 2 +- .../upgrade/4_1.rst | 2 +- .../upgrade/4_2.rst | 2 +- .../upgrade/4_3.rst | 2 +- user/hardware/system-requirements.rst | 6 +- .../how-to-back-up-restore-and-migrate.rst | 2 +- user/how-to-guides/how-to-copy-from-dom0.rst | 4 +- .../how-to-guides/how-to-install-software.rst | 4 +- user/how-to-guides/how-to-update.rst | 2 +- .../how-to-use-block-storage-devices.rst | 4 +- user/how-to-guides/how-to-use-usb-devices.rst | 4 +- user/security-in-qubes/ctap-proxy.rst | 6 +- user/security-in-qubes/firewall.rst | 2 +- user/security-in-qubes/firewall_4.1.rst | 2 +- user/security-in-qubes/split-gpg.rst | 8 ++- user/templates/debian/debian-upgrade.rst | 4 +- user/templates/debian/debian.rst | 2 +- user/templates/fedora/fedora-upgrade.rst | 2 +- user/templates/fedora/fedora.rst | 2 +- user/templates/templates.rst | 18 ++--- 38 files changed, 139 insertions(+), 133 deletions(-) diff --git a/developer/general/developing-gui-applications.rst b/developer/general/developing-gui-applications.rst index 4eb42d60..00d237aa 100644 --- a/developer/general/developing-gui-applications.rst +++ b/developer/general/developing-gui-applications.rst @@ -63,7 +63,7 @@ If error should be thrown, you need to provide the error code and name, for exam b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00' -For details of particular calls, you can use `Extending the mock Qubes object <#extending-the-mock-qubes-object>`__. +For details of particular calls, you can use :ref:`developer/general/developing-gui-applications:extending the mock qubes object`. Available mocks --------------- diff --git a/developer/general/how-to-edit-the-website.rst b/developer/general/how-to-edit-the-website.rst index a70e6b1e..37c96862 100644 --- a/developer/general/how-to-edit-the-website.rst +++ b/developer/general/how-to-edit-the-website.rst @@ -24,7 +24,7 @@ hosted on `GitHub `__. A few notes to consider: -- Since Qubes is a security-oriented project, every change will be `reviewed <#security>`__ before it’s accepted. This allows us to maintain quality control and protect our users. +- Since Qubes is a security-oriented project, every change will be :ref:`reviewed ` before it’s accepted. This allows us to maintain quality control and protect our users. - To give your contribution a better chance of being accepted, please follow our :doc:`website style guide `. - We don’t want you to spend time and effort on a contribution that we can’t accept. If your contribution would take a lot of time, please :doc:`file an issue ` for it first so that we can make sure we’re on the same page before significant works begins. - Finally, if you’ve written something that doesn’t belong in `qubesos.github.io `__ but would be beneficial to the Qubes community, please consider adding it to the :doc:`documentation ` or the :ref:`external documentation `. @@ -212,7 +212,7 @@ Once a pull request passes review, the reviewer should add a signed comment stat Questions, problems, and improvements ------------------------------------- -If you have a question about something you read in the website or about how to edit the it, please post it on the `forum `__ or send it to the appropriate :doc:`mailing list `. If you see that something in the website should be fixed or improved, please `contribute <#how-to-submit-a-pull-request>`__ the change yourself. To report an issue with the wesbite, please follow our standard :doc:`issue reporting guidelines `. (If you report an issue with the website, you will likely be asked to submit a pull request for it, unless there is a clear indication in your report that you are not willing or able to do so.) +If you have a question about something you read in the website or about how to edit the it, please post it on the `forum `__ or send it to the appropriate :doc:`mailing list `. If you see that something in the website should be fixed or improved, please :ref:`contribute ` the change yourself. To report an issue with the wesbite, please follow our standard :doc:`issue reporting guidelines `. (If you report an issue with the website, you will likely be asked to submit a pull request for it, unless there is a clear indication in your report that you are not willing or able to do so.) .. |news-section| image:: /attachment/doc/website_news_section.png :alt: Depicts the News section of the Qubes OS website diff --git a/developer/general/package-contributions.rst b/developer/general/package-contributions.rst index 0ea46f52..55ffb9a0 100644 --- a/developer/general/package-contributions.rst +++ b/developer/general/package-contributions.rst @@ -35,7 +35,7 @@ Contribution Procedure Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the :ref:`qubes-devel mailing list `. Once you have a package that’s ready to become part of Qubes OS, please follow this procedure: -1. Ensure that your package satisfies the `Inclusion Criteria <#inclusion-criteria>`__. +1. Ensure that your package satisfies the :ref:`developer/general/package-contributions:inclusion criteria`. 2. If your code isn’t already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called `qubes-skeleton `__. @@ -43,7 +43,7 @@ Before you start putting serious work into a package, we recommend that you disc 4. Create an issue in `qubes-issues `__ with the title ``[Contribution] your-package-name``. Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes. Please note that the Qubes core developers are very busy. If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package. If this happens, please do not be discouraged. If you think they may have forgotten about your pending contribution, you may “bump” your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month). We appreciate your understanding! -5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the `QubesOS-contrib `__ organization on GitHub as public recognition of your contribution (but without push access; see `Review Procedure <#review-procedure>`__), and `QubesOS-contrib `__ will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue. +5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the `QubesOS-contrib `__ organization on GitHub as public recognition of your contribution (but without push access; see :ref:`developer/general/package-contributions:review procedure`), and `QubesOS-contrib `__ will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue. @@ -59,7 +59,7 @@ Review Procedure ---------------- -This review procedure covers both original package contributions (see `Contribution Procedure <#contribution-procedure>`__) and all subsequent updates to those packages, including updates from the original package contributor (see `Update Procedure <#update-procedure>`__). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the `Package Maintainer <#package-maintainers>`__ (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package. +This review procedure covers both original package contributions (see :ref:`developer/general/package-contributions:contribution procedure`) and all subsequent updates to those packages, including updates from the original package contributor (see :ref:`developer/general/package-contributions:update procedure`). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the :ref:`Package Maintainer ` (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package. The review procedure is as follows: @@ -97,7 +97,7 @@ Package Maintainers If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise. As the maintainer of the package, it is your privilege and responsibility to: -- `Review <#review-procedure>`__ each pull request made against the package. +- :ref:`Review ` each pull request made against the package. - Decide when the package has reached a new version, and notify the Qubes core developers when this occurs. diff --git a/developer/general/website-style-guide.rst b/developer/general/website-style-guide.rst index 75ed93fc..3e6c923d 100644 --- a/developer/general/website-style-guide.rst +++ b/developer/general/website-style-guide.rst @@ -109,7 +109,7 @@ HTML and CSS ^^^^^^^^^^^^ -Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as `alerts <#alerts>`__). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead. +Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as :ref:`developer/general/website-style-guide:alerts`). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead. Headings ^^^^^^^^ @@ -161,7 +161,7 @@ There are two problems with this: -Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using `alerts <#alerts>`__. Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,: +Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using :ref:`developer/general/website-style-guide:alerts`. Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,: .. code:: markdown diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst index fa668893..a744e568 100644 --- a/developer/services/qrexec.rst +++ b/developer/services/qrexec.rst @@ -212,7 +212,7 @@ When calling a service that takes an argument, just add the argument to the serv The script will receive ``ARGUMENT`` as its argument. The argument will also become available as the ``QREXEC_SERVICE_ARGUMENT`` environment variable. This means it is possible to install a different script for a particular service argument. -See `below <#rpc-service-with-argument-file-reader>`__ for an example of an RPC service using an argument. +See :ref:`developer/services/qrexec:rpc service with argument (file reader)` for an example of an RPC service using an argument. Qubes RPC examples ------------------ @@ -278,7 +278,7 @@ RPC service with argument (file reader) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Here we create an RPC call that reads a specific file from a predefined directory on the target. This example uses an `argument <#service-policies-with-arguments>`__ to the policy. In this example a simplified workflow will be used. The service code is placed directly in the service definition file on the target VM. No separate client script will be needed. +Here we create an RPC call that reads a specific file from a predefined directory on the target. This example uses an :ref:`argument ` to the policy. In this example a simplified workflow will be used. The service code is placed directly in the service definition file on the target VM. No separate client script will be needed. First, on your target VM, create two files in the home directory: ``testfile1`` and ``testfile2``. Have them contain two different “Hello world!” lines. diff --git a/developer/services/qrexec2.rst b/developer/services/qrexec2.rst index 2b62aa7e..f49dfdda 100644 --- a/developer/services/qrexec2.rst +++ b/developer/services/qrexec2.rst @@ -102,7 +102,7 @@ By default, stderr of client and server is logged to respective ``/var/log/qubes Be very careful when coding and adding a new RPC service! Any vulnerability in a RPC server can be fatal to security of the target VM! -If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*, connect directly to ``/var/run/qubes/qrexec-agent-fdpass`` socket as described `below <#all-the-pieces-together-at-work>`__. +If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*, connect directly to ``/var/run/qubes/qrexec-agent-fdpass`` socket as described :ref:`below `. Revoking "Yes to All" authorization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/introduction/faq.rst b/introduction/faq.rst index b916799d..67021932 100644 --- a/introduction/faq.rst +++ b/introduction/faq.rst @@ -25,7 +25,7 @@ The second sense is more complicated. Qubes OS is *mostly* “free as in speech, However, since Qubes OS is a security-focused operating system, it includes some non-free firmware that was not created by the Qubes OS Project (such as CPU microcode), which is necessary in order to protect against known security vulnerabilities. Moreover, the :doc:`architecture ` of Qubes OS as a meta-operating system means that it incorporates other software (including entire operating systems) from various upstream projects, some of which may include non-free software of their own. In order to make the installation process easier for a wide range of users across many different devices, standard Qubes :doc:`templates ` also include some non-free firmware and drivers. -Also see: `Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)? <#will-qubes-seek-to-get-certified-under-the-gnu-free-system-distribution-guidelines-gnu-fsdg>`__ +Also see: :ref:`introduction/faq:will qubes seek to get certified under the gnu free system distribution guidelines (gnu fsdg)?` Why is OS security important? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -63,7 +63,7 @@ What about privacy in non-Whonix qubes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The main way Qubes OS `provides privacy <#how-does-qubes-os-provide-privacy>`__ is via its `integration with Whonix `__. Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-Whonix qubes. This includes :doc:`disposables `. +The main way Qubes OS :ref:`provides privacy ` is via its `integration with Whonix `__. Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-Whonix qubes. This includes :doc:`disposables `. Privacy is far more difficult than is commonly understood. In addition to the `web browser `__, there is also `VM fingerprinting `__ and `advanced deanonymization attacks `__ that most users have never considered (and this is just to mention a few examples). The `Whonix Project `__ specializes in `protecting against these risks `__. @@ -297,13 +297,13 @@ Instead, Qubes aims to be as free as possible *without sacrificing security*. Al The `four essential freedoms `__ are part of the core of our philosophy, but so is security. Together, they inform our decisions and motivate our actions. Qubes aims to maximize both security and software freedom to the extent that they are compatible in the world today. -Also see `Is Qubes OS free and open-source software? <#is-qubes-os-free-and-open-source-software>`__ and the Qubes OS :doc:`software license `. +Also see :ref:`introduction/faq:is qubes os free and open-source software?` and the Qubes OS :doc:`software license `. Why is the documentation hosted on ReadTheDocs as opposed to the website? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Qubes OS documentation is written in reStructuredText and hosted on `Read The Docs `__. -The infrastructure is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. +The infrastructure is largely outside of our control. We don’t consider this a problem, however, since we explicitly :ref:`distrust the infrastructure `. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of the documentation in a secure way, you should clone our `documentation repo `__, @@ -320,7 +320,7 @@ Should I trust this website? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This website is hosted on `GitHub Pages `__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo `__, :ref:`verify the PGP signatures on the commits and/or tags ` signed by the `doc-signing keys `__ (which indicates that the content has undergone :ref:`review `), then either `render the site on your local machine `__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason `. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible. +This website is hosted on `GitHub Pages `__ (:ref:`why? `). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly :ref:`distrust the infrastructure `. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo `__, :ref:`verify the PGP signatures on the commits and/or tags ` signed by the `doc-signing keys `__ (which indicates that the content has undergone :ref:`review `), then either `render the site on your local machine `__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason `. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible. What does it mean to "distrust the infrastructure"? @@ -331,7 +331,7 @@ A core tenet of the Qubes philosophy is “distrust the infrastructure,” where Users can never fully control all the infrastructure they rely upon, and they can never fully trust all the entities who do control it. Therefore, we believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so. We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users. Since we don’t want to encourage or endorse this, we make our distrust of the infrastructure explicit. -Also see: `Should I trust this website? <#should-i-trust-this-website>`__ +Also see: :ref:`introduction/faq:should i trust this website?` Why do you use GitHub? ^^^^^^^^^^^^^^^^^^^^^^ @@ -339,7 +339,7 @@ Why do you use GitHub? Three main reasons: -1. We `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__ including GitHub (though there are aspects we’re still `working on `__). +1. We :ref:`distrust the infrastructure ` including GitHub (though there are aspects we’re still `working on `__). 2. It’s free (as in beer). We’d have to spend either time or money to implement a solution ourselves or pay someone to do so, and we can’t spare either one right now. @@ -347,13 +347,13 @@ Three main reasons: -Also see: `Should I trust this website? <#should-i-trust-this-website>`__ +Also see: :ref:`introduction/faq:should i trust this website?` Why doesn't this website have security feature X? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Although we caution users against `placing undue trust in this website <#should-i-trust-this-website>`__ because we `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__, we have no objection to enabling website security features when doing so is relatively costless and provides some marginal benefit to website visitors. So, if feature X isn’t enabled, it’s most likely for one of three reasons: +Although we caution users against :ref:`placing undue trust in this website ` because we :ref:`distrust the infrastructure `, we have no objection to enabling website security features when doing so is relatively costless and provides some marginal benefit to website visitors. So, if feature X isn’t enabled, it’s most likely for one of three reasons: 1. Our GitHub Pages platform doesn’t support it. @@ -457,7 +457,7 @@ Why is VT-d/AMD-Vi/AMD IOMMU important? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -On a system without VT-d/AMD-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple `DMA attack <#what-is-a-dma-attack>`__ to go from the NetVM to Dom0. Nonetheless, all of Qubes’ other security mechanisms, such as qube separation, work without VT-d/AMD-Vi/AMD IOMMU. Therefore, a system running Qubes without VT-d/AMD-Vi/AMD IOMMU would still be significantly more secure than one running Windows, Mac, or Linux. +On a system without VT-d/AMD-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple :ref:`DMA attack ` to go from the NetVM to Dom0. Nonetheless, all of Qubes’ other security mechanisms, such as qube separation, work without VT-d/AMD-Vi/AMD IOMMU. Therefore, a system running Qubes without VT-d/AMD-Vi/AMD IOMMU would still be significantly more secure than one running Windows, Mac, or Linux. What is a DMA attack? ^^^^^^^^^^^^^^^^^^^^^ @@ -735,7 +735,7 @@ Could you please make my preference the default? It would be great if Qubes were configured just the way we like it by default with all of our favorite programs and settings. Then, we could just install Qubes without having to install any programs in it or adjust any settings. We might even think that if a particular program or setting works so well for *us*, it would work well for *everyone*, so we’d actually be doing everyone a favor! The problem is that Qubes has :doc:`tens of thousands of different users ` with radically different needs and purposes. There is no particular configuration that will be ideal for everyone (despite how much we might feel that our preference would be better for everyone), so the best we can do is to put power in the hands of users to configure their Qubes installations the way they like (subject to security constraints, of course). For this reason, we generally do not grant requests for people’s favorite programs to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches the requester’s preference. -See also: `What is Qubes’ attitude toward changing guest distros? <#what-is-qubes-attitude-toward-changing-guest-distros>`__ +See also: :ref:`introduction/faq:what is qubes' attitude toward changing guest distros?` Software installed in a qube is gone after restarting. Why? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/introduction/issue-tracking.rst b/introduction/issue-tracking.rst index e5573a71..2ac7e394 100644 --- a/introduction/issue-tracking.rst +++ b/introduction/issue-tracking.rst @@ -35,13 +35,13 @@ 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: -1. Carefully read our issue tracking `guidelines <#guidelines>`__. If your issue would violate any of the guidelines, **stop**. Please do not submit it. +1. Carefully read our issue tracking :ref:`introduction/issue-tracking: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**. :ref:`Do not open a duplicate. ` Instead, comment on the existing issue. +2. :ref:`Search through the existing issues `, both open and closed, to see if your issue already exists. If it does, **stop**. :ref:`Do not open a duplicate. ` Instead, comment on the existing issue. 3. Go `here `__. -4. Select the `type <#types>`__ of issue you want to open. +4. Select the :ref:`type ` of issue you want to open. 5. Enter a descriptive title. @@ -119,7 +119,7 @@ Meta-issues ^^^^^^^^^^^ -A meta-issue is an issue that serves primarily to collect and organize a group of other issues. This group of other issues typically exists in a hierarchy of `sub-issues `__, usually with the meta-issue at the top. (For example, we use meta-issues when we need a way to track work on specific features. We cannot use `projects <#projects>`__ for this, because we already use a project for tracking the work of the Qubes team as a whole, and projects cannot contain milestones or other projects.) +A meta-issue is an issue that serves primarily to collect and organize a group of other issues. This group of other issues typically exists in a hierarchy of `sub-issues `__, usually with the meta-issue at the top. (For example, we use meta-issues when we need a way to track work on specific features. We cannot use :ref:`introduction/issue-tracking:projects` for this, because we already use a project for tracking the work of the Qubes team as a whole, and projects cannot contain milestones or other projects.) Meta-issues should have informative descriptions, not just lists of issues. In particular, each meta-issue should explain its goal, what is in scope, and what the relevant categories and priorities are. @@ -149,7 +149,7 @@ 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 :doc:`Help, Support, Mailing Lists, and Forum `). 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 :ref:`introduction/issue-tracking: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 ^^^^^^^^^^^^^^^^^^^^^^^ @@ -171,7 +171,7 @@ Every issue must be about a single, actionable thing If your issue is not actionable, please see :doc:`Help, Support, Mailing Lists, and Forum ` 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 `__. -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 :ref:`introduction/issue-tracking:the issue tracker is not a discussion forum`). Every issue must be of a single type ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -206,7 +206,7 @@ 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>`__. +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 :ref:`collapsible section `. Use collapsible sections for long, nonessential content ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -249,7 +249,7 @@ Being closed as ``completed`` means that the issue has been fixed (in the case o 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>`__. +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 :ref:`introduction/issue-tracking:search tips`. Backports ^^^^^^^^^ diff --git a/introduction/privacy.rst b/introduction/privacy.rst index 66a3f241..0e3459b9 100644 --- a/introduction/privacy.rst +++ b/introduction/privacy.rst @@ -54,7 +54,7 @@ Mirrors ------- -There are also other third-party mirrors hosted by volunteers. These are used both for `ISO downloads `__ and `updates <#update-servers-and-repositories>`__. We have no control over what data these mirrors collect or with whom they share it. Please see the privacy policy of each respective mirror operator. +There are also other third-party mirrors hosted by volunteers. These are used both for `ISO downloads `__ and :ref:`updates `. We have no control over what data these mirrors collect or with whom they share it. Please see the privacy policy of each respective mirror operator. Qubes OS -------- diff --git a/introduction/statistics.rst b/introduction/statistics.rst index 867ea855..bafbe11d 100644 --- a/introduction/statistics.rst +++ b/introduction/statistics.rst @@ -28,7 +28,7 @@ How is the userbase estimated? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We simply count the number of unique IPv4 addresses that connect to the Qubes update servers each month (except for Tor connections; see `below <#how-are-tor-users-counted>`__). (**Note:** Users who have manually configured their systems to bypass the metalink and connect directly to a mirror are not counted.) +We simply count the number of unique IPv4 addresses that connect to the Qubes update servers each month (except for Tor connections; see :ref:`introduction/statistics:how are tor users counted?`). (**Note:** Users who have manually configured their systems to bypass the metalink and connect directly to a mirror are not counted.) How are Tor users counted? ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/introduction/support.rst b/introduction/support.rst index 724edc24..1ebeefb8 100644 --- a/introduction/support.rst +++ b/introduction/support.rst @@ -3,7 +3,7 @@ Help, support, mailing lists, and forum ======================================= -The Qubes community is here to help! Since Qubes is a security-oriented operating system, we want to make sure you `stay safe <#staying-safe>`__ as you get the support you need, and we want to make sure our community remains a friendly and productive place by ensuring we all follow the :doc:`Code of Conduct ` and `discussion guidelines <#discussion-guidelines>`__. +The Qubes community is here to help! Since Qubes is a security-oriented operating system, we want to make sure you :ref:`stay safe ` as you get the support you need, and we want to make sure our community remains a friendly and productive place by ensuring we all follow the :doc:`/introduction/code-of-conduct` and :ref:`introduction/support:discussion guidelines`. How to get help and support --------------------------- @@ -17,7 +17,7 @@ I have a problem or a question. No worries! Here’s how we recommend proceeding: -1. Check the :doc:`documentation `. There may already be a page about it. Specifically, check out the :ref:`How-To Guides ` and :ref:`Troubleshooting ` sections. +1. Check the :doc:`documentation `. There may already be a page about it. Specifically, check out the :ref:`how-to-guides` and :ref:`troubleshooting` sections. 2. Search the :doc:`FAQ `. Your question might already be answered. @@ -33,37 +33,37 @@ I didn't find a solution or an answer! ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sorry to hear that! In that case, we recommend asking for help on the `Qubes Forum `__ or on the `qubes-users mailing list <#qubes-users>`__. Choose the venue you prefer, but please don’t ask on both at the same time! Before you ask, please review our `discussion guidelines <#discussion-guidelines>`__ and StackOverflow’s advice on `how to ask good questions `__. Don’t forget to `stay safe <#staying-safe>`__! +Sorry to hear that! In that case, we recommend asking for help on the `Qubes Forum `__ or on the :ref:`qubes-users mailing list `. Choose the venue you prefer, but please don’t ask on both at the same time! Before you ask, please review our :ref:`introduction/support:discussion guidelines` and StackOverflow’s advice on `how to ask good questions `__. Don’t forget to :ref:`stay safe `! I don't need support, but I think I found a bug. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We’d be grateful if you reported it (but please make sure no one else has already reported it first)! Please see :doc:`Issue Tracking ` for details. +We’d be grateful if you reported it (but please make sure no one else has already reported it first)! Please see :doc:`/introduction/issue-tracking` for details. I don't need support, but I'd like to request a feature. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -No promises, but we’d be happy to consider it! Please see :doc:`Issue Tracking ` for details. +No promises, but we’d be happy to consider it! Please see :doc:`/introduction/issue-tracking` for details. Where's the best place to discuss Qubes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -That would be the `Qubes Forum `__ and the `qubes-users mailing list <#qubes-users>`__. Please have a look at our `discussion guidelines <#discussion-guidelines>`__ before diving in. Enjoy! +That would be the `Qubes Forum `__ and the :ref:`qubes-users mailing list `. Please have a look at our :ref:`introduction/support:discussion guidelines` before diving in. Enjoy! How can I get involved and contribute? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Thank you for asking! Please see :doc:`How to Contribute ` for all the ways you can do so. +Thank you for asking! Please see :doc:`/introduction/contributing` for all the ways you can do so. I would like to report a security vulnerability. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -That sounds more like you helping us! Thanks! Please see :ref:`Reporting Security Issues in Qubes OS `. +That sounds more like you helping us! Thanks! Please see :ref:`project-security/security:reporting security issues in qubes os`. Staying safe ------------ @@ -83,7 +83,7 @@ Discussion guidelines --------------------- -Qubes discussions mainly take place on ``qubes-users``, ``qubes-devel``, and our `forum <#forum>`__, all of which are explained below. Most questions should be directed to ``qubes-users`` or the `forum <#forum>`__. **Please do not send questions to individual Qubes developers.** By sending a message to the appropriate mailing list, you are not only giving others a chance to help you, but you may also be helping others by starting a public discussion about a shared problem or interest. +Qubes discussions mainly take place on ``qubes-users``, ``qubes-devel``, and our :ref:`introduction/support:forum`, all of which are explained below. Most questions should be directed to ``qubes-users`` or the :ref:`introduction/support:forum`. **Please do not send questions to individual Qubes developers.** By sending a message to the appropriate mailing list, you are not only giving others a chance to help you, but you may also be helping others by starting a public discussion about a shared problem or interest. These are open venues where people freely come together to discuss Qubes and voluntarily help each other out of mutual interest and good will. They are *not* your personal, paid support service. **No one owes you a reply.** No one here is responsible for solving your problems for you. Nonetheless, there are many things you can do to make it more likely that you will receive a reply. This community is fortunate to have an exceptionally large number of friendly and knowledgeable people who enjoy corresponding on these lists. The vast majority of them will be happy to help you if you follow these simple guidelines. @@ -103,7 +103,7 @@ Help us help you ^^^^^^^^^^^^^^^^ -Tell us what you’ve already tried, and which documentation pages you’ve already read. Put yourself in your readers’ shoes. What essential information would they require in order to be able to help you? Make sure to include that information in your message. A great way to provide your hardware details is by :ref:`generating and submitting a Hardware Compatibility List (HCL) report `, then linking to it in your message. `Ask questions the smart way. `__ +Tell us what you’ve already tried, and which documentation pages you’ve already read. Put yourself in your readers’ shoes. What essential information would they require in order to be able to help you? Make sure to include that information in your message. A great way to provide your hardware details is by :ref:`user/hardware/how-to-use-the-hcl:generating and submitting new reports`, then linking to it in your message. `Ask questions the smart way. `__ Be patient ^^^^^^^^^^ @@ -121,7 +121,7 @@ Report issues and submit changes in the right places ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker ` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum `.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, :doc:`submit the change `. +The mailing lists and :ref:`introduction/support:forum` are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker ` so that it doesn’t get overlooked. (However, please remember that :ref:`introduction/issue-tracking:the issue tracker is not a discussion forum`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, :doc:`submit the change `. Moderation ^^^^^^^^^^ @@ -185,7 +185,7 @@ Google Groups ^^^^^^^^^^^^^ -While the mailing lists are implemented as Google Group web forums, a Google account is in no way required, expected, or encouraged. Many discussants (including most members of the Qubes team) treat these lists as conventional `mailing lists `__, interacting with them solely through plain text email with `MUAs `__ like `Thunderbird `__ and `Mutt `__. The Google Groups service is just free infrastructure, and we :ref:`distrust the infrastructure `. This is why, for example, we encourage discussants to use :doc:`Split GPG ` to sign all of their messages to the lists, but we do not endorse the use of these Google Groups as web forums. For that, we have a separate, dedicated `forum <#forum>`__. +While the mailing lists are implemented as Google Group web forums, a Google account is in no way required, expected, or encouraged. Many discussants (including most members of the Qubes team) treat these lists as conventional `mailing lists `__, interacting with them solely through plain text email with `MUAs `__ like `Thunderbird `__ and `Mutt `__. The Google Groups service is just free infrastructure, and we :ref:`distrust the infrastructure `. This is why, for example, we encourage discussants to use :doc:`Split GPG ` to sign all of their messages to the lists, but we do not endorse the use of these Google Groups as web forums. For that, we have a separate, dedicated :ref:`introduction/support:forum`. Mailing lists ------------- @@ -337,7 +337,7 @@ The Qubes OS Project has a presence on the following social media platforms: -Generally speaking, these are not intended to be primary support venues. (Those would be `qubes-users <#qubes-users>`__ and the `forum <#forum>`__.) Rather, these are primarily intended to be a way to more widely disseminate items published on the `news `__ page. If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news. +Generally speaking, these are not intended to be primary support venues. (Those would be :ref:`introduction/support:qubes-users` and the :ref:`introduction/support:forum`.) Rather, these are primarily intended to be a way to more widely disseminate items published on the `news `__ page. If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news. Chat ---- diff --git a/project-security/security-pack.rst b/project-security/security-pack.rst index b187e90c..1b6b5587 100644 --- a/project-security/security-pack.rst +++ b/project-security/security-pack.rst @@ -42,7 +42,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and Checking connectivity... done. -2. Import the included PGP keys. See our `PGP key policies <#pgp-key-policies>`__ for important information about these keys. +2. Import the included PGP keys. See our :ref:`project-security/security-pack:pgp key policies` for important information about these keys. .. code:: console diff --git a/project-security/security.rst b/project-security/security.rst index da93b6ca..c746e903 100644 --- a/project-security/security.rst +++ b/project-security/security.rst @@ -51,7 +51,7 @@ Qubes security team The **Qubes security team (QST)** is the subset of the `core team `__ that is responsible for ensuring the security of Qubes OS and the Qubes OS Project. In particular, the QST is responsible for: -- Responding to `reported security issues <#reporting-security-issues-in-qubes-os>`__ +- Responding to :ref:`reported security issues ` - Evaluating whether `XSAs `__ affect the security of Qubes OS diff --git a/project-security/verifying-signatures.rst b/project-security/verifying-signatures.rst index b03ec0b5..3d266e5c 100644 --- a/project-security/verifying-signatures.rst +++ b/project-security/verifying-signatures.rst @@ -35,7 +35,7 @@ We use `PGP `__ (specifically **Windows:** `Gpg4win `__ (`documentation `__). Use the Windows command line (``cmd.exe``) to enter commands. -Throughout this page, we’ll use GnuPG via the ``gpg2`` command. If that doesn’t work for you, try ``gpg`` instead. If that still doesn’t work, please consult the documentation for your specific program (see links above) and the `troubleshooting FAQ <#troubleshooting-faq>`__ below. +Throughout this page, we’ll use GnuPG via the ``gpg2`` command. If that doesn’t work for you, try ``gpg`` instead. If that still doesn’t work, please consult the documentation for your specific program (see links above) and the :ref:`project-security/verifying-signatures:troubleshooting faq` below. How to import and authenticate the Qubes Master Signing Key ----------------------------------------------------------- @@ -45,7 +45,7 @@ Many important Qubes OS Project assets (e.g., ISOs, RPMs, TGZs, and Git objects) The developer signing keys are set to expire after one year, while the QMSK and RSKs have no expiration date. The QMSK was generated on and is kept only on a dedicated, air-gapped “vault” machine, and the private portion will (hopefully) never leave this isolated machine. -Before we proceed, you must first complete the prerequisite step of `installing OpenPGP software <#openpgp-software>`__. +Before we proceed, you must first complete the prerequisite step of :ref:`installing OpenPGP software `. Once you have appropriate OpenPGP software installed, there are several ways to get the QMSK. @@ -222,7 +222,7 @@ As a final sanity check, make sure the QMSK is in your keyring with the correct -If you don’t see the QMSK here with a trust level of “ultimate,” go back and follow the instructions in this section carefully and consult the `troubleshooting FAQ <#troubleshooting-faq>`__ below. +If you don’t see the QMSK here with a trust level of “ultimate,” go back and follow the instructions in this section carefully and consult the :ref:`project-security/verifying-signatures:troubleshooting faq` below. How to import and authenticate release signing keys --------------------------------------------------- @@ -232,9 +232,9 @@ Every Qubes OS release is signed by a **release signing key (RSK)**, which is, i Before we proceed, you must first complete the following prerequisite steps: -1. `Install OpenPGP software. <#openpgp-software>`__ +1. :ref:`Install OpenPGP software. ` -2. `Import and authenticate the QMSK. <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ +2. :ref:`Import and authenticate the QMSK. ` @@ -289,7 +289,7 @@ As a final sanity check, make sure the RSK is in your keyring with the correct t uid [ full ] Qubes OS Release X Signing Key -If you don’t see the correct RSK here with a trust level of “full” or higher, go back and follow the instructions in this section carefully, and consult the `troubleshooting FAQ <#troubleshooting-faq>`__ below. +If you don’t see the correct RSK here with a trust level of “full” or higher, go back and follow the instructions in this section carefully, and consult the :ref:`project-security/verifying-signatures:troubleshooting faq` below. How to obtain and authenticate other signing keys ------------------------------------------------- @@ -301,15 +301,15 @@ How to verify the cryptographic hash values of Qubes ISOs --------------------------------------------------------- -There are two ways to verify Qubes ISOs: cryptographic hash values and detached PGP signatures. Both methods are equally secure. Using just one method is sufficient to verify your Qubes ISO. Using both methods is not necessary, but you can do so if you like. One method might be more convenient than another in certain circumstances, so we provide both. This section covers cryptographic hash values. For the other method, see `how to verify detached PGP signatures on Qubes ISOs <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__. +There are two ways to verify Qubes ISOs: cryptographic hash values and detached PGP signatures. Both methods are equally secure. Using just one method is sufficient to verify your Qubes ISO. Using both methods is not necessary, but you can do so if you like. One method might be more convenient than another in certain circumstances, so we provide both. This section covers cryptographic hash values. For the other method, see :ref:`project-security/verifying-signatures:how to verify detached pgp signatures on qubes isos`. Before we proceed, you must first complete the following prerequisite steps: -1. `Install OpenPGP software. <#openpgp-software>`__ +1. :ref:`Install OpenPGP software. ` -2. `Import and authenticate the Qubes Master Signing Key. <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ +2. :ref:`Import and authenticate the Qubes Master Signing Key. ` -3. `Import and authenticate your release signing key. <#how-to-import-and-authenticate-release-signing-keys>`__ +3. :ref:`Import and authenticate your release signing key. ` @@ -401,21 +401,21 @@ However, it is possible that an attacker replaced ``Qubes-RX-x86_64.iso`` with a This is just an example, so the output you receive will not look exactly the same. What matters is the line that says ``Good signature from "Qubes OS Release X Signing Key"``. This confirms that the signature on the digest file is good. -If you don’t see a good signature here, go back and follow the instructions in this section carefully, and consult the `troubleshooting FAQ <#troubleshooting-faq>`__ below. +If you don’t see a good signature here, go back and follow the instructions in this section carefully, and consult the :ref:`project-security/verifying-signatures:troubleshooting faq` below. How to verify detached PGP signatures on Qubes ISOs --------------------------------------------------- -There are two ways to verify Qubes ISOs: cryptographic hash values and detached PGP signatures. Both methods are equally secure. Using just one method is sufficient to verify your Qubes ISO. Using both methods is not necessary, but you can do so if you like. One method might be more convenient than another in certain circumstances, so we provide both. This section covers detached PGP signatures. For the other method, see `how to verify the cryptographic hash values of Qubes ISOs <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__. +There are two ways to verify Qubes ISOs: cryptographic hash values and detached PGP signatures. Both methods are equally secure. Using just one method is sufficient to verify your Qubes ISO. Using both methods is not necessary, but you can do so if you like. One method might be more convenient than another in certain circumstances, so we provide both. This section covers detached PGP signatures. For the other method, see :ref:`project-security/verifying-signatures:how to verify the cryptographic hash values of qubes isos`. Before we proceed, you must first complete the following prerequisite steps: -1. `Install OpenPGP software. <#openpgp-software>`__ +1. :ref:`Install OpenPGP software. ` -2. `Import and authenticate the Qubes Master Signing Key. <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ +2. :ref:`Import and authenticate the Qubes Master Signing Key. ` -3. `Import and authenticate your release signing key. <#how-to-import-and-authenticate-release-signing-keys>`__ +3. :ref:`Import and authenticate your release signing key. ` @@ -435,7 +435,7 @@ Download both the ISO and its signature file. Put both of them in the same direc This is just an example, so the output you receive will not look exactly the same. What matters is the line that says ``Good signature from "Qubes OS Release X Signing Key"``. This confirms that the signature on the ISO is good. -If you don’t see a good signature here, go back and follow the instructions in this section carefully, and consult the `troubleshooting FAQ <#troubleshooting-faq>`__ below. +If you don’t see a good signature here, go back and follow the instructions in this section carefully, and consult the :ref:`project-security/verifying-signatures:troubleshooting faq` below. How to re-verify installation media after writing ------------------------------------------------- @@ -447,7 +447,7 @@ After you have authenticated your Qubes ISO and written it onto your desired med This section will walk through an example of re-verifying the installer on such a device. We begin by assuming that you have just :ref:`written your desired Qubes ISO onto the USB drive `. First, unplug your USB drive and flip the write protect switch so that the data on the drive can no longer be altered. If you have a different computer from the one you used to create the installation medium, consider using that computer. If not, try to at least use a fresh VM (e.g., if it’s a Qubes system). The idea is that the original machine may have been compromised, and using a different one for re-verification forces your hypothetical adversary to compromise an additional machine in order to succeed. -Now, our goal is to perform the same verification steps as we did with the original ISO, except, this time, we’ll be reading the installer data directly from the write-protected USB drive instead of from the original ISO file. First, let’s compute the SHA-256 hash value of the data on the drive. (This assumes you’re already familiar with `how to verify the cryptographic hash values of Qubes ISOs <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__.) In order to do this, we have to know the exact size, in bytes, of the original ISO. There are two ways to get this information: from the ISO itself and from the Qubes website. Here’s an example of the first way: +Now, our goal is to perform the same verification steps as we did with the original ISO, except, this time, we’ll be reading the installer data directly from the write-protected USB drive instead of from the original ISO file. First, let’s compute the SHA-256 hash value of the data on the drive. (This assumes you’re already familiar with :ref:`project-security/verifying-signatures:how to verify the cryptographic hash values of qubes isos`.) In order to do this, we have to know the exact size, in bytes, of the original ISO. There are two ways to get this information: from the ISO itself and from the Qubes website. Here’s an example of the first way: .. code:: console @@ -479,7 +479,7 @@ Therefore, in order to make things a bit more difficult for your hypothetical ad If you wish to compute the values of other hash functions, you can replace ``sha256sum``, e.g., with ``md5sum``, ``sha1sum``, or ``sha512sum``. -In addition to checking hash values, you can also use GnuPG to verify the detached PGP signature directly against the data on the USB drive. (This assumes you’re already familiar with `how to verify detached PGP signatures on Qubes ISOs <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__.) +In addition to checking hash values, you can also use GnuPG to verify the detached PGP signature directly against the data on the USB drive. (This assumes you’re already familiar with :ref:`project-security/verifying-signatures:how to verify detached pgp signatures on qubes isos`.) .. code:: console @@ -496,7 +496,7 @@ In addition to checking hash values, you can also use GnuPG to verify the detach (Where ``/dev/sdX`` is your USB drive, ```` is the size of the original ISO in bytes, and ``Qubes-RX-x86_64.iso.asc`` is the detached signature file of the original ISO.) -This command reads the exact number of bytes from your USB drive as the size of the original ISO and pipes them into ``gpg``. The usual form of a ``gpg`` verification command is ``gpg --verify ``. Our command is using shell redirection in order to use data from your USB drive as the ````, which is why the ``-`` at the end of the command is required. Remember that you still must have properly imported and trusted the `QMSK <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ and appropriate `RSK <#how-to-import-and-authenticate-release-signing-keys>`__ in order for this to work. You should receive a ``Good signature`` message for the appropriate RSK, which should be signed by a copy of the QMSK that you previously confirmed to be genuine. +This command reads the exact number of bytes from your USB drive as the size of the original ISO and pipes them into ``gpg``. The usual form of a ``gpg`` verification command is ``gpg --verify ``. Our command is using shell redirection in order to use data from your USB drive as the ````, which is why the ``-`` at the end of the command is required. Remember that you still must have properly imported and trusted the :ref:`QMSK ` and appropriate :ref:`RSK ` in order for this to work. You should receive a ``Good signature`` message for the appropriate RSK, which should be signed by a copy of the QMSK that you previously confirmed to be genuine. How to verify signatures on Git repository tags and commits ----------------------------------------------------------- @@ -504,9 +504,9 @@ How to verify signatures on Git repository tags and commits Before we proceed, you must first complete the following prerequisite steps: -1. `Install OpenPGP software. <#openpgp-software>`__ +1. :ref:`Install OpenPGP software. ` -2. `Import and authenticate the Qubes Master Signing Key. <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ +2. :ref:`Import and authenticate the Qubes Master Signing Key. ` 3. :doc:`Import and authenticate keys from the Qubes security pack (qubes-secpack). ` Please see our :ref:`PGP key policies ` for important information about these keys. @@ -556,7 +556,7 @@ Why am I getting "Can't check signature: public key not found"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You don’t have the correct `release signing key <#how-to-import-and-authenticate-release-signing-keys>`__. +You don’t have the correct :ref:`release signing key `. Why am I getting "BAD signature from ‘Qubes OS Release X Signing Key'"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -568,7 +568,7 @@ The problem could be one or more of the following: - You’re using the wrong GPG command. Follow the provided examples carefully, or try using ``gpg`` instead of ``gpg2`` (or vice versa). -- The ISO or `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__ is bad (e.g., incomplete or corrupt download). Try downloading the signature file again from a different source, then try verifying again. If you still get the same result, try downloading the ISO again from a different source, then try verifying again. +- The ISO or :ref:`detached PGP signature file ` is bad (e.g., incomplete or corrupt download). Try downloading the signature file again from a different source, then try verifying again. If you still get the same result, try downloading the ISO again from a different source, then try verifying again. @@ -594,13 +594,13 @@ Why am I getting "can't open ‘Qubes-RX-x86_64.iso.asc' / verify signatures fai ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The correct `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__ is not in your working directory. +The correct :ref:`detached PGP signature file ` is not in your working directory. Why am I getting "no valid OpenPGP data found"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Either you don’t have the correct `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__, or you inverted the arguments to ``gpg2``. (The signature file goes first.) +Either you don’t have the correct :ref:`detached PGP signature file `, or you inverted the arguments to ``gpg2``. (The signature file goes first.) Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -608,11 +608,11 @@ Why am I getting "WARNING: This key is not certified with a trusted signature! T There are several possibilities: -- You don’t have the `Qubes Master Signing Key <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__. +- You don’t have the :ref:`Qubes Master Signing Key `. -- You have not `set the Qubes Master Signing Key’s trust level correctly. <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ +- You have not :ref:`set the Qubes Master Signing Key’s trust level correctly. ` -- In the case of a key that is not directly signed by the Qubes Master Signing Key, you have not `set that key’s trust level correctly. <#how-to-verify-signatures-on-git-repository-tags-and-commits>`__ +- In the case of a key that is not directly signed by the Qubes Master Signing Key, you have not :ref:`set that key’s trust level correctly. ` @@ -620,7 +620,7 @@ Why am I getting "X signature not checked due to a missing key"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You don’t have the keys that created those signatures in your keyring. For the purpose of verifying a Qubes ISO, you don’t need them as long as you have the `Qubes Master Signing Key <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__ and the `release signing key <#how-to-import-and-authenticate-release-signing-keys>`__ for your Qubes release. +You don’t have the keys that created those signatures in your keyring. For the purpose of verifying a Qubes ISO, you don’t need them as long as you have the :ref:`Qubes Master Signing Key ` and the :ref:`release signing key ` for your Qubes release. Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -632,21 +632,21 @@ Why am I getting "verify signatures failed: unexpected data"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You’re not verifying against the correct `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__. +You’re not verifying against the correct :ref:`detached PGP signature file `. Why am I getting "not a detached signature"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You’re not verifying against the correct `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__. +You’re not verifying against the correct :ref:`detached PGP signature file `. Why am I getting "CRC error; […] no signature found […]"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You’re not verifying against the correct `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__, or the signature file has been modified. Try downloading it again or from a different source. +You’re not verifying against the correct :ref:`detached PGP signature file `, or the signature file has been modified. Try downloading it again or from a different source. -Do I have to verify both the `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__ and the `cryptographic hash values <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__? +Do I have to verify both the :ref:`detached PGP signature file ` and the :ref:`cryptographic hash values `? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -656,13 +656,13 @@ Why am I getting "no properly formatted X checksum lines found"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You’re not checking the correct `cryptographic hash values <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__. +You’re not checking the correct :ref:`cryptographic hash values `. Why am I getting "WARNING: X lines are improperly formatted"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Read `how to verify the cryptographic hash values of Qubes ISOs <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__ again. +Read :ref:`project-security/verifying-signatures:how to verify the cryptographic hash values of qubes isos` again. Why am I getting "WARNING: 1 listed file could not be read"? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -674,4 +674,4 @@ I have another problem that isn't mentioned here. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Carefully reread this page to be certain that you didn’t skip any steps. In particular, make sure you have the `Qubes Master Signing Key <#how-to-import-and-authenticate-the-qubes-master-signing-key>`__, the `release signing key <#how-to-import-and-authenticate-release-signing-keys>`__ for your Qubes release, *and* the `cryptographic hash values <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__ and/or `detached PGP signature file <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__, all for the *correct* Qubes OS release. If your question is about GPG, please see the `GnuPG documentation `__. Still have question? Please see :doc:`help, support, mailing lists, and forum ` for places where you can ask! +Carefully reread this page to be certain that you didn’t skip any steps. In particular, make sure you have the :ref:`Qubes Master Signing Key `, the :ref:`release signing key ` for your Qubes release, *and* the :ref:`cryptographic hash values ` and/or :ref:`detached PGP signature file `, all for the *correct* Qubes OS release. If your question is about GPG, please see the `GnuPG documentation `__. Still have question? Please see :doc:`help, support, mailing lists, and forum ` for places where you can ask! diff --git a/user/advanced-topics/i3.rst b/user/advanced-topics/i3.rst index 010dd203..b64d44fb 100644 --- a/user/advanced-topics/i3.rst +++ b/user/advanced-topics/i3.rst @@ -13,7 +13,7 @@ i3 is part of the stable repository (as of Qubes R3.1) and can be installed by u $ sudo qubes-dom0-update i3 i3-settings-qubes -The Qubes-specific configuration (package ``i3-settings-qubes``) can be installed optionally in case you would prefer writing your own configuration (see `customization <#customization>`__ section for scripts and configuration). +The Qubes-specific configuration (package ``i3-settings-qubes``) can be installed optionally in case you would prefer writing your own configuration (see :ref:`user/advanced-topics/i3:customization` section for scripts and configuration). That’s it. After logging out, you can select i3 in the login manager. diff --git a/user/advanced-topics/usb-qubes.rst b/user/advanced-topics/usb-qubes.rst index be975abe..6915677a 100644 --- a/user/advanced-topics/usb-qubes.rst +++ b/user/advanced-topics/usb-qubes.rst @@ -24,7 +24,7 @@ How to create a USB qube for use with a USB keyboard ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you’re reading this section, it’s likely because the installer did not allow you to create a USB qube automatically because you’re using a USB keyboard. This section will explain how to create a USB qube that you can use with your USB keyboard. This section assumes that you have only a single USB controller. If you have more than one USB controller, see `how to enable a USB keyboard on a separate USB controller <#qubes-4-1-how-to-enable-a-usb-keyboard-on-a-separate-usb-controller>`__. +If you’re reading this section, it’s likely because the installer did not allow you to create a USB qube automatically because you’re using a USB keyboard. This section will explain how to create a USB qube that you can use with your USB keyboard. This section assumes that you have only a single USB controller. If you have more than one USB controller, see :ref:`how to enable a USB keyboard on a separate USB controller `. First, make sure you have the latest ``qubes-mgmt-salt-dom0-virtual-machines`` package by :ref:`updating dom0 `. Then, enter the following command in dom0: @@ -36,7 +36,7 @@ First, make sure you have the latest ``qubes-mgmt-salt-dom0-virtual-machines`` p This command will take care of all required configuration, including creating a USB qube if not already present. Note, however, that this setup will expose dom0 to USB devices while you are entering your LUKS passphrase. While only input devices (keyboards, mice, etc.) are initialized at this stage, users are advised to physically disconnect other devices from the system during this vulnerable window in order to minimize the risk. -To undo these changes, see `how to remove a USB qube <#how-to-remove-a-usb-qube>`__. +To undo these changes, see :ref:`user/advanced-topics/usb-qubes:how to remove a usb qube`. If you wish to perform only a subset of this configuration (for example, you do not wish to enable the USB keyboard during boot), see the manual instructions below. @@ -72,7 +72,7 @@ You can set up your system so that there’s a confirmation prompt each time the -If you wish to use a USB keyboard to enter your LUKS passphrase, you cannot `hide its USB controller from dom0 <#how-to-hide-usb-controllers-from-dom0>`__. If you’ve already hidden that USB controller from dom0, you must revert the procedure by removing the ``rd.qubes.hide_all_usb`` option and employ an alternative strategy for protecting your system by physically disconnecting other devices during startup. +If you wish to use a USB keyboard to enter your LUKS passphrase, you cannot :ref:`hide its USB controller from dom0 `. If you’ve already hidden that USB controller from dom0, you must revert the procedure by removing the ``rd.qubes.hide_all_usb`` option and employ an alternative strategy for protecting your system by physically disconnecting other devices during startup. **Qubes 4.1 only:** You should also add the ``usbcore.authorized_default=0`` option, which prevents the initialization of non-input devices. (Qubes ships with a USBGuard configuration that allows only input devices when ``usbcore.authorized_default=0`` is set.) @@ -96,7 +96,7 @@ When using a USB keyboard on a system with multiple USB controllers, we recommen 7. Reboot. -8. Proceed with `creating a USB qube <#how-to-create-a-usb-qube>`__ normally. The selected USB controller will remain in dom0. +8. Proceed with :ref:`creating a USB qube ` normally. The selected USB controller will remain in dom0. @@ -142,7 +142,7 @@ How to create a USB qube ------------------------ -If `automatically creating a USB qube for use with a USB keyboard <#how-to-create-a-usb-qube-for-use-with-a-usb-keyboard>`__ does not apply to your situation, then you may be interested in more general methods for creating USB qubes. +If :ref:`automatically creating a USB qube for use with a USB keyboard ` does not apply to your situation, then you may be interested in more general methods for creating USB qubes. You can create a USB qube using the management stack by executing the following command as root in dom0: @@ -176,7 +176,7 @@ How to hide USB controllers from dom0 ------------------------------------- -USB controllers are automatically hidden from dom0 if you opt to create a USB qube during installation. This also occurs automatically if you choose to `create a USB qube <#how-to-create-a-usb-qube>`__ using the ``qubesctl`` method. However, if you create a USB qube manually and do not hide USB controllers from dom0, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices). This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised. There are two approaches to this problem: +USB controllers are automatically hidden from dom0 if you opt to create a USB qube during installation. This also occurs automatically if you choose to :ref:`create a USB qube ` using the ``qubesctl`` method. However, if you create a USB qube manually and do not hide USB controllers from dom0, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices). This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised. There are two approaches to this problem: 1. Physically disconnect all USB devices whenever you reboot the host. @@ -184,7 +184,7 @@ USB controllers are automatically hidden from dom0 if you opt to create a USB qu -**Warning:** If you use a USB keyboard, hiding your USB controllers from dom0 could lock you out of your system. See `USB keyboards <#usb-keyboards>`__ for more information. +**Warning:** If you use a USB keyboard, hiding your USB controllers from dom0 could lock you out of your system. See :ref:`user/advanced-topics/usb-qubes:usb keyboards` for more information. **Warning:** Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM will hang. diff --git a/user/downloading-installing-upgrading/installation-guide-4.1.rst b/user/downloading-installing-upgrading/installation-guide-4.1.rst index 75584ac5..7eb2855f 100644 --- a/user/downloading-installing-upgrading/installation-guide-4.1.rst +++ b/user/downloading-installing-upgrading/installation-guide-4.1.rst @@ -137,7 +137,7 @@ Prior to the next screen, a compatibility test runs to check whether IOMMU-virtu |Unsupported hardware detected| -Do not panic. It may simply indicate that IOMMU-virtualization hasn’t been activated in the BIOS or UEFI. Return to the `hardware requirements <#hardware-requirements>`__ section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware. +Do not panic. It may simply indicate that IOMMU-virtualization hasn’t been activated in the BIOS or UEFI. Return to the :ref:`user/downloading-installing-upgrading/installation-guide-4.1:hardware requirements` section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware. If the test passes, you will reach the installation summary screen. The installer loads Xen right at the beginning. If you can see the installer’s graphical screen, and you pass the compatibility check that runs immediately afterward, Qubes OS is likely to work on your system! @@ -317,7 +317,7 @@ Security ^^^^^^^^ -The Qubes OS Project occasionally issues `Qubes Security Bulletins (QSBs) `__ as part of the :doc:`Qubes Security Pack (qubes-secpack) `. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While `updating <#updating>`__ will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce ` mailing list. +The Qubes OS Project occasionally issues `Qubes Security Bulletins (QSBs) `__ as part of the :doc:`Qubes Security Pack (qubes-secpack) `. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While :ref:`user/downloading-installing-upgrading/installation-guide-4.1:updating` will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce ` mailing list. In addition to QSBs, the Qubes OS Project also publishes `Canaries `__, XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to :ref:`qubes-announce ` in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the `Qubes News RSS feed `__ or join one of our other :doc:`venues `, where these news items are also announced. diff --git a/user/downloading-installing-upgrading/installation-guide.rst b/user/downloading-installing-upgrading/installation-guide.rst index 4fff1620..e453c704 100644 --- a/user/downloading-installing-upgrading/installation-guide.rst +++ b/user/downloading-installing-upgrading/installation-guide.rst @@ -141,7 +141,7 @@ Prior to the next screen, a compatibility test runs to check whether IOMMU-virtu |Unsupported hardware detected| -Do not panic. It may simply indicate that IOMMU-virtualization hasn’t been activated in the BIOS or UEFI. Return to the `hardware requirements <#hardware-requirements>`__ section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware. +Do not panic. It may simply indicate that IOMMU-virtualization hasn’t been activated in the BIOS or UEFI. Return to the :ref:`user/downloading-installing-upgrading/installation-guide:hardware requirements` section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware. If the test passes, you will reach the installation summary screen. The installer loads Xen right at the beginning. If you can see the installer’s graphical screen, and you pass the compatibility check that runs immediately afterward, Qubes OS is likely to work on your system! @@ -305,7 +305,7 @@ Security ^^^^^^^^ -The Qubes OS Project occasionally issues `Qubes Security Bulletins (QSBs) `__ as part of the :doc:`Qubes Security Pack (qubes-secpack) `. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While `updating <#updating>`__ will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce ` mailing list. +The Qubes OS Project occasionally issues `Qubes Security Bulletins (QSBs) `__ as part of the :doc:`Qubes Security Pack (qubes-secpack) `. It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While :ref:`user/downloading-installing-upgrading/installation-guide:updating` will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the :ref:`qubes-announce ` mailing list. In addition to QSBs, the Qubes OS Project also publishes `Canaries `__, XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to :ref:`qubes-announce ` in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the `Qubes News RSS feed `__ or join one of our other :doc:`venues `, where these news items are also announced. diff --git a/user/downloading-installing-upgrading/testing.rst b/user/downloading-installing-upgrading/testing.rst index 61246536..6be34cd1 100644 --- a/user/downloading-installing-upgrading/testing.rst +++ b/user/downloading-installing-upgrading/testing.rst @@ -42,7 +42,7 @@ How to test updates: -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 :ref:`user/downloading-installing-upgrading/testing: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. diff --git a/user/downloading-installing-upgrading/upgrade/4_1.rst b/user/downloading-installing-upgrading/upgrade/4_1.rst index 4b5932eb..7f0ec238 100644 --- a/user/downloading-installing-upgrading/upgrade/4_1.rst +++ b/user/downloading-installing-upgrading/upgrade/4_1.rst @@ -31,7 +31,7 @@ In-place upgrade ---------------- -**Warning:** It is not possible to upgrade directly from releases earlier than 4.0. If you’re still on an earlier release, please either perform a `clean installation of 4.1 <#clean-installation>`__ or :doc:`upgrade to 4.0 ` first. +**Warning:** It is not possible to upgrade directly from releases earlier than 4.0. If you’re still on an earlier release, please either perform a :ref:`clean installation of 4.1 ` or :doc:`upgrade to 4.0 ` first. The upgrade may take several hours, and will download several gigabytes of data. diff --git a/user/downloading-installing-upgrading/upgrade/4_2.rst b/user/downloading-installing-upgrading/upgrade/4_2.rst index 6e580b3b..a579f810 100644 --- a/user/downloading-installing-upgrading/upgrade/4_2.rst +++ b/user/downloading-installing-upgrading/upgrade/4_2.rst @@ -50,7 +50,7 @@ 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 :doc:`upgrade to 4.1 ` first. +**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 :ref:`clean installation of 4.2 ` or :doc:`upgrade to 4.1 ` first. The upgrade may take several hours, and will download several gigabytes of data. diff --git a/user/downloading-installing-upgrading/upgrade/4_3.rst b/user/downloading-installing-upgrading/upgrade/4_3.rst index 2a5f904f..7d9b57fb 100644 --- a/user/downloading-installing-upgrading/upgrade/4_3.rst +++ b/user/downloading-installing-upgrading/upgrade/4_3.rst @@ -48,7 +48,7 @@ In-place upgrade ---------------- -**Warning:** It is not possible to upgrade directly from releases earlier than 4.2. If you’re still on an earlier release, please either perform a `clean installation of 4.3 <#clean-installation>`__ or :doc:`upgrade to 4.2 ` first. +**Warning:** It is not possible to upgrade directly from releases earlier than 4.2. If you’re still on an earlier release, please either perform a :ref:`clean installation of 4.3 ` or :doc:`upgrade to 4.2 ` first. The upgrade may take several hours, and will download several gigabytes of data. diff --git a/user/hardware/system-requirements.rst b/user/hardware/system-requirements.rst index 92d2c2e0..ac5ac3d7 100644 --- a/user/hardware/system-requirements.rst +++ b/user/hardware/system-requirements.rst @@ -5,7 +5,7 @@ System requirements .. warning:: - Notice: The system requirements on this page are *necessary, but not sufficient*, for Qubes compatibility at a minimal or recommended level. In other words, just because a computer satisfies these requirements doesn’t mean that Qubes will successfully install and run on it. We strongly recommend consulting the `resources below <#choosing-hardware>`__ when selecting hardware for Qubes. + Notice: The system requirements on this page are *necessary, but not sufficient*, for Qubes compatibility at a minimal or recommended level. In other words, just because a computer satisfies these requirements doesn’t mean that Qubes will successfully install and run on it. We strongly recommend consulting :ref:`user/hardware/system-requirements:choosing hardware` when selecting hardware for Qubes. Minimum ------- @@ -35,9 +35,9 @@ Recommended - `Intel VT-d `__ - - For security, we recommend processors that are recent enough to still be receiving microcode updates (see `below <#important-notes>`__ for details). + - For security, we recommend processors that are recent enough to still be receiving microcode updates (see :ref:`user/hardware/system-requirements:important notes` for details). - - AMD processors are not recommended due to inconsistent security support on client platforms (see `below <#important-notes>`__ for details). + - AMD processors are not recommended due to inconsistent security support on client platforms (see :ref:`user/hardware/system-requirements:important notes` for details). diff --git a/user/how-to-guides/how-to-back-up-restore-and-migrate.rst b/user/how-to-guides/how-to-back-up-restore-and-migrate.rst index 957445a4..2fed9d0c 100644 --- a/user/how-to-guides/how-to-back-up-restore-and-migrate.rst +++ b/user/how-to-guides/how-to-back-up-restore-and-migrate.rst @@ -60,7 +60,7 @@ Creating a backup 5. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. -6. Test restore your backup. Follow the `restore procedure <#restoring-from-a-backup>`__, selecting **Verify backup integrity, do not restore the data**. This step is optional but strongly recommended. A backup is useless if you can’t restore your data from it, and you can’t be sure that your backup is good until you try to restore. +6. Test restore your backup. Follow the :ref:`restore procedure `, selecting **Verify backup integrity, do not restore the data**. This step is optional but strongly recommended. A backup is useless if you can’t restore your data from it, and you can’t be sure that your backup is good until you try to restore. diff --git a/user/how-to-guides/how-to-copy-from-dom0.rst b/user/how-to-guides/how-to-copy-from-dom0.rst index 07726c82..02e91c92 100644 --- a/user/how-to-guides/how-to-copy-from-dom0.rst +++ b/user/how-to-guides/how-to-copy-from-dom0.rst @@ -41,7 +41,7 @@ Use the **Qubes Clipboard** widget: -Alternatively, you can put your text in a file, then `copy it as a file <#copying-files-from-dom0>`__. Or, you can write the data you wish to copy into ``/var/run/qubes/qubes-clipboard.bin``, then ``echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source``. Then use Ctrl+Shift+V to paste the data to the target qube. +Alternatively, you can put your text in a file, then :ref:`copy it as a file `. Or, you can write the data you wish to copy into ``/var/run/qubes/qubes-clipboard.bin``, then ``echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source``. Then use Ctrl+Shift+V to paste the data to the target qube. Copying logs from dom0 ^^^^^^^^^^^^^^^^^^^^^^ @@ -65,7 +65,7 @@ Copying *to* dom0 ----------------- -Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system. For this reason, there is no simple means of copying anything into dom0, unlike `copying from dom0 <#copying-from-dom0>`__. +Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system. For this reason, there is no simple means of copying anything into dom0, unlike :ref:`user/how-to-guides/how-to-copy-from-dom0:copying *from* dom0`. There should normally be few reasons for the user to want to copy anything from domUs to dom0, as dom0 only acts as a “thin trusted terminal”, and no user applications run there. Sometimes, new users feel the urge to copy a desktop wallpaper image into dom0, but that is not necessary. A safer approach is simply to display the image in :doc:`full-screen mode ` in an app qube, then take a screenshot from dom0, which results in exactly the image needed for a wallpaper, created securely and natively in dom0. diff --git a/user/how-to-guides/how-to-install-software.rst b/user/how-to-guides/how-to-install-software.rst index 4b0f3545..fa5d7696 100644 --- a/user/how-to-guides/how-to-install-software.rst +++ b/user/how-to-guides/how-to-install-software.rst @@ -56,7 +56,7 @@ If you are using another installation method fetching remote resources, you migh Using direct networking ^^^^^^^^^^^^^^^^^^^^^^^ -.. Warning:: This method gives your template direct network access, which is `risky <#why-dont-templates-have-normal-network-access>`__. This method is **not** recommended for trusted templates. Moreover, depending on how you install this software, it may not get updated automatically when you :doc:`update Qubes normally `, which means you may have to update it manually yourself. +.. Warning:: This method gives your template direct network access, which is :ref:`risky `. This method is **not** recommended for trusted templates. Moreover, depending on how you install this software, it may not get updated automatically when you :doc:`update Qubes normally `, which means you may have to update it manually yourself. This method assumes that you are trying to follow instructions to install some piece of software in a normal operating system, except *that* operating system is running as a template in Qubes OS. @@ -112,7 +112,7 @@ Please see :doc:`/user/how-to-guides/how-to-update`. Why don't templates have normal network access? ----------------------------------------------- -In order to protect you from performing risky activities in templates, they do not have normal network access by default. Instead, templates use an :ref:`updates-proxy` which allows you to install and update software using the distribution’s package manager over the proxy connection. **The updates proxy is already set up to work automatically out-of-the-box and requires no special action from you.** Most users should simply follow the normal instructions for :ref:`installing-software-from-default-repositories` and :doc:`updating ` software. If your software is not available in the default repositories, see `installing software from other sources <#installing-software-from-other-sources>`__. +In order to protect you from performing risky activities in templates, they do not have normal network access by default. Instead, templates use an :ref:`updates-proxy` which allows you to install and update software using the distribution’s package manager over the proxy connection. **The updates proxy is already set up to work automatically out-of-the-box and requires no special action from you.** Most users should simply follow the normal instructions for :ref:`installing-software-from-default-repositories` and :doc:`updating ` software. If your software is not available in the default repositories, see :ref:`user/how-to-guides/how-to-install-software:installing software from other sources`. Advanced -------- diff --git a/user/how-to-guides/how-to-update.rst b/user/how-to-guides/how-to-update.rst index bbc22324..a09a68f8 100644 --- a/user/how-to-guides/how-to-update.rst +++ b/user/how-to-guides/how-to-update.rst @@ -45,7 +45,7 @@ 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 :ref:`user/how-to-guides/how-to-update:command-line interface`.) |Qubes Update| diff --git a/user/how-to-guides/how-to-use-block-storage-devices.rst b/user/how-to-guides/how-to-use-block-storage-devices.rst index 064ba9d7..f0d2d823 100644 --- a/user/how-to-guides/how-to-use-block-storage-devices.rst +++ b/user/how-to-guides/how-to-use-block-storage-devices.rst @@ -41,7 +41,7 @@ Beware that when you attach a whole block device, partitions can be identified b If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after ``xvdi`` the next device will be named ``xvdj``, the next ``xvdk``, and so on. -To specify this device node name, you need to use the command line tool and its `frontend-dev-option <#frontend-dev>`__. +To specify this device node name, you need to use the command line tool and its :ref:`frontend-dev-option `. Command Line Tool Guide ----------------------- @@ -131,7 +131,7 @@ To recover from this error state, in dom0 run -(where ``targetVM`` is to be replaced with the VM name you attached the device to and ``xvdi`` is to be replaced with the used `frontend device node <#frontend-dev>`__.) +(where ``targetVM`` is to be replaced with the VM name you attached the device to and ``xvdi`` is to be replaced with the used :ref:`frontend device node `.) However, if the block device originated in dom0, you will have to refer to the next section. diff --git a/user/how-to-guides/how-to-use-usb-devices.rst b/user/how-to-guides/how-to-use-usb-devices.rst index a5a85ec0..326304d4 100644 --- a/user/how-to-guides/how-to-use-usb-devices.rst +++ b/user/how-to-guides/how-to-use-usb-devices.rst @@ -68,7 +68,7 @@ Attaching selected USB device: sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse -Now, you can use your USB device (camera in this case) in the ``work`` qube. If you see the error ``ERROR: qubes-usb-proxy not installed in the qube`` instead, please refer to the `Installation Section <#installation-of-qubes-usb-proxy>`__. +Now, you can use your USB device (camera in this case) in the ``work`` qube. If you see the error ``ERROR: qubes-usb-proxy not installed in the qube`` instead, please refer to the :ref:`Installation Section `. When you finish, detach the device. @@ -92,6 +92,8 @@ Creating and using a USB qube If you’ve selected to install a usb-qube during system installation, everything is already set up for you in ``sys-usb``. If you’ve later decided to create a usb-qube, please follow :doc:`this guide `. +.. _installation-of-qubes-usb-proxy: + Installation of ``qubes-usb-proxy`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/user/security-in-qubes/ctap-proxy.rst b/user/security-in-qubes/ctap-proxy.rst index 364ef34f..9311d0f3 100644 --- a/user/security-in-qubes/ctap-proxy.rst +++ b/user/security-in-qubes/ctap-proxy.rst @@ -41,7 +41,7 @@ The ``vault`` qube with a dashed line in the bottom portion of the diagram depic One very important assumption of protocol is that the browser verifies every request sent to the authenticator — in particular, that the web application sending an authentication request matches the application that would be authenticated by answering that request (in order to prevent, e.g., a phishing site from sending an authentication request for your bank’s site). With the WebUSB feature in Chrome, however, a malicious website can `bypass `__ this safeguard by connecting directly to the token instead of using the browser’s CTAP API. -The Qubes CTAP Proxy also prevents this class of attacks by implementing an additional verification layer. This verification layer allows you to enforce, for example, that the web browser in your ``twitter`` qube can only access the CTAP key associated with ``https://twitter.com``. This means that if anything in your ``twitter`` qube were compromised — the browser or even the OS itself — it would still not be able to access the CTAP keys on your token for any other websites or services, like your email and bank accounts. This is another significant security advantage over monolithic systems. (For details and instructions, see the `Advanced usage <#advanced-usage-per-qube-key-access>`__ section below.) +The Qubes CTAP Proxy also prevents this class of attacks by implementing an additional verification layer. This verification layer allows you to enforce, for example, that the web browser in your ``twitter`` qube can only access the CTAP key associated with ``https://twitter.com``. This means that if anything in your ``twitter`` qube were compromised — the browser or even the OS itself — it would still not be able to access the CTAP keys on your token for any other websites or services, like your email and bank accounts. This is another significant security advantage over monolithic systems. For details and instructions, see :ref:`per-qube-key-access`. For even more protection, you can combine this with the :doc:`Qubes firewall ` to ensure, for example, that the browser in your ``banking`` qube accesses only one website (your bank’s website). By configuring the Qubes firewall to prevent your ``banking`` qube from accessing any other websites, you reduce the risk of another website compromising the browser in an attempt to bypass CTAP authentication. @@ -78,7 +78,9 @@ In Debian templates: -As usual with software updates, shut down the templates after installation, then restart ``sys-usb`` and all qubes that use the proxy. After that, you may use your CTAP authenticator (but see `Browser support <#template-and-browser-support>`__ below). +As usual with software updates, shut down the templates after installation, then restart ``sys-usb`` and all qubes that use the proxy. After that, you may use your CTAP authenticator (but see :ref:`Browser support ` below). + +.. _per-qube-key-access: Advanced usage: per-qube key access ----------------------------------- diff --git a/user/security-in-qubes/firewall.rst b/user/security-in-qubes/firewall.rst index f5a8352f..f92ee42c 100644 --- a/user/security-in-qubes/firewall.rst +++ b/user/security-in-qubes/firewall.rst @@ -53,7 +53,7 @@ The firewall rules for each qube are saved in an XML file in that qube’s direc Rules are implemented on the netvm. -You can also manually create rules in the qube itself using standard firewalling controls. See `Where to put firewall rules <#where-to-put-firewall-rules>`__. In complex cases, it might be appropriate to load a ruleset using ``nft -f /path/to/ruleset`` called from ``/rw/config/rc.local``, the ruleset file can be populated from the current ruleset using ``nft list ruleset > /path/to/ruleset``, you should add ``flush ruleset`` at the top of the file to remove all existing rules before loading them. if you do this, be aware that ``rc.local`` is called *after* the network is up, so local rules should not be relied upon to block leaks. +You can also manually create rules in the qube itself using standard firewalling controls. See :ref:`user/security-in-qubes/firewall:where to put firewall rules`. In complex cases, it might be appropriate to load a ruleset using ``nft -f /path/to/ruleset`` called from ``/rw/config/rc.local``, the ruleset file can be populated from the current ruleset using ``nft list ruleset > /path/to/ruleset``, you should add ``flush ruleset`` at the top of the file to remove all existing rules before loading them. if you do this, be aware that ``rc.local`` is called *after* the network is up, so local rules should not be relied upon to block leaks. Reconnecting qubes after a NetVM reboot --------------------------------------- diff --git a/user/security-in-qubes/firewall_4.1.rst b/user/security-in-qubes/firewall_4.1.rst index 72283576..46970e8d 100644 --- a/user/security-in-qubes/firewall_4.1.rst +++ b/user/security-in-qubes/firewall_4.1.rst @@ -55,7 +55,7 @@ The firewall rules for each qube are saved in an XML file in that qube’s direc Rules are implemented on the netvm. -You can also manually create rules in the qube itself using standard firewalling controls. See `Where to put firewall rules <#where-to-put-firewall-rules>`__. In complex cases, it might be appropriate to load a ruleset using ``iptables-restore`` called from ``/rw/config/rc.local``. if you do this, be aware that ``rc.local`` is called *after* the network is up, so local rules should not be relied upon to block leaks. +You can also manually create rules in the qube itself using standard firewalling controls. See :ref:`user/security-in-qubes/firewall_4.1:where to put firewall rules`. In complex cases, it might be appropriate to load a ruleset using ``iptables-restore`` called from ``/rw/config/rc.local``. if you do this, be aware that ``rc.local`` is called *after* the network is up, so local rules should not be relied upon to block leaks. Reconnecting qubes after a NetVM reboot --------------------------------------- diff --git a/user/security-in-qubes/split-gpg.rst b/user/security-in-qubes/split-gpg.rst index a304e9d5..3db7d92d 100644 --- a/user/security-in-qubes/split-gpg.rst +++ b/user/security-in-qubes/split-gpg.rst @@ -80,7 +80,7 @@ This is pretty much all that is required. However, you might want to modify the Please note that previously, this parameter was set in ~/.bash_profile. This will no longer work. If you have the parameter set in ~/.bash_profile you *must* update your configuration. -Please be aware of the caveat regarding passphrase-protected keys in the `Current limitations <#current-limitations>`__ section. +Please be aware of the caveat regarding passphrase-protected keys in the :ref:`user/security-in-qubes/split-gpg:current limitations` section. Configuring the client apps to use Split GPG backend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -288,6 +288,8 @@ A safe, unspoofable user consent dialog box is displayed. Selecting “Yes to All” will add a line in the corresponding :doc:`RPC Policy ` file. +.. _using-split-gpg-with-subkeys: + Advanced: Using Split GPG with Subkeys -------------------------------------- @@ -388,11 +390,11 @@ Current limitations ------------------- -- Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket `#474 `__ for more details and plans how to get around this problem, as well as the section on `using Split GPG with subkeys <#advanced-using-split-gpg-with-subkeys>`__. +- Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket `#474 `__ for more details and plans how to get around this problem, as well as the section on :ref:`using-split-gpg-with-subkeys`. - It doesn’t solve the problem of allowing the user to know what is to be signed before the operation gets approved. Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined. -- The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase. It will give an ``Inappropriate ioctl for device`` error. Do not set passphrases for the private keys in the GPG backend domain. Doing so won’t provide any extra security anyway, as explained in the introduction and in `using Split GPG with subkeys <#advanced-using-split-gpg-with-subkeys>`__. If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use ``gpg2 --edit-key `` then ``passwd`` to set an empty passphrase. Note that ``pinentry`` might show an error when you try to set an empty passphrase, but it will still make the change. (See `this StackExchange answer `__ for more information.) **Note:** The error shows only if you **do not** have graphical pinentry installed. +- The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase. It will give an ``Inappropriate ioctl for device`` error. Do not set passphrases for the private keys in the GPG backend domain. Doing so won’t provide any extra security anyway, as explained in the introduction and in :ref:`using-split-gpg-with-subkeys`. If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use ``gpg2 --edit-key `` then ``passwd`` to set an empty passphrase. Note that ``pinentry`` might show an error when you try to set an empty passphrase, but it will still make the change. (See `this StackExchange answer `__ for more information.) **Note:** The error shows only if you **do not** have graphical pinentry installed. .. [1] diff --git a/user/templates/debian/debian-upgrade.rst b/user/templates/debian/debian-upgrade.rst index dc546097..53948b41 100644 --- a/user/templates/debian/debian-upgrade.rst +++ b/user/templates/debian/debian-upgrade.rst @@ -16,7 +16,7 @@ Summary instructions for Debian templates ----------------------------------------- -**Important:** The prompt on each line indicates where each command should be entered: ``dom0``, ``debian-``, or ``debian-``, where ```` is the Debian version number *from* which you are upgrading, and ```` is the Debian version number *to* which you are upgrading. The instructions may differ for certain releases. See `release-specific notes <#release-specific-notes>`__ for any instructions specific to your particular release. +**Important:** The prompt on each line indicates where each command should be entered: ``dom0``, ``debian-``, or ``debian-``, where ```` is the Debian version number *from* which you are upgrading, and ```` is the Debian version number *to* which you are upgrading. The instructions may differ for certain releases. See :ref:`user/templates/debian/debian-upgrade:release-specific notes` for any instructions specific to your particular release. .. code:: console @@ -38,7 +38,7 @@ Detailed instructions for Debian templates These instructions will show you how to upgrade Debian templates. The same general procedure may be used to upgrade any template based on the standard Debian template. -**Important:** The prompt on each line indicates where each command should be entered: ``dom0``, ``debian-``, or ``debian-``, where ```` is the Debian version number *from* which you are upgrading, and ```` is the Debian version number *to* which you are upgrading. The instructions may differ for certain releases. See `release-specific notes <#release-specific-notes>`__ for any instructions specific to your particular release. +**Important:** The prompt on each line indicates where each command should be entered: ``dom0``, ``debian-``, or ``debian-``, where ```` is the Debian version number *from* which you are upgrading, and ```` is the Debian version number *to* which you are upgrading. The instructions may differ for certain releases. See :ref:`user/templates/debian/debian-upgrade:release-specific notes` for any instructions specific to your particular release. 1. Ensure the existing template is not running. diff --git a/user/templates/debian/debian.rst b/user/templates/debian/debian.rst index a344091a..135767da 100644 --- a/user/templates/debian/debian.rst +++ b/user/templates/debian/debian.rst @@ -53,7 +53,7 @@ Upgrading There are two ways to upgrade your template to a new Debian release: -- **Recommended:** `Install a fresh template to replace the existing one. <#installing>`__ **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and :ref:`switch everything that was set to the old template to the new template `. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see ``/var/log/dpkg.log`` and ``/var/log/apt/history.log`` for logs of package manager actions. +- **Recommended:** :ref:`Install a fresh template to replace the existing one. ` **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and :ref:`switch everything that was set to the old template to the new template `. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see ``/var/log/dpkg.log`` and ``/var/log/apt/history.log`` for logs of package manager actions. - **Advanced:** :doc:`Perform an in-place upgrade of an existing Debian template. ` This option will preserve any modifications you’ve made to the template, **but it may be more complicated for less experienced users.** diff --git a/user/templates/fedora/fedora-upgrade.rst b/user/templates/fedora/fedora-upgrade.rst index 0b39ce41..3cbeac17 100644 --- a/user/templates/fedora/fedora-upgrade.rst +++ b/user/templates/fedora/fedora-upgrade.rst @@ -105,7 +105,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th If this attempt is successful, proceed to step 4. - ``dnf`` may error with the text: ``At least X MB more space needed on the / filesystem.`` - In this case, one option is to :doc:`resize the template’s disk image ` before reattempting the upgrade process. (See `Additional Information <#additional-information>`__ below for other options.) + In this case, one option is to :doc:`resize the template’s disk image ` before reattempting the upgrade process. (See :ref:`user/templates/fedora/fedora-upgrade:additional information` below for other options.) diff --git a/user/templates/fedora/fedora.rst b/user/templates/fedora/fedora.rst index 44adc0f3..6e45f100 100644 --- a/user/templates/fedora/fedora.rst +++ b/user/templates/fedora/fedora.rst @@ -53,7 +53,7 @@ Upgrading There are two ways to upgrade your template to a new Fedora release: -- **Recommended:** `Install a fresh template to replace the existing one. <#installing>`__ **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and :ref:`switch everything that was set to the old template to the new template `. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the ``dnf history`` command. +- **Recommended:** :ref:`Install a fresh template to replace the existing one. ` **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and :ref:`switch everything that was set to the old template to the new template `. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the ``dnf history`` command. - **Advanced:** :doc:`Perform an in-place upgrade of an existing Fedora template. ` This option will preserve any modifications you’ve made to the template, **but it may be more complicated for less experienced users.** diff --git a/user/templates/templates.rst b/user/templates/templates.rst index c709f466..34522a3f 100644 --- a/user/templates/templates.rst +++ b/user/templates/templates.rst @@ -3,7 +3,7 @@ Templates ========= -In :doc:`Getting Started `, we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software. Software that you use in most everyday tasks, is installed within :term:`templates