diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md index 5f54c02b..d9cf0a26 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,70 +54,113 @@ 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. -4. **Shut down the template. (Do not skip this step.)** +5. Restart all qubes based on the template. -5. **Restart all qubes based on the template. (Do not skip this step.)** - -6. (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.) +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 +[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) + +## 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. Moreover, depending on how you install this +software, it may not get updated automatically when you [update Qubes +normally](/doc/how-to-update/), which means you may have to update it manually +yourself. + +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 **Settings > Basic** tab, 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 **Settings > Basic** tab, 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 **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.) + +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 **Settings > Basic** tab, change the + **Networking** value from `sys-firewall (current)` (or whichever + network-providing qube you chose) back to `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 + [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**. +- Make sure your app qube is assigned to the right 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 +170,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 +194,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 +210,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 +218,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 +240,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 +260,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 +280,12 @@ first! qvm-volume revert