Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-02 11:36:36 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' into spelling-grammar-fixes

Browse source 
Resolved conflicts in:
      basics_user/doc-guidelines.md
      basics_user/reporting-bugs.md
      common-tasks/backup-restore.md
      common-tasks/software-update-dom0.md
      common-tasks/software-update-vm.md
      common-tasks/usb.md
      configuration/disk-trim.md
      configuration/external-audio.md
      configuration/network-printer.md
      configuration/resize-disk-image.md
      configuration/resize-root-disk-image.md
      customization/fedora-minimal-template-customization.md
      managing-os/hvm.md
      managing-os/templates/archlinux.md
      privacy/whonix-install.md
      security/yubi-key.md
      troubleshooting/install-nvidia-driver.md
      troubleshooting/macbook-troubleshooting.md
This commit is contained in:
Marek Marczykowski-Górecki 2018-02-10 16:46:43 +01:00
commit 919f2ed17e
No known key found for this signature in database
GPG key ID: F32894BE9684938A
123 changed files with 2914 additions and 1254 deletions
Download patch file Download diff file Expand all files Collapse all files

44
managing-os/templates/archlinux.md
View file

@ -32,22 +32,23 @@ A prebuilt template is available only for Qubes 3.2. Before Qubes 3.2, it should
## Binary packages activation
The update repository is disabled when you install (signed) template package. You can however choose to trust it by registering it into pacman.
The Qubes update repository is disabled by default in the Archlinux template. You can however choose to trust it by registering it into pacman.
Enable the repository by running the following command:
Since November 2017, an activation package is present in the template. The update repository can thus be activated by running the following command inside the template:
# mv /etc/pacman.d/99-qubes-repository-3.2.disabled /etc/pacman.d/99-qubes-repository-3.2.conf
# pacman -sU /etc/pacman.d/qubes-vm-keyring*.pkg.tar.xz
It should be noted to this command will create a trust for packages provided by [Olivier Médoc](mailto:o_medoc@yahoo.fr) and signed by the PGP key above.
Then you need to install and sign the public GPG key of the package maintainer (note that accessing to GPG servers requires to temporarily disable the firewall in your template):
If the qubes-vm-keyring package is not present in `/etc/pacman.d/`, please refer to the section #Activating binary packages manually.
# pacman-key --recv-key 2043E7ACC1833B9C
# pacman-key --finger 2043E7ACC1833B9C
If the fingerprint is correct, you can then sign the key:
## Optional Qubes packages
# pacman-key --lsign-key 2043E7ACC1833B9C
Several Qubes packages are not necessarily installed by default in the Archlinux Template. These packages can be installed to add additional functionnalities to the template:
* `qubes-vm-networking`: Contains Qubes tools and dependencies required to use the template as a NetVM/ProxyVM
* `qubes-vm-pulseaudio`: Contains `Pulseaudio` agent enabling sound support in the template
## Default packages
## Default template packages
In order to keep the template as small and simple as possible, default installed package have been arbitrarily selected based on multiple subjective criterias that however essentially include libraries dependencies. This packages are:
* Some font packages to keep good user experience
@ -60,6 +61,28 @@ In order to keep the template as small and simple as possible, default installed
Note that Archlinux does not install GUI packages by default as this decision is left to users. These packages have only been selected to have a usable template.
## Activating binary packages manually
Enable the repository by running the following command:
# rm /etc/pacman.d/99-qubes-repository-3.2.conf
# ln -s /etc/pacman.d/99-qubes-repository-3.2.disabled /etc/pacman.d/99-qubes-repository-3.2.conf
Then you need to install and sign the public GPG key of the package maintainer (note that accessing to GPG servers requires to temporarily disable the firewall in your template):
# pacman-key --recv-key 2043E7ACC1833B9C
# pacman-key --finger 2043E7ACC1833B9C
If the fingerprint is correct, you can then sign the key:
# pacman-key --lsign-key 2043E7ACC1833B9C
## Updating a Qubes-3.2 Archlinux Template
Because of changes in the Qubes-4.0 partition layout, and usage of XEN HVMs instead of pv-guests. It is not straightforward to update a Qubes-3.2 template to Qubes-4.0.
For this reason, it is recommended to start from a new template in Qubes-4.0.
## Updating a Qubes-3.1 Archlinux Template
If you decide to use binary packages but that you were using a Qubes-3.1 Template, you can follow these instructions to enable Qubes 3.2 agents.
@ -111,7 +134,6 @@ Finally, errors related to the GUI agent can be found inside the VM in `/home/us
## Packages manager wrapper
Powerpill is a full Pacman wrapper that not only gives easy proxy configuration but further offers numerous other advantages.
Please check out:

42
managing-os/templates/debian.md
View file

@ -25,8 +25,8 @@ can also obtain the key from [git
repository](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/misc/qubes-archive-keyring.gpg),
which is also integrity-protected using signed git tags.
Install
-------
Installing
----------
Templates can be installed with the following command:
@ -40,21 +40,35 @@ Debian 8 (jessie) - oldstable:
Debian 9 (stretch) - stable:
A prebuilt template is not yet available, but there are two options for
In Qubes 4.0 -
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-9
A prebuilt template is not available in Qubes 3.2, but there are two options for
achieving a stretch template:
* Build an experimental stretch template from source.
1. Build an experimental stretch template from source.
* Clone a `debian-8` template and then modify `/etc/apt/sources.list` and
`/etc/apt/sources.list.d/qubes-r3.list` to pull from stretch repos rather
than jessie repos. After that, an `apt-get dist-upgrade` followed by a
reboot should "just work."
2. Clone a `debian-8` template and then modify in the cloned template `/etc/apt/sources.list` and `/etc/apt/sources.list.d/qubes-r3.list` to pull from stretch repos rather than jessie repos.
Simply replace all instances of "jessie" with "stretch".
After that, an `apt-get dist-upgrade` followed by a reboot should "just work".
Unused packages will have to be removed or else it will conflict with the upgrade.
Full instructions are on [this page][stretch]
Upgrading
---------
To upgrade your Debian TemplateVM, please consult the guide that corresponds to your situation:
* [Upgrading the Debian 8 Template to Debian 9](/doc/template/debian/upgrade-8-to-9/)
Known issues
------------
###Starting services
### Starting services
The Debian way (generally) is to start daemons if they are installed.
@ -79,7 +93,7 @@ Where you **DO** want the service to run, put this in /rw/config/rc.local:
Don't forget to make the file executable.
###Unattended Upgrades
### Unattended Upgrades
Some users have noticed that on upgrading to Stretch, the unattended-upgrade package is installed.
@ -88,11 +102,17 @@ 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.
###Contributing
Contributing
----------------
If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto).
More information
----------------
* [Debian wiki](https://wiki.debian.org/Qubes)
[stretch]: /doc/template/debian/upgrade-8-to-9/

11
managing-os/templates/debian/upgrade-8-to-9.md
View file

@ -12,7 +12,8 @@ redirect_from:
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-r3.list` before attempting the upgrade. Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
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-r3.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
--------------------------------------------------
@ -115,9 +116,12 @@ 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-r3.list file and uncommenting the Qubes Updates Candidates repo.
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-r3.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 can be [disabled with](https://github.com/QubesOS/qubes-issues/issues/2621) `systemctl disable apt-daily.timer`.
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
--------------------
@ -125,3 +129,4 @@ Relevant Discussions
* [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)

42
managing-os/templates/fedora-minimal.md
View file

@ -12,7 +12,7 @@ redirect_from:
Fedora - minimal
================
The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation.
The template only weighs about 600 MB compressed (2 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 the instructions on duplicating the template and provide some examples for commonly desired use cases.
Installation
@ -21,7 +21,7 @@ Installation
The Fedora minimal template can be installed with the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-25-minimal
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-26-minimal
~~~
The download may take a while depending on your connection speed.
@ -32,16 +32,10 @@ Duplication and first steps
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 `your-new-clone` with your desired name.
~~~
[user@dom0 ~]$ qvm-clone fedora-25-minimal your-new-clone
[user@dom0 ~]$ qvm-clone fedora-26-minimal your-new-clone
~~~
You must start the template in order to customize it.
A recommended first step is to install the `sudo` package, which is not installed by default in the minimal template:
~~~
[user@your-new-clone ~]$ su -
[user@your-new-clone ~]$ dnf install sudo
~~~
Customization
-------------
@ -59,12 +53,39 @@ 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`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall.
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy` `notification-daemon` `gnome-keyring`.
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager-wifi` `wireless-tools` `dejavu-sans-fonts` `notification-daemon`.
**NetVM (extra firmware)** | 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.
**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 USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender`
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | 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 howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
**DVM Template** | If you want to use this VM as a [DVM Template](/doc/glossary/#dvm-template) | Install `perl-Encode`
A comprehensive guide to customizing the minimal template is available [here][GUIDE]
Qubes 4.0
---------
In Qubes R4.0, sudo is not installed by default in the minimal template. To update or install packages to it, from a dom0 terminal window:
~~~
[user@dom0 ~]$ qvm-run -u root fedora-26-minimal xterm
~~~
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-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-26-minimal' template doesn't have passwordless root. These two packages fix the situation.
- `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 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.
Logging
-------
@ -74,3 +95,4 @@ Users requiring the `rsyslog` service should install it manually.
To access the `journald` log, use the `journalctl` command.
[GUIDE]: /doc/fedora-minimal-template-customization/

60
managing-os/templates/fedora.md
View file

@ -7,5 +7,63 @@ permalink: /doc/templates/fedora/
The Fedora TemplateVM
=====================
The Fedora TemplateVM is the default TemplateVM in Qubes OS.
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.
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.:
1. When a version of Fedora reaches EOL ([end-of-life]).
2. When a new version of Fedora you wish to use becomes [supported] as a TemplateVM.
3. When you suspect your Fedora TemplateVM has been compromised.
4. 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:
$ sudo qubes-dom0-update qubes-template-fedora-26
(If necessary, replace `26` with your desired Fedora version.)
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
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.
3. If desired, remove the old TemplateVM by running the following command in dom0:
$ sudo dnf remove qubes-template-fedora-26
(If necessary, replace `26` with your desired Fedora version.)
Upgrading
---------
To upgrade your Fedora TemplateVM, please consult the guide that corresponds to your situation:
* [Upgrading the Fedora 25 Template to Fedora 26](/doc/template/fedora/upgrade-25-to-26/)
* [Upgrading the Fedora 24 Template to Fedora 25](/doc/template/fedora/upgrade-24-to-25/)
* [Upgrading the Fedora 23 Template to Fedora 24](/doc/template/fedora/upgrade-23-to-24/)
* [Upgrading the Fedora 21 Template to Fedora 23](/doc/template/fedora/upgrade-21-to-23/)
* [Upgrading the Fedora 20 Template to Fedora 21](/doc/template/fedora/upgrade-20-to-21/)
* [Upgrading the Fedora 18 Template to Fedora 20](/doc/template/fedora/upgrade-18-to-20/)
[TemplateVM]: /doc/templates/
[Fedora Minimal]: /doc/templates/fedora-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/
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[remove the old TemplateVM]: /doc/templates/#important-notes

386
managing-os/templates/fedora/upgrade-25-to-26.md Normal file
View file

@ -0,0 +1,386 @@
---
layout: doc
title: Upgrading the Fedora 25 Template to Fedora 26
permalink: /doc/template/fedora/upgrade-25-to-26/
redirect_from:
- /doc/fedora-template-upgrade-25/
- /en/doc/fedora-template-upgrade-25/
- /doc/FedoraTemplateUpgrade25/
- /wiki/FedoraTemplateUpgrade25/
---
Upgrading the Fedora 25 Template to Fedora 26
=============================================
This page provides instructions for performing an in-place upgrade of an
installed Fedora 25 [TemplateVM] to Fedora 26. If you wish to install a new,
unmodified Fedora 26 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 24 TemplateVM to
Fedora 26. Simply start by cloning `fedora-24` instead of `fedora-25` in the
instructions below.
Qubes 3.2 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 25 Template to Fedora 26 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-26`).
[user@dom0 ~]$ qvm-clone fedora-25 fedora-26
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-26 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-26 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-26 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-26 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-26 ~]$ sudo dnf clean all
[user@fedora-26 ~]$ sudo dnf --releasever=26 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-trim-template fedora-26
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
### Detailed: Upgrading the Standard Fedora 25 Template to Fedora 26 ###
These instructions will show you how to upgrade the standard Fedora 25
TemplateVM to Fedora 26. The same general procedure may be used to upgrade any
template based on the standard Fedora 25 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-26`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-25
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-25 fedora-26
[user@dom0 ~]$ qvm-run -a fedora-26 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-26 ~]$ sudo dnf clean all
[user@fedora-26 ~]$ sudo dnf --releasever=26 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.fc26.noarch.rpm: Header V3 RSA/SHA266 Signature, key ID 64dab85d: NOKEY
Importing GPG key 0x64DAB85D:
Userid : "Fedora (26) <fedora-26-primary@fedoraproject.org>"
Fingerprint: E641 850B 77DF 4353 78D1 D7E2 812A 6B4B 64DA B85D
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-26-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 ~]$ qvm-block -A fedora-26 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-26 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-26 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-26 ~]$ sudo dnf clean all
[user@fedora-26 ~]$ sudo dnf --releasever=26 --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. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-26
5. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
6. Trim the new template (see [Compacting the Upgraded Template] for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-26
7. (Recommended) Switch everything that was set to the old template to the new
template, e.g.:
1. Make the new template the default template:
Qubes Manager --> Global settings --> Default template
2. Base AppVMs on the new template. In Qubes Manager, for each VM that is
currently based on `fedora-25` that you would like to base on
`fedora-26`, enter its VM settings and change the Template selection:
Qubes Manager --> (Select a VM) --> VM settings --> Template
3. Base the [DispVM] template on the new template.
If you have set the new template as your default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Otherwise:
[user@dom0 ~]$ qvm-create-default-dvm fedora-26
8. (Optional) Remove the old template. (Make sure to type `fedora-25`, not
`fedora-26`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-25
### Compacting the Upgraded Template ###
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
dom0. This means that the template will use about twice as much space as is
really necessary after upgrading.
You can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-26
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 25 to Fedora 26 is the
same as for a TemplateVM, except that `qvm-trim-template` does not work on
StandaloneVMs. Instead, you should run the following command inside the
StandaloneVM in order to compact it:
$ sudo fstrim -v -a
### Summary: Upgrading the Minimal Fedora 25 Template to Fedora 26 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-26`).
[user@dom0 ~]$ qvm-clone fedora-25-minimal fedora-26-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-26-minimal xterm
[root@fedora-26-minimal ~]# dnf clean all
[user@fedora-26-minimal ~]# dnf --releasever=26 --best --allowerasing distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-26-minimal
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Qubes 4.0 Instructions
----------------------
### Summary: Upgrading the Standard Fedora 25 Template to Fedora 26 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-26`).
[user@dom0 ~]$ qvm-clone fedora-25 fedora-26
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-26 gnome-terminal
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
[user@dom0 ~]$ qvm-block attach fedora-26 dom0:${dev##*/}
[user@fedora-26 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-26 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-26 ~]$ sudo dnf clean all
[user@fedora-26 ~]$ sudo dnf --releasever=26 --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
[user@fedora-26 ~]$ sudo fstrim -v /
(Shut down TemplateVM by any normal means.)
[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 25 Template to Fedora 26 ###
These instructions will show you how to upgrade the standard Fedora 25
TemplateVM to Fedora 26. The same general procedure may be used to upgrade any
template based on the standard Fedora 25 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-26`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-25
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-25 fedora-26
[user@dom0 ~]$ qvm-run -a fedora-26 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-26 ~]$ sudo dnf clean all
[user@fedora-26 ~]$ sudo dnf --releasever=26 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.fc26.noarch.rpm: Header V3 RSA/SHA266 Signature, key ID 64dab85d: NOKEY
Importing GPG key 0x64DAB85D:
Userid : "Fedora (26) <fedora-26-primary@fedoraproject.org>"
Fingerprint: E641 850B 77DF 4353 78D1 D7E2 812A 6B4B 64DA B85D
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-26-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-26 dom0:${dev##*/}
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-26 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-26 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-26 ~]$ sudo dnf clean all
[user@fedora-26 ~]$ sudo dnf --releasever=26 --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-26 ~]$ sudo fstrim -v /
5. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-26
6. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
7. (Recommended) Switch everything that was set to the old template to the new
template, e.g.:
1. Make the new template the default template:
Applications Menu --> System Tools --> Qubes Global Settings --> Default template
2. Base AppVMs on the new template. In Qubes Manager, for each VM that is
currently based on `fedora-25` that you would like to base on
`fedora-26`, enter its VM settings and change the Template selection:
Applications Menu --> (select a VM) --> VM settings --> Template
3. Base the [DispVM] template on the new template.
[user@dom0 ~]$ qvm-create -l red -t fedora-26 fedora-26-dvm
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm fedora-26-dvm
8. (Optional) Remove the old template. (Make sure to type `fedora-25`, not
`fedora-26`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-25
### Upgrading StandaloneVMs ###
The procedure for upgrading a StandaloneVM from Fedora 25 to Fedora 26 is the
same as for a TemplateVM.
### Summary: Upgrading the Minimal Fedora 25 Template to Fedora 26 ###
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-26`).
[user@dom0 ~]$ qvm-clone fedora-25-minimal fedora-26-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-26-minimal xterm
[root@fedora-26-minimal ~]# dnf clean all
[user@fedora-26-minimal ~]# dnf --releasever=26 --best --allowerasing distro-sync
[user@fedora-26-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. Increase the `root.img` size with `qvm-grow-root`.
4. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
5. 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
[DispVM]: /doc/dispvm/

2
managing-os/templates/ubuntu.md
View file

@ -22,7 +22,7 @@ redistribution of a modified Ubuntu. The redistribution is not allowed by their
Install
-------
It can built using [Qubes Builder](/doc/qubes-builder/). You can also access its
It can be built using [Qubes Builder](/doc/qubes-builder/). You can also access its
documentation in the [source code
repository](https://github.com/QubesOS/qubes-builder/blob/master/README.md).