Blog Work Stories Contact

How to upgrade your web server from Debian 7 Wheezy to Debian 8 Jessie

Upgrading your Debian machine to a new, major release is not as difficult of an operation as it seems.  Actually, the most difficult part for me was remembering which version name pairs with which release number.  The tough part is dealing with the big changes that are introduced with the new version, rather than the upgrade itself.

These instructions are primarily targeted to web servers running Debian 7, but the instructions can also be applied to regular desktop machines as well.  (Just ignore all the parts about Apache!)

Before you begin

Understand that the move to Debian 8 is a major change to your system.

  • Back up your system. Don’t attempt to upgrade a production server unless you have a full backup of the entire system that you can quickly roll-back to if something goes wrong.
  • Don’t upgrade during peak hours. Assume that your system will go down during the upgrade.  Reduce the pressure on yourself by upgrading your system during off-peak hours, when your system isn’t being used as much, and when your users aren’t likely to notice an outage.
  • New commands to start and stop services. Debian 8 now uses systemd instead of SysVinit and introduces new commands to start, stop, and restart services.  Before you upgrade, consider printing out a Systemd cheatsheet and have it at the ready. The most important commands are:
sudo systemctl start {unit}      // Start a service
sudo systemctl stop {unit}       // Stop a service
sudo systemctl status {unit}     // Check if a service is running
sudo systemctl enable {unit}     // Run a service at boot
sudo systemctl disable {unit}    // Don't run a service at boot
sudo systemctl is-enabled {unit} // See if a service will load at boot</pre></li>
  • Log files may be stored in new locations. They also may be in new formats, especially if they have anything to do with systemd (which now stores logs in a binary format instead of plaintext).
  • Debugging system issues is different in systemd. The commands you run to debug a failed service are different than they used to be.  When services fail to start, you will need to use commands like:
systemctl status varnish.service
journalctl -xn

The upgrade process

Here are the steps I used to upgrade my Debian 7 (Wheezy) machines to Debian 8 (Jessie).

Step 1: Start off by ensuring that your system is up-to-date with its current distribution

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

Step 2: Set the apt sources to the new distribution version

You can either go through /etc/apt/sources.list and change instances of wheezy to jessie manually, or use this command to do the find-and-replace for you in one step.

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

Step 3: Upgrade packages with the new source

You will want to stick around during the upgrade processes. Two things will happen that will require your input:

During the upgrade process, packages will be upgraded and some configuration files that you may have modified will need to be updated also.  APT will give you the option to keep the existing files and preserve your changes, or overwrite them with the latest package maintainer’s version.  I choose to wipe out my changes and install new configuration files.

  • Yes, it’s a hassle to go back and update the files with my customizations, but I prefer to have the latest settings from the package maintainers (who I trust more to know how to configure the software than myself).  I don’t want to miss out on the latest and most secure configuration for Apache because I couldn’t be bothered to edit the config files to disable indexes again.
  • I keep a log of all customizations that I need to make to each configuration file (a sort of poor man’s version tracking), so it’s a simple matter to identify which changes need to be made again.
  • I consider this burden to be part of the upgrade process – learn what has changed in the services that you run.  Be familiar with your system.  As much as you need to keep your system up to date, keep yourself and your notes on those systems up to date.

Your computer may stop during the upgrade process to show you important release notes for the packages that are being upgraded.  When you see the notes come up, you can use Page Down/Up to browse through them.  When you reach the bottom, it will tell you.  Pressing q will exit the notes and proceed with the installation.

  • It’s important to take a look at the notes as some services you run will operate differently after the upgrade.  Sometimes options are retired, or file locations are changed.
  • One of those major changes is to Apache, when moving to version 2.4.  There are some major changes to the virtualhost configuration files which will take your sites down when you upgrade, so it’s important to understand what you need to do to correct this.  I’ll outline those changes later in this post.

Run these commands to upgrade your system to the new package versions.  These commands are the same as the ones above – that’s not a typo!  The only thing that changes is the distribution source, which we changed in step 2.  Easy, eh?

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

Step 4: Reboot the system

Sorry, uptime lords, you’re going to lose that super-long uptime you’ve been maintaining.  I find that it’s best to do a full restart every now and then to ensure the system is cleaned out, and more importantly that it will recover cleanly from an unexpected reboot.

I especially want to do a full system restart after a major upgrade to ensure that all of the new packages are working properly, and that there are no hidden surprises.

Step 5: Verify your services are running properly, then troubleshoot any issues

Some major things broke for me during the upgrade to Debian 8.  Here are the issues I ran into and how I fixed them.

  • Apache 2.4 virtualhost files now need to end in .conf If the virtualhost files don’t have that extension, a2ensite will report File not found when you try to enable them.
  • Apache 2.4 virtualhost syntax for disallowing indicies has changed. You can no longer have Options -Indexes in your virtualhost declaration files.  It appears that they are no longer allowed by default, so it’s OK to remove this entry from the list of Options.
  • MySQL may not start. The error Warning: mysqli\_real\_connect(): Headers and client library minor version mismatch. Headers:50544 would display.  Turns out the fix was to install php5-mysqlnd and then restart the apache2 service.

  • WordPress pages may return a 404. Apache 2.4 is stricter than its predecessor, and it doesn’t look to local .htaccess files for overriding options by default. The homepage will load, but any other page you browse to will return a 404. You can fix this by editing /etc/apache2/apache2.conf and changing [AllowOverride None] to [AllowOverride All].

  • WordPress permalinks may break. Just reset them by going to Settings > Permalinks, changing them from their current state to default, and then back to whatever they used to be.
  • Munin would not start. I couldn’t get it to work, for some reason it had been marked by as masked (unsuitable for running) by the system.  Manually unmasking it wouldn’t make it run, and I got uncomfortable with trying to force it into working. I uninstalled it and then reinstalled the latest version. It turns out there’s a lot of new configuration changes with Munin + Apache 2.4, so learning how to install it from scratch helped.

Step 6: Tidy up by removing any unused packages

sudo apt-get autoremove

And that’s it!  You’re now up and running with Jessie.