Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Revamp documentation on managing OSes in Qubes

Browse Source 
- Unify and normalize Fedora and Debian docs
- Deduplicate content
- Cross-link pages
- Move content to correct pages
- Use more accurate and intuitive terms and names

Fixes QubesOS/qubes-issues#5284
This commit is contained in:
Andrew David Wong 2019-09-02 04:34:26 -05:00
parent f9fab270e8
commit 4fc71ac4a9
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
17 changed files with 875 additions and 1564 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc.md
View File

@ -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

218
user/common-tasks/software-update-vm.md
View File

@ -1,55 +1,50 @@
---
layout: doc
title: Installing and updating software in VMs
permalink: /doc/software-update-vm/
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 VMs
=======================================
# Installing and updating software in domUs
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 [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.
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.
## Installing software in TemplateVMs
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.
To permanently install new software in a TemplateVM:
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.**
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.
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
----------------------------------------------------
## Updating software in TemplateVMs
In order to permanently install new software, you should:
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.
- 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*),
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.
- 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
Testing repositories
--------------------
If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories.
### Fedora ###
### Fedora
There are three Qubes VM testing repositories (where `*` denotes the Release):
@ -68,7 +63,8 @@ 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
Debian also has three Qubes VM testing repositories (where `*` denotes the Release):
@ -78,8 +74,8 @@ Debian also has three Qubes VM testing repositories (where `*` denotes the Relea
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
---------------------------------
## 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.
@ -90,108 +86,49 @@ This means that if you have already restarted the TemplateVM, using this command
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:
For example, to revert changes to the `fedora-XX` TemplateVM (where `XX` is your Fedora version):
1. Shut down `fedora-26`.
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-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 Over<sup>TM</sup>.
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 <label> --property virt_mode=hvm <vmname>
```
... or click appropriate options in the Qubes Manager's Create VM window.
(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM.
However, it makes sense if you want to use a kernel from within the VM.)
qvm-volume revert fedora-XX:root
Using more than one template
----------------------------
## StandaloneVMs
It's also possible to have more than one template VM in the system.
E.g. one could clone the default template using the `qvm-clone` command in Dom0.
This allows to have a customized template, e.g. with devel packages, or less trusted apps, shared by some subset of domains.
It is important to note that the default template is "system managed" and therefore cannot be backed up using Qubes' built-in backup function.
In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
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.
When you create a new domain you can choose which template this VM should be based on.
If you use command line, you should use the `--template` switch:
## 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:
~~~
qvm-create <vmname> --template <templatename> --label <label>
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 yum repositories, and need to be manually downloaded and installed.
### 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
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.
@ -203,7 +140,7 @@ Thanks to such configuration all the VMs can use the same proxy address, and if
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](https://www.qubes-os.org/doc/qubes-service/)):
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
@ -211,15 +148,16 @@ There are two services (`qvm-service`, [service framework](https://www.qubes-os.
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
#### 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.
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):
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
@ -230,37 +168,13 @@ Example policy file in R4.0 (with whonix installed, but not set as default updat
@anyvm @anyvm deny
```
Note on treating AppVM's root filesystem non-persistence as a security feature
------------------------------------------------------------------------------
As explained above, any AppVM that is based on a Template VM (i.e. which is not a Standalone VM) has its root filesystem non-persistent across the VM reboots.
In other words whatever changes the VM makes (or the malware running in this AppVM makes) to its root filesystem, are automatically discarded whenever one restarts the AppVM.
This might seem like an excellent anti-malware mechanism to be used inside the AppVM...
However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free.
This is because the non-persistence, in the case of normal AppVMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons.
It is possible that malware, especially malware that could be specifically written to target a Qubes-based AppVMs, could install its hooks inside the user home directory files only.
Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM.
But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there).
Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem.
However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
Also note that DisposableVMs do not have persistent user filesystem, and so they start up completely "clean" every time.
Note the word "clean" means in this context: the same as their template filesystem, of course.
RPMFusion for a Fedora TemplateVM
---------------------------------
If you would like to enable the [RPM Fusion](http://rpmfusion.org/) 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
~~~
[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/

4
user/common-tasks/updating-qubes-os.md
View File

@ -32,8 +32,8 @@ The one exception is dom0, which [doesn't have to be upgraded][dom0-eol].
[Upgrade Guides]: /doc/upgrade/
[security]: /security/
[Dom0]: /doc/software-update-dom0/
[TemplateVMs]: /doc/software-update-vm/#installing-or-updating-software-in-the-templatevm
[StandaloneVMs]: /doc/software-update-vm/#standalone-vms
[TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[StandaloneVMs]: /doc/software-update-domu/#standalonevms
[Fedora TemplateVM]: /doc/templates/fedora/
[Fedora Project]: https://getfedora.org/
[schedule]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule

115
user/managing-os/debian/debian-minimal.md
View File

@ -1,115 +0,0 @@
---
layout: doc
title: Debian Minimal Template
permalink: /doc/templates/debian-minimal/
---
Debian - minimal
================
The template weighs about 200 MB compressed (0.75 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements.
The sections below contain instructions on cloning the template and provide some examples for commonly desired use cases.
Note that use of the minimal template requires some familiarity with the command line and basics of Qubes.
Installation
------------
The Debian minimal template can be installed with the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-debian-9-minimal
~~~
The download may take a while depending on your connection speed.
Duplication and first steps
---------------------------
It is highly recommended that you clone the original template, and make any changes in the clone instead of the original template.
The following command clones the template.
(Replace `your-new-clone` with your desired name.)
~~~
[user@dom0 ~]$ qvm-clone debian-9-minimal your-new-clone
~~~
You must start the template in order to customize it.
Customization
-------------
Customizing the template for specific use cases normally only requires installing additional packages.
The following table provides an overview of which packages are needed for which purpose.
As you would expect, the required packages can be installed in the running template with any apt-based command.
For example : (Replace "packages` with a space-delimited list of packages to be installed.)
~~~
[user@your-new-clone ~]$ sudo apt install packages
~~~
Qubes 4.0
---------
In Qubes R4.0 the minimal template is not configured for passwordless root.
To update or install packages to it, from a dom0 terminal window run:
~~~
[user@dom0 ~]$ qvm-run -u root debian-9-minimal xterm
~~~
to open a root terminal in the template, from which you can use apt tools without sudo.
You will have to do this every time you want root access if you choose not to enable passwordless root.
If you want the usual qubes `sudo ...` commands, open the root terminal using the above command, and in the root xterm window enter
~~~
bash-4.4# apt install qubes-core-agent-passwordless-root
~~~
Optionally check this worked: from the gui open the minimal template's xterm and give the command:
~~~
[user@debian-9-minimal ~]$ sudo -l
~~~
which should give you output that includes the NOPASSWD keyword.
### Package table for Qubes 4.0
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**Networking** | If you want networking | Install qubes-core-agent-networking
**Audio** | If you want sound from your VM... | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a template for a [FirewallVM](/doc/firewall/), like `sys-firewall` | Install `qubes-core-agent-networking`, and `nftables`. Also install `qubes-core-agent-dom0-updates` if you want to use a qube based on the template as an updateVM (normally sys-firewall).
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `qubes-core-agent-networking`, `qubes-core-agent-network-manager`, and `nftables`.
**NetVM (extra firmware)** | If your network devices need extra packages for a network VM | Use the `lspci` command to identify the devices, then find the package that provides necessary firnware and install it.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-usb-proxy`. To use USB mouse or keyboard install `qubes-input-proxy-sender`.
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | You may need to install network-manager VPN packages, depending on the VPN technology you'll be using. After creating a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly.
These packages are:
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template on which the qube responsible for 'dom0' updates (e.g. `sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop experience.
Also, there are packages to provide additional services:
- `qubes-gpg-split`: For implementing split GPG.
- `qubes-u2f`: For implementing secure forwarding of U2F messages.
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-img-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
- `qubes-thunderbird`: Additional tools for use in thunderbird.
- `qubes-app-shutdown-idle`: If you want qubes to automatically shutdown when idle.
- `qubes-mgmt-\*`: If you want to use salt management on the template and qubes.
Documentation on all of these can be found in the [docs](/doc)
You could, of course, use qubes-vm-recommended to automatically install many of these, but in that case you are well on the way to a standard Debian template.

91
user/managing-os/debian/debian-upgrade-8-to-9.md
View File

@ -1,91 +0,0 @@
---
layout: doc
title: Upgrading the Debian 8 Template to Debian 9
permalink: /doc/template/debian/upgrade-8-to-9/
redirect_from:
- /doc/debian-template-upgrade-8/
- /en/doc/debian-template-upgrade-8/
- /doc/DebianTemplateUpgrade8/
- /wiki/DebianTemplateUpgrade8/
---
Upgrading the Debian 8 Template
===============================
Please note that if you installed packages from one of the testing repositories you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r4.list` before attempting the upgrade.
Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
Summary: Upgrading a Debian 8 Template to Debian 9
--------------------------------------------------
[user@dom0 ~]$ qvm-clone debian-8 debian-9
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
[user@debian-9 ~]$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list
[user@debian-9 ~]$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r4.list
[user@debian-9 ~]$ sudo apt-get update && sudo apt-get dist-upgrade -y
[user@debian-9 ~]$ sudo apt-get autoremove
Detailed: Upgrading the Standard Debian 8 Template to Debian 9
--------------------------------------------------------------
These instructions will show you how to upgrade the standard Debian 8
TemplateVM to Debian 9. The same general procedure may be used to upgrade
any template based on the standard Debian 8 template.
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown debian-8
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone debian-8 debian-9
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
3. Update your apt repositories to use stretch instead of jessie
(This can be done manually with a text editor, but sed can be used to
automatically update the files.)
[user@debian-9 ~]$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list
[user@debian-9 ~]$ sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r4.list
4. Update the package lists and upgrade to Debian 9. During the process,
it will likely prompt to overwrite two files, qubes-r4.list and
pulse/client.conf. qubes-r4.list can be overwritten, while pulse/client.conf
need to left as the currently installed version.
[user@debian-9 ~]$ sudo apt-get update && sudo apt-get dist-upgrade -y
5. Remove unnecessary packages that were previously installed
[user@debian-9 ~]$ sudo apt-get autoremove
6. Shutdown the new TemplateVM via dom0 command line or Qubes VM Manager;
[user@dom0 ~]$ qvm-shutdown debian-9
7. (Recommended) [Switch everything that was set to the old template to the new
template.](/doc/templates/#how-to-switch-templates)
8. (Optional) Remove the old default template.
[user@dom0 ~]$ sudo yum remove qubes-template-debian-8
Additional Information
----------------------
Debian Stretch packages were first made available in the Qubes R3.1 repositories.
If sound is not working, you may need to enable the Qubes testing repository to get the testing version of qubes-gui-agent.
This can be done by editing the /etc/apt/sources.list.d/qubes-r4.list file and uncommenting the Qubes Updates Candidates repo.
User-initiated updates/upgrades may not run when a templateVM first starts.
This is due to a new Debian config setting that attempts to update automatically; it should be disabled with:
`sudo systemctl disable apt-daily.{service,timer}`.
Relevant Discussions
--------------------
* [Stretch Template Installation](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/4rdayBF_UTc)
* [Stretch availability in 3.2](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/cekPfBqQMOI)
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621)

208
user/managing-os/debian/debian-upgrade.md
View File

@ -1,122 +1,164 @@
---
layout: doc
title: Upgrading the Debian Templates
title: Upgrading Debian TemplateVMs
permalink: /doc/template/debian/upgrade/
redirect_from:
- /doc/template/debian/upgrade-8-to-9/
- /doc/debian-template-upgrade-8/
- /en/doc/debian-template-upgrade-8/
- /doc/DebianTemplateUpgrade8/
- /wiki/DebianTemplateUpgrade8/
---
Upgrading Debian Templates
===============================
# Upgrading Debian TemplateVMs
In general, upgrading a Debian template follows the same process as [upgrading a native Debian system][upgrade].
You should consult the release notes for the target version. For Debian-10 see [here][release].
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM].
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead.
Please note that if you installed packages from one of the testing repositories you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r4.list` before attempting the upgrade.
Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
By default, Qubes uses codenames in the apt sources files, although the templates are referred to by release number.
Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitons.
In this example we are upgrading from debian-9 (stretch) to debian-10 (buster)
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system][upgrade].
Summary: Upgrading a Debian Template
--------------------------------------------------
## Summary instructions for Debian TemplateVMs
1. Clone the existing template.
2. Open a terminal in the new template.
3. Edit the sources.list files to refer to the new version.
4. Perform the upgrade:
```
sudo apt update
sudo apt upgrade
sudo apt dist-upgrade
```
5. Compact the template
6. Shutdown and start using the new template.
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian version number *from* which you are upgrading, and `<new>` is the Debian version number *to* which you are upgrading.
Detailed instructions:
--------------------------------------------------------------
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo apt dist-upgrade
[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
[user@dom0 ~]$ qvm-start debian-<new>
[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
These instructions show you how to upgrade the standard Debian 9 TemplateVM to Debian 10.
**Recommended:** [Switch everything that was set to the old template to the new template.][switch]
## Detailed instructions for Debian TemplateVMs
These instructions will show you how to upgrade Debian TemplateVMs.
The same general procedure may be used to upgrade any template based on the standard Debian TemplateVM.
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian version number *from* which you are upgrading, and `<new>` is the Debian version number *to* which you are upgrading.
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown debian-9
[user@dom0 ~]$ qvm-shutdown debian-<old>
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone debian-9 debian-10
[user@dom0 ~]$ qvm-run -a debian-10 gnome-terminal
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
3. Update your apt repositories to use buster instead of stretch
(This can be done manually with a text editor, but sed can be used to automatically update the files.)
3. Update your `apt` repositories to use the new release's code name instead of the old release's code name.
(This can be done manually with a text editor, but `sed` can be used to automatically update the files.)
```
$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r4.list
```
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
4. Update the package lists and upgrade to Debian 10.
During the process, it may prompt you to overwrite the file `qubes-r4.list`.
You should overwrite this file.
```
$ sudo apt update
$ sudo apt upgrade
$ sudo apt dist-upgrade
```
5. (optional) Remove unnecessary packages that were previously installed
4. Update the package lists and upgrade.
During the process, it may prompt you to overwrite the file `qubes-r4.list`.
You should overwrite this file.
`sudo apt-get autoremove`
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo apt dist-upgrade
6. (optional) Clean cached packages from /var/cache/apt
```
$ sudo apt-get clean
```
5. (Optional) Remove unnecessary packages that were previously installed.
7. Compact the template.
[user@debian-<new> ~]$ sudo apt-get autoremove
8. Shutdown the new TemplateVM via dom0 command line or the Qube Manager.
6. (Optional) Clean cached packages from `/var/cache/apt`.
[user@debian-<new> ~]$ sudo apt-get clean
7. (Recommended) Trim the new template.
[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
[user@dom0 ~]$ qvm-start debian-<new>
[user@debian-<new> ~]$ sudo fstrim -av
8. Shut down the new TemplateVM.
[user@dom0 ~]$ qvm-shutdown debian-<new>
9. (Recommended) [Switch everything that was set to the old template to the new template.][switch]
10. (Optional) Change the global default template to use the new template.
10. (Optional) Make the new template the global default.
11. (Optional) Remove the old template using dom0 command line or the Qube Manager.
[user@dom0 ~]$ qubes-prefs --set debian-<new>
11. (Optional) Remove the old template.
(Make sure to type the name of the old template, not the new one.)
[user@dom0 ~]$ sudo dnf remove qubes-template-debian-<old>
Compacting the Upgraded Template
--------------------------------
## StandaloneVMs
1. Open a terminal in the template and run:
```
$ sudo fstrim -av
$ sudo shutdown -h
```
2. Restart the template and run step 1 again.
This ensures that changes in the upgrade process are not stored in a difference file.
The procedure for upgrading a Debian [StandaloneVM] is the same as for a TemplateVM.
Additional Information
----------------------
User-initiated updates/upgrades may not run when a templateVM first starts.
This is due to a Debian config setting that attempts to update the system automatically.
You should disable this by opening a terminal in the template and running:
```
$ sudo systemctl disable apt-daily.{service,timer}`.
```
## Release-specific notes
Look [here][jessie] for notes specific to updating a jessie template.
This section contains notes about upgrading to specific releases.
Relevant Discussions
--------------------
* [User apt commands blocked on startup][2621]
### Debian 10 ("Buster")
Please see [Debian's Buster upgrade instructions][buster].
### Debian 9 ("Stretch")
* The upgrade process may prompt you to overwrite two files: `qubes-r4.list` and `pulse/client.conf`.
`qubes-r4.list` can be overwritten, but `pulse/client.conf` must be left as the currently-installed version.
* If sound is not working, you may need to enable the Qubes testing repository to get the testing version of `qubes-gui-agent`.
This can be done by editing the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes Updates Candidates` repo.
* User-initiated updates/upgrades may not run when a templateVM first starts.
This is due to a new Debian config setting that attempts to update automatically; it should be disabled with `sudo systemctl disable apt-daily.{service,timer}`.
Relevant discussions:
* [Stretch Template Installation](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/4rdayBF_UTc)
* [Stretch availability in 3.2](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/cekPfBqQMOI)
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621)
Also see [Debian's Stretch upgrade instructions][stretch].
### Debian 8 ("Jessie")
Please see [Debian's Jessie upgrade instructions][jessie].
### End-of-life (EOL) releases
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)].
## Additional information
* Please note that, if you installed packages from one of the testing repositories, you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r4.list` before attempting the upgrade.
Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
* By default, Qubes uses code names in the `apt` sources files, although the templates are referred to by release number.
Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitions.
[Debian TemplateVM]: /doc/templates/debian/
[upgrade]: https://wiki.debian.org/DebianUpgrade
[2621]: https://github.com/QubesOS/qubes-issues/issues/2621
[switch]: /doc/templates/#how-to-switch-templates)
[release]: https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html
[switch]: /doc/templates/#how-to-switch-templates
[jessie]: /doc/template/debian/upgrade-8-to-9/
[switch]: /doc/templates/#switching
[jessie]: https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html
[stretch]: https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html
[buster]: https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html
[end-of-life (EOL)]: https://wiki.debian.org/DebianReleases#Production_Releases
[StandaloneVM]: /doc/standalone-and-hvm/

105
user/managing-os/debian/debian.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Debian Template
title: The Debian TemplateVM
permalink: /doc/templates/debian/
redirect_from:
- /doc/debian/
@ -9,40 +9,54 @@ redirect_from:
- /wiki/Templates/Debian/
---
Debian template(s)
===============
# The Debian TemplateVM
If you would like to use Debian Linux distribution in your qubes, you can install one of the available Debian templates.
Updates for these templates are provided by ITL and are signed by this key:
pub 4096R/47FD92FA 2014-07-27
Key fingerprint = 2D43 E932 54EE EA7C B31B 6A77 5E58 18AB 47FD 92FA
uid Qubes OS Debian Packages Signing Key
The key is already installed when you install (signed) template package.
You can also obtain the key from [git repository][git] which is also integrity-protected using signed git tags.
The Debian [TemplateVM] is an officially [supported] TemplateVM in Qubes OS.
This page is about the standard (or "full") Debian TemplateVM.
For the minimal version, please see the [Minimal TemplateVMs] page.
There is also a [Qubes page on the Debian Wiki].
Installing
----------
## Installing
Templates can be installed with the following command:
To [install] a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
Debian 7 (wheezy) - obsolete/archive:
$ sudo qubes-dom0-update qubes-template-debian-XX
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-7
(Replace `XX` with the Debian version number of the template you wish to install.)
Debian 8 (jessie) - oldoldstable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8
Debian 9 (stretch) - oldstable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-9
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
Debian-10 templates are currently available from the testing repository.
## After Installing
After installing a fresh Debian TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
3. If desired, [uninstall the old TemplateVM].
## Updating
Please see [Updating software in TemplateVMs].
## Upgrading
Please see [Upgrading Debian TemplateVMs].
## Release-specific notes
This section contains notes about specific Debian releases.
### Debian 10
Debian 10 templates are currently available from the testing repository.
Debian 10 (buster) - minimal:
@ -59,18 +73,8 @@ Debian 10 (buster) - stable:
Because this template was built *before* buster became stable, it cannot be updated without [manually accepting the change in status][5149].
Upgrading
---------
To upgrade an existing Debian TemplateVM, please consult [this guide][Upgrading]
Known issues
------------
### Starting services
The Debian way (generally) is to start daemons if they are installed.
This means that if you install (say) ssh-server in a template, *all* the qubes that use that template will run a ssh server when they start. (They will, naturally, all have the same server key.) This may not be what you want.
@ -116,20 +120,17 @@ One solution is to add a dummy interface to allow the package to install correct
ip link set d0 up
Contributing
----------------
If you want to help in improving the template, feel free to [contribute]
More information
----------------
* [Debian wiki](https://wiki.debian.org/Qubes)
[Upgrading]: /doc/template/debian/upgrade
[TemplateVM]: /doc/templates/
[Minimal TemplateVMs]: /doc/templates/minimal/
[Qubes page on the Debian Wiki]: https://wiki.debian.org/Qubes
[end-of-life]: https://wiki.debian.org/DebianReleases#Production_Releases
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[switch]: /doc/templates/#switching
[uninstall the old TemplateVM]: /doc/templates/#how-to-uninstall
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-softare-in-templatevms
[Upgrading Debian TemplateVMs]: /doc/template/debian/upgrade/
[5149]: https://github.com/QubesOS/qubes-issues/issues/5149
[git]: https://github.com/QubesOS/qubes-core-agent-linux/blob/master/misc/qubes-archive-keyring.gpg
[builder]: /doc/qubes-builder/
[contribute]: /doc/contributing/
[install]: /doc/templates/#installing

134
user/managing-os/fedora/fedora-minimal.md
View File

@ -1,134 +0,0 @@
---
layout: doc
title: The Fedora Minimal TemplateVM
permalink: /doc/templates/fedora-minimal/
redirect_from:
- /doc/fedora-minimal/
- /en/doc/templates/fedora-minimal/
- /doc/Templates/FedoraMinimal/
- /wiki/Templates/FedoraMinimal/
---
The Fedora Minimal TemplateVM
=============================
The Fedora Minimal TemplateVM (`fedora-minimal`) only weighs about 600 MB compressed (1.6 GB on disk) and has only the most vital packages installed, including a minimal X and xterm installation.
The sections below contain instructions for using the template and provide some examples for common use cases.
Important
---------
1. The Fedora Minimal template is intended only for advanced users.
If you encounter problems with the Fedora Minimal template, we recommend that you use the [default Fedora template] instead.
2. If something works with the default Fedora template but not the Fedora Minimal template, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, you should write to [qubes-users] to ask for help rather than filing a bug report, then [contribute what you learn to the documentation][doc-guidelines].
3. The Fedora Minimal template is intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
Installation
------------
The Fedora Minimal template can be installed with the following command (where `XX` is your desired version number):
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-XX-minimal
~~~
The download may take a while depending on your connection speed.
Customization
-------------
It is highly recommended to clone the original template and make any changes in the clone instead of the original template.
The following command clones the template.
Replace `XX` with your installed Fedora Minimal version number and `your-new-clone` with your desired clone name.
~~~
[user@dom0 ~]$ qvm-clone fedora-XX-minimal your-new-clone
~~~
You must start the clone in order to customize it.
Customizing the template for specific use cases normally only requires installing additional packages.
The following list provides an overview of which packages are needed for which purpose.
As usual, the required packages are to be installed in the running template with the following command (replace `packages` with a space-delimited list of packages to be installed):
~~~
[user@your-new-clone ~]$ sudo dnf install packages
~~~
- Commonly used utilities: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`.
- Audio: `pulseaudio-qubes`.
- [FirewallVM](/doc/firewall/), such as the template for `sys-firewall`: at least `qubes-core-agent-networking` and `iproute`, and also `qubes-core-agent-dom0-updates` if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dejavu-sans-fonts` `notification-daemon` `gnome-keyring` `polkit` `@hardware-support`.
If your network devices need extra packages for the template to work as a network VM, use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
If you need utilities for debugging and analyzing network connections, install `tcpdump` `telnet` `nmap` `nmap-ncat`.
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-input-proxy-sender`.
- [VPN qube](/doc/vpn/): Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them.
Some GNOME related packages may be needed as well.
After creation of a machine based on this template, follow the [VPN instructions](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
You may also wish to consider additional packages from the `qubes-core-agent` suite:
- `qubes-core-agent-qrexec`: Qubes qrexec agent. Installed by default.
- `qubes-core-agent-systemd`: Qubes unit files for SystemD init style. Installed by default.
- `qubes-core-agent-passwordless-root`, `polkit`: By default, the Fedora Minimal template doesn't have passwordless root. These two packages enable this feature.
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it things like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-sysvinit`: Qubes unit files for SysV init style or upstart.
- `qubes-core-agent-networking`: Networking support. Required for general network access and particularly if the template is to be used for a `sys-net` or `sys-firewall` VM.
- `qubes-core-agent-network-manager`: Integration for NetworkManager. Useful if the template is to be used for a `sys-net` VM.
- `network-manager-applet`: Useful (together with `dejavu-sans-fonts` and `notification-daemon`) to have a system tray icon if the template is to be used for a `sys-net` VM.
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template which the VM responsible for 'dom0' updates (e.g. `sys-firewall`) is based on must contain this package.
- `qubes-usb-proxy`: Required if the template is to be used for a USB qube (`sys-usb`) or for any destination qube to which USB devices are to be attached (e.g `sys-net` if using USB network adapter).
- `pulseaudio-qubes`: Needed to have audio on the template VM.
See [here][customization] for further information on customizing `fedora-minimal`.
Passwordless root
-----------------
It is an intentional design choice for passwordless to be optional.
Since the Fedora Minimal template is *minimal*, it is not configured for passwordless root by default.
To update or install packages to it, from a dom0 terminal window:
~~~
[user@dom0 ~]$ qvm-run -u root fedora-29-minimal xterm
~~~
to open a root terminal in the template, from which you can use dnf without sudo. You will have to do this every time if you choose not to enable passwordless root.
If you want the usual qubes `sudo dnf ...` commands, open the root terminal just this once using the above command, and in the root xterm window enter
~~~
bash-4.4# dnf install qubes-core-agent-passwordless-root polkit
~~~
Optionally check this worked: from the gui open the minimal template's xterm and give the command
~~~
[user@fed-min-clone ~]$ sudo -l
~~~
which should give you output that includes the NOPASSWD keyword.
Logging
-------
The `rsyslog` logging service is not installed by default, as all logging is instead being handled by the `systemd` journal.
Users requiring the `rsyslog` service should install it manually.
To access the `journald` log, use the `journalctl` command.
[default Fedora template]: /doc/templates/fedora/
[qubes-users]: /support/#qubes-users
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[customization]: /doc/fedora-minimal-template-customization/

208
user/managing-os/fedora/fedora-upgrade-26-to-27.md
View File

@ -1,208 +0,0 @@
---
layout: doc
title: Upgrading the Fedora 26 Template to Fedora 27
permalink: /doc/template/fedora/upgrade-26-to-27/
redirect_from:
- /doc/fedora-template-upgrade-26/
- /en/doc/fedora-template-upgrade-26/
- /doc/FedoraTemplateUpgrade26/
- /wiki/FedoraTemplateUpgrade26/
---
Upgrading the Fedora 26 Template to Fedora 27
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 26 [TemplateVM] to Fedora 27. If you wish to install a new,
unmodified Fedora 27 template instead of upgrading a template that is already
installed in your system, please see the [Fedora TemplateVM] page instead.
These instructions can also be used to upgrade a Fedora 25 TemplateVM to
Fedora 27. Simply start by cloning `fedora-25` instead of `fedora-26` in the
instructions below.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 26 to 27, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Instructions
------------
### Summary: Upgrading the Standard Fedora 26 Template to Fedora 27 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-27`).
[user@dom0 ~]$ qvm-clone fedora-26 fedora-27
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-27 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-27 dom0:${dev##*/}
[user@fedora-27 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-27 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-27 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 26 Template to Fedora 27 ###
These instructions will show you how to upgrade the standard Fedora 26
TemplateVM to Fedora 27. The same general procedure may be used to upgrade any
template based on the standard Fedora 26 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-27`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-26
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-26 fedora-27
[user@dom0 ~]$ qvm-run -a fedora-27 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc27.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID f5282ee4: NOKEY
Importing GPG key 0xF5282EE4:
Userid : "Fedora (27) <fedora-27-primary@fedoraproject.org>"
Fingerprint: 860E 19B0 AFA8 00A1 7518 81A6 F55E 7430 F528 2EE4
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-27-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-27 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-27 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-27 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-27 ~]$ sudo dnf clean all
[user@fedora-27 ~]$ sudo dnf --releasever=27 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Trim the new template.
[user@fedora-27 ~]$ sudo fstrim -v /
5. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-27
6. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
7. (Recommended) [Switch everything that was set to the old template to the new
template.][switching]
8. (Optional) Remove the old template. (Make sure to type `fedora-26`, not
`fedora-27`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-26
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 26 to Fedora 27 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 26 Template to Fedora 27 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-27`).
[user@dom0 ~]$ qvm-clone fedora-26-minimal fedora-27-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-27-minimal xterm
[root@fedora-27-minimal ~]# dnf clean all
[user@fedora-27-minimal ~]# dnf --releasever=27 --best --allowerasing distro-sync
[user@fedora-27-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
4. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching]: /doc/templates/#how-to-switch-templates
[DispVM]: /doc/disposablevm/

231
user/managing-os/fedora/fedora-upgrade-27-to-28.md
View File

@ -1,231 +0,0 @@
---
layout: doc
title: Upgrading the Fedora 27 Template to Fedora 28
permalink: /doc/template/fedora/upgrade-27-to-28/
redirect_from:
- /doc/fedora-template-upgrade-27/
- /en/doc/fedora-template-upgrade-27/
- /doc/FedoraTemplateUpgrade27/
- /wiki/FedoraTemplateUpgrade27/
---
Upgrading the Fedora 27 Template to Fedora 28
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 27 [TemplateVM] to Fedora 28. If you wish to install a new,
unmodified Fedora 28 template instead of upgrading a template that is already
installed in your system, please see the [Fedora TemplateVM] page instead.
These instructions can also be used to upgrade a Fedora 26 TemplateVM to
Fedora 28. Simply start by cloning `fedora-26` instead of `fedora-27` in the
instructions below.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 27 to 28, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Workaround for `python2-xcffib` upgrade error
---------------------------------------------
When attempting to upgrade from Fedora 26 or 27 to Fedora 28, you may encounter an error similar to this:
Error: Transaction check error:
file /usr/lib/python2.7/site-packages/xcffib-0.5.1-py2.7.egg-info/PKG-INFO from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/_ffi.pyc from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/_ffi.pyo from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/xinput.pyc from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
file /usr/lib/python2.7/site-packages/xcffib/xinput.pyo from install of python2-xcffib-0.5.1-5.fc28.noarch conflicts with file from package python-xcffib-0.5.1-1.fc26.noarch
To work around this error:
1. Upgrade while excluding the problematic packages by using `-x python2-xcffib -x qubes-gui-vm -x qubes-gui-agent`.
2. Upgrade `python2-xcffib` using `sudo dnf swap python-xcffib python2-xcffib`.
(This should automatically upgrade the other excluded packages too.)
Instructions
------------
### Summary: Upgrading the Standard Fedora 27 Template to Fedora 28 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-28`).
[user@dom0 ~]$ qvm-clone fedora-27 fedora-28
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-28 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-28 dom0:${dev##*/}
[user@fedora-28 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-28 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-28 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 27 Template to Fedora 28 ###
These instructions will show you how to upgrade the standard Fedora 27
TemplateVM to Fedora 28. The same general procedure may be used to upgrade any
template based on the standard Fedora 27 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-28`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-27
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-27 fedora-28
[user@dom0 ~]$ qvm-run -a fedora-28 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc28.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 9db62fb1: NOKEY
Importing GPG key 0x9DB62FB1:
Userid : "Fedora (28) <fedora-28-primary@fedoraproject.org>"
Fingerprint: 128C F232 A937 1991 C8A6 5695 E08E 7E62 9DB6 2FB1
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-28 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-28 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-28 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-28 ~]$ sudo dnf clean all
[user@fedora-28 ~]$ sudo dnf --releasever=28 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Check that you are on the correct (new) fedora release.
[user@fedora-28 ~]$ cat /etc/fedora-release
5. Trim the new template.
[user@fedora-28 ~]$ sudo fstrim -v /
6. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-28
7. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
8. (Recommended) [Switch everything that was set to the old template to the new
template.][switching]
9. (Optional) Remove the old template. (Make sure to type `fedora-27`, not
`fedora-28`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-27
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 27 to Fedora 28 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 27 Template to Fedora 28 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-28`).
[user@dom0 ~]$ qvm-clone fedora-27-minimal fedora-28-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-28-minimal xterm
[root@fedora-28-minimal ~]# dnf clean all
[user@fedora-28-minimal ~]# dnf --releasever=28 --best --allowerasing distro-sync
[user@fedora-28-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
4. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching]: /doc/templates/#how-to-switch-templates
[DispVM]: /doc/disposablevm/

212
user/managing-os/fedora/fedora-upgrade-28-to-29.md
View File

@ -1,212 +0,0 @@
---
layout: doc
title: Upgrading the Fedora 28 Template to Fedora 29
permalink: /doc/template/fedora/upgrade-28-to-29/
redirect_from:
- /doc/fedora-template-upgrade-28/
- /en/doc/fedora-template-upgrade-28/
- /doc/FedoraTemplateUpgrade28/
- /wiki/FedoraTemplateUpgrade28/
---
Upgrading the Fedora 28 Template to Fedora 29
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 28 [TemplateVM] to Fedora 29. If you wish to install a new,
unmodified Fedora 29 template instead of upgrading a template that is already
installed in your system, please see the [Fedora TemplateVM] page instead.
These instructions can also be used to upgrade a Fedora 26 TemplateVM to
Fedora 29. Simply start by cloning `fedora-26` instead of `fedora-28` in the
instructions below.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 28 to 29, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Instructions
------------
### Summary: Upgrading the Standard Fedora 28 Template to Fedora 29 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-29`).
[user@dom0 ~]$ qvm-clone fedora-28 fedora-29
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-29 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-29 dom0:${dev##*/}
[user@fedora-29 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-29 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-29 ~]$ sudo dnf clean all
[user@fedora-29 ~]$ sudo dnf --releasever=29 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-29 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 28 Template to Fedora 29 ###
These instructions will show you how to upgrade the standard Fedora 28
TemplateVM to Fedora 29. The same general procedure may be used to upgrade any
template based on the standard Fedora 28 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-29`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-28
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-28 fedora-29
[user@dom0 ~]$ qvm-run -a fedora-29 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-29 ~]$ sudo dnf clean all
[user@fedora-29 ~]$ sudo dnf --releasever=29 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /mnt/removable/updates-0b4cc238d1aa4ffe/packages/kernel-4.18.17-300.fc29.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 429476b4: NOKEY
Importing GPG key 0x429476B4:
Userid : "Fedora 29 (29) <fedora-29@fedoraproject.org>"
Fingerprint: 5A03 B4DD 8254 ECA0 2FDA 1637 A20A A56B 4294 76B4
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-29-x86_64
Is this ok [y/N]: y
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-29 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-29 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-29 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-29 ~]$ sudo dnf clean all
[user@fedora-29 ~]$ sudo dnf --releasever=29 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Check that you are on the correct (new) fedora release.
[user@fedora-29 ~]$ cat /etc/fedora-release
5. Trim the new template.
[user@fedora-29 ~]$ sudo fstrim -v /
6. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-29
7. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
8. (Recommended) [Switch everything that was set to the old template to the new
template.][switching]
9. (Optional) Remove the old template. (Make sure to type `fedora-28`, not
`fedora-29`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-28
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 28 to Fedora 29 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 28 Template to Fedora 29 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-29`).
[user@dom0 ~]$ qvm-clone fedora-28-minimal fedora-29-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-29-minimal xterm
[root@fedora-29-minimal ~]# dnf clean all
[user@fedora-29-minimal ~]# dnf --releasever=29 --best --allowerasing distro-sync
[user@fedora-29-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
4. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching]: /doc/templates/#how-to-switch-templates
[DispVM]: /doc/dispvm/

213
user/managing-os/fedora/fedora-upgrade.md Normal file
View File

@ -0,0 +1,213 @@
---
layout: doc
title: Upgrading Fedora TemplateVMs
permalink: /doc/template/fedora/upgrade/
redirect_from:
- /doc/template/fedora/upgrade-26-to-27/
- /doc/fedora-template-upgrade-26/
- /en/doc/fedora-template-upgrade-26/
- /doc/FedoraTemplateUpgrade26/
- /wiki/FedoraTemplateUpgrade26/
- /doc/template/fedora/upgrade-27-to-28/
- /doc/fedora-template-upgrade-27/
- /en/doc/fedora-template-upgrade-27/
- /doc/FedoraTemplateUpgrade27/
- /wiki/FedoraTemplateUpgrade27/
- /doc/template/fedora/upgrade-28-to-29/
- /doc/fedora-template-upgrade-28/
- /en/doc/fedora-template-upgrade-28/
- /doc/FedoraTemplateUpgrade28/
- /wiki/FedoraTemplateUpgrade28/
- /doc/template/fedora/upgrade-29-to-30/
---
# Upgrading Fedora TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM].
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead.
## Summary instructions for standard Fedora TemplateVMs
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `fedora-<old>`, or `fedora-<new>`, where `<old>` is the Fedora version number *from* which you are upgrading, and `<new>` is the Fedora version number *to* which you are upgrading.
[user@dom0 ~]$ qvm-clone fedora-<old> fedora-<new>
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-<new> gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-<new> dom0:${dev##*/}
[user@fedora-<new> ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-<new> ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-<new> ~]$ sudo dnf clean all
[user@fedora-<new> ~]$ sudo dnf --releasever=<new> --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown fedora-<new>
[user@dom0 ~]$ qvm-start fedora-<new>
[user@fedora-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown fedora-<new>
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
**Recommended:** [Switch everything that was set to the old template to the new template.][switch]
## Detailed instructions for standard Fedora TemplateVMs
These instructions will show you how to upgrade the standard Fedora TemplateVM.
The same general procedure may be used to upgrade any template based on the standard Fedora TemplateVM.
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `fedora-<old>`, or `fedora-<new>`, where `<old>` is the Fedora version number *from* which you are upgrading, and `<new>` is the Fedora version number *to* which you are upgrading.
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-<old>
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-<old> fedora-<new>
[user@dom0 ~]$ qvm-run -a fedora-<new> gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-<new> ~]$ sudo dnf clean all
[user@fedora-<new> ~]$ sudo dnf --releasever=<new> distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing key.
For example, you might see a prompt like this one:
warning: /mnt/removable/updates-0b4cc238d1aa4ffe/packages/example-package.fc<new>.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID XXXXXXXX: NOKEY
Importing GPG key 0xXXXXXXXX:
Userid : "Fedora <new> (<new>) <fedora-<new>@fedoraproject.org>"
Fingerprint: XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-<new>-x86_64
Is this ok [y/N]: y
This key was already checked when it was installed (notice that the "From" line refers to a location on your local disk), so you can safely say yes to this prompt.
**Note:** If you encounter no errors, proceed to step 4.
If you do encounter errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-<new> dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk as a cache.
[user@fedora-<new> ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-<new> ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-<new> ~]$ sudo dnf clean all
[user@fedora-<new> ~]$ sudo dnf --releasever=<new> --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Check that you are on the correct (new) Fedora release.
[user@fedora-<new> ~]$ cat /etc/fedora-release
5. (Recommended) Trim the new template.
[user@fedora-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown fedora-<new>
[user@dom0 ~]$ qvm-start fedora-<new>
[user@fedora-<new> ~]$ sudo fstrim -av
6. Shut down the new TemplateVM.
[user@dom0 ~]$ qvm-shutdown fedora-<new>
7. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
8. (Recommended) [Switch everything that was set to the old template to the new template.][switch]
9. (Optional) Make the new template the global default.
[user@dom0 ~]$ qubes-prefs --set fedora-<new>
10. (Optional) Remove the old template.
(Make sure to type the name of the old template, not the new one.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-<old>
## Summary instructions for Fedora Minimal TemplateVMs
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `fedora-<old>`, or `fedora-<new>`, where `<old>` is the Fedora version number *from* which you are upgrading, and `<new>` is the Fedora version number *to* which you are upgrading.
[user@dom0 ~]$ qvm-clone fedora-<old>-minimal fedora-<new>-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-<new>-minimal xterm
[root@fedora-<new>-minimal ~]# dnf clean all
[user@fedora-<new>-minimal ~]# dnf --releasever=<new> --best --allowerasing distro-sync
[user@fedora-<new>-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods described for the standard template above.)
## StandaloneVMs
The procedure for upgrading a Fedora [StandaloneVM] is the same as for a TemplateVM.
## Release-specific notes
This section contains notes about upgrading to specific releases.
### Fedora 30
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM to 30, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
### End-of-life (EOL) releases
We strongly recommend against using any Fedora release that has reached [end-of-life (EOL)].
## Additional information
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by uninstalling packages.
You may then reinstall them again after you finish the upgrade process, if desired).
However, you may end up having to increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups.
(First upgrade `@core` packages, then the rest.)
4. Do not perform an in-place upgrade.
Instead, simply download and install a new template package, then redo all desired template modifications.
Here are some useful messages from the mailing list that also apply to TemplateVM management and migration in general from
[Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J) and
[Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ).
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[switch]: /doc/templates/#switching
[DispVM]: /doc/dispvm/
[end-of-life (EOL)]: https://fedoraproject.org/wiki/End_of_life
[StandaloneVM]: /doc/standalone-and-hvm/

51
user/managing-os/fedora/fedora.md
View File

@ -4,25 +4,16 @@ title: The Fedora TemplateVM
permalink: /doc/templates/fedora/
---
The Fedora TemplateVM
=====================
# The Fedora TemplateVM
The Fedora [TemplateVM] is the default TemplateVM in Qubes OS.
This page is about the standard (or "full") Fedora TemplateVM.
For the minimal version, please see the [Fedora Minimal] page.
For the minimal version, please see the [Minimal TemplateVMs] page.
Installing
----------
The Fedora TemplateVM comes preinstalled with Qubes OS.
However, there may be times when you wish to install a fresh copy from the Qubes repositories, e.g.:
## Installing
* When a version of Fedora reaches EOL ([end-of-life]).
* When a new version of Fedora you wish to use becomes [supported] as a TemplateVM.
* When you suspect your Fedora TemplateVM has been compromised.
* When you have made modifications to the Fedora TemplateVM that you no longer want.
To install a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install] a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
$ sudo qubes-dom0-update qubes-template-fedora-XX
@ -31,35 +22,43 @@ To install a specific Fedora TemplateVM that is not currently installed in your
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
After Installing
----------------
## After Installing
After installing a fresh Fedora TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch-templates].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
3. If desired, [uninstall the old TemplateVM].
Upgrading
---------
## Updating
To upgrade your Fedora TemplateVM, please consult the guide that corresponds to your situation:
Please see [Updating software in TemplateVMs].
* [Upgrading the Fedora 29 Template to Fedora 30](/doc/template/fedora/upgrade-29-to-30/)
* [Upgrading the Fedora 28 Template to Fedora 29](/doc/template/fedora/upgrade-28-to-29/)
* [Upgrading the Fedora 27 Template to Fedora 28](/doc/template/fedora/upgrade-27-to-28/)
* [Upgrading the Fedora 26 Template to Fedora 27](/doc/template/fedora/upgrade-26-to-27/)
## Upgrading
Please see [Upgrading Fedora TemplateVMs].
## Release-specific notes
This section contains notes about specific Fedora releases.
(There is currently no release-specific information documented.)
[TemplateVM]: /doc/templates/
[Fedora Minimal]: /doc/templates/fedora-minimal/
[Minimal TemplateVMs]: /doc/templates/minimal/
[end-of-life]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[switch-templates]: /doc/templates/#how-to-switch-templates
[uninstall the old TemplateVM]: /doc/templates/#how-to-uninstall
[switch]: /doc/templates/#switching
[uninstall the old TemplateVM]: /doc/templates/#uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-softare-in-templatevms
[Upgrading Fedora TemplateVMs]: /doc/template/fedora/upgrade/
[install]: /doc/templates/#installing

185
user/managing-os/fedora/upgrade-29-to-30.md
View File

@ -1,185 +0,0 @@
---
layout: doc
title: Upgrading the Fedora 29 TemplateVM to Fedora 30
permalink: /doc/template/fedora/upgrade-29-to-30/
---
Upgrading the Fedora 29 TemplateVM to Fedora 30
===============================================
This page provides instructions for performing an in-place upgrade of an installed Fedora 29 [TemplateVM] to Fedora 30.
If you wish to install a new, unmodified Fedora 30 template instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead.
Important information regarding RPM Fusion repos
------------------------------------------------
If your RPM Fusion repositories are **disabled** when you upgrade a TemplateVM from Fedora 29 to 30, all RPM Fusion packages and RPM Fusion repo definitions will be removed from that TemplateVM.
If your RPM Fusion repositories are **enabled** when upgrading, all RPM Fusion packages and repo definitions will be retained and updated as expected.
For most users, this behavior should not cause a problem, since a TemplateVM in which the RPM Fusion repos are disabled is probably a TemplateVM in which you never wish to use them.
However, if you wish to have the RPM Fusion repo definitions after upgrading in a TemplateVM in which they are currently disabled, you may wish to temporarily enable them prior to upgrading or manually create, copy, or download them after upgrading.
Summary Instructions for Standard Fedora TemplateVMs
----------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered (`@dom0` or `@fedora-30`).
[user@dom0 ~]$ qvm-clone fedora-29 fedora-30
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-30 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-30 dom0:${dev##*/}
[user@fedora-30 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-30 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-30 ~]$ sudo dnf clean all
[user@fedora-30 ~]$ sudo dnf --releasever=30 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-30 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
(Optional cleanup: Switch everything over to the new template and delete the old one.
See instructions below for details.)
Detailed Instructions for Standard Fedora TemplateVMs
-----------------------------------------------------
These instructions will show you how to upgrade the standard Fedora 29 TemplateVM to Fedora 30.
The same general procedure may be used to upgrade any template based on the standard Fedora 29 template.
**Note:** The command-line prompt on each line indicates where each command should be entered (`@dom0` or `@fedora-30`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-29
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-29 fedora-30
[user@dom0 ~]$ qvm-run -a fedora-30 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-30 ~]$ sudo dnf clean all
[user@fedora-30 ~]$ sudo dnf --releasever=30 distro-sync --best --allowerasing
**Note:** `dnf` might ask you to approve importing a new package signing key.
For example, you might see a prompt like this one:
warning: /mnt/removable/updates-0b4cc238d1aa4ffe/packages/example-package.fc30.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID cfc659b9: NOKEY
Importing GPG key 0xCFC659B9:
Userid : "Fedora 30 (30) <fedora-30@fedoraproject.org>"
Fingerprint: F1D8 EC98 F241 AAF2 0DF6 9420 EF3C 111F CFC6 59B9
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-30-x86_64
Is this ok [y/N]: y
This key was already checked when it was installed (notice that the "From" line refers to a location on your local disk), so you can safely say yes to this prompt.
**Note:** If you encounter no errors, proceed to step 4.
If you do encounter errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-30 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk as a cache.
[user@fedora-30 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-30 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-30 ~]$ sudo dnf clean all
[user@fedora-30 ~]$ sudo dnf --releasever=30 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Check that you are on the correct (new) fedora release.
[user@fedora-30 ~]$ cat /etc/fedora-release
5. Trim the new template.
[user@fedora-30 ~]$ sudo fstrim -v /
6. Shut down the new TemplateVM (from the command line or the Qube Manager).
[user@dom0 ~]$ qvm-shutdown fedora-30
7. Remove the cache file, if you created one.
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
8. (Recommended) [Switch everything that was set to the old template to the new template.][switching]
9. (Optional) Remove the old template. (Make sure to type `fedora-29`, not `fedora-30`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-29
Summary Instructions for Fedora Minimal TemplateVMs
---------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered (`@dom0` or `@fedora-30`).
[user@dom0 ~]$ qvm-clone fedora-29-minimal fedora-30-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-30-minimal xterm
[root@fedora-30-minimal ~]# dnf clean all
[user@fedora-30-minimal ~]# dnf --releasever=30 --best --allowerasing distro-sync
[user@fedora-30-minimal ~]# fstrim -v /
(Shut down TemplateVM by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods described for the standard template above.)
Upgrading StandaloneVMs
-----------------------
The procedure for upgrading a StandaloneVM from Fedora 29 to Fedora 30 is the same as for a TemplateVM.
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by uninstalling packages.
You may then reinstall them again after you finish the upgrade process, if desired).
However, you may end up having to increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups.
(First upgrade `@core` packages, then the rest.)
4. Do not perform an in-place upgrade.
Instead, simply download and install a new template package, then redo all desired template modifications.
Here are some useful messages from the mailing list that also apply to TemplateVM management and migration in general from
[Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J) and
[Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ).
[TemplateVM]: /doc/templates/
[Fedora TemplateVM]: /doc/templates/fedora/
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[switching]: /doc/templates/#how-to-switch-templates
[DispVM]: /doc/dispvm/

80
user/managing-os/hvm.md
View File

@ -1,29 +1,58 @@
---
layout: doc
title: HVM
permalink: /doc/hvm/
title: StandaloneVMs and HVMs
permalink: /doc/standalone-and-hvm
redirect_from:
- /doc/hvm/
- /doc/hvm-create/
- /en/doc/hvm-create/
- /doc/HvmCreate/
- /wiki/HvmCreate/
---
HVM
===
# StandaloneVMs and HVMs
A **Hardware-assisted Virtual Machine (HVM)**, also known as a **Fully-Virtualized Virtual Machine**, utilizes the virtualization extensions of the host CPU.
These are typically contrasted with **Paravirtualized (PV)** VMs.
A [StandaloneVM](/doc/glossary/#standalonevm) is a type of VM in Qubes that is created by cloning a [TemplateVM](/doc/templates/).
Unlike TemplateVMs, however, StandaloneVMs do not supply their root filesystems to other VMs.
Examples of situations in which StandaloneVMs can be useful include:
HVMs allow you to create qubes based on any OS for which you have an installation ISO.
So you can easily have qubes running Windows, *BSD, or any Linux distribution. You can also use HVMs to run "live" distros.
* VMs used for development (dev environments often require a lot of specific packages and 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.
By default, every Qubes VM runs in **PVH** mode (which has security advantages over both PV and HVM) except for those with attached PCI devices, which run in HVM mode.
Meanwhile, a [Hardware-assisted Virtual Machine (HVM)](/doc/glossary/#hvm), also known as a "Fully-Virtualized Virtual Machine," utilizes the virtualization extensions of the host CPU.
These are typically contrasted with [Paravirtualized (PV)](/doc/glossary/#pv) VMs.
HVMs allow you to create qubes based on any OS for which you have an installation ISO, so you can easily have qubes running Windows, *BSD, or any Linux distribution.
You can also use HVMs to run "live" distros.
By default, every Qubes VM runs in [PVH](/doc/glossary/#pvhvm) mode (which has security advantages over both PV and HVM) except for those with attached PCI devices, which run in HVM mode.
See [here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion of the switch from PV to HVM and [here](/news/2018/01/11/qsb-37/) for the announcement about the change to using PVH as default.
The StandaloneVM/TemplateVM distinction and the HVM/PV/PVH distinctions are orthogonal.
The former is about root filesystem inheritance, whereas the latter is about the virtualization mode.
In practice, however, it is most common for StandaloneVMs to be HVMs and for HVMs to be StandaloneVMs.
In fact, this is so common that [StandaloneHVMs](/doc/glossary/#standalonehvm) are typically just called "HVMs."
Hence, this page covers both topics.
Creating an HVM qube
----------------------
## Creating a StandaloneVM
You can create a StandaloneVM in the Qube Manager by selecting the "Type" of "Standalone qube copied from a template" or "Empty standalone qube (install your own OS)."
Alternatively, from the dom0 command line:
```
qvm-create --class StandaloneVM --label <label> --property virt_mode=hvm <vmname>
```
(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM.
However, it makes sense if you want to use a kernel from within the VM.)
## Creating an HVM
Using the GUI:
In Qube Manager, select "Create new qube" from the Qube menu, or select the "Create a new qube" button.
@ -49,8 +78,7 @@ libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86
Make sure that you give the new qube adequate memory to install and run.
Installing an OS in an HVM qube
---------------------------------
## Installing an OS in an HVM
You will have to boot the qube with the installation media "attached" to it. You may either use the GUI or use command line instructions.
At the command line you can do this in three ways:
@ -76,8 +104,7 @@ You may have to restart the qube several times in order to complete installation
Several invocations of `qvm-start` command (as shown above) might be needed.
Setting up networking for HVM domains
-------------------------------------
## Setting up networking for HVMs
Just like standard paravirtualized AppVMs, the HVM qubes get fixed IP addresses centrally assigned by Qubes.
Normally Qubes agent scripts (or services on Windows) running within each AppVM are responsible for setting up networking within the VM according to the configuration created by Qubes (through [keys](/doc/vm-interface/#qubesdb) exposed by dom0 to the VM).
@ -99,13 +126,12 @@ The DNS IP addresses are `10.139.1.1` and `10.139.1.2`.
There is [opt-in support](/doc/networking/#ipv6) for IPv6 forwarding.
Using Template-based HVM domains
--------------------------------
## Using TemplateBasedHVMs
Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just as for Linux AppVMs.
Qubes allows HVMs to share a common root filesystem from a select TemplateVM (see [TemplateHVM](/doc/glossary/#templatehvm) and [TemplateBasedHVM](/doc/glossary/#templatebasedhvm)).
This mode can be used for any HVM (e.g. FreeBSD running in a HVM).
In order to create a HVM TemplateVM you use the following command, suitably adapted:
In order to create a TemplateHVM you use the following command, suitably adapted:
~~~
qvm-create --class TemplateVM <qube> --property virt_mode=HVM --property kernel='' -l green
@ -120,8 +146,7 @@ If you use this Template as it is, then any HVMs that use it will effectively be
Please see [this page](/doc/windows-appvms/) for specific advice on installing and using Windows-based Templates.
Cloning HVM domains
-------------------
## Cloning HVMs
Just like normal AppVMs, the HVM domains can also be cloned either using the command-line `qvm-clone` or via the Qube Manager's 'Clone VM' option in the right-click menu.
@ -222,9 +247,7 @@ timezone : localtime
~~~
Assigning PCI devices to HVM domains
------------------------------------
## Assigning PCI devices to HVMs
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs.
E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc.
@ -236,10 +259,9 @@ This is illustrated on the screenshot below:
![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)
Converting VirtualBox VM to HVM
-------------------------------
## Converting VirtualBox VMs to Qubes HVMs
You can convert any VirtualBox VMs to an HVM using this method.
You can convert any VirtualBox VM to a Qubes HVM using this method.
For example, Microsoft provides [free 90 day evaluation VirtualBox VMs for browser testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/).
@ -310,10 +332,10 @@ qemu-img -h | tail -n1
~~~
Further reading
---------------
## Further reading
Other documents related to HVM:
- [Windows VMs](/doc/windows-vm/)
- [LinuxHVMTips](/doc/linux-hvm-tips/)

174
user/managing-os/minimal-templates.md Normal file
View File

@ -0,0 +1,174 @@
---
layout: doc
title: Minimal TemplateVMs
permalink: /doc/templates/minimal/
redirect_from:
- /doc/templates/fedora-minimal/
- /doc/fedora-minimal/
- /en/doc/templates/fedora-minimal/
- /doc/Templates/FedoraMinimal/
- /wiki/Templates/FedoraMinimal/
- /doc/templates/debian-minimal/
---
# Minimal TemplateVMs
The Minimal [TemplateVMs] are lightweight versions of their standard TemplateVM counterparts.
They have only the most vital packages installed, including a minimal X and xterm installation.
The sections below contain instructions for using the template and provide some examples for common use cases.
There are currently two Minimal TemplateVMs corresponding to the standard [Fedora] and [Debian] TemplateVMs.
## Important
1. The Minimal TemplateVMs are intended only for advanced users.
If you encounter problems with the Minimal TemplateVMs, we recommend that you use theird standard TemplateVM counterparts instead.
2. If something works with a standard TemplateVM but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, you should write to [qubes-users] to ask for help rather than filing a bug report, then [contribute what you learn to the documentation][doc-guidelines].
3. The Minimal TemplateVMs are intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
## Installation
The Minimal TemplateVMs can be installed with the following command (where `X` is your desired distro and version number):
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-minimal
If your desired version is not found, it may still be in [testing].
You may wish to try again with the testing repository enabled:
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-X-minimal
The download may take a while depending on your connection speed.
## Passwordless root
It is an intentional design choice for [Passwordless Root Access in VMs] to be optional in Minimal TemplateVMs.
Since the Minimal TemplateVMs are *minimal*, they are not configured for passwordless root by default.
To update or install packages, execute the following command in dom0 (where `X` is your distro and version number):
[user@dom0 ~]$ qvm-run -u root X-minimal xterm
This opens a root terminal in the Minimal TemplateVM, from which you can use execute root commands without `sudo`.
You will have to do this every time if you choose not to enable passwordless root.
If you want to be able to use `sudo` inside a Minimal TemplateVM (or TemplateBasedVMs based on a Minimal TemplateVM), open a root terminal as just instructed, then install the `qubes-core-agent-passwordless-root` package.
Optionally, verify that passwordless root now works by opening a normal (non-root) xterm window in the Minimal TemplateVM, then issue the command `sudo -l`.
This should give you output that includes the `NOPASSWD` keyword.
## Customization
You may wish to clone the original template and make any changes in the clone instead of the original template.
You must start the clone in order to customize it.
Customizing the template for specific use cases normally only requires installing additional packages.
## Distro-specific notes
This following sections provide information that is specific to a particular Minimal TemplateVM distro.
### Fedora
The following list provides an overview of which packages are needed for which purpose.
As usual, the required packages are to be installed in the running template with the following command (replace `packages` with a space-delimited list of packages to be installed):
[user@your-new-clone ~]$ sudo dnf install packages
- Commonly used utilities: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`.
- Audio: `pulseaudio-qubes`.
- [FirewallVM](/doc/firewall/), such as the template for `sys-firewall`: at least `qubes-core-agent-networking` and `iproute`, and also `qubes-core-agent-dom0-updates` if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking` `qubes-core-agent-network-manager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dejavu-sans-fonts` `notification-daemon` `gnome-keyring` `polkit` `@hardware-support`.
If your network devices need extra packages for the template to work as a network VM, use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
If you need utilities for debugging and analyzing network connections, install `tcpdump` `telnet` `nmap` `nmap-ncat`.
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-input-proxy-sender`.
- [VPN qube](/doc/vpn/): Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them.
Some GNOME related packages may be needed as well.
After creation of a machine based on this template, follow the [VPN instructions](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
You may also wish to consider additional packages from the `qubes-core-agent` suite:
- `qubes-core-agent-qrexec`: Qubes qrexec agent. Installed by default.
- `qubes-core-agent-systemd`: Qubes unit files for SystemD init style. Installed by default.
- `qubes-core-agent-passwordless-root`, `polkit`: By default, the Fedora Minimal template doesn't have passwordless root. These two packages enable this feature.
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it things like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-sysvinit`: Qubes unit files for SysV init style or upstart.
- `qubes-core-agent-networking`: Networking support. Required for general network access and particularly if the template is to be used for a `sys-net` or `sys-firewall` VM.
- `qubes-core-agent-network-manager`: Integration for NetworkManager. Useful if the template is to be used for a `sys-net` VM.
- `network-manager-applet`: Useful (together with `dejavu-sans-fonts` and `notification-daemon`) to have a system tray icon if the template is to be used for a `sys-net` VM.
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template which the VM responsible for 'dom0' updates (e.g. `sys-firewall`) is based on must contain this package.
- `qubes-usb-proxy`: Required if the template is to be used for a USB qube (`sys-usb`) or for any destination qube to which USB devices are to be attached (e.g `sys-net` if using USB network adapter).
- `pulseaudio-qubes`: Needed to have audio on the template VM.
See [here][customization] for further information on customizing `fedora-minimal`.
#### Logging
The `rsyslog` logging service is not installed by default, as all logging is instead being handled by the `systemd` journal.
Users requiring the `rsyslog` service should install it manually.
To access the `journald` log, use the `journalctl` command.
### Debian
As you would expect, the required packages can be installed in the running template with any apt-based command.
For example : (Replace "packages` with a space-delimited list of packages to be installed.)
[user@your-new-clone ~]$ sudo apt install packages
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**Networking** | If you want networking | Install qubes-core-agent-networking
**Audio** | If you want sound from your VM... | Install `pulseaudio-qubes`
**FirewallVM** | You can use the minimal template as a template for a [FirewallVM](/doc/firewall/), like `sys-firewall` | Install `qubes-core-agent-networking`, and `nftables`. Also install `qubes-core-agent-dom0-updates` if you want to use a qube based on the template as an updateVM (normally sys-firewall).
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `qubes-core-agent-networking`, `qubes-core-agent-network-manager`, and `nftables`.
**NetVM (extra firmware)** | If your network devices need extra packages for a network VM | Use the `lspci` command to identify the devices, then find the package that provides necessary firnware and install it.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-usb-proxy`. To use USB mouse or keyboard install `qubes-input-proxy-sender`.
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | You may need to install network-manager VPN packages, depending on the VPN technology you'll be using. After creating a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly.
These packages are:
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template on which the qube responsible for 'dom0' updates (e.g. `sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop experience.
Also, there are packages to provide additional services:
- `qubes-gpg-split`: For implementing split GPG.
- `qubes-u2f`: For implementing secure forwarding of U2F messages.
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-img-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
- `qubes-thunderbird`: Additional tools for use in thunderbird.
- `qubes-app-shutdown-idle`: If you want qubes to automatically shutdown when idle.
- `qubes-mgmt-\*`: If you want to use salt management on the template and qubes.
Documentation on all of these can be found in the [docs](/doc)
You could, of course, use qubes-vm-recommended to automatically install many of these, but in that case you are well on the way to a standard Debian template.
[TemplateVMs]: /doc/templates/
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[qubes-users]: /support/#qubes-users
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[testing]: /doc/testing/
[customization]: /doc/fedora-minimal-template-customization/
[Passwordless Root Access in VMs]: /doc/vm-sudo/

202
user/managing-os/templates.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Templates
title: TemplateVMs
permalink: /doc/templates/
redirect_from:
- /doc/template/
@ -11,46 +11,68 @@ redirect_from:
# TemplateVMs
Every TemplateBasedVM in Qubes is, as the name implies, based on some TemplateVM.
The TemplateVM is where all the software available to TemplateBasedVMs is installed.
The default template is based on Fedora, but there are additional templates based on other Linux distributions.
In [Getting Started], we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software.
Your software is installed in [TemplateVMs] (or "templates" for short).
Each TemplateVM shares its root filesystem (i.e., all of its programs and system files) with other qubes called [TemplateBasedVMs].
TemplateBasedVMs are where you run your software and store your data.
The TemplateVM system has significant benefits:
* **Security:** Each qube has read-only access to the TemplateVM on which it's based, so if a qube is compromised, it cannot infect its TemplateVM or any of the other qubes based on that TemplateVM.
* **Storage:** Each qube based on a TemplateVM uses only the disk space required to store its own data (i.e., your files in its home directory), which dramatically saves on disk space.
* **Speed:** It is extremely fast to create new TemplateBasedVMs, since the root filesystem already exists in the TemplateVM.
* **Updates:** Updates are naturally centralized, since updating a TemplateVM means that all qubes based on it will automatically use those updates after they're restarted.
An important side effect of this system is that any software installed in a TemplateBasedVM (rather than in the TemplateVM on which it is based) will disappear after the TemplateBasedVM reboots (see [Inheritance and Persistence]).
For this reason, we recommend installing most of your software in TemplateVMs, not TemplateBasedVMs.
The default TemplateVM in Qubes is based on Fedora, but there are additional templates based on other Linux distributions.
There are also templates available with or without certain software preinstalled.
The concept of TemplateVMs is initially described [here](/getting-started/#appvms-qubes-and-templatevms).
The technical details of this implementation are described in the developer documentation [here](/doc/template-implementation/).
You may find it useful to have multiple TemplateVMs installed in order to provide:
Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder](/doc/qubes-builder/).
In particular, some template "flavors" are available in source code form only.
Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them.
* Different security levels (e.g., more or less trusted software installed)
* Different environments (e.g., Fedora, Debian, Whonix)
* Different tools (e.g., office, media, development, hardware drivers)
## Official templates
## Official
These are the official Qubes OS Project templates.
We build and release updates for these templates.
We guarantee that the binary updates are compiled from exactly the same source code as we publish.
* [Fedora](/doc/templates/fedora/) (default base template)
* [Fedora - Minimal](/doc/templates/fedora-minimal)
* [Debian](/doc/templates/debian/)
* [Fedora] (default)
* Fedora [Minimal]
* [Debian]
* Debian [Minimal]
## Community templates
## Community
These templates are supported by the Qubes community. Some of them are available in ready-to-use binary package form (built by the Qubes developers), while others are available only in source code form. In all cases, the Qubes OS Project does not provide updates for these templates. However, such updates may be provided by the template maintainer.
These templates are supported by the Qubes community.
Some of them are available in ready-to-use binary package form (built by the Qubes developers), while others are available only in source code form.
In all cases, the Qubes OS Project does not provide updates for these templates.
However, such updates may be provided by the template maintainer.
By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer. In addition, these templates may be somewhat less stable, since the Qubes developers do not test them.
By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer.
In addition, these templates may be somewhat less stable, since the Qubes developers do not test them.
* [Whonix](/doc/templates/whonix/)
* [Ubuntu](/doc/templates/ubuntu/)
* [Archlinux](/doc/templates/archlinux/)
* [Whonix]
* [Ubuntu]
* [Arch Linux]
## How to install, uninstall, reinstall, and switch
## Installing
Certain TemplateVMs come preinstalled with Qubes OS.
However, there may be times when you wish to install a fresh TemplateVM from the Qubes repositories, e.g.:
### How to install
* When a TemplateVM version you're using reaches [end-of-life][supported].
* When a new version of a TemplateVM that you wish to use becomes [supported].
* When you suspect your TemplateVM has been compromised.
* When you have made modifications to your TemplateVM that you no longer want.
Please refer to each TemplateVM's installation instructions below.
Please refer to each TemplateVM's installation instructions.
Usually, the installation method is to execute the following type of command in dom0:
$ sudo qubes-dom0-update qubes-template-<name>
@ -58,7 +80,24 @@ Usually, the installation method is to execute the following type of command in
(where `qubes-template-<name>` is the name of your TemplateVM package)
### How to uninstall
## After Installing
After installing a fresh TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
3. If desired, [uninstall the old TemplateVM].
## Updating
Updating TemplateVMs is an important part of [Updating Qubes OS].
Please see [Updating softare in TemplateVMs].
## Uninstalling
To uninstall a TemplateVM, execute the following type of command in dom0:
@ -66,19 +105,19 @@ To uninstall a TemplateVM, execute the following type of command in dom0:
(where `qubes-template-<name>` is the name of your TemplateVM package)
If this doesn't work, you can [remove it manually](/doc/remove-vm-manually/).
If this doesn't work, please see [How to Remove VMs Manually].
If the Applications Menu entry doesn't go away after you uninstall a TemplateVM, execute the following type of command in dom0:
$ rm ~/.local/share/applications/<template-vm-name>
### How to reinstall
## Reinstalling
To reinstall a currently installed TemplateVM, see [here](/doc/reinstall-template/).
Please see [How to Reinstall a TemplateVM].
### How to switch templates
## Switching
When you install a new template or upgrade a clone of a template, it is recommended that you switch everything that was set to the old template to the new template:
@ -90,15 +129,19 @@ When you install a new template or upgrade a clone of a template, it is recommen
Applications Menu --> System Tools --> Qubes Template Manager
3. Base the [DisposableVM Template](/doc/glossary/#disposablevm-template) on the new template.
3. Base the [DisposableVM Template] on the new template.
[user@dom0 ~]$ qvm-create -l red -t new-template new-template-dvm
[user@dom0 ~]$ qvm-prefs new-template-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-features new-template-dvm appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm new-template-dvm
## Advanced
## Inheritance and Persistence
The following sections cover advanced topics pertaining to TemplateVMs.
### Inheritance and Persistence
Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are *not* copied to the child TemplateBasedVM's `/home`.
The child TemplateBasedVM's `/home` is always independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`.
@ -114,23 +157,106 @@ No changes in any other directories in TemplateBasedVMs persist in this manner.
(1) Upon creation
(2) Following shutdown
(3) Including [DisposableVM Templates](/doc/glossary/#disposablevm-template)
(3) Including [DisposableVM Template]s
## Updating TemplateVMs
### Trusting your TemplateVMs
Templates are not automatically updated when [updating dom0](/doc/software-update-dom0/).
This is by design, since doing so would cause all user modifications to templates to be lost.
Instead, you should update your templates [from within each template](/doc/software-update-vm/).
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.
When you create a StandaloneVM from a TemplateVM, the StandaloneVM is independent from the TemplateVM.
It will not be updated when the TemplateVM is updated.
Rather, it must be updated individually from inside the StandaloneVM.
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 Over<sup>TM</sup>.
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.
## Important Notes
### Note on treating TemplateBasedVMs' root filesystem non-persistence as a security feature
Any TemplateBasedVM that is based on a TemplateVM has its root filesystem non-persistent across VM reboots.
In other words, whatever changes the VM makes (or the malware running in this VM makes) to its root filesystem, are automatically discarded whenever one restarts the VM.
This might seem like an excellent anti-malware mechanism to be used inside the VM.
However, one should be careful with treating this property as a reliable way to keep the VM malware-free.
This is because the non-persistence, in the case of normal VMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons.
It is possible that malware, especially malware that could be specifically written to target a Qubes-based VMs, could install its hooks inside the user home directory files only.
Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM.
But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there).
Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem.
However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
Also note that DisposableVMs do not have persistent user filesystem, and so they start up completely "clean" every time.
Note the word "clean" means in this context: the same as their template filesystem, of course.
### Important Notes
* `qvm-trim-template` is no longer necessary or available in Qubes 4.0 and higher.
All VMs are created in a thin pool and trimming is handled automatically.
No user action is required.
See [Disk Trim] for more information.
* RPM-installed templates are "system managed" and therefore cannot be backed up using Qubes' built-in backup function.
In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
* Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder].
In particular, some template "flavors" are available in source code form only.
For the technical details of the template system, please see [TemplateVM Implementation].
Take a look at the [Qubes Builder] documentation for instructions on how to compile them.
[Getting Started]: /getting-started/
[TemplateVMs]: /doc/glossary/#templatevm
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[Fedora]: /doc/templates/fedora/
[Minimal]: /doc/templates/minimal/
[Debian]: /doc/templates/debian/
[Whonix]: /doc/templates/whonix/
[Ubuntu]: /doc/templates/ubuntu/
[Arch Linux]: /doc/templates/archlinux/
[Qubes Builder]: /doc/qubes-builder/
[TemplateVM Implementation]: /doc/template-implementation/
[How to Remove VMs Manually]: /doc/remove-vm-manually/
[DisposableVM Template]: /doc/glossary/#disposablevm-template
[Updating Qubes OS]: /doc/updating-qubes-os/
[Disk Trim]: /doc/disk-trim
[Inheritance and Persistence]: #inheritance-and-persistence
[supported]: /doc/supported-versions/
[Update the TemplateVM]: #updating
[switch]: #switching
[uninstall the old TemplateVM]: #uninstalling
[Updating softare in TemplateVMs]: /doc/software-update-domu/#updating-softare-in-templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/