qubes-doc/user/downloading-installing-upgrading/upgrade/4_0.rst

=================
Upgrading to R4.0
=================


**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users** :doc:`back up their systems </user/how-to-guides/how-to-back-up-restore-and-migrate>` **.**

Current Qubes R3.2 systems cannot be upgraded in-place to R4.0. A full
backup, clean 4.0 install, and restore is required. This can be done by
following the procedure below.

Preparation
-----------


1. Go to :doc:`downloads </user/downloading-installing-upgrading/downloads>` and prepare a USB drive or DVD with
   the R4.0 installer.

2. If this is your only computer, and you do not have a R3.2 installer,
   you should also create a separate R3.2 USB drive or DVD installer at
   this time.



Backup R3.2
-----------


1. Attach the backup drive you will be using. These steps assume it is a
   USB drive.

2. Shutdown all non-essential VMs. Typically, ``sys-usb`` will be the
   only VM you need to leave running.

3. Follow the **Creating a Backup** section in the :doc:`Backup, Restoration, and Migration </user/how-to-guides/how-to-back-up-restore-and-migrate>` guide to back up **all VMs**
   except sys-usb.

4. Verify the integrity of your backup by following the **Restoring from a Backup** section in the :doc:`Backup, Restoration, and Migration </user/how-to-guides/how-to-back-up-restore-and-migrate>` guide and:

   - If you’re using Qubes Manager, check the box under “Restore
     options” that says, “Verify backup integrity, do not restore the
     data.”

   - If you’re using ``qvm-backup-restore`` from the command-line, use
     the ``--verify-only`` option.



5. If your backup verifies successfully, proceed to the next section. If
   it does not, **stop**. Go back and repeat the backup steps, review
   the documentation, and ask for :doc:`help </introduction/support>`.



Install R4.0
------------


This section provides general guidance on installing R4.0 as part of
migrating from R3.2. For further details, please see the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.

1. Shut down R3.2 and boot the R4.0 installer.

2. Follow the installation prompts until you get to the drive selection
   screen. Choose **I want to make additional space available**. Select
   the box at the top of the list in order to select all partitions.
   **This will erase the entire drive**, so do this only if Qubes is the
   only OS installed on your computer. If you did not successfully
   verify your backup in the previous section, cancel the installation,
   and go back to do that now.

3. Complete the R4.0 installation. Ask for :doc:`help </introduction/support>` if you
   run into trouble.

4. If you are unable to successfully install R4.0 on your system, all is
   not lost. Use the R3.2 installer to reinstall R3.2, then restore from
   your backup.



Restore from your backup
------------------------


1. Welcome to Qubes R4.0! The first thing you might notice is that
   **Qubes Manager** is not started by default. We won’t need it for the
   next step, but we will be starting it later.

2. Since patches may have been released since your installation image
   was created, update Qubes R4.0 by going to the dom0 command line
   (**Qubes menu -> Terminal Emulator**) then running:

   .. code:: bash

         sudo qubes-dom0-update



3. Reboot dom0.

4. Go to **Qubes menu -> System Tools -> Qubes Manager** to start it.

5. Follow the **Restoring from a Backup** section in the :doc:`Backup, Restoration, and Migration </user/how-to-guides/how-to-back-up-restore-and-migrate>` guide. We
   recommend that you restore only your :ref:`app qubes <user/reference/glossary:app qube>` and
   :ref:`standalones <user/reference/glossary:standalone>` from R3.2. Using
   :doc:`templates </user/templates/templates>` and :ref:`service qubes <user/reference/glossary:service qube>` from R3.2 is not fully
   supported (see
   `#3514 <https://github.com/QubesOS/qubes-issues/issues/3514>`__).
   Instead, we recommend using the templates that were created
   specifically for R4.0, which you can
   :doc:`customize </user/how-to-guides/how-to-install-software>` according to your needs. For
   the template OS versions supported in R4.0, see :ref:`supported releases <user/downloading-installing-upgrading/supported-releases:templates>`. If the restore tool
   complains about missing templates, you can select the option to
   restore the app qubes anyway, then change them afterward to use one
   of the default R4.0 templates.



Note about additional disp-* qubes created during restore
---------------------------------------------------------


One of differences between R3.2 and R4.0 is the handling of disposables.
In R3.2, a disposable inherited its network settings (NetVM and firewall
rules) from the calling qube. In R4.0, this is no longer the case.
Instead, in R4.0 it’s possible to create multiple disposable templates
and choose which one should be used by each qube. It’s even possible to
use different disposable templates for different operations from the
same qube. This allows much more flexibility, since it allows you to
differentiate not only network settings, but all of a qube’s properties
(including its template, memory settings, etc.).

Restoring a backup from R3.2 preserves the old behavior by creating
separate disposable template for each network-providing qube (and also
``disp-no-netvm`` for network-isolated qubes). Then, each restored qube
is configured to use the appropriate disposable template according to
its ``netvm`` or ``dispvm_netvm`` property from R3.2. This way,
disposables started on R4.0 by qubes restored from a R3.2 backup have
the same NetVM settings as they had on R3.2.

If you find this behavior undesirable and want to configure it
differently, you can remove those ``disp-*`` disposable templates. But,
to do so, you must first make sure they are not set as the value for the
``default_dispvm`` property on any other qube. Both Qubes Manager and
the ``qvm-remove`` tool will show you where a disposable template is
being used, so you can go there and change the setting.

Upgrade all Template and Standalone VM(s)
-----------------------------------------


We strongly recommend that you update **all** templates and standalones
before use so that you have the latest security patches from upstream
distributions. In addition, if the default templates have reached EOL
(end-of-life) by the time you install R4.0, we strongly recommend that
you upgrade them before use. Please see :doc:`supported releases </user/downloading-installing-upgrading/supported-releases>` for information on supported OS
versions and consult the guides below for specific upgrade instructions:

- :ref:`Upgrading Fedora templates <user/templates/fedora/fedora:upgrading>`

- :ref:`Upgrading Debian templates <user/templates/debian/debian:upgrading>`

- `Updating Whonix templates <https://www.whonix.org/wiki/Qubes/Update>`__