qubes-doc/user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md
Andrew David Wong a18174dc5e
Fix capitalization; update terms (QubesOS/qubes-issues#6769)
Thank you to @unman for the initial sentence case pass.
2021-07-09 05:10:44 -07:00

4.0 KiB

lang layout permalink redirect_from ref title
en doc /doc/upgrade-to-r3.1/
/en/doc/upgrade-to-r3.1/
/doc/UpgradeToR3.1/
/doc/UpgradeToR3.1rc1/
155 Upgrading to R3.1

Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up their systems.

Current Qubes R3.0 systems can be upgraded in-place to the latest R3.1 by following the procedure below.

Upgrade all Template and Standalone VM(s)

By default, in Qubes R3.0, there is only one template. However, users are free to create more templates for special purposes, as well as standalones. More information on using multiple templates, as well as standalones, can be found here. The steps described in this section should be repeated in all the user's Template and Standalone VMs.

Upgrade Fedora templates:

  1. Open a terminal in the template (or standalone). (E.g., use Qubes VM Manager's right-click menu, choose "Run Command in VM," and type gnome-terminal there.)

  2. Install the qubes-upgrade-vm package:

    sudo yum install qubes-upgrade-vm
    
  3. Proceed with a normal upgrade in the template:

    sudo yum upgrade
    
  4. Shut down the template.

Upgrade Debian (and Whonix) templates:

  1. Open a terminal in the template (or standalone). (E.g., use Qubes VM Manager's right-click menu, choose "Run Command in VM," and type gnome-terminal there.)

  2. Update repository definition:

    sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
    sudo sed -i 's/r3.0/r3.1/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
    
  3. Proceed with a normal update in the template:

    sudo apt-get update
    sudo apt-get dist-upgrade
    
  4. Remove unnecessary now file:

    sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
    
  5. Shut down the template.

Upgrading dom0

Important: Do not perform the steps described in this section until all your Template and Standalone VMs have been upgraded as described in the previous section. Also, do not shut down sys-net or sys-firewall, since you will not be able to start them again until after the entire in-place upgrade procedure is complete.

  1. Open a terminal in Dom0. (E.g., Start -> System Settings -> Konsole.)

  2. Upgrade dom0 to R3.1:

    sudo qubes-dom0-update --releasever=3.1
    

    At this point, most of the qvm-* tools will stop working until after you reboot the system.

  3. If the previous step completed successfully, your qubes-core-dom0 version should be 3.1.4 or higher. If it's not, repeat the previous step with the --clean option.

  4. Reboot dom0.

    The system may hang during the reboot. If that happens, do not panic. All the filesystems will have already been unmounted at this stage, so you can simply perform a hard reboot (e.g., hold the physical power button down until the machine shuts off, wait a moment, then press it again to start it back up).

Please note that if you use Anti Evil Maid, it won't be able to unseal the passphrase the first time the system boots after performing this in-place upgrade procedure since the Xen, kernel, and initramfs binaries will have changed. Once the system boots up again, you can reseal your Anti Evil Maid passphrase to the new configuration. Please consult the Anti Evil Maid documentation for instructions on how to do that.

If you use USB VM, you may encounter problem with starting it on updated Xen version (because of strict default settings). Take a look at User FAQ for details.

Once you have upgraded dom0, you can install new templates from Qubes R3.1 repositories, in particular the new default Fedora 23 template:

sudo qubes-dom0-update qubes-template-fedora-23