Upgrading from Debian Jessie to Stretch

Well boys and girls, it's been 785 days, but the long wait is over. Debian Stretch is here, bringing with it PHP 7.0, MariaDB 10.1, brotli, and all sorts of random goodies and version bumps. If your servers are already running Jessie, upgrading is pretty straightforward.

Before we begin, though, the usual caution: every server is ever so slightly different, so please make sure you have backups before you begin, and do your work while everyone else is asleep in case something goes dreadfully wrong.

Actually, one more caution: READ THE PROMPTS. While updating, you'll likely be asked whether this or that configuration file should be updated with the new distribution version. If you made weird changes to the original, the answer is probably "no", however you should make a note and go back later to see what the differences were. In other cases, you can probably blow the original away. Regardless, you'll want to monitor the system logs for a little while to see if anything's unhappy.

Anyhoo, onward!

Update That Shit

# First things first, make sure Jessie is up-to-date.
sudo apt-get update && sudo apt-get upgrade

# Next, adjust your APT sources, both sources.list and anything
# in sources.list.d/. Something like the following will get you
# there quickly, but you may need to tweak things manually.
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list

# Run regular updates one more time.
sudo apt-get update && sudo apt-get upgrade

# Now run a full distribution upgrade!
sudo apt-get update && sudo apt-get dist-upgrade

# Go ahead and reboot now.
sudo reboot

# Run updates one more time. Some of my servers had updates at this
# stage, some didn't. You can use "dist-upgrade" from here on out
# if you prefer it.
sudo apt-get update && sudo apt-get dist-upgrade

# Now some quick cleanup!
sudo apt-get autoremove --purge
sudo apt-get clean

With that, you might be done!

Or, maybe not.

If you, like me, grow impatient towards the end of a Debian cycle, wanting some newer-than-ancient version of your L(A/E)MP stack, etc., then you might end up avoiding upgrade issues or creating some. I'm a LEMP guy myself, so my Jessie servers happened to be running the jessie-backports edition of nginx, MariaDB 10.0 (rather than MySQL whatever), and Dotdeb's PHP7.0.

Let's tackle these three in order:


If you were running the jessie-backports version of Nginx, you probably won't run into any issues; that version more or less matches the main stretch version. But if you're coming from an older version, the main thing to watch out for is that SPDY support has been replaced with HTTP/2 support. If your Nginx configuration is failing, remove all mentions of SPDY, then adjust your SSL lines to look like

listen 443 ssl http2;

If you can't figure out why Nginx hates you, you can test the configuration by running:

nginx -t

MariaDB 10.0

All of my Jessie servers were running the same version of MariaDB (10.0), but for some reason, the upgrade to Stretch saw different things happen. In some cases, MariaDB was ignored, not upgraded, and ran just fine. In others, unsatisfiable dependencies caused the server to blow up. Either way, MariaDB needs to be synced with Stretch's version (10.1), so shit's gotta change. I had to go with the nuclear option.

Before we jump in, a few notes:

  1. When asked, DO NOT let Debian blow away your databases;
  2. Copy your configuration files (like my.cnf) to another directory for later reference;
  3. If any non-MySQL programs get caught in the cross-fire, make a mental note and re-install them later.
# Kill, kill.
sudo apt-get purge mysql*

# Now re-install MariaDB, which the single "mariadb-server" package
# will handle, and anything not related to MySQL that got purged,
# for example "boinc-client".
sudo apt-get install mariadb-server [...]

# Make sure the databases are good and upgraded:
mysql_upgrade -u root -p

# And for good measure, re-run the security wizard:

You should be back up and running, but the config files will be missing your blood, sweat, and tears. If you tweaked the hell out of it the previously, move your configurations back to the /etc/mysql directory.

One more gotcha: Stretch's version drops a handful of under-loved engines that I used to disable manually via --skip-foobar configurations. I had to remove those entries to get MariaDB to boot.


If you had been using Dotdeb's PHP 7.0 binaries under Jessie, congratulations!, PHP shouldn't cause any issues during the OS upgrade. The package naming patterns are the same, so the source handoff should be smooth.

But if you manually compiled PHP7 or were still running Jessie's PHP5, there will be blood.

Because of build compatibility issues and an approaching end-of-life, PHP5 binaries are completely missing from Stretch's repos. That means that during the OS upgrade, PHP may or may not be upgraded, may or may not be cleaned, but either way, probably won't boot correctly. You'll need to manually install PHP7 along with any optional modules you're using (e.g. Intl, JSON, bcmath, etc.), and manually purge any PHP5 libraries after the reboot.

Config-wise, there are some path changes, so Nginx configurations might need to be adjusted to ensure PHP requests still get routed to the right place. But on the bright side, most PHP applications that were running on PHP 5.6 should be happy to continue running on PHP 7.0 without any code changes or library fixes. When in doubt, you can check the migration guide to see if any issues might affect you.


All in all, I found the process to be comparatively painless. Debian has come a long way, baby.

Josh Stoik
21 June 2017
Previous How to Science the Shit Out of Your Server
Next Nginx Static Compression, Gzip and Brotli