diff --git a/.gitignore b/.gitignore index e35d8850..4b11d9e4 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ _build +**/__pycache__/* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e2bd856..a881afba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,11 @@ Thank you for your interest in contributing to `qubes-doc`, the Qubes OS Project's dedicated documentation repository! Please see [how to edit the -documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/) for +documentation](https://doc.qubes-os.org/developer/general/how-to-edit-the-documentation.html) for detailed contribution instructions. In addition, please take a moment to read our [documentation style -guide](https://www.qubes-os.org/doc/documentation-style-guide/) before +guide](https://doc.qubes-os.org/developer/general/documentation-style-guide.html) before contributing. These guidelines are important to maintaining high standards of quality, and following them will increase the likelihood that your contribution will be accepted. diff --git a/README.md b/README.md index 0ab67025..f017b158 100644 --- a/README.md +++ b/README.md @@ -8,4 +8,4 @@ regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the Web. To contribute, please see [how to edit the -documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/). +documentation](https://doc.qubes-os.org/developer/general/how-to-edit-the-documentation.html). diff --git a/_dev/index.rst b/_dev/index.rst index cc737d8a..bd9debf2 100644 --- a/_dev/index.rst +++ b/_dev/index.rst @@ -18,6 +18,9 @@ This is documentation for the source code. Please choose specific repostitory: + qubes-core-qrexec <> +.. _qubes-core-qrexec: /projects/qubes-core-qrexec + Or see the main Qubes OS documentation diff --git a/attachment/doc/4-3_device-ux-assignments.png b/attachment/doc/4-3_device-ux-assignments.png new file mode 100644 index 00000000..793e2f91 Binary files /dev/null and b/attachment/doc/4-3_device-ux-assignments.png differ diff --git a/attachment/doc/4-3_device-ux-deny-attachment.png b/attachment/doc/4-3_device-ux-deny-attachment.png new file mode 100644 index 00000000..67122a84 Binary files /dev/null and b/attachment/doc/4-3_device-ux-deny-attachment.png differ diff --git a/attachment/doc/4-3_device-ux-edit-assignment.png b/attachment/doc/4-3_device-ux-edit-assignment.png new file mode 100644 index 00000000..c27936f0 Binary files /dev/null and b/attachment/doc/4-3_device-ux-edit-assignment.png differ diff --git a/attachment/doc/4-3_device-ux-required-device.png b/attachment/doc/4-3_device-ux-required-device.png new file mode 100644 index 00000000..fece4cf6 Binary files /dev/null and b/attachment/doc/4-3_device-ux-required-device.png differ diff --git a/attachment/doc/4-3_manager.png b/attachment/doc/4-3_manager.png new file mode 100644 index 00000000..5a17c9f9 Binary files /dev/null and b/attachment/doc/4-3_manager.png differ diff --git a/attachment/doc/4-3_notes.png b/attachment/doc/4-3_notes.png new file mode 100644 index 00000000..caf3b4df Binary files /dev/null and b/attachment/doc/4-3_notes.png differ diff --git a/attachment/doc/4-3_qui-devices.png b/attachment/doc/4-3_qui-devices.png new file mode 100644 index 00000000..222fb03d Binary files /dev/null and b/attachment/doc/4-3_qui-devices.png differ diff --git a/attachment/doc/4-3_qwt-hi.png b/attachment/doc/4-3_qwt-hi.png new file mode 100644 index 00000000..52e2b872 Binary files /dev/null and b/attachment/doc/4-3_qwt-hi.png differ diff --git a/attachment/doc/4-3_qwt-win11.png b/attachment/doc/4-3_qwt-win11.png new file mode 100644 index 00000000..87f801bd Binary files /dev/null and b/attachment/doc/4-3_qwt-win11.png differ diff --git a/attachment/doc/4-3_vmsettings-applications.png b/attachment/doc/4-3_vmsettings-applications.png new file mode 100644 index 00000000..43e0ef40 Binary files /dev/null and b/attachment/doc/4-3_vmsettings-applications.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png new file mode 100644 index 00000000..27ecf049 Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png new file mode 100644 index 00000000..ca22d6a9 Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png b/attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png new file mode 100644 index 00000000..9b7a1d7f Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png b/attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png new file mode 100644 index 00000000..5566bdd7 Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png differ diff --git a/attachment/doc/r4.1-converting-pdf.png b/attachment/doc/r4.1-converting-pdf.png old mode 100755 new mode 100644 diff --git a/attachment/doc/r4.1-dom0-appmenu-select.png b/attachment/doc/r4.1-dom0-appmenu-select.png old mode 100755 new mode 100644 diff --git a/attachment/doc/r4.1-snapshot_40.png b/attachment/doc/r4.1-snapshot_40.png old mode 100755 new mode 100644 diff --git a/attachment/icons/128x128/apps/qubes-logo-icon.png b/attachment/icons/128x128/apps/qubes-logo-icon.png new file mode 100644 index 00000000..98f6036e Binary files /dev/null and b/attachment/icons/128x128/apps/qubes-logo-icon.png differ diff --git a/attachment/icons/favicon-16x16.png b/attachment/icons/favicon-16x16.png new file mode 100644 index 00000000..c26853d5 Binary files /dev/null and b/attachment/icons/favicon-16x16.png differ diff --git a/conf.py b/conf.py index c64f76b7..20d2d73b 100644 --- a/conf.py +++ b/conf.py @@ -32,6 +32,7 @@ extensions = [ 'sphinx.ext.autosectionlabel', 'sphinxnotes.strike', 'sphinx_reredirects', + 'sphinxext.opengraph', 'youtube_frame', ] @@ -42,12 +43,8 @@ redirects = { "https://www.qubes-os.org/downloads/mirrors/", "developer/general/visual-style-guide": "https://www.qubes-os.org/doc/visual-style-guide/", - "developer/general/website-style-guide": - "https://www.qubes-os.org/doc/website-style-guide/", "user/downloading-installing-upgrading/downloads": "https://www.qubes-os.org/downloads/", - "developer/general/how-to-edit-the-documentation": - "https://www.qubes-os.org/doc/how-to-edit-the-documentation/", } @@ -86,6 +83,9 @@ html_static_path = ['attachment/doc'] html_use_opensearch = "https://doc.qubes-os.org" +html_logo = "attachment/icons/128x128/apps/qubes-logo-icon.png" +html_favicon = "attachment/icons/favicon-16x16.png" + # -- -- Options for the linkcheck builder ------------------------------------ linkcheck_anchors = False @@ -95,6 +95,8 @@ linkcheck_ignore = [r'^https?://[^/\s]+\.onion'] autosectionlabel_prefix_document = True +ogp_image = "https://www.qubes-os.org/attachment/icons/qubes-logo-icon-name-slogan-fb.png" +ogp_image_alt = False # -- HTML configuration ------------------------------------------------------ @@ -116,3 +118,10 @@ locale_dirs = ['_translated'] gettext_compact = False gettext_uuid = True + +# -- -- Options for markup --------------------------------------------------- + +rst_epilog = """ +.. |debian-codename| replace:: bookworm +.. |debian-version| replace:: 12 +""" diff --git a/developer/building/development-workflow.rst b/developer/building/development-workflow.rst index 5dbffc41..c9c01945 100644 --- a/developer/building/development-workflow.rst +++ b/developer/building/development-workflow.rst @@ -40,7 +40,7 @@ In ``qubes-builder/artifacts/sources/linux-kernel``: .. code:: console - make prep + $ make prep @@ -48,7 +48,7 @@ The resulting tree will be in kernel-/linux-: .. code:: console - ls -ltrd kernel*/linux* + $ ls -ltrd kernel*/linux* drwxr-xr-x 23 user user 4096 Nov 5 09:50 kernel-3.4.18/linux-3.4.18 drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj @@ -62,7 +62,7 @@ In ``qubes-builder/artifacts/sources/linux-kernel``: .. code:: console - cd kernel-3.4.18/linux-3.4.18 + $ cd kernel-3.4.18/linux-3.4.18 @@ -74,8 +74,8 @@ In ``kernel-3.4.18/linux-3.4.18``: .. code:: console - cp ../../config .config - make oldconfig + $ cp ../../config .config + $ make oldconfig @@ -83,7 +83,7 @@ Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``: .. code:: console - make menuconfig + $ make menuconfig @@ -91,7 +91,7 @@ Copy the modified config back into the kernel tree: .. code:: console - cp .config ../../../config + $ cp .config ../../../config @@ -103,20 +103,20 @@ TODO: describe the workflow for patching the code, below are some random notes, .. code:: console - ln -s ../../patches.xen - export QUILT_PATCHES=patches.xen - export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index" - export QUILT_SERIES=../../series-pvops.conf + $ ln -s ../../patches.xen + $ export QUILT_PATCHES=patches.xen + $ export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index" + $ export QUILT_SERIES=../../series-pvops.conf - quilt new patches.xen/pvops-3.4-0101-usb-xen-pvusb-driver-bugfix.patch - quilt add drivers/usb/host/Kconfig drivers/usb/host/Makefile \ + $ quilt new patches.xen/pvops-3.4-0101-usb-xen-pvusb-driver-bugfix.patch + $ quilt add drivers/usb/host/Kconfig drivers/usb/host/Makefile \ drivers/usb/host/xen-usbback/* drivers/usb/host/xen-usbfront.c \ include/xen/interface/io/usbif.h *edit something* - quilt refresh - cd ../.. + $ quilt refresh + $ cd ../.. vi series.conf @@ -133,7 +133,7 @@ To actually build RPMs, in qubes-builder: .. code:: console - ./qb -c linux-kernel package fetch prep build + $ ./qb -c linux-kernel package fetch prep build @@ -398,7 +398,7 @@ Then use ``make update-repo-unstable`` to upload the packages. You can also spec .. code:: console - make COMPONENTS="core-agent-linux gui-agent-linux linux-utils" qubes update-repo-unstable + $ make COMPONENTS="core-agent-linux gui-agent-linux linux-utils" qubes update-repo-unstable diff --git a/developer/building/qubes-builder-v2.rst b/developer/building/qubes-builder-v2.rst index 1fc607a5..30c441e6 100644 --- a/developer/building/qubes-builder-v2.rst +++ b/developer/building/qubes-builder-v2.rst @@ -2,7 +2,6 @@ Qubes builder v2 ================ - This is a brief introduction to using Qubes Builder v2 to work with Qubes OS sources. It will walk you through installing and configuring Builder v2, and using it to fetch and build Qubes OS packages. For details and customization, use `Qubes OS v2 builder documentation `__. @@ -10,40 +9,29 @@ For details and customization, use `Qubes OS v2 builder documentation `. - git clone https://github.com/QubesOS/qubes-builder.git qubes-builder - cd qubes-builder +.. code:: console - # Verify its integrity: - git tag -v `git describe` + $ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc + $ gpg --import qubes-developers-keys.asc + + $ git clone https://github.com/QubesOS/qubes-builder.git qubes-builder + $ cd qubes-builder + + +Verify its integrity: + +.. code:: console + + $ git tag -v `git describe` + + +Copy the example ``builder.conf``: + +.. code:: console + + $ cp example-configs/qubes-os-master.conf builder.conf + + +Edit the builder.conf file and set the following variables: + +.. code:: bash - cp example-configs/qubes-os-master.conf builder.conf - # edit the builder.conf file and set the following variables: # NO_SIGN="1" - # Download all components: - make get-sources +Download all components: - # And now to build all Qubes RPMs (this will take a few hours): +.. code:: console - make qubes + $ make get-sources - # ... and then to build the ISO - make iso +And now to build all Qubes RPMs (this will take a few hours): + +.. code:: console + + $ make qubes + + +... and then to build the ISO + +.. code:: console + + $ make iso And this should produce a shiny new ISO. @@ -125,7 +158,7 @@ You can also build selected component separately. Eg. to compile only gui virtua .. code:: console - make gui-daemon + $ make gui-daemon You can get a full list from make help. @@ -146,7 +179,7 @@ You can also modify sources somehow if you wish. Here are some basic steps: -- You can also set GIT_PREFIX=“marmarek/qubes-” to use marmarek’s repo instead of “mainstream” - it contains newer (but less tested) versions + - You can also set GIT_PREFIX=“marmarek/qubes-” to use marmarek’s repo instead of “mainstream” - it contains newer (but less tested) versions @@ -154,7 +187,7 @@ You can also modify sources somehow if you wish. Here are some basic steps: .. code:: console - make get-sources + $ make get-sources 4. **Make your modifications here** @@ -165,14 +198,14 @@ You can also modify sources somehow if you wish. Here are some basic steps: .. code:: console - make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates + $ make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates 7. build iso installation image .. code:: console - make iso + $ make iso diff --git a/developer/building/qubes-iso-building.rst b/developer/building/qubes-iso-building.rst index f14523e4..1c9ec826 100644 --- a/developer/building/qubes-iso-building.rst +++ b/developer/building/qubes-iso-building.rst @@ -17,14 +17,14 @@ Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below .. code:: console - sudo setenforce 0 + $ sudo setenforce 0 In ``dom0``, install the Fedora 36 (or 37) template if you don’t already have it. .. code:: console - sudo qubes-dom0-update qubes-template-fedora-36 + $ sudo qubes-dom0-update qubes-template-fedora-36 @@ -66,9 +66,9 @@ Now let’s bootstrap the builder. Unfortunately, the builder cannot verify itse .. code:: console - git clone https://github.com/QubesOS/qubes-builder.git - cd qubes-builder - git tag -v `git describe` + $ git clone https://github.com/QubesOS/qubes-builder.git + $ cd qubes-builder + $ git tag -v `git describe` @@ -120,8 +120,8 @@ Continue the build process with: .. code:: console - make install-deps - make get-sources + $ make install-deps + $ make get-sources @@ -133,8 +133,8 @@ Finally, if you are making a test build, use: .. code:: console - make qubes - make iso + $ make qubes + $ make iso @@ -142,9 +142,9 @@ Or for a fully signed build (this requires setting ``SIGN_KEY`` in ``builder.con .. code:: console - make qubes - make sign-all - make iso + $ make qubes + $ make sign-all + $ make iso @@ -160,9 +160,9 @@ If you will be building Whonix templates: .. code:: console - cd ~ - gpg --keyserver pgp.mit.edu --recv-keys 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA - gpg --fingerprint 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA + $ cd ~ + $ gpg --keyserver pgp.mit.edu --recv-keys 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA + $ gpg --fingerprint 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA @@ -185,11 +185,11 @@ Next, prepare the Git keyring directory and copy them in: .. code:: console - export GNUPGHOME=~/qubes-builder/keyrings/git - mkdir --parents "$GNUPGHOME" - cp ~/.gnupg/pubring.gpg "$GNUPGHOME" - cp ~/.gnupg/trustdb.gpg "$GNUPGHOME" - chmod --recursive 700 "$GNUPGHOME" + $ export GNUPGHOME=~/qubes-builder/keyrings/git + $ mkdir --parents "$GNUPGHOME" + $ cp ~/.gnupg/pubring.gpg "$GNUPGHOME" + $ cp ~/.gnupg/trustdb.gpg "$GNUPGHOME" + $ chmod --recursive 700 "$GNUPGHOME" @@ -197,8 +197,8 @@ Copy one of the example configurations: .. code:: console - cd ~/qubes-builder - cp example-configs/qubes-os-master.conf builder.conf + $ cd ~/qubes-builder + $ cp example-configs/qubes-os-master.conf builder.conf @@ -208,9 +208,9 @@ Continue the build process with: .. code:: console - make install-deps - make get-sources - unset GNUPGHOME + $ make install-deps + $ make get-sources + $ unset GNUPGHOME @@ -220,8 +220,8 @@ Finally, if you are making a test build, use: .. code:: console - make qubes - make iso + $ make qubes + $ make iso @@ -229,9 +229,9 @@ Or for a fully signed build (this requires setting ``SIGN_KEY`` in ``builder.con .. code:: console - make qubes - make sign-all - make iso + $ make qubes + $ make sign-all + $ make iso diff --git a/developer/code/code-signing.rst b/developer/code/code-signing.rst index 690c4dd0..c547534f 100644 --- a/developer/code/code-signing.rst +++ b/developer/code/code-signing.rst @@ -91,7 +91,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign .. code:: console - git config --global user.signingkey + $ git config --global user.signingkey @@ -99,23 +99,24 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign .. code:: console - git config --global commit.gpgsign true + $ git config --global commit.gpgsign true Alternatively, manually specify when a commit is to be signed: .. code:: console - git commit -S + $ git commit -S 3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check. + This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history. .. code:: console - git tag -s -m "" + $ git tag -s -m "" You can also create an alias to make this easier. Edit your ``~/.gitconfig`` file. In the ``[alias]`` section, add ``stag`` to create signed tags and ``spush`` to create signed tags and push them. @@ -171,14 +172,14 @@ In this case, you have several options to sign the commit: .. code:: console - git commit --amend -S + $ git commit --amend -S This also rewrites the commit so you need to push it forcefully: .. code:: console - git push -f + $ git push -f @@ -186,8 +187,8 @@ In this case, you have several options to sign the commit: .. code:: console - git checkout - git spush + $ git checkout + $ git spush Now, the signature checker needs to re-check the signature. Please comment on the pull request that you would like to have the signatures checked again. diff --git a/developer/code/coding-style.rst b/developer/code/coding-style.rst index d8f5f3cb..759dacea 100644 --- a/developer/code/coding-style.rst +++ b/developer/code/coding-style.rst @@ -49,7 +49,7 @@ General typographic conventions - **Maintain a decent amount of horizontal spacing**, e.g. add a space after ``if`` or before ``{`` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x*2+5) vs. (x * 2 + 5) is left to the developer’s judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: ``if ( condition )`` and use ones like this: ``if (condition)`` instead. -- **Use single new lines** (‘\n’ aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (–). This will allow the source code to be easily viewable in various Windows-based programs. +- **Use single new lines** (‘\\n’ aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (–). This will allow the source code to be easily viewable in various Windows-based programs. - **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names. diff --git a/developer/code/source-code.rst b/developer/code/source-code.rst index 34db1952..6b8e6c1f 100644 --- a/developer/code/source-code.rst +++ b/developer/code/source-code.rst @@ -21,7 +21,7 @@ To clone a repository: .. code:: console - git clone https://github.com/QubesOS/qubes-.git + $ git clone https://github.com/QubesOS/qubes-.git @@ -29,7 +29,7 @@ e.g.: .. code:: console - git clone https://github.com/QubesOS/qubes-core-admin.git core-admin + $ git clone https://github.com/QubesOS/qubes-core-admin.git core-admin @@ -39,8 +39,8 @@ If you really do want to clone **all** of the repositories, you can use these co .. code:: console - curl "https://api.github.com/orgs/QubesOS/repos?page=1&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone - curl "https://api.github.com/orgs/QubesOS/repos?page=2&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone + $ curl "https://api.github.com/orgs/QubesOS/repos?page=1&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone + $ curl "https://api.github.com/orgs/QubesOS/repos?page=2&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone @@ -48,7 +48,7 @@ To update (git fetch) **all** of these repositories : .. code:: console - find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \; + $ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \; @@ -61,6 +61,7 @@ How to Send Patches If you want to :ref:`contribute code ` to the project, there are two ways. Whichever method you choose, you must :doc:`sign your code ` before it can be accepted. - **Preferred**: Use GitHub’s `fork & pull requests `__. + Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it’s a good idea to send a message to the :ref:`qubes-devel mailing list ` in order to notify people who do not receive GitHub notifications. - Send a patch to the :ref:`qubes-devel mailing list ` (``git format-patch``). diff --git a/developer/debugging/automated-tests.rst b/developer/debugging/automated-tests.rst index 2e9ed06c..75bf92a8 100644 --- a/developer/debugging/automated-tests.rst +++ b/developer/debugging/automated-tests.rst @@ -119,7 +119,7 @@ Tests are also compatible with nose2 test runner, so you can use this instead: .. code:: console - sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd + $ sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd This may be especially useful together with various nose2 plugins to store tests results (for example ``nose2.plugins.junitxml``), to ease presenting results. This is what we use on `OpenQA `__. @@ -140,15 +140,15 @@ Assuming you cloned the ``qubes-builder`` repository to your home directory insi .. code:: console - cd ~ - sudo dnf install python3-pip lvm2 python35 python3-virtualenv - virtualenv -p /usr/bin/python35 python35 - source python35/bin/activate - python3 -V - cd ~/qubes-builder/qubes-src/core-admin - pip3 install -r ci/requirements.txt - export PYTHONPATH=../core-qrexec:test-packages - ./run-tests + $ cd ~ + $ sudo dnf install python3-pip lvm2 python35 python3-virtualenv + $ virtualenv -p /usr/bin/python35 python35 + $ source python35/bin/activate + $ python3 -V + $ cd ~/qubes-builder/qubes-src/core-admin + $ pip3 install -r ci/requirements.txt + $ export PYTHONPATH=../core-qrexec:test-packages + $ ./run-tests To run only the tests related to e.g. ``lvm``, you may use: diff --git a/developer/debugging/safe-remote-ttys.rst b/developer/debugging/safe-remote-ttys.rst index 4ef4918f..cb53a527 100644 --- a/developer/debugging/safe-remote-ttys.rst +++ b/developer/debugging/safe-remote-ttys.rst @@ -70,7 +70,7 @@ If your machine has a serial console, you may with to use that, but note that a .. code:: console - script -f /dev/ttyS0 + $ script -f /dev/ttyS0 diff --git a/developer/debugging/test-bench.rst b/developer/debugging/test-bench.rst index 5324baac..4a64cc20 100644 --- a/developer/debugging/test-bench.rst +++ b/developer/debugging/test-bench.rst @@ -96,11 +96,11 @@ Internet access is intentionally disabled by default in dom0. But to ease the de .. code:: console - sudo systemctl enable sshd - sudo systemctl start sshd + $ sudo systemctl enable sshd + $ sudo systemctl start sshd - sudo systemctl enable dom0-network-direct - sudo systemctl start dom0-network-direct + $ sudo systemctl enable dom0-network-direct + $ sudo systemctl start dom0-network-direct @@ -123,26 +123,26 @@ The following commands should work for you, but do keep in mind that the provisi # https://github.com/marmarek/openqa-tests-qubesos/blob/master/tests/update.pm # Install git - sudo qubes-dom0-update git || sudo dnf --setopt=reposdir=/etc/yum.repos.d install git + $ sudo qubes-dom0-update git || sudo dnf --setopt=reposdir=/etc/yum.repos.d install git # Download the openQA automated testing environment Salt configuration - git clone https://github.com/marmarek/openqa-tests-qubesos/ - cd openqa-tests-qubesos/extra-files - sudo cp -a system-tests/ /srv/salt/ - sudo qubesctl top.enable system-tests + $ git clone https://github.com/marmarek/openqa-tests-qubesos/ + $ cd openqa-tests-qubesos/extra-files + $ sudo cp -a system-tests/ /srv/salt/ + $ sudo qubesctl top.enable system-tests # Install the same configuration as the one in openQA - QUBES_VERSION=4.1 - PILLAR_DIR=/srv/pillar/base/update - sudo mkdir -p $PILLAR_DIR - printf 'update:\n qubes_ver: '$QUBES_VERSION'\n' | sudo tee $PILLAR_DIR/init.sls - printf "base:\n '*':\n - update\n" | sudo tee $PILLAR_DIR/init.top - sudo qubesctl top.enable update pillar=True + $ QUBES_VERSION=4.1 + $ PILLAR_DIR=/srv/pillar/base/update + $ sudo mkdir -p $PILLAR_DIR + $ printf 'update:\n qubes_ver: '$QUBES_VERSION'\n' | sudo tee $PILLAR_DIR/init.sls + $ printf "base:\n '*':\n - update\n" | sudo tee $PILLAR_DIR/init.top + $ sudo qubesctl top.enable update pillar=True # Apply states to dom0 and VMs # NOTE: These commands can take several minutes (if not more) without showing output - sudo qubesctl --show-output state.highstate - sudo qubesctl --max-concurrency=2 --skip-dom0 --templates --show-output state.highstate + $ sudo qubesctl --show-output state.highstate + $ sudo qubesctl --max-concurrency=2 --skip-dom0 --templates --show-output state.highstate Development VM @@ -157,7 +157,7 @@ Arrange firewall so you can reach the testbench from your ``qubes-dev`` VM. Gene .. code:: console - ssh-keygen -t ecdsa -b 521 + $ ssh-keygen -t ecdsa -b 521 diff --git a/developer/debugging/vm-interface.rst b/developer/debugging/vm-interface.rst index 7864d6c8..87523cc8 100644 --- a/developer/debugging/vm-interface.rst +++ b/developer/debugging/vm-interface.rst @@ -199,11 +199,11 @@ Services called by dom0 to provide some VM configuration: - - ``xdgicon:NAME`` - search for NAME in standard icons theme + - ``xdgicon:NAME`` - search for NAME in standard icons theme - - ``-`` - get icon data from stdin (the caller), can be prefixed with format name, for example ``png:-`` + - ``-`` - get icon data from stdin (the caller), can be prefixed with format name, for example ``png:-`` - - file name + - file name diff --git a/developer/general/gsod.rst b/developer/general/gsod.rst index 617bf753..00e53e54 100644 --- a/developer/general/gsod.rst +++ b/developer/general/gsod.rst @@ -113,22 +113,17 @@ Instructional video series ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _the-projects-problem-1: - - -The project's problem -^^^^^^^^^^^^^^^^^^^^^ +Instructional video series: The project's problem +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There is user demand for high-quality, up-to-date video guides that take users from zero Linux knowledge to using Qubes as a daily driver and performing specific tasks inside of Qubes, but almost no such videos exist. Although most of the required knowledge is documented, many users report that they would prefer to watch videos rather than read text or that they would find videos easier to understand and follow along with. -.. _the-projects-scope-1: - -The project's scope -^^^^^^^^^^^^^^^^^^^ +Instructional video series: The project's scope +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -219,11 +214,10 @@ Below is an example of the content (which is already :doc:`documented `) The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, and Marek Marczykowski-Górecki, will supervise and support the creator. -.. _measuring-the-projects-success-1: -Measuring the project's success -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Instructional video series: Measuring the project's success +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer/general/markdown-style-guide.rst b/developer/general/markdown-style-guide.rst index 2599cdf5..ddabc7ea 100644 --- a/developer/general/markdown-style-guide.rst +++ b/developer/general/markdown-style-guide.rst @@ -1,6 +1,6 @@ -========================= -Documentation style guide -========================= +==================== +Markdown style guide +==================== *Also see* :doc:`how to edit the documentation ` *.* diff --git a/developer/general/usability-ux.rst b/developer/general/usability-ux.rst index 593de59b..c3f9515e 100644 --- a/developer/general/usability-ux.rst +++ b/developer/general/usability-ux.rst @@ -2,19 +2,15 @@ Usability & UX ============== - Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review `our visual style guide `__ for other design related information. - ---- - Easy To Use ----------- - An ideal user experience is friendly, and it beckons a new user to explore the interface. In this process, they can naturally discover how to use the software. Below are some guidelines that will help you design a user interface that accomplishes this goal. |redx| **Interfaces Should Not** @@ -27,8 +23,6 @@ An ideal user experience is friendly, and it beckons a new user to explore the i - Overwhelm the user with too much information and cognitive load - - Perhaps the most common cause of mistakes is complexity. If there is a configuration setting that will significantly affect the user’s experience, choose a safe and smart default then tuck this setting in an ``Advanced Settings`` panel. |checkmark| **Interfaces Should** @@ -41,18 +35,13 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura - Choose intelligent defaults for settings - - In making software easy to use, it is crucial to be mindful of `cognitive load `__ which dictates that *“humans are generally able to hold only seven +/- two units of information in short-term memory.”* Making sure your interfaces don’t pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed. - ---- - Easy to Understand ------------------ - There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims! |redx| **Avoid Acronyms** @@ -67,8 +56,6 @@ Acronyms are compact and make good names for command line tools. They do not mak - ``NetVM`` - Networking Virtual Machine - - Despite this rule, some acronyms like ``USB`` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms when the full words like ``Universal Serial Bus`` are more likely to confuse users. |checkmark| **Use Simple Words** @@ -83,12 +70,8 @@ Use the minimum amount of words needed to be descriptive, but also informative. - Use ``Networking`` or ``Networking Qube`` instead of ``NetVM`` given context - - - ---- - |redx| **Avoid Technical Words** Technical words are usually more accurate, but they often *only* make sense to technical users and are confusing and unhelpful to non-technical users. Examples of technical words that might show up in Qubes OS are: @@ -99,8 +82,6 @@ Technical words are usually more accurate, but they often *only* make sense to t - ``qrexec-daemon`` - - These are all terms that have at some point showed up in users’ notification messages. Each term is very specific, but requires the user to understand virtualization to interpret. |checkmark| **Use Common Concepts** @@ -113,14 +94,10 @@ Large amounts of the global population have been using computers for one or two - Use ``Qubes`` instead of ``qrexec-daemon`` as it gives better context on what is happening - - These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes). - ---- - |redx| **Avoid Inconsistencies** It is easy to start abbreviating (or making acronyms) of long terms like ``Disposable Virtual Machine`` depending on where the term shows up in an interface. @@ -131,8 +108,6 @@ It is easy to start abbreviating (or making acronyms) of long terms like ``Dispo - ``DisposableVM`` - - This variation in terms can cause new users to question or second guess what the three different variations mean, which can lead to inaction or mistakes. |checkmark| **Make Things Consistent** @@ -141,14 +116,10 @@ Always strive to keep things consistent in the interfaces as well as documentati - Use ``Disposable Qube`` at all times as it meets other criteria as well. - - By using the same term throughout an interface, a user can create a mental model and relationship with that term allowing them to feel empowered. - ---- - |redx| **Avoid Duplicate Words** It is easy to add words like ``Domain`` before items in a list or menu in an attempt to be descriptive, such as: @@ -160,8 +131,6 @@ It is easy to add words like ``Domain`` before items in a list or menu in an att - Domain: banking - Domain: personal - - The repeated use of the word ``Domain`` requires a user to read it for each item in the list, which makes extra work for the eye in parsing out the relevant word like ``work, banking, or personal``. This also affects horizontal space on fixed width lines. |checkmark| **Create Groups & Categories** @@ -175,16 +144,11 @@ It is more efficient to group things under headings instead as this allows the e - Banking - Personal - - - ---- - Easy To Complete ---------------- - Lastly, expected (and unexpected) situations often require user actions or input. Make resolving these occurences as easy as possible to complete the action. |redx| **Don’t Leave Users Stranded** @@ -195,8 +159,6 @@ Consider the following notifications: - ``There was an error saving Qube "Personal"`` - - Instead of displaying solvable errors like these and neglecting to provide a fix: |checkmark| **Offer Actionable Solutions** @@ -207,14 +169,10 @@ Error messages and limits such as those in the previous example can be greatly i - Add a link to a documentation page called ``Troubleshoot saving data`` - - In adhering to these principles, you’ll make undesirable situations more manageable for users instead of feeling stranded. - ---- - |checkmark| **Minimize Repetitive Steps** There are many cases where a user wants to perform an action on more than one file or folder. However in order to do the action, the user must repeat certain steps such as: @@ -223,26 +181,18 @@ There are many cases where a user wants to perform an action on more than one fi 2. Navigate through file system + - Click Folder One + - Click Folder Two -- Click Folder One - -- Click Folder Two - -- Click Folder Three - -- Click Folder Four - + - Click Folder Three + - Click Folder Four 3. Select proper file 4. Complete task on file - - - - That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process: 1. Click on ``Open File`` from a menu or button @@ -253,18 +203,13 @@ That subtle act of clicking through a file system can prove to be significant if 4. Complete task - - Clearly, cutting out something as simple as navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item like ``Open Multiple Files`` might be even better, because remembering and using relevant hotkeys is often something only power users know how to do! - ---- - GNOME, KDE, and Xfce -------------------- - The desktop GUIs that QubesOS versions 1 - 4.1 offer are `KDE `__ and `Xfce `__. We are currently migrating towards using `GNOME `__. We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments. This change means you should use `GTK `__ rather than Qt for new GUIs. @@ -277,16 +222,11 @@ All three of these mentioned desktop environments have their own `human interfac - `Xfce UI Guidlines `__ - - - ---- - Further Learning & Inspiration ------------------------------ - Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources: - `Learn Design Principles `__ by Melissa Mandelbaum @@ -301,7 +241,5 @@ Learning to make well designing intuitive interfaces and software is specialized - `Hack Design `__ - online learning program - - .. |checkmark| image:: /attachment/doc/checkmark.png .. |redx| image:: /attachment/doc/red_x.png diff --git a/developer/general/website-style-guide.rst b/developer/general/website-style-guide.rst new file mode 100644 index 00000000..1a8e0f82 --- /dev/null +++ b/developer/general/website-style-guide.rst @@ -0,0 +1,73 @@ +=================== +Website style guide +=================== + + +This page explains the standards we follow for building and maintaining the website. Please follow these guidelines and conventions when modifying the website. For the standards governing the documentation in particular, please see the :doc:`documentation style guide `. + +Coding conventions +------------------ + + +The following conventions apply to the website as a whole, including everything written in HTML, CSS, YAML, and Liquid. These conventions are intended to keep the codebase consistent when multiple collaborators are working on it. They should be understood as a practical set of rules for maintaining order in this specific codebase rather than as a statement of what is objectively right or good. + +General practices +^^^^^^^^^^^^^^^^^ + + +- Use comments to indicate the purposes of different blocks of code. This makes the file easier to understand and navigate. + +- Use descriptive variable names. Never use one or two letter variable names. Avoid obscure abbreviations and made-up words. + +- In general, make it easy for others to read your code. Your future self will thank you, and so will your collaborators! + +- `Don’t Repeat Yourself (DRY)! `__ Instead of repeating the same block of code multiple times, abstract it out into a separate file and ``include`` that file where you need it. + + + +Whitespace +^^^^^^^^^^ + + +- Always use spaces. Never use tabs. + +- Each indentation step should be exactly two (2) spaces. + +- Whenever you add an opening tag, indent the following line. (Exception: If you open and close the tag on the same line, do not indent the following line.) + +- Indent Liquid the same way as HTML. + +- In general, the starting columns of every adjacent pair of lines should be no more than two spaces apart (example below). + +- No blank or empty lines. (Hint: When you feel you need one, add a comment on that line instead.) + + + +Indentation example +^^^^^^^^^^^^^^^^^^^ + + +Here’s an example that follows the indentation rules: + + + +.. code:: html + + + + + {% for item in secs.htmlsections[0].columns %} + + {% endfor %} + + {% for canary in site.data.sec-canary reversed %} + + + + + + {% endfor %} +
{{ item.title }}
{{ canary.date }}Qubes Canary #{{ canary.canary }}
+ + + diff --git a/developer/releases/1_0/release-notes.rst b/developer/releases/1_0/release-notes.rst index ec040aca..1fd7d45f 100644 --- a/developer/releases/1_0/release-notes.rst +++ b/developer/releases/1_0/release-notes.rst @@ -19,8 +19,8 @@ Known issues .. code:: console - qvm-prefs -s fedora-17-x64-dvm maxmem 3072 - qvm-create-default-dvm --default-template --default-script + $ qvm-prefs -s fedora-17-x64-dvm maxmem 3072 + $ qvm-create-default-dvm --default-template --default-script @@ -58,6 +58,6 @@ If you have Qubes Beta 3 currently installed on your system, you must reinstall .. code:: console - qvm-backup-restore --replace-template=fedora-15-x64:fedora-17-x64 + $ qvm-backup-restore --replace-template=fedora-15-x64:fedora-17-x64 diff --git a/developer/releases/3_0/release-notes.rst b/developer/releases/3_0/release-notes.rst index f8aaed7f..9c96ceaf 100644 --- a/developer/releases/3_0/release-notes.rst +++ b/developer/releases/3_0/release-notes.rst @@ -3,11 +3,6 @@ Qubes R3.0 release notes ======================== -Qubes R3.0 Release Notes ------------------------- - - - This Qubes OS release is dedicated to the memory of Caspar Bowden. diff --git a/developer/releases/4_0/release-notes.rst b/developer/releases/4_0/release-notes.rst index dbedb6d7..601e192a 100644 --- a/developer/releases/4_0/release-notes.rst +++ b/developer/releases/4_0/release-notes.rst @@ -56,6 +56,7 @@ Security Notes - PV VMs migrated from 3.2 to 4.0-rc4 or later are automatically set to PVH mode in order to protect against Meltdown (see `QSB #37 `__). However, PV VMs migrated from any earlier 4.0 release candidate (RC1, RC2, or RC3) are not automatically set to PVH mode. These must be set manually. - The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see `#3737 `__). + Steps for dom0 updates: 1. Open the Qubes Menu by clicking on the “Q” icon in the top-left corner of the screen. @@ -66,7 +67,7 @@ Security Notes .. code:: console - sudo nano /etc/yum.repos.d/qubes-dom0.repo + $ sudo nano /etc/yum.repos.d/qubes-dom0.repo diff --git a/developer/releases/4_3/release-notes.rst b/developer/releases/4_3/release-notes.rst new file mode 100644 index 00000000..ba188a3f --- /dev/null +++ b/developer/releases/4_3/release-notes.rst @@ -0,0 +1,347 @@ +========================== +Qubes OS 4.3 release notes +========================== + + +Major features and improvements since Qubes 4.2 +=============================================== + +- Dom0 upgraded to Fedora 41 + (`#9402 `__). + +- Xen upgraded to version 4.19 + (`#9420 `__). + +- Default Fedora template upgraded to Fedora 42 (Fedora TemplateVMs and + StandaloneVMs with version lower than 41 are not supported). + +- Default Debian template upgraded to Debian 13 (Debian TemplateVMs and + StandaloneVMs with version lower than 12 are not supported). + +- Default Whonix templates upgraded to Whonix 17.4.3 (Whonix TemplateVMs + and StandaloneVMs with version lower than 17 are not supported). + +- Preloaded disposables + (`#1512 `__, + `#9907 `__, + `#9917 `__, + `#9918 `__ & + `#10026 `__). + +- Device “self-identity oriented” assignment (a.k.a New Devices API) + (`#9325 `__). + +- QWT (Qubes Windows Tools) reintroduction with improved features + (`#1861 `__). + +|Screenshot of QWT, Welcome page| + +|Screenshot of QWT, Windows 11| + +UI/UX +----- + +- New Device UX workflow to allow users easy utilization of new Devices API. + A dedicated ``Device Assignments`` page is added to Global Config. + Qubes Devices widget is completely redesigned. + (`#8537 `__). + +|Screenshot of Device UX assignments| + +|Screenshot of Device UX deny attachment| + +|Screenshot of Device UX edit assignment| + +|Screenshot of Device UX required devices| + +|Screenshot of Device UX Qubes Devices widget| + +- New and improved flat icons for GUI tools + (`#5657 `__). + +|Screenshot of Qube Manager| + +- The far left icons from the Qube Manager are removed + (`#9776 `__). + +- Application icons are available in VM Settings + (`#9829 `__). + +|Screenshot of Qube Settings Applications| + +- Option to add Qubes video Companion to AppMenu + (`#9761 `__). + +- Improved AppMenu navigation with keyboard + (`#9006 `__). + +- Better wording to clarify updater settings and actions + (`#8096 `__). + +- Centralized Tray Notifications + (`#889 `__). + +- Option to launch root terminal or console terminal from Qubes Domains widget + (`#9788 `__) + +- Option to open Global Config at a selected section for user + convenience + (`#9530 `__). + +- A ``Saving changes...`` dialog is added to Global Config + (`#9926 `__). + +GUI Daemon/Agent improvements +----------------------------- + +- Allowing the GUI Daemon background color to be configurable, mostly + useful for people with dark themes + (`#9304 `__). + +- Audio daemon does not connect to recording stream unless recording is + explicitly enabled + (`#9999 `__). + +- Legacy X11 App icons (e.g. Xterm) are properly displayed + (`#9973 `__). + +- Labeling virtual pointing device as absolute and not relative + (`#228 `__). + +- Improved global clipboard notifications & configurable global clipboard size + (`#9296 `__ & + `#9978 `__). + +- Supporting Windows qubes in systems with ``sys-gui*`` + (`#7565 `__). + +Hardware support improvements +----------------------------- + +- Support for `Advanced Format + (AF) `__ drives better known + as 4K sector + (`#4974 `__). + +- Replacing bus/slot/function with full PCI paths for device assignments + (`#8681 `__ + & `#8127 `__). + +- Ability to filter input devices with udev rules. + (`#3604 `__). + +- Fix for graceful rebooting on some (U)EFI systems with buggy firmware + (`#6258 `__). + +- Better support for Bluetooth and external hot-pluggable audio devices + with dynamic AudioVM switching + (`#7750 `__). + +Security features +----------------- + +- Templates could request custom kernel command line parameters; + currently used for Kicksecure and Whonix templates ``user-sysmaint-split`` + (`#9750 `__). + + - Allow VMs to specify boot modes as being only intended for AppVMs or + templates + (`#9920 `__). + +- Shipping GRUB2 from Fedora with all security patches and Bootloader + Specification support + (`#9471 `__). + +- SSL client certificate and GPG key support for private template repositories + (`#9850 `__). + +- Preventing unsafe practice of 3rd party template installation with rpm/dnf + (`#9943 `__). + +- Ability to prohibit start of specific qubes + (`#9622 `__). + +- UUID support for qubes and support for addressing them by UUID in policies + (`#8862 `__ & + `#8510 `__). + +- Custom persist feature to avoid unwanted data to persist as much as possible + (`#1006 `__). + +Anonymity improvements +---------------------- + +- Disallowing files, URLs, or any application from Whonix-Workstation + qubes to be opened in non-Whonix disposable + (`#10051 `__). + +- Preventing users from changing their Whonix Workstation qubes’ netvm + to ``sys-firewall`` (or other clearnet netvms) to avoid IP leaks + (`#8551 `__). + +- kloak: Keystroke-level online anonymization kernel + (`#1850 `__). + +Performance optimizations +------------------------- + +- Option to use volumes directly without snapshots + (`#8767 `__). + +- Retiring ``qubes-rpc-multiplexer`` and directly executing the command from c + (`#9062 `__). + +- Caching "system info" structure for qrexec policy evaluation + (`#9362 `__). + +- Minimal state qubes to make NetVM and USBVM to consume as little RAM as + possible. + +Updating & upgrading +-------------------- + +- Ability to always hide specific TemplateVMs and StandaloneVMs from + update tools + (`#9029 `__). + +- pacman hook to notify dom0 about successful manual Archlinux upgrades + (`#9233 `__), + +- Improved R4.2 -> R4.3 upgrade tool + (`#9317 `__), + + - Using `lvmdevices` feature instead of device filter + (`#9421 `__). + +New/Improved experimental features +---------------------------------- + +- Support for Ansible + (`#10004 `__). + +- Support for `Qubes + Air `__ + (`#9015 `__). + + - qrexec protocol extension to support sending source information to + destination + (`#9475 `__). + +- Better support for GUIVM. + + - GUI/Admin domain splitting + (`#833 `__). + + - Automatically removing ‘nomodeset’ boot option when GPU is attached + (`#9792 `__). + +- Initial basic steps to support Wayland session only in GUIVM (but not GUI + daemon/agent intra-communication) + (`#8515 `__ & + `#8410 `__). + +Other +----- + +- Allowing user to add free-form text to qubes (for descriptions, notes, + comments, remarks, reminders, etc.) + (`#899 `__). + +|Screenshot of Qube Settings Notes| + +- Automatically clean up `QubesIncoming` directory if empty + (`#8307 `__). + +- ``vm-config.*`` features to pass external configuration to inside the qube + (`#9837 `__). + +- Admin API for reading/writing denied device-interface list + (`#9674 `__). + +- New Devices API for salt + (`#9753 `__). + +- IPv6 DNS support for full IPv4-less environments + (`#10038 `__). + +Dropped or replaced features +---------------------------- + +- Default screen locker is changed from ``XScreenSaver`` to + ``xfce4-screensaver`` + +- ``Create Qubes VM`` is retired in favor of the improved ``Create New Qube`` + (`#6561 `__). + +- Windows 7 support is dropped from QWT. + +For a full list, including more detailed descriptions, please see +`here `__. + +Known issues +============ + +- Templates restored in 4.3 from a pre-4.3 backup continue to target + their original Qubes OS release repos. If you are using fresh + templates on a clean 4.3 installation, or if you performed an + :ref:`in-place upgrade from 4.2 to 4.3 `, + then this does not affect you. (For more information, see issue + `#8701 `__.) + +Also see the `full list of open bug reports affecting Qubes +4.3 `__. + +We strongly recommend :doc:`updating Qubes OS ` +immediately after installation in order to apply all available bug fixes. + +Notes +===== + +- Additional notes for future release candidates will be added here + +Download +======== + +All Qubes ISOs and associated :doc:`verification files ` +are available on the `downloads `__ page. + +Installation instructions +========================= + +See the :doc:`installation guide `. + +Upgrading +========= + +Please see :doc:`how to upgrade to Qubes 4.3 `. + +.. |Screenshot of QWT, Welcome page| image:: /attachment/doc/4-3_qwt-hi.png + :alt: Windows 11 welcome page after installation in an HVM + +.. |Screenshot of QWT, Windows 11| image:: /attachment/doc/4-3_qwt-win11.png + :alt: Windows 11 within an HVM qube showing file explorer + +.. |Screenshot of Device UX assignments| image:: /attachment/doc/4-3_device-ux-assignments.png + :alt: Device Assignments page in Global Config + +.. |Screenshot of Device UX deny attachment| image:: /attachment/doc/4-3_device-ux-deny-attachment.png + :alt: Deny device attachment config in Global Config + +.. |Screenshot of Device UX edit assignment| image:: /attachment/doc/4-3_device-ux-edit-assignment.png + :alt: Editing device assignment for a network interface in Global Config + +.. |Screenshot of Device UX required devices| image:: /attachment/doc/4-3_device-ux-required-device.png + :alt: Editing a required device in Global Config + +.. |Screenshot of Device UX Qubes Devices widget| image:: /attachment/doc/4-3_qui-devices.png + :alt: Redesigned Qubes Devices widget + +.. |Screenshot of Qube Manager| image:: /attachment/doc/4-3_manager.png + :alt: Qube Manager with improved flat icons + +.. |Screenshot of Qube Settings Applications| image:: /attachment/doc/4-3_vmsettings-applications.png + :alt: Qube settings showing icons of Apps + +.. |Screenshot of Qube Settings Notes| image:: /attachment/doc/4-3_notes.png + :alt: Qube settings showing qube notes + diff --git a/developer/releases/4_3/schedule.rst b/developer/releases/4_3/schedule.rst new file mode 100644 index 00000000..7e9d1710 --- /dev/null +++ b/developer/releases/4_3/schedule.rst @@ -0,0 +1,20 @@ +=========================== +Qubes R4.3 release schedule +=========================== + + +**Please note:** *This page is still an unfinished draft in progress. It is being updated as Qubes 4.3 development and testing continues.* + +The table below is based on our :ref:`release schedule policy `. + +.. list-table:: + :widths: 10 10 + :align: center + :header-rows: 1 + + * - Date + - Stage + * - TBD + - 4.3.0-rc1 release + + diff --git a/developer/releases/notes.rst b/developer/releases/notes.rst index bbea04f7..9657223d 100644 --- a/developer/releases/notes.rst +++ b/developer/releases/notes.rst @@ -22,4 +22,6 @@ Release notes Qubes R4.2 release notes + Qubes R4.3 release notes + diff --git a/developer/releases/schedules.rst b/developer/releases/schedules.rst index 8c3fe7c1..6eb15237 100644 --- a/developer/releases/schedules.rst +++ b/developer/releases/schedules.rst @@ -18,4 +18,6 @@ Release schedules Qubes R4.2 release schedule + Qubes R4.3 release schedule + diff --git a/developer/services/admin-api.rst b/developer/services/admin-api.rst index 03964deb..72f89097 100644 --- a/developer/services/admin-api.rst +++ b/developer/services/admin-api.rst @@ -91,9 +91,11 @@ it easy to set the policy using current mechanism. * - ``admin.vm.CreateInPool.`` - ``dom0`` - template - - ``name= label=` so that different security levels are easily identifiable. @@ -39,7 +44,7 @@ Features - **Strong isolation** Isolate different pieces of software as if they were installed on separate physical machines using advanced virtualization techniques. -- **Template system** Use :ref:`app qubes ` to +- **Template system** Use :term:`app qubes ` to share a root file system without sacrificing security using the innovative :doc:`Template system `. @@ -47,7 +52,7 @@ Features - **Multiple operating systems** Use multiple operating systems at the same time, including :doc:`Fedora `, :doc:`Debian `, and `Windows `__ - + - **Disposables** Create :doc:`disposables ` on the fly that self-destruct when shut down. - **Whonix integration** Run `Tor `__ securely system-wide using `Whonix with Qubes `__. @@ -137,7 +142,7 @@ plug in devices, and install software free from worry. It's a place where **you** have control over your software, not the other way around. (See some :doc:`examples of how different types of users organize their qubes `.) -Qubes is also powerful. Organizations like the `Freedom of the Press Foundation `__, +Qubes is also powerful. Organizations like the `Freedom of the Press Foundation `__, `Mullvad `__, and `Let's Encrypt `__ rely on Qubes as they build and maintain critical privacy and @@ -187,7 +192,7 @@ presentation. - If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation ` and the :ref:`user FAQ `. -- If you’re a developer, there’s dedicated :ref:`developer documentation ` and a :ref:`developer FAQ ` just for you. -- Ready to give Qubes a try? Head on over to the `downloads page `__, and read the :doc:`installation guide `. +- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ ` just for you. +- Ready to give Qubes a try? Head on over to the `downloads page `__, and read the :ref:`Installation guide`. - Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum `. diff --git a/introduction/issue-tracking.rst b/introduction/issue-tracking.rst index 026f25c3..089fce87 100644 --- a/introduction/issue-tracking.rst +++ b/introduction/issue-tracking.rst @@ -21,7 +21,7 @@ I see something that should be changed in the documentation. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We encourage you to submit the change yourself! Please see the `how to edit the documentation `__ for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue. +We encourage you to submit the change yourself! Please see the :doc:`how to edit the documentation ` for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue. I would like to report a security vulnerability. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -47,13 +47,15 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure 6. Do not delete the provided issue template. Fill out every applicable section. -7. Make sure to mention any relevant documentation and other issues you’ve already seen. We don’t know what you’ve seen unless you tell us. If you don’t list it, we’ll assume you haven’t seen it. +7. Please note that AIs often `hallucinate `__ about Qubes OS. If you're using an AI to assist you, please check its conclusions against the `official documentation `__. -8. If any sections of the issue template are *truly* not applicable, you may remove them. +8. Make sure to mention any relevant documentation and other issues you’ve already seen. We don’t know what you’ve seen unless you tell us. If you don’t list it, we’ll assume you haven’t seen it. -9. Submit your issue. +9. If any sections of the issue template are *truly* not applicable, you may remove them. -10. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information. +10. Submit your issue. + +11. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information. @@ -171,18 +173,23 @@ If your issue is not actionable, please see :doc:`Help, Support, Mailing Lists, This guideline is extremely important for making the issue tracker a useful tool for the developers. When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see `the issue tracker is not a discussion forum <#the-issue-tracker-is-not-a-discussion-forum>`__). -New issues should not be duplicates of existing issues -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -Before you submit an issue, check to see whether it has already been reported. Search through the existing issues – both open and closed – by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it. If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed. If an issue affects more than one Qubes version, we usually keep only one issue for all versions. The Qubes team will see your comment and reopen the issue, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don’t have anything to add but still want to receive email updates, you can click the “Subscribe” button at the side or bottom of the comments. - Every issue must be of a single type ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Every issue must be exactly one of the following types: a bug report (``bug``), a feature or improvement request (``enhancement``), or a task (``task``). Do not file multi-typed issues. Instead, file multiple issues of distinct types. The Qubes team will classify your issue according to its type. +New issues should not be duplicates of existing issues +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +Before you submit an issue, check to see whether it has already been reported. Search through the existing issues – both open and closed – by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it. + +For bug reports, if you find an issue that is the same as or subsumes yours, leave a comment on the existing bug report issue rather than opening a new one, even if the existing bug report is closed. If a bug report affects more than one Qubes version, we usually keep only one bug report for all versions. The Qubes team will see your comment and reopen the bug report, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don’t have anything to add but still want to receive email updates, you can click the “Subscribe” button at the side or bottom of the comments. + +For feature requests, it depends on what you want to report. If the initial implementation was incomplete or unsuccessful, then please leave a comment on the existing feature request issue, and we will reopen it. However, if the initial implementation of the feature was successful, and you are reporting a problem with the feature that arose later, then please open a separate bug report (if one doesn't already exist for that bug) instead of commenting on the old feature request, as we generally prefer not to reopen old feature requests the initial implemntation of which was successfully completed. + + New issues should include all relevant information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/introduction/support.rst b/introduction/support.rst index f8ecc321..8eb479ba 100644 --- a/introduction/support.rst +++ b/introduction/support.rst @@ -77,7 +77,7 @@ It’s always possible that a bad actor could try to impersonate any member of t Given that there may be impostors and others trying to lead you astray, how should you sort the good advice from the bad? This is up to each individual to decide, but it helps to know that many members of our community have proven themselves knowledgeable through their :doc:`contributions ` to the project. Often, these individuals sign their messages with the same key as (or another key authenticated by) the one they use to :doc:`sign their contributions `. -For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages ` or `contributing to the documentation `__. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify ` that these came from the same keyholder. +For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages ` or :doc:`contributing to the documentation `. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify ` that these came from the same keyholder. Discussion guidelines --------------------- @@ -121,7 +121,7 @@ Report issues and submit changes in the right places ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker ` 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, `submit the change `__. +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 `. Moderation ^^^^^^^^^^ diff --git a/project-security/security-pack.rst b/project-security/security-pack.rst index 915dad59..b187e90c 100644 --- a/project-security/security-pack.rst +++ b/project-security/security-pack.rst @@ -31,7 +31,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and 1. Use Git to clone the qubes-secpack repo. - .. code:: + .. code:: console $ git clone https://github.com/QubesOS/qubes-secpack.git Cloning into 'qubes-secpack'... @@ -44,7 +44,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and 2. Import the included PGP keys. See our `PGP key policies <#pgp-key-policies>`__ for important information about these keys. - .. code:: + .. code:: console $ gpg --import qubes-secpack/keys/*/* gpg: directory `/home/user/.gnupg' created diff --git a/project-security/security.rst b/project-security/security.rst index ae2e6d98..da93b6ca 100644 --- a/project-security/security.rst +++ b/project-security/security.rst @@ -31,7 +31,7 @@ Reporting security issues in Qubes OS If you’ve discovered a security issue affecting Qubes OS, either directly or indirectly (e.g., the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! We promise to take all reported issues seriously. If our investigation confirms that an issue affects Qubes, we will patch it within a reasonable time and release a public `Qubes security bulletin (QSB) `__ that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer. Please use the `Qubes security team PGP key `__ to encrypt your email to this address: -.. code:: console +.. code:: text security at qubes-os dot org diff --git a/project-security/verifying-signatures.rst b/project-security/verifying-signatures.rst index 9c548f13..b03ec0b5 100644 --- a/project-security/verifying-signatures.rst +++ b/project-security/verifying-signatures.rst @@ -178,11 +178,11 @@ Now that you’ve imported the authentic QMSK, set its trust level to “ultimat trust: unknown validity: unknown [ unknown] (1). Qubes Master Signing Key - gpg> fpr + $ gpg> fpr pub 4096R/36879494 2010-04-01 Qubes Master Signing Key Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - gpg> trust + $ gpg> trust pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC trust: unknown validity: unknown [ unknown] (1). Qubes Master Signing Key @@ -206,7 +206,7 @@ Now that you’ve imported the authentic QMSK, set its trust level to “ultimat Please note that the shown key validity is not necessarily correct unless you restart the program. - gpg> q + $ gpg> q Now, when you import any of the release signing keys and many Qubes team member keys, they will already be trusted in virtue of being signed by the QMSK. diff --git a/requirements.txt b/requirements.txt index bf0592f6..3e6ade68 100644 --- a/requirements.txt +++ b/requirements.txt @@ -29,6 +29,7 @@ sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==2.0.0 sphinxcontrib-serializinghtml==2.0.0 +sphinxext-opengraph==0.12.0 sphinxnotes-any==2.5 sphinxnotes-comboroles==1.0 sphinxnotes-strike==1.2.1 diff --git a/user/advanced-topics/bind-dirs.rst b/user/advanced-topics/bind-dirs.rst index c318fc18..5a97b624 100644 --- a/user/advanced-topics/bind-dirs.rst +++ b/user/advanced-topics/bind-dirs.rst @@ -30,7 +30,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f .. code:: console - sudo mkdir -p /rw/config/qubes-bind-dirs.d + $ sudo mkdir -p /rw/config/qubes-bind-dirs.d @@ -38,7 +38,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f .. code:: console - sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf + $ sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf @@ -56,7 +56,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f .. code:: console - sudo mkdir -p /rw/bind-dirs/var/lib/tor + $ sudo mkdir -p /rw/bind-dirs/var/lib/tor @@ -157,7 +157,7 @@ To use this feature, first, enable it: .. code:: console - qvm-service -e my-app-vm custom-persist + $ qvm-service -e my-app-vm custom-persist @@ -165,7 +165,7 @@ Then, configure a persistent directory with ``qvm-features``: .. code:: console - qvm-features my-app-vm custom-persist.my_persistent_dir /var/my_persistent_dir + $ qvm-features my-app-vm custom-persist.my_persistent_dir /var/my_persistent_dir @@ -173,8 +173,8 @@ To re-enable ``/home`` and ``/usr/local`` persistence, just add them to the list .. code:: console - qvm-features my-app-vm custom-persist.home /home - qvm-features my-app-vm custom-persist.usrlocal /usr/local + $ qvm-features my-app-vm custom-persist.home /home + $ qvm-features my-app-vm custom-persist.usrlocal /usr/local @@ -184,8 +184,8 @@ A user may want their bind-dirs to be automatically pre-created in ``/rw/bind-di .. code:: console - qvm-features my-app-vm custom-persist.downloads dir:user:user:0755:/home/user/Downloads - qvm-features my-app-vm custom-persist.my_ssh_known_hosts_file file:user:user:0600:/home/user/.ssh/known_hosts + $ qvm-features my-app-vm custom-persist.downloads dir:user:user:0755:/home/user/Downloads + $ qvm-features my-app-vm custom-persist.my_ssh_known_hosts_file file:user:user:0600:/home/user/.ssh/known_hosts diff --git a/user/advanced-topics/disposable-customization.rst b/user/advanced-topics/disposable-customization.rst index 41360de0..de7cb813 100644 --- a/user/advanced-topics/disposable-customization.rst +++ b/user/advanced-topics/disposable-customization.rst @@ -10,7 +10,7 @@ Introduction ------------ -A :doc:`disposable ` can be based on any :ref:`app qube `. You can also choose to use different :ref:`disposable templates ` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property: +A :doc:`disposable ` can be based on any :term:`app qube`. You can also choose to use different :term:`disposable templates ` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property: .. code:: console @@ -89,17 +89,17 @@ Using named disposables for service qubes ----------------------------------------- -You can use a :ref:`named disposable ` for service qubes (such as those with the ``sys-*`` naming scheme) as long as they are stateless. For example, a ``sys-net`` using DHCP or ``sys-usb`` will work. In most cases ``sys-firewall`` will also work, even if you have configured app qube firewall rules. The only exception is if you require something like VM to VM communication and have manually edited ``iptables`` or other items directly inside the firewall app qube. +You can use a :term:`named disposable` for service qubes (such as those with the ``sys-*`` naming scheme) as long as they are stateless. For example, a ``sys-net`` using DHCP or ``sys-usb`` will work. In most cases ``sys-firewall`` will also work, even if you have configured app qube firewall rules. The only exception is if you require something like VM to VM communication and have manually edited ``iptables`` or other items directly inside the firewall app qube. To create one that has no PCI devices attached, such as for ``sys-firewall``: .. code:: console - qvm-create -C DispVM -l green - qvm-prefs autostart true - qvm-prefs netvm - qvm-prefs provides_network true - qvm-features appmenus-dispvm '' + $ qvm-create -C DispVM -l green + $ qvm-prefs autostart true + $ qvm-prefs netvm + $ qvm-prefs provides_network true + $ qvm-features appmenus-dispvm '' @@ -111,13 +111,13 @@ To create one with a PCI device attached such as for ``sys-net`` or ``sys-usb``, .. code:: console - qvm-create -C DispVM -l red - qvm-prefs virt_mode hvm - qvm-service meminfo-writer off - qvm-pci attach --persistent dom0: - qvm-prefs autostart true - qvm-prefs netvm '' - qvm-features appmenus-dispvm '' + $ qvm-create -C DispVM -l red + $ qvm-prefs virt_mode hvm + $ qvm-service meminfo-writer off + $ qvm-pci attach --persistent dom0: + $ qvm-prefs autostart true + $ qvm-prefs netvm '' + $ qvm-features appmenus-dispvm '' @@ -125,7 +125,7 @@ Optionally, if this disposable will also provide network access to other qubes: .. code:: console - qvm-prefs provides_network true + $ qvm-prefs provides_network true @@ -133,7 +133,7 @@ Next, set the old service qube’s autostart to false, and update any references .. code:: console - qvm-prefs sys-firewall netvm + $ qvm-prefs sys-firewall netvm @@ -143,17 +143,17 @@ Here is an example of a complete ``sys-net`` replacement: .. code:: console - qvm-create -C DispVM -l red sys-net2 - qvm-prefs sys-net2 virt_mode hvm - qvm-service sys-net2 meminfo-writer off - qvm-pci attach --persistent sys-net2 dom0:00_1a.0 - qvm-prefs sys-net2 autostart true - qvm-prefs sys-net2 netvm '' - qvm-features sys-net2 appmenus-dispvm '' - qvm-prefs sys-net2 provides_network true - qvm-prefs sys-net autostart false - qvm-prefs sys-firewall netvm sys-net2 - qubes-prefs clockvm sys-net2 + $ qvm-create -C DispVM -l red sys-net2 + $ qvm-prefs sys-net2 virt_mode hvm + $ qvm-service sys-net2 meminfo-writer off + $ qvm-pci attach --persistent sys-net2 dom0:00_1a.0 + $ qvm-prefs sys-net2 autostart true + $ qvm-prefs sys-net2 netvm '' + $ qvm-features sys-net2 appmenus-dispvm '' + $ qvm-prefs sys-net2 provides_network true + $ qvm-prefs sys-net autostart false + $ qvm-prefs sys-firewall netvm sys-net2 + $ qubes-prefs clockvm sys-net2 diff --git a/user/advanced-topics/gui-configuration.rst b/user/advanced-topics/gui-configuration.rst index efde467d..45a7473f 100644 --- a/user/advanced-topics/gui-configuration.rst +++ b/user/advanced-topics/gui-configuration.rst @@ -16,8 +16,8 @@ To increase the minimum size of the video RAM buffer: .. code:: console - qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024)) - qvm-features dom0 gui-videoram-overhead 0 + $ qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024)) + $ qvm-features dom0 gui-videoram-overhead 0 Where ``$WIDTH`` × ``$HEIGHT`` is the maximum desktop size that you anticipate needing. For example, if you expect to use a 1080p display and a 4k display side-by-side, that is ``(1920 + 3840) × 2160 × 4 / 1024 = 48600``, or slightly more than 48 MiB per qube. After making these adjustments, the qubes need to be restarted. @@ -26,7 +26,7 @@ In the case of multiple display with different orientations or if you plug/unplu .. code:: console - qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e 's/.*current //' -e 's/\,.*//' | awk '{print $1*$3*4/1024}') + $ qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e 's/.*current //' -e 's/\,.*//' | awk '{print $1*$3*4/1024}') The amount of memory allocated per qube is the maximum of: diff --git a/user/advanced-topics/gui-domain.rst b/user/advanced-topics/gui-domain.rst index 5b4fe8e5..6f26e755 100644 --- a/user/advanced-topics/gui-domain.rst +++ b/user/advanced-topics/gui-domain.rst @@ -22,22 +22,22 @@ In ``dom0``, enable the formula for ``sys-gui`` with pillar data: .. code:: console - sudo qubesctl top.enable qvm.sys-gui - sudo qubesctl top.enable qvm.sys-gui pillar=True + $ sudo qubesctl top.enable qvm.sys-gui + $ sudo qubesctl top.enable qvm.sys-gui pillar=True then, execute it: .. code:: console - sudo qubesctl --all state.highstate + $ sudo qubesctl --all state.highstate You can now disable the ``sys-gui`` formula: .. code:: console - sudo qubesctl top.disable qvm.sys-gui + $ sudo qubesctl top.disable qvm.sys-gui At this point, you need to shutdown all your running qubes as the ``default_guivm`` qubes global property has been set to ``sys-gui``. In order to use ``sys-gui`` as GUI domain, you need to logout and, in the top right corner, select ``lightdm`` session type to **GUI domain (sys-gui)**. Once logged, you are running ``sys-gui`` as fullscreen window and you can perform any operation as if you would be in ``dom0`` desktop. @@ -58,29 +58,29 @@ In ``dom0``, enable the formula for ``sys-gui-gpu`` with pillar data: .. code:: console - sudo qubesctl top.enable qvm.sys-gui-gpu - sudo qubesctl top.enable qvm.sys-gui-gpu pillar=True + $ sudo qubesctl top.enable qvm.sys-gui-gpu + $ sudo qubesctl top.enable qvm.sys-gui-gpu pillar=True then, execute it: .. code:: console - sudo qubesctl --all state.highstate + $ sudo qubesctl --all state.highstate You can now disable the ``sys-gui-gpu`` formula: .. code:: console - sudo qubesctl top.disable qvm.sys-gui-gpu + $ sudo qubesctl top.disable qvm.sys-gui-gpu One more step is needed: attaching the actual GPU to ``sys-gui-gpu``. This can be done either manually via ``qvm-pci`` (remember to enable permissive option), or via: .. code:: console - sudo qubesctl state.sls qvm.sys-gui-gpu-attach-gpu + $ sudo qubesctl state.sls qvm.sys-gui-gpu-attach-gpu The latter option assumes Intel graphics card (it has hardcoded PCI address). If you don’t have Intel graphics card, please use the former method with ``qvm-pci`` (see :doc:`How to use PCI devices `). @@ -105,29 +105,29 @@ In ``dom0``, enable the formula for ``sys-gui-vnc`` with pillar data: .. code:: console - sudo qubesctl top.enable qvm.sys-gui-vnc - sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True + $ sudo qubesctl top.enable qvm.sys-gui-vnc + $ sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True then, execute it: .. code:: console - sudo qubesctl --all state.highstate + $ sudo qubesctl --all state.highstate You can now disable the ``sys-gui-vnc`` formula: .. code:: console - sudo qubesctl top.disable qvm.sys-gui-vnc + $ sudo qubesctl top.disable qvm.sys-gui-vnc At this point, you need to shutdown all your running qubes as the ``default_guivm`` qubes global property has been set to ``sys-gui-vnc``. Then, you can start ``sys-gui-vnc``: .. code:: console - qvm-start sys-gui-vnc + $ qvm-start sys-gui-vnc A VNC server session is running on ``localhost:5900`` in ``sys-gui-vnc``. In order to reach the ``VNC`` server, we encourage to not connect ``sys-gui-vnc`` to a ``NetVM`` but rather to use another qube for remote access, say ``sys-remote``. First, you need to bind port 5900 of ``sys-gui-vnc`` into a ``sys-remote`` local port (you may want to use another port than 5900 to reach ``sys-remote`` from the outside). For that, use ``qubes.ConnectTCP`` RPC service (see :doc:`Firewall `. Then, you can use any ``VNC`` client to connect to you ``sys-remote`` on the chosen local port (5900 if you kept the default one). For the first connection, you will reach ``lightdm`` for which you can log as ``user`` where ``user`` refers to the first ``dom0`` user in ``qubes`` group and with corresponding ``dom0`` password. @@ -188,21 +188,21 @@ Set ``default_guivm`` as ``dom0``: .. code:: console - qubes-prefs default_guivm dom0 + $ qubes-prefs default_guivm dom0 and for every selected qubes not using default value for GUI domain property, for example with a qube ``personal``: .. code:: console - qvm-prefs personal guivm dom0 + $ qvm-prefs personal guivm dom0 You are now able to delete the GUI domain, for example ``sys-gui-gpu``: .. code:: console - qvm-remove -f sys-gui-gpu + $ qvm-remove -f sys-gui-gpu .. |sys-gui| image:: /attachment/posts/guivm-hybrid.png diff --git a/user/advanced-topics/how-to-install-software-in-dom0.rst b/user/advanced-topics/how-to-install-software-in-dom0.rst index e2c13d7f..5aed0d8e 100644 --- a/user/advanced-topics/how-to-install-software-in-dom0.rst +++ b/user/advanced-topics/how-to-install-software-in-dom0.rst @@ -48,7 +48,7 @@ To downgrade a specific package in dom0: .. code:: console - sudo qubes-dom0-update --action=downgrade package-version + $ sudo qubes-dom0-update --action=downgrade package-version @@ -60,7 +60,7 @@ To re-install a package in dom0: .. code:: console - sudo qubes-dom0-update --action=reinstall package + $ sudo qubes-dom0-update --action=reinstall package @@ -72,7 +72,7 @@ If you’ve installed a package such as anti-evil-maid, you can remove it with t .. code:: console - sudo dnf remove anti-evil-maid + $ sudo dnf remove anti-evil-maid @@ -96,9 +96,9 @@ To temporarily enable any of these repos, use the ``--enablerepo=`` o .. code:: console - sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing - sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing - sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable + $ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing + $ sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing + $ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable @@ -154,7 +154,7 @@ Example .. code:: console - sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm + $ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm @@ -168,7 +168,7 @@ Replace the example version numbers with the one you are upgrading to. .. code:: console - sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64 + $ sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64 @@ -178,7 +178,7 @@ Grub2 .. code:: console - sudo grub2-mkconfig -o /boot/grub2/grub.cfg + $ sudo grub2-mkconfig -o /boot/grub2/grub.cfg @@ -192,14 +192,25 @@ Changing default kernel This section describes changing the default kernel in dom0. It is sometimes needed if you have upgraded to a newer kernel and are having problems booting, for example. On the next kernel update, the default will revert to the newest. + .. code:: console - sudo nano /etc/default/grub - [update the following two lines, add if needed] + $ sudo nano /etc/default/grub + + +Update the following two lines, add if needed: + +.. code:: bash + GRUB_DISABLE_SUBMENU=false GRUB_SAVEDEFAULT=true - [save and exit nano] - sudo grub2-mkconfig -o /boot/grub2/grub.cfg + + +Save and exit nano. Regenerate the GRUB 2 configuration. + +.. code:: console + + $ sudo grub2-mkconfig -o /boot/grub2/grub.cfg @@ -211,7 +222,7 @@ Updating over Tor Requires installed `Whonix `__. -Go to Qubes VM Manager -> System -> Global Settings. See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix. +Go to :menuselection:`Qubes VM Manager --> System --> Global Settings`. See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix. :menuselection:`Qubes VM Manager --> System --> Global Settings --> UpdateVM --> sys-whonix` diff --git a/user/advanced-topics/installing-contributed-packages.rst b/user/advanced-topics/installing-contributed-packages.rst index 09b9f211..07f6cc41 100644 --- a/user/advanced-topics/installing-contributed-packages.rst +++ b/user/advanced-topics/installing-contributed-packages.rst @@ -22,7 +22,7 @@ In dom0, use ``qubes-dom0-update``: .. code:: console - sudo qubes-dom0-update qubes-repo-contrib + $ sudo qubes-dom0-update qubes-repo-contrib In a Fedora-based template, use ``dnf``: @@ -31,7 +31,7 @@ In a Fedora-based template, use ``dnf``: .. code:: console - sudo dnf install qubes-repo-contrib + $ sudo dnf install qubes-repo-contrib In a Debian-based template, use ``apt``: @@ -40,7 +40,7 @@ In a Debian-based template, use ``apt``: .. code:: console - sudo apt update && sudo apt install qubes-repo-contrib + $ sudo apt update && sudo apt install qubes-repo-contrib The new repository definition will be in the usual location for your distro, and it will follow the naming pattern ``qubes-contrib-*``, depending on your Qubes release and whether it is in dom0 or a template. For example, in a Fedora template on Qubes 4.0, the new repository definition would be: @@ -65,7 +65,7 @@ For example, to install ``qvm-screenshot-tool`` in dom0: .. code:: console - sudo qubes-dom0-update --clean qvm-screenshot-tool + $ sudo qubes-dom0-update --clean qvm-screenshot-tool Please see the package’s README for specific installation and setup instructions. diff --git a/user/advanced-topics/kde.rst b/user/advanced-topics/kde.rst index d2f13cbb..71cd5835 100644 --- a/user/advanced-topics/kde.rst +++ b/user/advanced-topics/kde.rst @@ -37,7 +37,7 @@ KDE is very customisable, and there is a range of widgets to use. If you want to -This allows you to edit the menu as you will. When editing the Menu *DO NOT use the option under “Edit->Restore to System Menu”* +This allows you to edit the menu as you will. When editing the Menu *DO NOT use the option under* :menuselection:`Edit --> Restore to System Menu` Login manager ^^^^^^^^^^^^^ @@ -99,7 +99,7 @@ You can also use ``kstart`` to control virtual desktop placement like this: .. code:: console - kstart --desktop 3 --windowclass -q --tray -a '' + $ kstart --desktop 3 --windowclass -q --tray -a '' @@ -117,6 +117,6 @@ The safest way to remove (most of) KDE is: .. code:: console - sudo dnf remove kdelibs plasma-workspace + $ sudo dnf remove kdelibs plasma-workspace diff --git a/user/advanced-topics/managing-vm-kernels.rst b/user/advanced-topics/managing-vm-kernels.rst index 55731ef9..3a5cfb24 100644 --- a/user/advanced-topics/managing-vm-kernels.rst +++ b/user/advanced-topics/managing-vm-kernels.rst @@ -246,8 +246,8 @@ Both debian-9 and fedora-26 templates already have grub and related tools preins .. code:: console - qvm-prefs virt_mode hvm - qvm-prefs kernel '' + $ qvm-prefs virt_mode hvm + $ qvm-prefs kernel '' @@ -263,7 +263,7 @@ If you are using a distribution kernel package (``kernel`` package), the initram .. code:: console - sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64 + $ sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64 @@ -271,7 +271,7 @@ Once the kernel is installed, you need to setup ``grub2`` by running: .. code:: console - sudo grub2-install /dev/xvda + $ sudo grub2-install /dev/xvda @@ -279,13 +279,13 @@ Finally, you need to create a GRUB configuration. You may want to adjust some se .. code:: console - sudo grub2-mkconfig -o /boot/grub2/grub.cfg + $ sudo grub2-mkconfig -o /boot/grub2/grub.cfg You can safely ignore this error message: -.. code:: console +.. code:: output grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map @@ -321,7 +321,7 @@ Install distribution kernel image, kernel headers and the grub. .. code:: console - sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support + $ sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support @@ -329,7 +329,7 @@ If you are doing that on a qube based on “Debian Minimal” template, a grub g .. code:: console - sudo grub-install /dev/xvda + $ sudo grub-install /dev/xvda @@ -339,7 +339,7 @@ You may want to adjust some settings in ``/etc/default/grub`` (or better ``/etc/ Then shutdown the VM. -Go to dom0 -> Qubes VM Manger -> right click on the VM -> Qube settings -> Advanced +Go to dom0: :menuselection:`Qubes VM Manager --> right click on the VM --> Qube settings --> Advanced` Depends on ``Virtualization`` mode setting: @@ -383,7 +383,7 @@ Run DKMS. Replace this with actual kernel version. .. code:: console - sudo dkms autoinstall -k + $ sudo dkms autoinstall -k For example. @@ -392,7 +392,7 @@ For example. .. code:: console - sudo dkms autoinstall -k 4.19.0-6-amd64 + $ sudo dkms autoinstall -k 4.19.0-6-amd64 Update initramfs. @@ -401,7 +401,7 @@ Update initramfs. .. code:: console - sudo update-initramfs -u + $ sudo update-initramfs -u The output should look like this: diff --git a/user/advanced-topics/resize-disk-image.rst b/user/advanced-topics/resize-disk-image.rst index 9d87b527..5dcdc36a 100644 --- a/user/advanced-topics/resize-disk-image.rst +++ b/user/advanced-topics/resize-disk-image.rst @@ -6,10 +6,6 @@ Resize disk image This page is intended for advanced users. -Resizing Disk Images --------------------- - - By default Qubes uses thin volumes for the disk images. This means that space is not actually allocated for the volume until it is used. So a 2GB private volume with 100M of files will only use 100M. This explains how you can have *many* qubes with large private volumes on quite a small disk. This is called over provisioning. You should keep an eye on the disk-space widget to see how much free space you actually have. It is easy to increase the size of disk images. There are risks attached to reducing the size of an image, and in general you should not need to do this. @@ -42,7 +38,7 @@ Use either GUI tool Qube Settings (``qubes-vm-settings``) or the CLI tool ``qvm- .. code:: console - qvm-volume extend :root + $ qvm-volume extend :root @@ -50,7 +46,7 @@ OR .. code:: console - qvm-volume extend :private + $ qvm-volume extend :private @@ -92,10 +88,10 @@ FreeBSD .. code:: console - gpart recover ada0 - sysctl kern.geom.debugflags=0x10 - gpart resize -i index ada0 - zpool online -e poolname ada0 + $ gpart recover ada0 + $ sysctl kern.geom.debugflags=0x10 + $ gpart resize -i index ada0 + $ zpool online -e poolname ada0 @@ -117,8 +113,8 @@ Or you can take the risk of reducing the size of the disk. For example, to reduc .. code:: console - qvm-shutdown qube1 - sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private + $ qvm-shutdown qube1 + $ sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private diff --git a/user/advanced-topics/secondary-storage.rst b/user/advanced-topics/secondary-storage.rst index 8c4c4382..36018085 100644 --- a/user/advanced-topics/secondary-storage.rst +++ b/user/advanced-topics/secondary-storage.rst @@ -22,7 +22,7 @@ You can query qvm-pool to list available storage drivers: .. code:: console - qvm-pool --help-drivers + $ qvm-pool --help-drivers qvm-pool driver explanation: @@ -50,18 +50,15 @@ First, collect some information in a dom0 terminal: .. code:: console - sudo pvs - sudo lvs + $ sudo pvs + $ sudo lvs -Take note of the VG and thin pool names for your second drive., then register it with Qubes: +Take note of the VG and thin pool names for your second drive, then register it with Qubes, where ```` is a freely chosen pool name, ```` is LVM volume group name and ```` is LVM thin pool name: .. code:: console - # is a freely chosen pool name - # is LVM volume group name - # is LVM thin pool name - qvm-pool --add lvm_thin -o volume_group=,thin_pool=,revisions_to_keep=2 + $ qvm-pool --add lvm_thin -o volume_group=,thin_pool=,revisions_to_keep=2 @@ -75,17 +72,15 @@ It is possible to use an existing Btrfs storage if it is configured. In dom0, av .. code:: console - mount -t btrfs - btrfs show filesystem + $ mount -t btrfs + $ btrfs show filesystem -To register the storage to qubes: +To register the storage to qubes use the following command where ```` is a freely chosen pool name adn ```` is the mounted path to the second btrfs storage: .. code:: console - # is a freely chosen pool name - # is the mounted path to the second btrfs storage - qvm-pool --add file-reflink -o dir_path=,revisions_to_keep=2 + $ qvm-pool --add file-reflink -o dir_path=,revisions_to_keep=2 Using the new pool @@ -96,22 +91,22 @@ Now, you can create qubes in that pool: .. code:: console - qvm-create -P --label red + $ qvm-create -P --label red It isn’t possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one: .. code:: console - qvm-clone -P - qvm-remove + $ qvm-clone -P + $ qvm-remove If that was a template, or other qube referenced elsewhere (netVM or such), you will need to adjust those references manually after moving. For example: .. code:: console - qvm-prefs template + $ qvm-prefs template Example setup of second drive. @@ -122,8 +117,8 @@ Assuming the secondary hard disk is at /dev/sdb , you can encrypt the drive as f .. code:: console - sudo cryptsetup luksFormat --sector-size=512 /dev/sdb - sudo blkid /dev/sdb + $ sudo cryptsetup luksFormat --sector-size=512 /dev/sdb + $ sudo blkid /dev/sdb @@ -146,28 +141,28 @@ First create the physical volume: .. code:: console - sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde + $ sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde Then create the LVM volume group, we will use for example “qubes” as the : .. code:: console - sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde + $ sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde And then use “poolhd0” as the (LVM thin pool name): .. code:: console - sudo lvcreate -T -n poolhd0 -l +100%FREE qubes + $ sudo lvcreate -T -n poolhd0 -l +100%FREE qubes Finally we will tell Qubes to add a new pool on the just created thin pool: .. code:: console - qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2 + $ qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2 For Btrfs @@ -179,22 +174,22 @@ First create the physical volume: .. code:: console # ` page for examples. +.. figure:: /attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png + :alt: + + Trying to enter fullscreen mode from a qube fails + + While browsing the page :doc:`/introduction/video-tours` in a disposable qube (*disp5596*), the user tries to enter fullscreen mode from the qube itself. Even if fullscreen mode is selected, the top bar of dom0 is still present. The window is decorated in red, providing the name of the qube. Why is fullscreen mode potentially dangerous? --------------------------------------------- +If one allowed a qube to “own” the full screen, e.g. to show a movie on a full screen, it might not be possible for the user to know if the application or the qube really “released” the full screen, or if it has started emulating the whole desktop and is pretending to be the trusted Window Manager, drawing shapes on the screen that look like other windows, belonging to other domains (e.g. to trick the user into entering a secret passphrase into a window that looks like belonging to some trusted domain). -If one allowed one of the VMs to “own” the full screen, e.g. to show a movie on a full screen, it might not be possible for the user to know if the applications/VM really “released” the full screen, or if it has started emulating the whole desktop and is pretending to be the trusted Window Manager, drawing shapes on the screen that look e.g. like other windows, belonging to other domains (e.g. to trick the user into entering a secret passphrase into a window that looks like belonging to some trusted domain). +That's why fullscreen mode is not allowed by default, when requested from a qube. + +.. _secure-use-of-fullscreen-mode: Secure use of fullscreen mode ----------------------------- +However, it is possible to deal with fullscreen mode in a secure way assuming there are mechanisms that can be used at any time to switch between windows or show the full desktop and that cannot be intercepted by the qube. The simplest example is the use of :kbd:`Alt` + :kbd:`Tab` for switching between windows, which is a shortcut handled by dom0. -However, it is possible to deal with fullscreen mode in a secure way assuming there are mechanisms that can be used at any time to switch between windows or show the full desktop and that cannot be intercepted by the VM. The simplest example is the use of Alt+Tab for switching between windows, which is a shortcut handled by dom0. +Other examples of such mechanisms are the KDE “Present Windows” and “Desktop Grid” effects, which are similar to Mac’s “Expose” effect, and which can be used to immediately detect potential “GUI forgery”, as they cannot be intercepted by any of the qube (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the qube cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (:menuselection:`System Settings --> Desktop --> Enable Desktop Effects`), which is recommended anyway. By default, they are triggered by the :kbd:`Ctrl` + :kbd:`F8` and :kbd:`Ctrl` + :kbd:`F9` key combinations, but can also be reassigned to other shortcuts. -Other examples such mechanisms are the KDE “Present Windows” and “Desktop Grid” effects, which are similar to Mac’s “Expose” effect, and which can be used to immediately detect potential “GUI forgery”, as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -> Desktop -> Enable Desktop Effects), which is recommended anyway. By default, they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. +Safely enabling fullscreen mode for a selected window +----------------------------------------------------- -Enabling fullscreen mode for select VMs ---------------------------------------- +You can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window’s title bar and selecting :guilabel:`Fullscreen` or pressing :kbd:`Alt` + :kbd:`F11`. This functionality should still be considered safe, since a qube window still can’t voluntarily enter fullscreen mode. The user must select this option from the trusted window manager in dom0. To exit fullscreen mode from here, press :kbd:`Alt` + :kbd:`Space` to bring up the title bar menu again, then select :guilabel:`Leave Fullscreen` or simply press :kbd:`Alt` + :kbd:`F11`. For :ref:`standalone HVMs `, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4. +.. image:: /attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png + :alt: -You can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window’s title bar and selecting “Fullscreen” or pressing ``alt`` + ``f11``. This functionality should still be considered safe, since a VM window still can’t voluntarily enter fullscreen mode. The user must select this option from the trusted window manager in dom0. To exit fullscreen mode from here, press ``alt`` + ``space`` to bring up the title bar menu again, then select “Leave Fullscreen” or simply press ``alt`` + ``f11``. For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4. +Enabling fullscreen mode from a selected qube +--------------------------------------------- -As an alternative to the Xfce4 method, you can enable fullscreen mode for select VMs by creating the following entry in the ``/etc/qubes/guid.conf`` file in dom0: +.. warning:: Be sure to read :ref:`secure-use-of-fullscreen-mode` first. -.. code:: text +As an alternative to the Xfce4 method, you can enable fullscreen mode for selected qubes by using the `gui-allow-fullscreen `__ feature of a qube. - VM: { - personal: { - allow_fullscreen = true; - }; - }; +Be sure to restart the qube after modifying this feature, for the changes to take effect. +With the qube's settings +^^^^^^^^^^^^^^^^^^^^^^^^ +In the qube's settings, go to the second tab, called :guilabel:`Advanced`. Under :guilabel:`Window options`, change the value of :guilabel:`Allow fullscreen`, from :guilabel:`(use system default) (current)` to :guilabel:`disallow`. -The string ‘personal’ above is an example only and should be replaced by the actual name of the VM for which you want to enable this functionality. +.. image:: /attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png + :alt: -**Note:** There should be only one ``VM: {}`` block in the file (or you will `get into problems `__). +With the command-line, targeting the qube +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -One can also enable this functionality for all the VMs globally in the same file, by modifying the ‘global’ section: +In dom0, run the following command, replacing :samp:`{}` by the actual name of the qube: -.. code:: text +.. code:: console - global: { - # default values - allow_fullscreen = true; - #allow_utf8_titles = false; - #secure_copy_sequence = "Ctrl-Shift-c"; - #secure_paste_sequence = "Ctrl-Shift-v"; - #windows_count_limit = 500; - }; + [user@dom0] $ qvm-features gui-allow-fullscreen 1 +Enabling fullscreen mode for every qubes +---------------------------------------- +.. warning:: Be sure to read :ref:`secure-use-of-fullscreen-mode` first. + +With Qubes Global Config +^^^^^^^^^^^^^^^^^^^^^^^^ + +Open :guilabel:`Qubes Global Config`. In the first tab (called :guilabel:`General settings`), under the :guilabel:`Window management`: section, change the value of :guilabel:`Fullscreen mode`, from :guilabel:`default (disallow)` to :guilabel:`allow`. + +.. image:: /attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png + :alt: + +With the command-line, on dom0 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In dom0, run the following command: + +.. code:: console + + [user@dom0] $ qvm-features dom0 gui-default-allow-fullscreen 1 -Be sure to restart the VM(s) after modifying this file, for the changes to take effect. diff --git a/user/how-to-guides/how-to-install-software.rst b/user/how-to-guides/how-to-install-software.rst index 35934c9d..e2ae50c8 100644 --- a/user/how-to-guides/how-to-install-software.rst +++ b/user/how-to-guides/how-to-install-software.rst @@ -3,51 +3,46 @@ How to install software ======================= -When you wish to install software in Qubes OS, you should generally install it in a :ref:`template `. For installing templates themselves, see :ref:`how to install a template `. Advanced users may also be interested in learning how to install software in :doc:`standalones ` and :doc:`dom0 `. +When you wish to install software in Qubes OS, you should generally install it in a :term:`template`. For installing templates themselves, see :ref:`how to install a template `. Advanced users may also be interested in learning how to install software in :doc:`standalones ` and :doc:`dom0 `. Qubes OS is effectively a “meta” operating system (OS) that can run almost any arbitrary OS inside of itself. For example, the way software is normally installed in a Linux distribution (“distro”) is quite different from the way software is normally installed in Windows. This isn’t up to Qubes. Qubes is just the framework in which you’re running these other OSes. Therefore, if you want to install software in a Linux template, for example, you should do so in whatever way is normal for that Linux distro. Most Linux software is distributed via `packages `__, which are stored in `software repositories `__ (“repos”). `Package managers `__ handle downloading, installing, updating, and removing packages. (Again, none of this is Qubes-specific.) If you’re not familiar with how software is normally installed in Linux distros via package managers or the software you want doesn’t seem to be available in your distro’s repos (or you’re in another situation not covered on this page), please read this `community guide to installing software in Qubes `__. The following instructions explain how to permanently install new software in a template. There are different instructions for software from the default repositories and all other software. (If you’re not sure, try the default repositories first.) +.. installing-software-from-default-repositories: + Installing software from default repositories --------------------------------------------- - 1. Start the template. 2. Start either a terminal (e.g. ``gnome-terminal``) or a dedicated software management application, such as ``gpk-application``. 3. Install software as normally instructed inside that operating system, e.g.: - - Fedora: ``sudo dnf install `` - - - Debian: ``sudo apt install `` - + - Fedora: :samp:`sudo dnf install {}` + - Debian: :samp:`sudo apt install {}` 4. Shut down the template. 5. Restart all qubes based on the template. -6. (Recommended) In the relevant qubes’ **Settings > Applications** tab, select the new application(s) from the list, and press **OK**. These new shortcuts will appear in the Applications Menu. (If you encounter problems, see :doc:`here ` for troubleshooting.) - - +6. (Recommended) In the relevant qubes’ :menuselection:`Settings --> Applications` tab, select the new application(s) from the list, and press :guilabel:`OK`. These new shortcuts will appear in the Applications Menu. (If you encounter problems, see :ref:`app-menu-troubleshooting`) .. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png :alt: The Applications tab in Qube Settings - + Installing software from other sources -------------------------------------- - Some software is not available from the default repositories and must be downloaded and installed from another source. Depending on the installation method, you may either use the updates proxy or direct networking. Using the updates proxy ^^^^^^^^^^^^^^^^^^^^^^^ - If you are still using the distribution package manager, updates will likely still work over the updates proxy without needing to give the TemplateVM direct network access. If you are using another installation method fetching remote resources, you might still be able to use the updates proxy by making the tools aware of the proxy. For many tools, it is enough to export the following environment variables in your shell session before proceeding: @@ -59,44 +54,44 @@ If you are using another installation method fetching remote resources, you migh ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \ NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY - 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 `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. 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. 1. (Recommended) Clone the desired template (since this new template will probably be less trusted than the original). -2. (Recommended) In the new template’s **Settings > Basic** tab, change the color label from black to red (or another color that signifies to you that the template is less trusted). +2. (Recommended) In the new template’s :menuselection:`Settings --> Basic` tab, change the color :guilabel:`label` from :guilabel:`black` to :guilabel:`red` (or another color that signifies to you that the template is less trusted). -3. In the new template’s **Settings > Basic** tab, change the **Networking** value from ``default (none) (current)`` to ``sys-firewall`` (or whichever network-providing qube you wish to use). +3. In the new template’s :menuselection:`Settings --> Basic` tab, change the :guilabel:`Networking` value from :guilabel:`default (none) (current)` to :guilabel:`sys-firewall` (or whichever network-providing qube you wish to use). -4. (Recommended) In the new template’s **Settings > Firewall rules** tab, select “Limit outgoing Internet connections to…” and tick “Allow full access for 5 min.” (This can help in case you forget to remove network access later.) +4. (Recommended) In the new template’s :menuselection:`Settings --> Firewall rules` tab: -5. Follow the normal instructions for installing your software in the new template. For example, open a terminal and enter the commands as instructed. **Warning:** If you don’t fully understand the commands you’re entering, then this can be extremely risky, and the template should be regarded as *completely untrusted*. + 1. select :guilabel:`Limit outgoing Internet connections to…` + 2. tick :guilabel:`Allow full access for 5 min.` (This can help in case you forget to remove network access later.) -6. (Recommended) In the new template’s **Settings > Basic** tab, change the **Networking** value from ``sys-firewall (current)`` (or whichever network-providing qube you chose) back to ``default (none)``. +5. Follow the normal instructions for installing your software in the new template. For example, open a terminal and enter the commands as instructed. + + .. warning:: If you don’t fully understand the commands you’re entering, then this can be extremely risky, and the template should be regarded as *completely untrusted*. + +6. (Recommended) In the new template’s :menuselection:`Settings --> Basic` tab, change the :guilabel:`Networking` value from :guilabel:`sys-firewall (current)` (or whichever network-providing qube you chose) back to :guilabel:`default (none)`. 7. Shut down the new template. 8. Create or assign your desired app qubes to use the new template. If any app qubes were already assigned to the new template, restart them. -9. (Recommended) In the relevant qubes’ **Settings > Applications** tab, select the new application(s) from the list, and press **OK**. These new shortcuts will appear in the Applications Menu. (If you encounter problems, see :doc:`here ` for troubleshooting.) - - - -.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png - :alt: The Applications tab in Qube Settings +9. (Recommended) In the relevant qubes’ :menuselection:`Settings --> Applications` tab, select the new application(s) from the list, and press :guilabel:`OK`. These new shortcuts will appear in the Applications Menu. (If you encounter problems, see :ref:`app-menu-troubleshooting`) +.. image:: /attachment/doc/r4.1-dom0-appmenu-select.png + :alt: + Troubleshooting --------------- - If things are still not working as expected: - Review the instructions very carefully, making sure you follow each step. @@ -111,38 +106,31 @@ If things are still not working as expected: - :doc:`Ask for help. ` - - How to update software ---------------------- - -Please see :doc:`How to Update `. +Please see :doc:`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 `updates-proxy <#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 `installing software from default repositories <#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 `installing software from other sources <#installing-software-from-other-sources>`__. Advanced -------- - The following sections cover advanced topics pertaining to installing and updating software in qubes. Testing repositories ^^^^^^^^^^^^^^^^^^^^ - If you wish to install updates that are still in :doc:`testing `, you must enable the appropriate testing repositories. -**Note:** The following repos are in templates and standalones. For dom0 testing repos, see :ref:`here `. For testing new templates, please see :ref:`here `. +.. note:: The following repos are in templates and standalones. For dom0 testing repos, see :ref:`user/advanced-topics/how-to-install-software-in-dom0:testing repositories`. For testing new templates, please see :ref:`user/downloading-installing-upgrading/testing:templates`. Fedora ^^^^^^ - There are three Qubes VM testing repositories (where ``*`` denotes the Release): - ``qubes-vm-*-current-testing`` – testing packages that will eventually land in the stable (``current``) repository @@ -151,25 +139,20 @@ There are three Qubes VM testing repositories (where ``*`` denotes the Release): - ``qubes-vm-*-unstable`` – packages that are not intended to land in the stable (``qubes-vm-*-current``) repository; mostly experimental debugging packages - - To temporarily enable any of these repos, use the ``--enablerepo=`` option. Example commands: .. code:: console - sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing - sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing - sudo dnf upgrade --enablerepo=qubes-vm-*-unstable + $ sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing + $ sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing + $ sudo dnf upgrade --enablerepo=qubes-vm-*-unstable - - -To enable or disable any of these repos permanently, change the corresponding ``enabled`` value to ``1`` in ``/etc/yum.repos.d/qubes-*.repo``. +To enable or disable any of these repos permanently, change the corresponding ``enabled`` value to ``1`` in :file:`/etc/yum.repos.d/qubes-*.repo`. Debian ^^^^^^ - -Debian also has three Qubes VM testing repositories (where ``*`` denotes the Release): +Debian also has three Qubes VM testing repositories (where ``*`` denotes the Debian codename, i.e. "|debian-codename|"): - ``*-testing`` – testing packages that will eventually land in the stable (``current``) repository @@ -177,29 +160,26 @@ Debian also has three Qubes VM testing repositories (where ``*`` denotes the Rel - ``*-unstable`` – packages that are not intended to land in the stable repository; mostly experimental debugging packages - - -To enable or disable any of these repos permanently, uncomment the corresponding ``deb`` line in ``/etc/apt/sources.list.d/qubes-r*.list``. +To enable or disable any of these repos permanently, uncomment the corresponding ``deb`` line in :file:`/etc/apt/sources.list.d/qubes-r4.list`. Standalones ^^^^^^^^^^^ -The process for installing and updating software in :ref:`standalones ` is the same as described above for templates, except no qubes are based on standalones, so there are no other qubes to restart. +The process for installing and updating software in :term:`standalones ` is the same as described above for templates, except no qubes are based on standalones, so there are no other qubes to restart. RPMFusion for Fedora templates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you would like to enable the `RPM Fusion `__ repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see `RPM Fusion `__ for details): +If you would like to enable the `RPM Fusion `__ repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see `RPM Fusion `__ for details): .. code:: console - sudo dnf config-manager setopt rpmfusion-free.enabled=1 - sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1 - sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1 - sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1 - sudo dnf upgrade --refresh + $ sudo dnf config-manager setopt rpmfusion-free.enabled=1 + $ sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1 + $ sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1 + $ sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1 + $ sudo dnf upgrade --refresh @@ -208,7 +188,6 @@ This will permanently enable the RPM Fusion repos. If you install software from Reverting changes to a template ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Perhaps you’ve just updated your template, and the update broke your template. Or perhaps you’ve made a terrible mistake, like accidentally confirming the installation of an unsigned package that could be malicious. If you want to undo changes to a template, there are three basic methods: 1. **Root revert.** This is appropriate for misconfigurations, but not for security concerns. It will preserve your customizations. @@ -217,13 +196,10 @@ Perhaps you’ve just updated your template, and the update broke your template. 3. **Full revert.** This is appropriate for both misconfigurations and security concerns, and it can preserve your customizations. However, it is a bit more complex. - - Root revert ^^^^^^^^^^^ - -**Important:** This command will roll back any changes made *during the last time the template was run, but* **not** *before.* This means that if you have already restarted the template, using this command is unlikely to help, and you’ll likely want to reinstall it from the repository instead. On the other hand, if the template is already broken or compromised, it won’t hurt to try reverting first. Just make sure to **back up** all of your data and changes first! +.. important:: This command will roll back any changes made *during the last time the template was run, but* **not** *before.* This means that if you have already restarted the template, using this command is unlikely to help, and you’ll likely want to reinstall it from the repository instead. On the other hand, if the template is already broken or compromised, it won’t hurt to try reverting first. Just make sure to **back up** all of your data and changes first! 1. Shut down ``