From c178da955e906c7a847a149c2391eb845a6b7b4d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 18 Jun 2021 06:58:10 -0700 Subject: [PATCH] Update "How to Install Software" - Explicitly state that software should be installed in a template - Add a note for advanced users who might be interested in installing software in standalones and dom0 - Fix Markdown syntax and formatting - Wrap text --- user/how-to-guides/how-to-install-software.md | 393 +++++++++++------- 1 file changed, 238 insertions(+), 155 deletions(-) diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md index 372fe0a5..e9ef7209 100644 --- a/user/how-to-guides/how-to-install-software.md +++ b/user/how-to-guides/how-to-install-software.md @@ -12,8 +12,15 @@ ref: 189 title: How to Install Software --- -This page explains how to install software in [templates](/doc/templates/). -Advanced users may also be interested in learning [how to install software in dom0](/doc/how-to-install-software-in-dom0). +When you install software in Qubes OS, you install it in your +[templates](/doc/glossary/#template). + + ## Instructions @@ -21,17 +28,22 @@ To permanently install new software in a 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. `sudo dnf install ` on Fedora, `sudo apt install ` on Debian). +3. Install software as normally instructed inside that operating system (e.g. + `sudo dnf install ` on Fedora, `sudo apt install + ` on Debian). 4. Shut down the template. 5. Restart all qubes based on the template so the changes can take effect. -6. (Optional) 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. (Optional) 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) @@ -41,27 +53,34 @@ Please see [How to Update](/doc/how-to-update/). ## Why don't templates have network access? -In order to protect you from performing risky activites in templates, they do not have normal network access. -Instead, templates use an [updates proxy](#updates-proxy) that allows you to install and update software without giving the template direct network access. +In order to protect you from performing risky activites in templates, they do +not have normal network access. Instead, templates use an [updates +proxy](#updates-proxy) that allows you to install and update software without +giving the template direct network access. ## Advanced -The following sections cover advanced topics pertaining to installing and updating software in domUs. +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 must enable the appropriate testing repositories. +If you wish to install updates that are still in [testing](/doc/testing), you +must enable the appropriate testing repositories. #### 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 -- `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes -- `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages +- `qubes-vm-*-current-testing` -- testing packages that will eventually land in + the stable (`current`) repository +- `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` + that contains packages that qualify as security fixes +- `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: +To temporarily enable any of these repos, use the `--enablerepo=` +option. Example commands: ~~~ sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing @@ -69,29 +88,40 @@ 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 `/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 +Release): -- `*-testing` -- testing packages that will eventually land in the stable (`current`) repository -- `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes -- `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages +- `*-testing` -- testing packages that will eventually land in the stable + (`current`) repository +- `*-securitytesting` -- a subset of `*-testing` that contains packages that + qualify as security fixes +- `*-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 `/etc/apt/sources.list.d/qubes-r*.list`. ### Standalones -When you create a [standalone](/doc/standalone-and-hvm/) from a template, the standalone is a complete clone of the template, including the entire filesystem. -After the moment of creation, the standalone is completely independent from the template. -Therefore, it will not be updated when the template is updated. -Rather, it must be updated individually. -The process for installing and updating software in standalones is the same as described above for templates. +When you create a [standalone](/doc/standalone-and-hvm/) from a template, the +standalone is a complete clone of the template, including the entire +filesystem. After the moment of creation, the standalone is completely +independent from the template. Therefore, it will not be updated when the +template is updated. Rather, it must be updated individually. The process for +installing and updating software in standalones is the same as described above +for templates. ### RPMFusion for Fedora templates -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): +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): ~~~ sudo dnf config-manager --set-enabled rpmfusion-free @@ -101,42 +131,49 @@ sudo dnf config-manager --set-enabled rpmfusion-nonfree-updates 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 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: +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. + This is appropriate for misconfigurations, but not for security concerns. It + will preserve your customizations. 2. **Reinstall the template.** - This is appropriate for both misconfigurations and security concerns, but you will lose all customizations. + This is appropriate for both misconfigurations and security concerns, but + you will lose all customizations. 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. + 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 `