From f71614efd9a581b6cb8a242a30b4fee567ed05d2 Mon Sep 17 00:00:00 2001 From: 3np <3np@example.com> Date: Sun, 23 Mar 2025 02:16:21 +0000 Subject: [PATCH 1/2] how-to-install-software: clarify updates-proxy usage - makes it less likely to get the false impression that the updates proxy does not allow arbitrary outbound connections - add example of how to download software in templates without enabling direct networking --- user/how-to-guides/how-to-install-software.md | 49 +++++++++++++------ user/how-to-guides/how-to-update.md | 2 +- user/templates/templates.md | 2 +- 3 files changed, 37 insertions(+), 16 deletions(-) diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md index be3ee664..094f526e 100644 --- a/user/how-to-guides/how-to-install-software.md +++ b/user/how-to-guides/how-to-install-software.md @@ -69,17 +69,38 @@ will appear in the Applications Menu. (If you encounter problems, see ## 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** +[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 [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. +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 + +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: + +```sh +$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \ + HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \ + ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \ + NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY +``` + +### Using direct networking + +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). @@ -140,18 +161,18 @@ If things are still not working as expected: Please see [How to Update](/doc/how-to-update/). -## Why don't templates have 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 [updates -proxy](#updates-proxy) that allows you to install and update software using -the distribution package manager without giving the template direct network -access.**The updates proxy is already setup 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 +proxy](#updates-proxy) which allows you to install and update software using +the distribution 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 [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). diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md index 8e865234..5a6a7b4f 100644 --- a/user/how-to-guides/how-to-update.md +++ b/user/how-to-guides/how-to-update.md @@ -32,7 +32,7 @@ However, you can also start the tool manually by selecting it in the Application By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the "last checked" column. If updates are available for any qube, you will receive a notification as described above, and in the "Updates available" column you will see "YES" for that qube(s). If the update check did not find any new updates, "NO" will appear in the column. Respectively, for qubes that are no longer supported, "OBSOLETE" will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the "Updates available" column will be set to "MAYBE". diff --git a/user/templates/templates.md b/user/templates/templates.md index d12e5585..20328164 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -140,7 +140,7 @@ After installing a fresh template, we recommend performing the following steps: For information about how templates access the network, please see [Why don’t templates have network -access?](/doc/how-to-install-software/#why-dont-templates-have-network-access) +access?](/doc/how-to-install-software/#why-dont-templates-have-normal-network-access) and the [Updates proxy](/doc/how-to-install-software/#updates-proxy). ## Updating From 73294eb89d3eeb7f7d891716a8c4cdf8a099c0da Mon Sep 17 00:00:00 2001 From: unman Date: Thu, 15 May 2025 11:08:21 +0000 Subject: [PATCH 2/2] Minor changes in how-to-install-software --- user/how-to-guides/how-to-install-software.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md index 094f526e..87f8af4b 100644 --- a/user/how-to-guides/how-to-install-software.md +++ b/user/how-to-guides/how-to-install-software.md @@ -68,13 +68,6 @@ will appear in the Applications Menu. (If you encounter problems, see ## Installing software from other sources -**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 [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. Depending on the installation method, you may either use the updates proxy or direct networking. @@ -98,8 +91,15 @@ $ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \ ### Using direct networking -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 +**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 [update Qubes +normally](/doc/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. 1. (Recommended) Clone the desired template (since this new template will @@ -166,7 +166,7 @@ Please see [How to Update](/doc/how-to-update/). 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 package manager over the proxy connection. +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 @@ -179,7 +179,7 @@ sources](#installing-software-from-other-sources). ## Advanced The following sections cover advanced topics pertaining to installing and -updating software in domUs. +updating software in qubes. ### Testing repositories