diff --git a/doc.md b/doc.md index 815cf4f9..350548c8 100644 --- a/doc.md +++ b/doc.md @@ -64,7 +64,7 @@ Core documentation for Qubes users. * [Copying from (and to) Dom0](/doc/copy-from-dom0/) * [Updating Qubes OS](/doc/updating-qubes-os/) * [Installing and Updating Software in Dom0](/doc/software-update-dom0/) - * [Installing and Updating Software in VMs](/doc/software-update-vm/) + * [Installing and Updating Software in DomUs](/doc/software-update-domu/) * [Backup, Restoration, and Migration](/doc/backup-restore/) * [DisposableVMs](/doc/disposablevm/) * [Block (or Storage) Devices](/doc/block-devices/) @@ -78,12 +78,8 @@ Core documentation for Qubes users. ### Managing Operating Systems within Qubes * [TemplateVMs](/doc/templates/) - * [Template: Fedora](/doc/templates/fedora/) - * [Template: Fedora Minimal](/doc/templates/fedora-minimal/) - * [Template: Debian](/doc/templates/debian/) - * [Template: Debian Minimal](/doc/templates/debian-minimal/) * [Windows](/doc/windows/) - * [HVM Domains](/doc/hvm/) + * [StandaloneVMs and HVMs](/doc/standalone-and-hvm/) ### Security in Qubes diff --git a/external/os-guides/windows/windows-vm.md b/external/os-guides/windows/windows-vm.md index c90fe015..3c8be14c 100644 --- a/external/os-guides/windows/windows-vm.md +++ b/external/os-guides/windows/windows-vm.md @@ -162,7 +162,7 @@ To avoid that error we temporarily have to switch the video adapter to 'cirrus': qvm-features win7new video-model cirrus ~~~ -The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/hvm/#installing-an-os-in-an-hvm-qube): +The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/standalone-and-hvm/#installing-an-os-in-an-hvm): ~~~ qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new diff --git a/external/troubleshooting/remove-vm-manually.md b/external/troubleshooting/remove-vm-manually.md index 7d8d52b0..fbc1c145 100644 --- a/external/troubleshooting/remove-vm-manually.md +++ b/external/troubleshooting/remove-vm-manually.md @@ -32,5 +32,5 @@ When a template is marked as 'installed by package manager', but cannot be unins - If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template. -[normal method]: /doc/templates/#how-to-install-uninstall-reinstall-and-switch +[normal method]: /doc/templates/#uninstalling diff --git a/introduction/faq.md b/introduction/faq.md index 13a61b23..d0469729 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -421,7 +421,7 @@ For Debian: For Fedora: 1. (Recommended) Clone an existing Fedora TemplateVM -2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM.](/doc/software-update-vm/#rpmfusion-for-a-fedora-templatevm) +2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM.](/doc/software-update-domu/#rpmfusion-for-fedora-templatevms) 3. Install VLC in that TemplateVM: $ sudo dnf install vlc diff --git a/user/advanced-configuration/disposablevm-customization.md b/user/advanced-configuration/disposablevm-customization.md index b4e9596b..16e51b43 100644 --- a/user/advanced-configuration/disposablevm-customization.md +++ b/user/advanced-configuration/disposablevm-customization.md @@ -50,7 +50,7 @@ Additionally you may want to set it as default DisposableVM Template: The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details. -If you wish to use the `fedora-minimal` template as a DisposableVM Template, see the "DisposableVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization). +If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a DisposableVM Template, please see the [Minimal TemplateVM](/doc/templates/minimal/) page. ## Customization of DisposableVM diff --git a/user/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md new file mode 100644 index 00000000..ccc83b2e --- /dev/null +++ b/user/common-tasks/software-update-domu.md @@ -0,0 +1,180 @@ +--- +layout: doc +title: Installing and updating software in domUs +permalink: /doc/software-update-domu/ +redirect_from: +- /doc/software-update-vm/ +- /en/doc/software-update-vm/ +- /doc/SoftwareUpdateVM/ +- /wiki/SoftwareUpdateVM/ +--- + +# Installing and updating software in domUs + +Updating [domUs], especially [TemplateVMs] and [StandaloneVMs][StandaloneVM] are important steps in [Updating Qubes OS]. +It is very import to keep domUs up-to-date with the latest [security] updates. +Updating these VMs also allows you to receive various non-security bug fixes and enhancements both from the Qubes OS Project and from your upstream distro maintainer. + + +## Installing software in TemplateVMs + +To permanently install new software in a TemplateVM: + + 1. Start the TemplateVM. + 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. using `dnf`, or the dedicated GUI application). + 4. Shut down the TemplateVM. + 5. Restart all [TemplateBasedVMs] based on the TemplateVM. + + +## Updating software in TemplateVMs + +The recommended way to update your TemplateVMs is to use the **Qubes Update** tool. +By default, the icon for this tool will appear in your Notification Area when updates are available. +Simply click on it and follow the guided steps. +If you wish to open this tool directly, you can find it in the System Tools area of the Applications menu. + +You can also update TemplateVMs individually. +In the Qube Manager, select the desired TemplateVM, then click **Update qube**. +Advanced users can execute the standard update command for that operating system from the command line, e.g., `dnf update` in Fedora and `apt-get update` in Debian. + + +## Testing repositories + +If you wish to install updates that are still in [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 + +To temporarily enable any of these repos, use the `--enablerepo=` option. +Example commands: + +~~~ +sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing +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`. + + +### Debian + +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 + +To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list` + + +## Reverting changes to a TemplateVM + +Perhaps you've just updated your TemplateVM, 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. +Fortunately, it's easy to revert changes to TemplateVMs using the command appropriate to your version of Qubes. + +**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.* +This means that if you have already restarted the TemplateVM, 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! + +For example, to revert changes to the `fedora-XX` TemplateVM (where `XX` is your Fedora version): + +1. Shut down `fedora-XX`. + If you've already just shut it down, do **not** start it again (see above). +2. In a dom0 terminal, type: + + qvm-volume revert fedora-XX:root + + +## StandaloneVMs + +When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem. +After the moment of creation, the StandaloneVM is completely independent from the TemplateVM. +Therefore, it will not be updated when the TemplateVM is updated. +Rather, it must be updated individually. +The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs. + + +## Advanced + +The following sections cover advanced topics pertaining to installing and updating software in domUs. + + +### RPMFusion for Fedora TemplateVMs + +If you would like to enable the [RPM Fusion] repository, open a Terminal of the TemplateVM and type the following commands: + +~~~ +sudo dnf config-manager --set-enabled rpmfusion-free rpmfusion-nonfree +sudo dnf upgrade --refresh +~~~ + + +### 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 VM 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 VM, 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 + +Updates proxy is a service which allows access only from package managers. +This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation. +It is done with http proxy (tinyproxy) instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date). +The proxy is used only to filter the traffic, not to cache anything. + +The proxy is running in selected VMs (by default all the NetVMs (1)) and intercepts traffic directed to 10.137.255.254:8082. +Thanks to such configuration all the VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allow that). +If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3). +Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic). + +There are two services (`qvm-service`, [service framework]): + +1. qubes-updates-proxy (and its deprecated name: qubes-yum-proxy) - a service providing a proxy for templates - by default enabled in NetVMs (especially: sys-net) +2. updates-proxy-setup (and its deprecated name: yum-proxy-setup) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates + +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 on dom0: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`. +By default this is set to sys-net and/or sys-whonix, depending on firstboot choices. +This new design allows for templates to be updated even when they are not connected to any NetVM. + + +Example policy file in R4.0 (with Whonix installed, but not set as default UpdateVM for all templates): +``` +# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone +@tag:whonix-updatevm @default allow,target=sys-whonix +@tag:whonix-updatevm @anyvm deny + +# other templates use sys-net +@type:TemplateVM @default allow,target=sys-net +@anyvm @anyvm deny +``` + +[domUs]: /doc/glossary/#domu +[TemplateVMs]: /doc/templates/ +[StandaloneVM]: /doc/standalone-and-hvm/ +[Updating Qubes OS]: /doc/updating-qubes-os/ +[security]: /security/ +[TemplateBasedVMs]: /doc/glossary/#templatebasedvm +[testing]: /doc/testing +[RPM Fusion]: http://rpmfusion.org/ +[service framework]: /doc/qubes-service/ + diff --git a/user/common-tasks/software-update-vm.md b/user/common-tasks/software-update-vm.md deleted file mode 100644 index bebc633c..00000000 --- a/user/common-tasks/software-update-vm.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -layout: doc -title: Installing and updating software in VMs -permalink: /doc/software-update-vm/ -redirect_from: -- /en/doc/software-update-vm/ -- /doc/SoftwareUpdateVM/ -- /wiki/SoftwareUpdateVM/ ---- - -Installing and updating software in VMs -======================================= - -Updating TemplateVMs and StandaloneVMs are two of the main steps in [Updating Qubes OS]. -It is very import to keep TemplateVMs and StandaloneVMs up-to-date with the latest [security] updates. -Updating these VMs also allows you to receive various non-security bug fixes and enhancements both from the Qubes OS Project and from your upstream distro maintainer. - -How TemplateVMs work in Qubes ------------------------------- - -Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. -This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). -Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way. - -In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update. -It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted. - -The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home`, `/usr/local`, or `/rw` then it will disappear after the AppVM reboots (as the root filesystem for this AppVM will again be "taken" from the TemplateVM). -**This means one normally installs software in the TemplateVM, not in AppVMs.** - -The template root filesystem is created in a thin pool, so manual trims are not necessary. -See [here](/doc/disk-trim) for further discussion on enabling discards/trim support. - -Installing (or updating) software in the TemplateVM ----------------------------------------------------- - -In order to permanently install new software, you should: - -- Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-\>Add/Remove software*), - -- Install/update software as usual (e.g. using dnf, or the dedicated GUI application). - Then, shutdown the template VM. - -- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. - This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. - You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. - You can restart others whenever this will be convenient to you. - -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 - -To temporarily enable any of these repos, use the `--enablerepo=` option. -Example commands: - -~~~ -sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing -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`. - -### Debian ### - -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 - -To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list` - -Reverting changes to a TemplateVM ---------------------------------- - -Perhaps you've just updated your TemplateVM, 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. -Fortunately, it's easy to revert changes to TemplateVMs using the command appropriate to your version of Qubes. - -**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.* -This means that if you have already restarted the TemplateVM, 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! - -For example, to revert changes to the `fedora-26` TemplateVM: - -1. Shut down `fedora-26`. - If you've already just shut it down, do **not** start it again (see above). -2. In a dom0 terminal, type: - - qvm-volume revert fedora-26:root - -Notes on trusting your TemplateVM(s) -------------------------------------- - -As the TemplateVM is used for creating filesystems for other AppVMs where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template. -In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise. - -There are several ways to deal with this problem: - -- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. - All those packages are signed by Fedora, and we expect that at least the package's installation scripts are not malicious. - This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. - -- Use *standalone VMs* (see below) for installation of untrusted software packages. - -- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos. - -Some popular questions: - -- So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might be buggy, right? - -As far as the template's compromise is concerned, it doesn't really matter whether `/usr/bin/firefox` is buggy and can be exploited, or not. -What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. -Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run `/usr/bin/firefox` and get infected from it, in case it was compromised. -Also, some of your more trusted AppVMs would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial `/usr/bin/firefox` being potentially buggy and easy to compromise. - -- But why trust Fedora? - -Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages). -We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0. -We had to trust *somebody* as we are unable to write all the software from scratch ourselves. -But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable. -We certainly do not assume the latter. - -- So, are the template VMs as trusted as Dom0? - -Not quite. -Dom0 compromise is absolutely fatal, and it leads to Game OverTM. -However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). -Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM. -Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow. - -Standalone VMs --------------- -Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own. -But this means that they take a few GBs on disk, and also that centralized updates do not apply to them. - -Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. -Such situations include e.g.: - -- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools) - -- VMs used for installing untrusted packages. - Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). - However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way. - -In order to create a standalone VM you can use a command line like this (from console in Dom0): - -``` -qvm-create --class StandaloneVM --label