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

@@ -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).
+see [how to install a template](/doc/templates/#installing). Advanced users may
-
+also be interested in learning how to install software in
-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 <PACKAGE_NAME>`
    - Debian: `sudo apt install <PACKAGE_NAME>`
 
-   **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
+- Review the instructions very carefully, making sure you follow each step.
-  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
+  you're an advanced user, see [standalones and
-  HVMs](/doc/standalones-and-hvms/) and [How to Make Any File Persistent
+  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
+giving the template direct network access. **The updates proxy is already set
-to work automatically out-of-the-box and requires no special action from you.**
+up to work automatically out-of-the-box and requires no special action from
-Most users should simply follow the normal instructions for
+you.** Most users should simply follow the normal instructions for [installing
-[installing](#instructions) and [updating](/doc/how-to-update/) software.
+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 <template>:root
    ```
 
+
 #### Reinstall the template
 
 Please see [How to Reinstall a template](/doc/reinstall-template/).
 
+
 #### Full revert
 
 This is like the simple revert, except:
@@ -229,23 +297,6 @@ This is like the simple revert, except:
   `revisions_to_keep=1` for the root volume, you must **not** have started the
   template since the compromising action.
 
-### Temporarily allowing networking for software installation
-
-Some third-party applications cannot be installed using the standard
-repositories and need to be manually downloaded and installed. When the
-installation requires internet connection to access third-party repositories,
-it will naturally fail when run in a template because the default firewall
-rules for templates only allow connections from package managers. So it is
-necessary to modify firewall rules to allow less restrictive internet access
-for the time of the installation, if one really wants to install those
-applications into a template. As soon as software installation is completed,
-firewall rules should be returned back to the default state. The user should
-decide by themselves whether such third-party applications should be equally
-trusted as the ones that come from the standard Fedora signed repositories and
-whether their installation will not compromise the default template, and
-potentially consider installing them into a separate template or a standalone
-VM (in which case the problem of limited networking access doesn't apply by
-default), as described above.
 
 ### Updates proxy
 
@@ -279,6 +330,7 @@ framework](/doc/qubes-service/)):
 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
 
 The updates proxy uses RPC/qrexec. The proxy is configured in qrexec policy in
@@ -300,6 +352,7 @@ UpdateVM for all templates):
 @anyvm @anyvm deny
 ```
 
+
 ### Installing Snap Packages
 
 Snap packages do not use the normal update channels for Debian and Fedora (apt
@@ -377,6 +430,7 @@ these in an app qube you need to take the following steps:
    snap will be persistent within the app qube and will receive updates when
    the app qube is running.
 
+
 ### Autostarting Installed Applications
 
 If you want a desktop app to start automatically every time a qube starts you