From ca5b73019404816146692ab273277e0bf06da6e7 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 20 Apr 2022 14:19:04 -0700 Subject: [PATCH] Update "how to install software" - Add section on installing software from non-default-repo sources - Remove deprecated content - Improve organization Thanks to Insurgo, Sven, and all the other participants in this forum thread: https://forum.qubes-os.org/t/10935/ --- user/how-to-guides/how-to-install-software.md | 154 ++++++++++++------ 1 file changed, 104 insertions(+), 50 deletions(-) diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md index 5f54c02b..4d4a7f8f 100644 --- a/user/how-to-guides/how-to-install-software.md +++ b/user/how-to-guides/how-to-install-software.md @@ -14,15 +14,36 @@ title: How to install software When you wish to install software in Qubes OS, you should generally install it in a [template](/doc/glossary/#template). For installing templates themselves, -see [how to install a template](/doc/templates/#installing). - -Advanced users may also be interested in learning how to install software in +see [how to install a template](/doc/templates/#installing). Advanced users may +also be interested in learning how to install software in [standalones](/doc/standalones-and-hvms/) and [dom0](/doc/how-to-install-software-in-dom0). -## Instructions +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/). -To permanently install new software in a template: +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 1. Start the template. @@ -33,25 +54,6 @@ To permanently install new software in a template: - Fedora: `sudo dnf install ` - Debian: `sudo apt install ` - **Note:** 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/). - 4. **Shut down the template. (Do not skip this step.)** 5. **Restart all qubes based on the template. (Do not skip this step.)** @@ -64,39 +66,97 @@ To permanently install new software in a template: ![[The Applications tab in Qube Settings](/attachment/doc/r4.1-dom0-appmenu-select.png)](/attachment/doc/r4.1-dom0-appmenu-select.png) + +## Installing software from other sources + +**Warning:** This method gives your template direct network access, which is +[risky](#why-dont-templates-have-network-access). This method is **not** +recommended for trusted templates. + +Some software is not available from the default repositories and must be +downloaded and installed from another source. This method assumes that you're +trying to follow the 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 Basic settings, change the color label + from black to red (or another color that signifies to you that the template + is less trusted). + +3. In the new template's Basic settings, change the Networking value from + `default (none) (current)` to `sys-firewall` (or whichever network-providing + qube you wish to use). + +4. (Recommended) In the new template's 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.) + +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 Basic settings, change the Networking + value from `sys-firewall (current)` (or whichever network-providing qube you + chose) back to `default (none)`. + +7. **Shut down the template. (Do not skip this step.)** + +8. **Restart all qubes based on the template. (Do not skip this step.)** + +9. (Recommended) In the relevant qubes' **Qube Settings**, go to the + **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 [here](/doc/app-menu-shortcut-troubleshooting/) for + troubleshooting.) + +![[The Applications tab in Qube Settings](/attachment/doc/r4.1-dom0-appmenu-select.png)](/attachment/doc/r4.1-dom0-appmenu-select.png) + + ## Troubleshooting If things are still not working as expected: -- Review the [instructions](#instructions) very carefully, making sure you - follow each step. +- Review the instructions very carefully, making sure you follow each step. - Make sure you **shut down the template after installing your software**. - Make sure you **restart your app qube *after* shutting down your template**. - If your software requires special files or directories to be persistent, and - you're an advanced user, see [Standalones and - HVMs](/doc/standalones-and-hvms/) and [How to Make Any File Persistent + you're an advanced user, see [standalones and + HVMs](/doc/standalones-and-hvms/) and [how to make any file persistent (bind-dirs)](/doc/bind-dirs/). - [Ask for help.](/support/) + ## How to update software Please see [How to Update](/doc/how-to-update/). + ## Why don't templates have network access? In order to protect you from performing risky activities in templates, they do -not have normal network access. Instead, templates use an [updates +not have normal network access by default. Instead, templates use an [updates proxy](#updates-proxy) that allows you to install and update software without -giving the template direct network access. **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](#instructions) and [updating](/doc/how-to-update/) software. +giving the template direct network access. **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 +[updating](/doc/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 The following sections cover advanced topics pertaining to installing and updating software in domUs. + ### Testing repositories If you wish to install updates that are still in [testing](/doc/testing), you @@ -106,6 +166,7 @@ must enable the appropriate testing repositories. repos, see [here](/doc/how-to-install-software-in-dom0/#testing-repositories). For testing new templates, please see [here](/doc/testing/#templates). + #### Fedora There are three Qubes VM testing repositories (where `*` denotes the Release): @@ -129,6 +190,7 @@ 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`. + #### Debian Debian also has three Qubes VM testing repositories (where `*` denotes the @@ -144,6 +206,7 @@ Release): To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`. + ### Standalones The process for installing and updating software in @@ -151,6 +214,7 @@ The process for installing and updating software in 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](https://rpmfusion.org/) @@ -172,6 +236,7 @@ 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 Perhaps you've just updated your template, and the update broke your template. @@ -191,6 +256,7 @@ undo changes to a template, there are three basic methods: 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 @@ -210,10 +276,12 @@ first! qvm-volume revert