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

Adding rst_epilog, better markup on some pages

Browse source 
Using more appropriate markup and some substitution, mostly on:

* `how-to-install-software.rst`
* `app-menu-shortcut-troubleshooting.rst`
This commit is contained in:
parulin 2025-07-27 10:19:56 -04:00
parent bac93bcb1d
commit 844c9f3caf
No known key found for this signature in database
GPG key ID: BC3830B42F4BF1F5
4 changed files with 62 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

5
conf.py
View file

@ -87,6 +87,11 @@ gettext_compact = False
locale_dirs = ['_translated'] locale_dirs = ['_translated']
rst_epilog = """
.. |debian-codename| replace:: bookworm
.. |debian-version| replace:: 12
"""
# from https://gist.github.com/ehles/bed012d78aad5d3cd6c35a49bef32f9f # from https://gist.github.com/ehles/bed012d78aad5d3cd6c35a49bef32f9f
def align(argument): def align(argument):
"""Conversion function for the "align" option.""" """Conversion function for the "align" option."""

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

@ -2,52 +2,46 @@
How to install software How to install software
======================= =======================
When you wish to install software in Qubes OS, you should generally install it in a :ref:`user/reference/glossary:template`. For installing templates themselves, see :ref:`how to install a template <user/templates/templates:installing>`. Advanced users may also be interested in learning how to install software in :doc:`standalones </user/advanced-topics/standalones-and-hvms>` and :doc:`/user/advanced-topics/how-to-install-software-in-dom0`.
When you wish to install software in Qubes OS, you should generally install it in a :ref:`template <user/reference/glossary:template>`. For installing templates themselves, see :ref:`how to install a template <user/templates/templates:installing>`. Advanced users may also be interested in learning how to install software in :doc:`standalones </user/advanced-topics/standalones-and-hvms>` and :doc:`dom0 </user/advanced-topics/how-to-install-software-in-dom0>`.
Qubes OS is effectively a “meta” operating system (OS) that can run almost any arbitrary OS inside of itself. For example, the way software is normally installed in a Linux distribution (“distro”) is quite different from the way software is normally installed in Windows. This isn’t up to Qubes. Qubes is just the framework in which you’re running these other OSes. Therefore, if you want to install software in a Linux template, for example, you should do so in whatever way is normal for that Linux distro. Most Linux software is distributed via `packages <https://en.wikipedia.org/wiki/Package_format>`__, which are stored in `software repositories <https://en.wikipedia.org/wiki/Software_repository>`__ (“repos”). `Package managers <https://en.wikipedia.org/wiki/Package_manager>`__ handle downloading, installing, updating, and removing packages. (Again, none of this is Qubes-specific.) If you’re not familiar with how software is normally installed in Linux distros via package managers or the software you want doesn’t seem to be available in your distro’s repos (or you’re in another situation not covered on this page), please read this `community guide to installing software in Qubes <https://forum.qubes-os.org/t/9991/>`__. Qubes OS is effectively a “meta” operating system (OS) that can run almost any arbitrary OS inside of itself. For example, the way software is normally installed in a Linux distribution (“distro”) is quite different from the way software is normally installed in Windows. This isn’t up to Qubes. Qubes is just the framework in which you’re running these other OSes. Therefore, if you want to install software in a Linux template, for example, you should do so in whatever way is normal for that Linux distro. Most Linux software is distributed via `packages <https://en.wikipedia.org/wiki/Package_format>`__, which are stored in `software repositories <https://en.wikipedia.org/wiki/Software_repository>`__ (“repos”). `Package managers <https://en.wikipedia.org/wiki/Package_manager>`__ handle downloading, installing, updating, and removing packages. (Again, none of this is Qubes-specific.) If you’re not familiar with how software is normally installed in Linux distros via package managers or the software you want doesn’t seem to be available in your distro’s repos (or you’re in another situation not covered on this page), please read this `community guide to installing software in Qubes <https://forum.qubes-os.org/t/9991/>`__.
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.) 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 Installing software from default repositories
--------------------------------------------- ---------------------------------------------
1. Start the template. 1. Start the template.
2. Start either a terminal (e.g. ``gnome-terminal``) or a dedicated software management application, such as ``gpk-application``. 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.: 3. Install software as normally instructed inside that operating system, e.g.:
- Fedora: ``sudo dnf install <PACKAGE_NAME>`` - Fedora: :samp:`sudo dnf install {<PACKAGE_NAME>}`
- Debian: ``sudo apt install <PACKAGE_NAME>``
- Debian: :samp:`sudo apt install {<PACKAGE_NAME>}`
4. Shut down the template. 4. Shut down the template.
5. Restart all qubes based on 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 </user/troubleshooting/app-menu-shortcut-troubleshooting>` 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 .. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
:alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__ :alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__
Installing software from other sources 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. 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 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 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: 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 +53,44 @@ If you are using another installation method fetching remote resources, you migh
ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \ ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \
NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY
Using direct networking 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 </user/how-to-guides/how-to-update>`, 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 </user/how-to-guides/how-to-update>`, 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. 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). 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. 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. 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 </user/troubleshooting/app-menu-shortcut-troubleshooting>` for troubleshooting.) 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:
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
:alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__
Troubleshooting Troubleshooting
--------------- ---------------
If things are still not working as expected: If things are still not working as expected:
- Review the instructions very carefully, making sure you follow each step. - Review the instructions very carefully, making sure you follow each step.
@ -111,38 +105,31 @@ If things are still not working as expected:
- :doc:`Ask for help. </introduction/support>` - :doc:`Ask for help. </introduction/support>`
How to update software How to update software
---------------------- ----------------------
Please see :doc:`how-to-update`.
Please see :doc:`How to Update </user/how-to-guides/how-to-update>`.
Why don't templates have normal network access? Why don't templates have normal network access?
----------------------------------------------- -----------------------------------------------
In order to protect you from performing risky activities in templates, they do not have normal network access by default. Instead, templates use an :ref:`updates-proxy` which allows you to install and update software using the distribution’s package manager over the proxy connection. **The updates proxy is already set up to work automatically out-of-the-box and requires no special action from you.** Most users should simply follow the normal instructions for :ref:`installing-software-from-default-repositories` and :doc:`updating <how-to-update>` 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 `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 </user/how-to-guides/how-to-update>` software. If your software is not available in the default repositories, see `installing software from other sources <#installing-software-from-other-sources>`__.
Advanced Advanced
-------- --------
The following sections cover advanced topics pertaining to installing and updating software in qubes. The following sections cover advanced topics pertaining to installing and updating software in qubes.
Testing repositories Testing repositories
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
If you wish to install updates that are still in :doc:`testing </user/downloading-installing-upgrading/testing>`, you must enable the appropriate testing repositories. If you wish to install updates that are still in :doc:`testing </user/downloading-installing-upgrading/testing>`, you must enable the appropriate testing repositories.
**Note:** The following repos are in templates and standalones. For dom0 testing repos, see :ref:`here <user/advanced-topics/how-to-install-software-in-dom0:testing repositories>`. For testing new templates, please see :ref:`here <user/downloading-installing-upgrading/testing:templates>`. **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 Fedora
^^^^^^ ^^^^^^
There are three Qubes VM testing repositories (where ``*`` denotes the Release): 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 - ``qubes-vm-*-current-testing`` – testing packages that will eventually land in the stable (``current``) repository
@ -151,25 +138,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 - ``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=<repo-name>`` option. Example commands: To temporarily enable any of these repos, use the ``--enablerepo=<repo-name>`` option. Example commands:
.. code:: bash .. code:: console
sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-unstable sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
To enable or disable any of these repos permanently, change the corresponding ``enabled`` value to ``1`` in :file:`/etc/yum.repos.d/qubes-*.repo`.
To enable or disable any of these repos permanently, change the corresponding ``enabled`` value to ``1`` in ``/etc/yum.repos.d/qubes-*.repo``.
Debian Debian
^^^^^^ ^^^^^^
Debian also has three Qubes VM testing repositories (where ``*`` denotes the Debian codename, i.e. "|debian-codename|"):
Debian also has three Qubes VM testing repositories (where ``*`` denotes the Release):
- ``*-testing`` – testing packages that will eventually land in the stable (``current``) repository - ``*-testing`` – testing packages that will eventually land in the stable (``current``) repository
@ -177,23 +159,19 @@ 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 - ``*-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 :file:`/etc/apt/sources.list.d/qubes-r4.list`.
To enable or disable any of these repos permanently, uncomment the corresponding ``deb`` line in ``/etc/apt/sources.list.d/qubes-r*.list``.
Standalones Standalones
^^^^^^^^^^^ ^^^^^^^^^^^
The process for installing and updating software in :ref:`standalones <user/reference/glossary:standalone>` 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 :ref:`standalones <user/reference/glossary:standalone>` 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 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 <https://rpmfusion.org/>`__ 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 <https://rpmfusion.org/>`__ for details): .. code:: console
.. code:: bash
sudo dnf config-manager setopt rpmfusion-free.enabled=1 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-free-updates.enabled=1
@ -201,14 +179,11 @@ If you would like to enable the `RPM Fusion <https://rpmfusion.org/>`__ reposito
sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1 sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
sudo dnf upgrade --refresh sudo dnf upgrade --refresh
This will permanently enable the RPM Fusion repos. If you install software from here, it’s important to keep these repos enabled so that you can receiving future updates. If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them. This will permanently enable the RPM Fusion repos. If you install software from here, it’s important to keep these repos enabled so that you can receiving future updates. If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them.
Reverting changes to a template 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: 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. 1. **Root revert.** This is appropriate for misconfigurations, but not for security concerns. It will preserve your customizations.
@ -217,48 +192,38 @@ 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. 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 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 ``<template>``. If you’ve already just shut it down, do **not** start it again (see above). 1. Shut down ``<template>``. If you’ve already just shut it down, do **not** start it again (see above).
2. In a dom0 terminal: 2. In a dom0 terminal:
.. code:: bash .. code:: console
qvm-volume revert <template>:root
[user@dom0]$ qvm-volume revert <template>:root
Reinstall the template Reinstall the template
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
Please see :doc:`how-to-reinstall-a-template`.
Please see :doc:`How to Reinstall a template </user/how-to-guides/how-to-reinstall-a-template>`.
Full revert Full revert
^^^^^^^^^^^ ^^^^^^^^^^^
This is like the simple revert, except: This is like the simple revert, except:
- You must also revert the private volume with ``qvm-volume revert <template>:private``. This requires you to have an old revision of the private volume, which does not exist with the current default config. However, if you don’t have anything important in the private volume (likely for a template), then you can work around this by just resetting the private volume with ``qvm-volume import --no-resize <template>:private /dev/null``. - You must also revert the private volume with :samp:`qvm-volume revert {<template>}:private`. This requires you to have an old revision of the private volume, which does not exist with the current default config. However, if you don’t have anything important in the private volume (likely for a template), then you can work around this by just resetting the private volume with :samp:`qvm-volume import --no-resize {<template>}:private /dev/null`.
- The saved revision of the volumes must be uncompromised. With the default ``revisions_to_keep=1`` for the root volume, you must **not** have started the template since the compromising action. - The saved revision of the volumes must be uncompromised. With the default ``revisions_to_keep=1`` for the root volume, you must **not** have started the template since the compromising action.
.. updates-proxy:
Updates proxy Updates proxy
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Updates proxy is a service which allows access from package managers configured to use the proxy by default, but can be used by any other program that accepts proxy arguments. The purpose of the proxy, instead of direct network access, is meant to mitigate user errors of using applications such as the browser in the template. Not necessarily what part of the network they can access, but only to applications trusted by the user, configured to use the proxy. The http proxy (tinyproxy) does not filter traffic because it is hard to list all the repository mirrors and keep that list up to date). it also does not cache anything. Updates proxy is a service which allows access from package managers configured to use the proxy by default, but can be used by any other program that accepts proxy arguments. The purpose of the proxy, instead of direct network access, is meant to mitigate user errors of using applications such as the browser in the template. Not necessarily what part of the network they can access, but only to applications trusted by the user, configured to use the proxy. The http proxy (tinyproxy) does not filter traffic because it is hard to list all the repository mirrors and keep that list up to date). it also does not cache anything.
The proxy is running in selected VMs (by default all the NetVMs (1)) and intercepts traffic directed to 127.0.0.1:8082. Thanks to such configuration all the VMs can use the same proxy address. If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf/apt to really use the proxy (3). Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic). The proxy is running in selected VMs (by default all the NetVMs (1)) and intercepts traffic directed to 127.0.0.1:8082. Thanks to such configuration all the VMs can use the same proxy address. If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf/apt to really use the proxy (3). Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
@ -269,38 +234,33 @@ There are two services (``qvm-service``, :doc:`service framework </user/advanced
2. ``updates-proxy-setup`` (and its deprecated name: ``yum-proxy-setup``) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates 2. ``updates-proxy-setup`` (and its deprecated name: ``yum-proxy-setup``) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates
Both the old and new names work. The defaults listed above are applied if the service is not explicitly listed in the services tab. Both the old and new names work. The defaults listed above are applied if the service is not explicitly listed in the services tab.
Technical details Technical details
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
The updates proxy uses RPC/qrexec. The proxy is configured in qrexec policy in dom0: :file:`/etc/qubes-rpc/policy/qubes.UpdatesProxy`. By default this is set to sys-net and/or sys-whonix, depending on firstboot choices. This new design allows for templates to be updated even when they are not connected to any NetVM.
The updates proxy uses RPC/qrexec. The proxy is configured in qrexec policy in dom0: ``/etc/qubes-rpc/policy/qubes.UpdatesProxy``. By default this is set to sys-net and/or sys-whonix, depending on firstboot choices. This new design allows for templates to be updated even when they are not connected to any NetVM.
Example policy file in R4.1 (with Whonix installed, but not set as default UpdateVM for all templates): Example policy file in R4.1 (with Whonix installed, but not set as default UpdateVM for all templates):
.. code:: bash .. code::
# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone # any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
@tag:whonix-updatevm @default allow,target=sys-whonix @tag:whonix-updatevm @default allow,target=sys-whonix
@tag:whonix-updatevm @anyvm deny @tag:whonix-updatevm @anyvm deny
# other templates use sys-net # other templates use sys-net
@type:TemplateVM @default allow,target=sys-net @type:TemplateVM @default allow,target=sys-net
@anyvm @anyvm deny @anyvm @anyvm deny
Installing Snap Packages Installing Snap Packages
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
Snap packages do not use the normal update channels for Debian and Fedora (apt and dnf) and are often installed as the user rather than as root. To support these in an app qube you need to take the following steps: Snap packages do not use the normal update channels for Debian and Fedora (apt and dnf) and are often installed as the user rather than as root. To support these in an app qube you need to take the following steps:
1. In the **template** you must install ``snapd`` and ``qubes-snapd-helper``. Open a terminal in the template and run: 1. In the **template** you must install ``snapd`` and ``qubes-snapd-helper``. Open a terminal in the template and run:
.. code:: bash .. code:: console
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper [user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06. Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
@ -313,15 +273,15 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k
Installing dependencies: Installing dependencies:
[...] [...]
Transaction Summary Transaction Summary
======================================================================================================== ========================================================================================================
Install 19 Packages Install 19 Packages
Total download size: 27 M Total download size: 27 M
Installed size: 88 M Installed size: 88 M
Is this ok [y/N]: y Is this ok [y/N]: y
Downloading Packages: Downloading Packages:
[..] [..]
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174 Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
@ -329,7 +289,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
[...] [...]
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06. Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
Notifying dom0 about installed applications Notifying dom0 about installed applications
Installed: Installed:
snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.noarch snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.noarch
[...] [...]
@ -337,47 +297,40 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
You may see the following message: You may see the following message:
.. code:: bash .. code:: console
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174 Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
/usr/sbin/semodule: Failed! /usr/sbin/semodule: Failed!
This is expected and you can safely continue. This is expected and you can safely continue.
Shutdown the template: Shutdown the template:
.. code:: bash .. code:: console
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now [user@fedora-36-snap-demo ~]$ sudo shutdown -h now
2. Now open the **app qube** in which you would like to install the Snap application and run a terminal: 2. Now open the **app qube** in which you would like to install the Snap application and run a terminal:
.. code:: bash .. code:: console
[user@snap-demo-app qube ~]$ snap install <package> [user@snap-demo-app qube ~]$ snap install <package>
When the install is complete you can close the terminal window. When the install is complete you can close the terminal window.
3. Refresh the Applications list for the app qube. In the Qubes Menu for the **app qube** launch the Qube Settings. Then go to the Applications tab and click “Refresh Applications” 3. Refresh the Applications list for the app qube. In the Qubes Menu for the **app qube** launch the Qube :guilabel:`Settings`. Then go to the Applications tab and click “Refresh Applications”
- The refresh will take a few minutes; after it’s complete the Snap app will appear in the app qube’s list of available applications. At this point the snap will be persistent within the app qube and will receive updates when the app qube is running. - The refresh will take a few minutes; after it’s complete the Snap app will appear in the app qube’s list of available applications. At this point the snap will be persistent within the app qube and will receive updates when the app qube is running.
Autostarting Installed Applications Autostarting Installed Applications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want a desktop app to start automatically every time a qube starts you can create a link to it in the ``~/.config/autostart`` directory of the **app qube**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app. If you want a desktop app to start automatically every time a qube starts you can create a link to it in the ``~/.config/autostart`` directory of the **app qube**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.
1. Open a terminal in the **app qube** where you would like the app to launch. 1. Open a terminal in the **app qube** where you would like the app to launch.
2. List the names of the available desktop shortcuts by running the command ``ls /usr/share/applications`` and find the exact name of the shortcut to the app you want to autostart: 2. List the names of the available desktop shortcuts by running the command ``ls /usr/share/applications`` and find the exact name of the shortcut to the app you want to autostart:
.. code:: bash .. code:: console
[user@example-app qube ~]$ ls /usr/share/applications/ [user@example-app qube ~]$ ls /usr/share/applications/
bluetooth-sendto.desktop bluetooth-sendto.desktop
@ -387,23 +340,18 @@ If you want a desktop app to start automatically every time a qube starts you ca
xterm.desktop xterm.desktop
yelp.desktop yelp.desktop
3. Create the autostart directory: 3. Create the autostart directory:
.. code:: bash .. code:: console
[user@example-app qube ~]$ mkdir -p ~/.config/autostart [user@example-app qube ~]$ mkdir -p ~/.config/autostart
4. Make a link to the desktop app file you’d like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory: 4. Make a link to the desktop app file you’d like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory:
.. code:: bash .. code:: console
[user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop [user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
Note that the app will autostart only when the app qube starts. If you would like the app qube to autostart, select the “Start qube automatically on boot” checkbox in the app qube’s Qube Settings. Note that the app will autostart only when the app qube starts. If you would like the app qube to autostart, select the “Start qube automatically on boot” checkbox in the app qube’s Qube Settings.
.. _RPM Fusion: https://rpmfusion.org

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

@ -3,7 +3,7 @@ Debian templates
================ ================
The Debian :doc:`template </user/templates/templates>` is an officially :ref:`supported <user/downloading-installing-upgrading/supported-releases:templates>` template in Qubes OS. The Current version is Debian 12 (“bookworm”). It is available in 3 versions - ``debian-12``, a standard template; ``debian-12-xfce``, a larger template with more installed applications, selected for :doc:`Xfce </user/templates/xfce-templates>`; ``debian-12-minimal``. This page is about the “full” templates. For the minimal version, please see the :doc:`Minimal templates </user/templates/minimal-templates>` page. The Debian :ref:`/user/reference/glossary:template` is an officially :ref:`supported <user/downloading-installing-upgrading/supported-releases:templates>` template in Qubes OS. The Current version is Debian |debian-version| (“|debian-codename|”). It is available in 3 versions - ``debian-12``, a standard template; ``debian-12-xfce``, a larger template with more installed applications, selected for :doc:`Xfce </user/templates/xfce-templates>`; ``debian-12-minimal``. This page is about the “full” templates. For the minimal version, please see the :doc:`Minimal templates </user/templates/minimal-templates>` page.
Installing Installing
---------- ----------

2
user/troubleshooting/app-menu-shortcut-troubleshooting.rst
View file

@ -1,3 +1,5 @@
.. _app-menu-troubleshooting:
================================= =================================
App menu shortcut troubleshooting App menu shortcut troubleshooting
================================= =================================