Upgrade from 4.x to 5.0

From Proxmox VE
Jump to: navigation, search

Introduction

Proxmox VE 5.x introduces major new features, therefore the upgrade must be carefully planned and tested. Depending on your existing configuration, several manual steps are required, including some downtime. NEVER start the upgrade process without a valid backup and without testing the same in a test lab setup.

If you run a customized installation and/or you installed additional packages, for example for sheepdog, or any other third party packages, you need to make sure that you also upgrade these package to Debian Stretch.

Generally speaking there are two possibilities to move from 4.x to 5.x

  • New installation on new hardware (and restore VM´s from backup)
  • In-place upgrade via apt, step by step

In both cases you'd better empty the browser's cache after upgrade and reload the GUI page or there is the possibility that you see a lot of glitches.

Caveats to know before you start

  • if using ceph, upgrade your ceph cluster to the Luminous release before you upgrade, following the article Ceph Jewel to Luminous. But be aware that the Ceph Luminous release, which is required for Proxmox VE 5.x, does not have a stable release yet as of 03/07/2017. For Ceph productive clusters, we recommend waiting for the release of ceph 12.2

New installation

  • Backup all VMs and containers to external media (see Backup and Restore)
  • Backup all files in /etc You will need various files in /etc/pve, as well as /etc/passwd, /etc/network/interfaces, /etc/resolv.conf and others depending on what has been configured from the defaults.
  • Install Proxmox VE from ISO (this will wipe all data on the existing host)
  • Rebuild the cluster if you had any
  • Restore the file /etc/pve/storage.cfg (this will re-map and make available any external media you used for backup)
  • Restore firewall configs /etc/pve/firewall/ and /etc/pve/nodes/<node>/host.fw (if relevant)
  • Restore full VMs from Backups (see Backup and Restore)

If you feel confortable with the command line, and all your VMs/CTs are one shared storage you can also follow the procedure Bypassing backup and restore when upgrading


In-place upgrade

In-place upgrades are done with apt-get, so make sure that you are familiar with apt before you start here.

Tip: You can perform a test upgrade and a standalone server first. Install the Proxmox VE 4.4 ISO on testing hardware, then upgrade this installation to the latest minor version of Proxmox VE 4.4 (see Package repositories), copy/create relevant configurations to the test machine to replicate your production setup as closely as possible. Then you can start the upgrade. You can even install Proxmox VE 4.4 in a VM and test the upgrade in this environment.

Preconditions

  • upgraded to latest V 4.4
  • reliable access to all configured storages
  • healthy cluster
  • no VM or CT running
  • valid backup of all VM (needed if something goes wrong)
  • Correct repository configuration
  • at least 1GB free disk space at root mount point
  • if using Ceph, you should be already running the Ceph Luminous version, but see the caveat above

Actions Step by Step

All has to be done on each Proxmox VE node's command line (via console or ssh; preferably via console in order to exclude interrupted ssh connections). Again, make sure that you have a valid backup of all CT and VM before you start.

Add the PVE repositories to you installation

First make sure that your actual installation has the latest package of the Proxmox VE 4.4 release:

apt-get update && apt-get dist-upgrade

Update the Debian repository entry to stretch.

sed -i 's/jessie/stretch/g' /etc/apt/sources.list

Update the Proxmox VE repository entry to stretch.

sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/pve-enterprise.list

More information about Package_Repositories

Replace ceph.com repositories with proxmox.com ceph repositories This step is only necessary if you have a ceph cluster on your PVE installation.

echo "deb http://download.proxmox.com/debian/ceph-luminous stretch main" > /etc/apt/sources.list.d/ceph.list

If there is a backports line then remove it. Currently the upgrade has not been tested when packages from the backports repository are installed.

Update the repositories data:

apt-get update

Upgrade the basic system to Debian Stretch and PVE 5.0

This action will consume some time - depending on the systems performance, this can take up to 60 min or even more. If you run on SSD, the dist-upgrade can be finished in 5 minutes.

Start with this step to get the initial set of upgraded packages.

 apt-get dist-upgrade

During either of the above, you may be asked to approve of some new packages replacing configuration files. Do with them as you see fit, but they are not relevant to the Proxmox upgrade.

Reboot the system in order to use the new PVE kernel

Troubleshooting

  • Failing upgrade to "stretch"

Make the sure that the repository configuration for stretch is correct.

If there was a network failure and the upgrade has been made partially try to repair the situation with

apt-get -fy install
  • Unable to boot due to grub failure

See Recover_From_Grub_Failure


Breaking Changes in 5.0

Configuration defaults

Default display switched from 'cirrus' to 'std'

Since: qemu-server 5.0-10

The default display is now 'std' (Standard VGA card with Bochs VBE extensions), changed from the 'cirrus' type. Cirrus has security bugs and 'std' is the default since qemu 2.2

Yellowpin.svg Note: If you use the default value for the Display(vga) option of your VM, then the live migration of from a PVE 4.4 host to a PVE 5.0 will not work, as the VM on the PVE 5.0 will have a different hardware from the source host.

If you need to live migrate VMs between a 4.4 and a 5.0 node, you need to configure your VM as indicated in the steps below.

Verify if I am using the Default option:

qm config <my_vmid> | grep ^vga ; echo $?

If the command returns '1' , then it means you're using the default value, and need to set a manual value for the live migration to work, following the steps below. Any other value returned means that things are fine.

Now depending on if you can tolerate a shutdown of the VM you have two options:

  • if a shutdown of the VM is acceptable. Simply power the VM off, migrate it offline to the target node, and start it again on the PVE 5 target node. The VM will run with the new default display, no editing of configuration needed
  • if a shutdown of the VM is not acceptable at this point, follow the steps below.

Step to execute:

  1. make a copy of the configuration file of you VM
  2. cp /etc/pve/qemu-server/<my_vmid>.conf  /etc/pve/qemu-server/<my_vmid>.conf.bak
    
  3. open the VM configuration with the editor of your choice ( nano, vim)
  4. vim /etc/pve/qemu-server/<my_vmid>.conf
    
  5. add the line
  6. vga: cirrus
    

at the beginning of the file

with this operation done, live migration between a 4.4 and a 5.0 node is now possible.

At the next maintenance window, we recommend you to change to the default 'std' graphic adapter for the VM.

qm set -vga std <my_vmid>

and then poweroff the VM, and start it again. A reboot is not enough to reread the VM configuration file.

External links