mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-07-24 23:35:53 -04:00
Update and reorganize documentation
- Convert "Common Tasks" to "How-to Guides" (QubesOS/qubes-issues#6694) - Make title capitalization consistent across docs - Fix leftover h1 headings - Reorganize various pages and topics - Update permalinks to better match titles - Create redirects for changed permalinks - Miscellaneous cleanup QubesOS/qubes-issues#6701
This commit is contained in:
Andrew David Wong
parent
12408884dd
commit
6d81f95cc2
73 changed files with 101 additions and 107 deletions
168
user/templates/debian/debian-upgrade.md
Normal file
168
user/templates/debian/debian-upgrade.md
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
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/
|
||||
ref: 133
|
||||
title: How to Upgrade a Debian Template In-place
|
||||
---
|
||||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<i class="fa fa-exclamation-triangle"></i>
|
||||
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/debian/#installing">install a new Debian TemplateVM</a>. Learn more about the two options <a href="/doc/templates/debian/#upgrading">here</a>.
|
||||
</div>
|
||||
|
||||
|
||||
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM](/doc/templates/debian/).
|
||||
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](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
|
||||
|
||||
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
|
||||
|
||||
## Summary instructions for Debian TemplateVMs
|
||||
|
||||
**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.
|
||||
|
||||
```
|
||||
[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@dom0 ~]$ qvm-shutdown debian-<new>
|
||||
```
|
||||
|
||||
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
|
||||
|
||||
## 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-<old>
|
||||
```
|
||||
|
||||
2. Clone the existing template and start a terminal in the new template.
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
|
||||
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
|
||||
```
|
||||
|
||||
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.)
|
||||
|
||||
```
|
||||
[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.
|
||||
During the process, it may prompt you to overwrite the file `qubes-r4.list`.
|
||||
You should overwrite this file.
|
||||
|
||||
```
|
||||
[user@debian-<new> ~]$ sudo apt update
|
||||
[user@debian-<new> ~]$ sudo apt upgrade
|
||||
[user@debian-<new> ~]$ sudo apt dist-upgrade
|
||||
```
|
||||
|
||||
5. (Optional) Remove unnecessary packages that were previously installed.
|
||||
|
||||
```
|
||||
[user@debian-<new> ~]$ sudo apt-get autoremove
|
||||
```
|
||||
|
||||
6. (Optional) Clean cached packages from `/var/cache/apt`.
|
||||
|
||||
```
|
||||
[user@debian-<new> ~]$ sudo apt-get clean
|
||||
```
|
||||
|
||||
7. (Optional) Trim the new template.
|
||||
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
|
||||
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
|
||||
|
||||
```
|
||||
[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.](/doc/templates/#switching)
|
||||
|
||||
10. (Optional) Make the new template the global default.
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qubes-prefs --set debian-<new>
|
||||
```
|
||||
|
||||
11. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
|
||||
Make sure that the template you're uninstalling is the old one, not the new one!
|
||||
|
||||
## StandaloneVMs
|
||||
|
||||
The procedure for upgrading a Debian [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
|
||||
|
||||
## Release-specific notes
|
||||
|
||||
This section contains notes about upgrading to specific releases.
|
||||
|
||||
### Debian 10 ("Buster")
|
||||
|
||||
Please see [Debian's Buster upgrade instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html).
|
||||
|
||||
### 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](https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html).
|
||||
|
||||
### Debian 8 ("Jessie")
|
||||
|
||||
Please see [Debian's Jessie upgrade instructions](https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html).
|
||||
|
||||
### End-of-life (EOL) releases
|
||||
|
||||
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)](https://wiki.debian.org/DebianReleases#Production_Releases).
|
||||
|
||||
## 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.
|
||||
|
||||
109
user/templates/debian/debian.md
Normal file
109
user/templates/debian/debian.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/templates/debian/
|
||||
redirect_from:
|
||||
- /doc/debian/
|
||||
- /en/doc/templates/debian/
|
||||
- /doc/Templates/Debian/
|
||||
- /wiki/Templates/Debian/
|
||||
ref: 134
|
||||
title: Debian Templates
|
||||
---
|
||||
|
||||
|
||||
The Debian [TemplateVM](/doc/templates/) is an officially [supported](/doc/supported-versions/#templatevms) TemplateVM in Qubes OS.
|
||||
This page is about the standard (or "full") Debian TemplateVM.
|
||||
For the minimal version, please see the [Minimal TemplateVMs](/doc/templates/minimal/) page.
|
||||
There is also a [Qubes page on the Debian Wiki](https://wiki.debian.org/Qubes).
|
||||
|
||||
## Installing
|
||||
|
||||
To [install](/doc/templates/#installing) a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update qubes-template-debian-XX
|
||||
```
|
||||
|
||||
(Replace `XX` with the Debian version number of the template you wish to install.)
|
||||
|
||||
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
|
||||
|
||||
## After Installing
|
||||
|
||||
After installing a fresh Debian TemplateVM, we recommend performing the following steps:
|
||||
|
||||
1. [Update the TemplateVM](/doc/software-update-vm/).
|
||||
|
||||
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
|
||||
|
||||
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
|
||||
|
||||
## Updating
|
||||
|
||||
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
|
||||
|
||||
## Upgrading
|
||||
|
||||
There are two ways to upgrade your TemplateVM to a new Debian release:
|
||||
|
||||
- [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
|
||||
|
||||
- [Perform an in-place upgrade of an existing Debian template.](/doc/template/debian/upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**
|
||||
|
||||
## Release-specific notes
|
||||
|
||||
This section contains notes about specific Debian releases.
|
||||
|
||||
### Debian 10
|
||||
|
||||
Debian 10 (buster) - minimal:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10-minimal
|
||||
```
|
||||
|
||||
Debian 10 (buster) - stable:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
So be very careful when installing software in Templates - if the daemon spawns outbound connections then there is a serious security risk.
|
||||
|
||||
In general, a reasonable approach would be, (using ssh as example):
|
||||
|
||||
- Install the ssh service.
|
||||
- `systemctl stop ssh`
|
||||
- `systemctl disable ssh`
|
||||
- `systemctl mask ssh`
|
||||
- Close down template
|
||||
|
||||
Now the ssh service will **NOT** start in qubes based on this template.
|
||||
|
||||
Where you **DO** want the service to run, put this in `/rw/config/rc.local`:
|
||||
|
||||
```
|
||||
systemctl unmask ssh
|
||||
systemctl start ssh
|
||||
```
|
||||
|
||||
Don't forget to make the file executable.
|
||||
|
||||
### Unattended Upgrades
|
||||
|
||||
Some users have noticed that on upgrading to Stretch, the `unattended-upgrade` package is installed.
|
||||
|
||||
This package is pulled in as part of a Recommend chain, and can be purged.
|
||||
|
||||
The lesson is that you should carefully look at what is being installed to your system, particularly if you run `dist-upgrade`.
|
||||
|
||||
### Package installation errors in Qubes 4.0
|
||||
|
||||
If some packages throw installation errors, see [this guide.](/doc/vm-troubleshooting/#fixing-package-installation-errors)
|
||||
|
||||
220
user/templates/fedora/fedora-upgrade.md
Normal file
220
user/templates/fedora/fedora-upgrade.md
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
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/
|
||||
ref: 137
|
||||
title: How to Upgrade a Fedora Template In-place
|
||||
---
|
||||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<i class="fa fa-exclamation-triangle"></i>
|
||||
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/fedora/#installing">install a new Fedora TemplateVM</a>. Learn more about the two options <a href="/doc/templates/fedora/#upgrading">here</a>.
|
||||
</div>
|
||||
|
||||
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM](/doc/templates/fedora/).
|
||||
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](/doc/templates/fedora/) page instead. ([Learn more about the two options.](/doc/templates/fedora/#upgrading))
|
||||
|
||||
## 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@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.](/doc/templates/#switching)
|
||||
|
||||
## 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](/doc/resize-disk-image/) before reattempting the upgrade process.
|
||||
(See [Additional Information](#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. (Optional) Trim the new template.
|
||||
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
|
||||
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
|
||||
|
||||
```
|
||||
[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.](/doc/templates/#switching)
|
||||
|
||||
9. (Optional) Make the new template the global default.
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qubes-prefs --set default_template fedora-<new>
|
||||
```
|
||||
|
||||
10. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
|
||||
Make sure that the template you're uninstalling is the old one, not the new one!
|
||||
|
||||
## 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](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
|
||||
|
||||
|
||||
## Release-specific notes
|
||||
|
||||
See the [news](/news/) announcement for each specific TemplateVM release for any important notices about that particular release.
|
||||
|
||||
|
||||
### End-of-life (EOL) releases
|
||||
|
||||
We strongly recommend against using any Fedora release that has reached [end-of-life (EOL)](https://fedoraproject.org/wiki/End_of_life).
|
||||
Also see [supported versions](/doc/supported-versions/).
|
||||
|
||||
|
||||
## 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](/doc/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, see [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading).
|
||||
|
||||
45
user/templates/fedora/fedora.md
Normal file
45
user/templates/fedora/fedora.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/templates/fedora/
|
||||
ref: 136
|
||||
title: Fedora Templates
|
||||
---
|
||||
|
||||
|
||||
The Fedora [TemplateVM](/doc/templates/) is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs](/doc/templates/minimal/) and [Xfce TemplateVMs](/doc/templates/xfce/) pages.
|
||||
|
||||
## Installing
|
||||
|
||||
To [install](/doc/templates/#installing) 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
|
||||
```
|
||||
|
||||
(Replace `XX` with the Fedora version number of the template you wish to install.)
|
||||
|
||||
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
|
||||
|
||||
## After Installing
|
||||
|
||||
After installing a fresh Fedora TemplateVM, we recommend performing the following steps:
|
||||
|
||||
1. [Update the TemplateVM](/doc/software-update-vm/).
|
||||
|
||||
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
|
||||
|
||||
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
|
||||
|
||||
## Updating
|
||||
|
||||
For routine daily updates within a given release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
|
||||
|
||||
## Upgrading
|
||||
|
||||
There are two ways to upgrade your TemplateVM to a new Fedora release:
|
||||
|
||||
- [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
|
||||
|
||||
- [Perform an in-place upgrade of an existing Fedora template.](/doc/template/fedora/upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**
|
||||
|
||||
93
user/templates/how-to-reinstall-a-template.md
Normal file
93
user/templates/how-to-reinstall-a-template.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/how-to-reinstall-a-template/
|
||||
redirect_from:
|
||||
- /doc/reinstall-template/
|
||||
- /doc/whonix/reinstall/
|
||||
ref: 128
|
||||
title: How to Reinstall a Template
|
||||
---
|
||||
|
||||
|
||||
If you suspect your [TemplateVM](/doc/templates/) is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
|
||||
|
||||
Automatic Method
|
||||
----------------
|
||||
|
||||
First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location.
|
||||
Then, in a dom0 terminal, run:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
|
||||
```
|
||||
|
||||
Replace `qubes-template-package-name` with the name of the *package* of the template you wish to reinstall.
|
||||
For example, use `qubes-template-fedora-25` if you wish to reinstall the `fedora-25` template.
|
||||
Only one template can be reinstalled at a time.
|
||||
|
||||
Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository.
|
||||
In this case, you can specify `upgrade` as the action instead and the newer version will be used.
|
||||
The other `dnf` package actions that are supported in addition to `reinstall` and `upgrade` are `upgrade-to` and `downgrade`.
|
||||
Note that the `upgrade`, `upgrade-to`, and `downgrade` commands are only supported under Fedora based UpdateVMs.
|
||||
If you receive a message about them being unsupported, review the manual reinstallation method below.
|
||||
|
||||
**Reminder:** If you're trying to reinstall a template that is not in an enabled repo, you must enable that repo.
|
||||
For example:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
|
||||
```
|
||||
|
||||
**Note:** VMs that are using the reinstalled template will not be affected until they are restarted.
|
||||
|
||||
Manual Method
|
||||
-------------
|
||||
|
||||
In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall.
|
||||
If you want to reinstall more than one TemplateVM, repeat these instructions for each one.
|
||||
|
||||
1. Clone the existing target TemplateVM.
|
||||
|
||||
This can be a good idea if you've customized the existing template and want to keep your customizations.
|
||||
On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
|
||||
|
||||
2. Temporarily change all VMs based on the target TemplateVM to the new clone template, or remove them.
|
||||
|
||||
This can be a good idea if you have user data in these VMs that you want to keep.
|
||||
On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
|
||||
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
|
||||
|
||||
3. Uninstall the target TemplateVM from dom0:
|
||||
|
||||
```
|
||||
$ sudo dnf remove <template-package-name>
|
||||
```
|
||||
|
||||
For example, to uninstall the `whonix-gw` template:
|
||||
|
||||
```
|
||||
$ sudo dnf remove qubes-template-whonix-gw
|
||||
```
|
||||
|
||||
4. Reinstall the target TemplateVM in dom0:
|
||||
|
||||
```shell_session
|
||||
$ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
|
||||
<template-package-name>
|
||||
```
|
||||
|
||||
For example, to install the `whonix-gw` template:
|
||||
|
||||
```shell_session
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
|
||||
qubes-template-whonix-gw
|
||||
```
|
||||
|
||||
5. If you temporarily changed all VMs based on the target TemplateVM to the clone template in step 3, change them back to the new target TemplateVM now.
|
||||
If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now.
|
||||
|
||||
6. Delete the cloned template.
|
||||
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the
|
||||
command `qvm-remove <vm-name>` in dom0.
|
||||
|
||||
221
user/templates/minimal-templates.md
Normal file
221
user/templates/minimal-templates.md
Normal file
|
|
@ -0,0 +1,221 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
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/
|
||||
ref: 132
|
||||
title: Minimal Templates
|
||||
---
|
||||
|
||||
The Minimal [TemplateVMs](/doc/templates/) 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 three Minimal TemplateVMs corresponding to the standard [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/) and [Gentoo](/doc/templates/gentoo/) 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 their 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, please do *not* file a bug report.
|
||||
Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to ask for help.
|
||||
Once you have learned how to solve your problem, please [contribute what you learned to the documentation](/doc/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.](/faq/#could-you-please-make-my-preference-the-default)
|
||||
|
||||
4. In order to reduce unnecessary risk, unused repositories have been disabled by default.
|
||||
If you wish to install or update any packages from those repositories, you must enable them.
|
||||
|
||||
## 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](/doc/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
|
||||
```
|
||||
|
||||
If you would like to install a community distribution, try the install command by enabling the community repository:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community 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](/doc/vm-sudo/) 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` `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-usb-proxy` to provide USB devices to other Qubes and `qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
|
||||
- [VPN qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md): 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](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
|
||||
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and `qubes-mgmt-salt-vm-connector`.
|
||||
|
||||
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.
|
||||
- `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-sysvinit`: Qubes unit files for SysV init style or upstart.
|
||||
|
||||
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.
|
||||
- `thunderbird-qubes`: Additional tools for use in thunderbird.
|
||||
- `qubes-app-shutdown-idle`: If you want qubes to automatically shutdown when idle.
|
||||
- `qubes-mgmt-salt-vm-connector`: If you want to use salt management on the template and qubes.
|
||||
|
||||
You may also wish to consider additional packages from the `qubes-core-agent` suite:
|
||||
|
||||
See [here](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md) 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
|
||||
|
||||
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 apt 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 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`. 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 firmware and install it. If you need utilities for debugging and analyzing network connections, install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`.
|
||||
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-usb-proxy` to provide USB devices to other Qubes and `qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
|
||||
- [VPN qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md): 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](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
|
||||
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and `qubes-mgmt-salt-vm-connector`.
|
||||
|
||||
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-salt-vm-connector`: If you want to use salt management on the template and qubes.
|
||||
|
||||
Documentation on all of these can be found in the [docs](/doc)
|
||||
|
||||
If you want to use interactive dialogs, (e.g file selection), you will need to add the `zenity` package. ([Here's an example](https://github.com/QubesOS/qubes-issues/issues/5202))
|
||||
|
||||
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.
|
||||
|
||||
### CentOS
|
||||
|
||||
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 yum 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 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` `notification-daemon` `gnome-keyring`. 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. If you need utilities for debugging and analyzing network connections, install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
|
||||
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`: `qubes-usb-proxy` to provide USB devices to other Qubes and `qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
|
||||
- [VPN qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md): 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](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
|
||||
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and `qubes-mgmt-salt-vm-connector`.
|
||||
|
||||
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-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-mgmt-salt-vm-connector`: 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.
|
||||
|
||||
290
user/templates/templates.md
Normal file
290
user/templates/templates.md
Normal file
|
|
@ -0,0 +1,290 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/templates/
|
||||
redirect_from:
|
||||
- /doc/template/
|
||||
- /en/doc/templates/
|
||||
- /doc/Templates/
|
||||
- /wiki/Templates/
|
||||
ref: 131
|
||||
title: Templates
|
||||
---
|
||||
|
||||
|
||||
In [Getting Started](/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](/doc/glossary/#templatevm) (or "templates" for short).
|
||||
Each TemplateVM shares its root filesystem (i.e., all of its programs and system files) with other qubes called [TemplateBasedVMs](/doc/glossary/#templatebasedvm).
|
||||
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](#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.
|
||||
You may find it useful to have multiple TemplateVMs installed in order to provide:
|
||||
|
||||
* 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
|
||||
|
||||
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)
|
||||
* [Fedora Minimal](/doc/templates/minimal/)
|
||||
* [Fedora Xfce](/doc/templates/xfce)
|
||||
* [Debian](/doc/templates/debian/)
|
||||
* [Debian Minimal](/doc/templates/minimal/)
|
||||
|
||||
## 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.
|
||||
|
||||
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/)
|
||||
* [Arch Linux](/doc/building-archlinux-template/)
|
||||
* [CentOS](/doc/templates/centos/)
|
||||
* [CentOS Minimal](/doc/templates/minimal/)
|
||||
* [Gentoo](/doc/templates/gentoo/)
|
||||
* [Gentoo Minimal](/doc/templates/minimal/)
|
||||
|
||||
## 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.:
|
||||
|
||||
* When a TemplateVM version you're using reaches [end-of-life](/doc/supported-versions/).
|
||||
* When a new version of a TemplateVM that you wish to use becomes [supported](/doc/supported-versions/).
|
||||
* 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.
|
||||
Usually, the installation method is to execute the following type of command in dom0:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update qubes-template-<name>
|
||||
```
|
||||
|
||||
where `qubes-template-<name>` is the name of your TemplateVM package.
|
||||
|
||||
If you wish to install a community template, you must enable the community template repo:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<name>
|
||||
```
|
||||
|
||||
If you receive the message that no match is found for `qubes-template-<name>`, see [here](/faq/#when-i-try-to-install-a-templatevm-it-says-no-match-is-found).
|
||||
|
||||
## After Installing
|
||||
|
||||
After installing a fresh TemplateVM, we recommend performing the following steps:
|
||||
|
||||
1. [Update the TemplateVM](#updating).
|
||||
|
||||
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](#switching).
|
||||
|
||||
3. If desired, [uninstall the old TemplateVM](#uninstalling).
|
||||
|
||||
## Updating
|
||||
|
||||
Please see [Updating Qubes OS](/doc/updating-qubes-os/).
|
||||
|
||||
## Uninstalling
|
||||
|
||||
The procedure for uninstalling a TemplateVM depends on how it was created.
|
||||
|
||||
If the TemplateVM was originaly created by cloning another TemplateVM, then you can delete it the same way as you would any other qube.
|
||||
In the Qube Manager, right-click on the TemplateVM and select **Delete qube**.
|
||||
(If you're not sure, you can safely try this method first to see if it works.)
|
||||
|
||||
If, on the other hand, the TemplateVM came pre-installed or was installed by installing a template package in dom0, per the instructions [above](#installing), then you must execute the following type of command in dom0 in order to uninstall it:
|
||||
|
||||
$ sudo dnf remove qubes-template-<name>
|
||||
|
||||
(where `qubes-template-<name>` is the name of your TemplateVM package)
|
||||
|
||||
You may see warning messages like the following:
|
||||
|
||||
```
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/whitelisted-appmenus.list: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/vm-whitelisted-appmenus.list: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.04: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.03: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.02: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.01: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.00: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/netvm-whitelisted-appmenus.list: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/icon.png: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/clean-volatile.img.tar: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.templates: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.tempicons: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps: remove failed: No such file or directory
|
||||
warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file or directory
|
||||
```
|
||||
|
||||
These are normal and expected. Nothing is wrong, and no action is required to address these warnings.
|
||||
|
||||
If this uninstallation command doesn't work, please see [How to Remove VMs Manually](/doc/remove-vm-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>
|
||||
```
|
||||
|
||||
Applications Menu entries for backups of removed VMs can also be found in `/usr/local/share/applications/` of dom0.
|
||||
|
||||
```
|
||||
$ rm /usr/local/share/applications/<template_vm_name>
|
||||
```
|
||||
|
||||
## Reinstalling
|
||||
|
||||
Please see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
|
||||
|
||||
## 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:
|
||||
|
||||
1. Make the new template the default template.
|
||||
|
||||
`
|
||||
Applications Menu --> System Tools --> Qubes Global Settings --> Default template
|
||||
`
|
||||
|
||||
2. If your keyboard or mouse is connected through `sys-usb`, switch `sys-usb` to the new template.
|
||||
(Note that this is a single command to ensure that `sys-usb` restarts.
|
||||
If it does not, you will not be able to use your USB keyboard or mouse.)
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qvm-shutdown --wait sys-usb; qvm-prefs sys-usb template <new_template>; qvm-start sys-usb
|
||||
```
|
||||
|
||||
3. Base AppVMs on the new template.
|
||||
|
||||
`
|
||||
Applications Menu --> System Tools --> Qubes Template Manager
|
||||
`
|
||||
|
||||
4. Base the [DisposableVM Template](/doc/glossary/#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
|
||||
|
||||
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`.
|
||||
|
||||
Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM.
|
||||
No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
|
||||
|
||||
| | Inheritance (1) | Persistence (2)
|
||||
|--------------------|-----------------------------------------------------------|------------------------------------------
|
||||
|TemplateVM | n/a | Everything
|
||||
|TemplateBasedVM (3) | `/etc/skel` to `/home`, `/usr/local.orig` to `/usr/local` | `/rw` (includes `/home`, `/usr/local` and `bind-dirs`)
|
||||
|DisposableVM | `/rw` (includes `/home`, `/usr/local` and `bind-dirs`) | Nothing
|
||||
|
||||
(1) Upon creation
|
||||
(2) Following shutdown
|
||||
(3) Including any [DisposableVM Templates](/doc/glossary/#disposablevm-template)
|
||||
|
||||
### Trusting your TemplateVMs
|
||||
|
||||
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.
|
||||
|
||||
### 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](/doc/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](/doc/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](/doc/template-implementation/).
|
||||
Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for instructions on how to compile them.
|
||||
|
||||
49
user/templates/xfce-templates.md
Normal file
49
user/templates/xfce-templates.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/templates/xfce/
|
||||
redirect_from:
|
||||
- /doc/xfce/
|
||||
- /en/doc/templates/xfce/
|
||||
- /doc/Templates/Xfce/
|
||||
- /wiki/Templates/Xfce/
|
||||
ref: 222
|
||||
title: XFCE Templates
|
||||
---
|
||||
|
||||
|
||||
If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
|
||||
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [CentOS](/doc/templates/centos/) or [Gentoo](/doc/templates/gentoo/).
|
||||
|
||||
## Installation
|
||||
|
||||
The Fedora Xfce 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-xfce
|
||||
```
|
||||
|
||||
If your desired version is not found, it may still be in [testing](/doc/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-xfce
|
||||
```
|
||||
|
||||
If you would like to install a community distribution, like CentOS or Gentoo, try the install command by enabling the community repository:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce
|
||||
```
|
||||
|
||||
If your desired version is not found, it may still be in [testing](/doc/testing/).
|
||||
You may wish to try again with the testing repository enabled:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing qubes-template-X-xfce
|
||||
```
|
||||
|
||||
The download may take a while depending on your connection speed.
|
||||
|
||||
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue