Akeeba Backup for WordPress 8.1.0 (beta)

09 October 2023 Last updated on 14 October 2023

We have released Akeeba Backup for WordPress 8.1.0.b1 (Beta 1). We ask our clients to test it as it involves a major migration of the settings and backup archives. The Beta and Release Candidate period will last at least until the end of October 2023. The stable version will be released in November 2023 as long as we have enough feedback from our clients.

Why is this beta necessary?

Upon release of Akeeba Backup for WordPress 8.0.0 we found out that there were two backwards incompatible changes (one a bug, the other one intentional and even worse than the first) in WordPress 6.3 which prevented the correct installation of the update.

The first problem was a backwards incompatible change with the upgrader_process_complete filter hook which is the only method WordPress provides to run code after updating a plugin. While this code worked perfectly fine up to and including WordPress 6.2.2, it stopped working on WordPress 6.3.0 and later as both the count and the order of arguments is now different. This seems to be an unintentional change (bug) in WordPress itself, as its core code clearly suggests that it intends to pass two arguments. Update October 14th, 2023: It is a confirmed bug in WordPress 6.3.0 and 6.3.1, fixed in WordPress 6.3.2.

More importantly, we discovered another issue which prevents any updates to Akeeba Backup for WordPress from working properly.

Earlier versions of WordPress would delete the plugin folder before update. This is not desirable for our plugin as it would remove any backup archives stored under the plugin's folder, e.g. backups stored in the default output directory, as well as remove the secretkey.php file which stores the encryption key to the backup profile configuration. As a result, if the plugin's folder is deleted you may lose your backups, and you will definitely lose your backup profile settings. We had addressed that issue by using WordPress' upgrader_package_options, telling WordPress not to do that. This method had worked without a problem for the past four years we've supported updating our plugin using WordPress' plugin updater.

Unfortunately, WordPress 6.3 introduced a major backwards compatibility break which is NOT documented in its release notes. Worse than that, it is misleadingly referenced as “Add rollback for failed plugin/theme updates” in WordPress' Trac. What this feature actually does do is move the already installed plugin version's folder, install the new version, and delete the old version. This is not even documented in the WordPress development ticket itself.

We only found out by running the update through a debugger after noticing that updating Akeeba Backup for WordPress 7.9.1.1 to 7.9.2 worked on WordPress 6.2.2 (as it had done perfectly well when it was released in July), but lost the backup settings when the same upgrade took place under WordPress 6.3.1. Remember that going from 7.9.1.1 to 7.9.2 does not require a migration, therefore this behaviour was inexplicable. As it turns out, the new feature is intentional and disregards the flag we already set in upgrader_package_options telling WordPress to not delete our plugin's folder.

You don't have to believe us, or the links to official WordPress properties we have provided. You can prove it yourself if you want, see Addendum A at the end of this article.

This also explains why users who installed versions 8.0.0.1 and 8.0.0.2 which included workarounds for the upgrader_process_complete WordPress bug (the post-upgrade code not running) still resulted in our clients losing their backup profiles. It was not our fault. It was WordPress doing the exact opposite of what we were asking it to do, causing data loss on your sites.

While much can be said in retrospect about whether we could have caught these issues during testing —and we have definitely been improving our process on that front as a result of the issues we saw last week— the fact remains that WordPress 6.3 introduced a backwards incompatible feature in a minor release, something that WordPress had pledged to never do. Even worse, the nature of the backwards incompatible change means that there is absolutely no way whatsoever that we can provide an automatic update to the update channel used by Akeeba Backup for WordPress up to and including version 8.0.0.2. Even if we had caught this change earlier, we'd still be here wondering what exactly are we supposed to do with WordPress' mess of a plugin update process. Therefore, upgrading from one of these versions to any version from Akeeba Backup 8.1.0 onwards requires a manual update.

Upgrading to Akeeba Backup 8.1.0.b1 or later is a MANUAL update

If you are using Akeeba Backup for WordPress version 7.x or 8.0.x you can not update to Akeeba Backup 8.1.0.b1 or later automatically. As explained above, due to the change in WordPress 6.3 that would result in a loss of your backups and your backup profile settings. We have, therefore, disabled that update channel forever.

Instead, download the new version and extract it on your computer. You will see a folder named akeebabackupwp extracted.

Upload the contents (files and folders) from the extracted akeebabackupwp folder into your site's wp-content/plugins/akeebabackupwp folder, overwriting existing files.

Finally, log into your site's wp-admin and go to Akeeba Backup. If there is a message at the top of the screen that migration is required click on its button. A (very) fast migration takes place, and you're taken to a page which tells you that no further migration is necessary.

IMPORTANT! Do NOT use WordPress' Plugins, Add New page, or WP-CLI, to install the first update you make from Akeeba Backup for WordPress versions 7.x and 8.0.x to 8.1.x or later. Doing so will delete the plugin's folder. As a result, you will lose your backups and your backup profile settings.

If you run into update issues (lost backups or backup profile settings) please let us know. We can only fix what we know. Please do not contact us for expected behaviour e.g. the plugin refusing to take a backup until you complete the migration in its interface, or the fact that any backups stored in and backup profiles having an output directory under the plugin's root are migrated to a folder under wp-content/backups. Please read Addendum B (and, if your have the time Addendum C) below to understand what changes were made in 8.1.0, why they were made, and what does that mean for the update.

Staying informed

We have always used the News section of our site to communicate important information about our software and our releases.

If you would like to stay up to date, you can subscribe to its RSS feed, https://www.akeeba.com/news.feed.

Our recommendations for RSS feed readers are:

  • Blogtrottr. Sends RSS feed items to you via email (free of charge).
  • Mozilla Thunderbird. Windows, macOS, and Linux. Free of charge, and FOSS. Email, RSS, instant messaging, and much more. It will notify you when there's new feed content.
  • Flipboard. iOS, Android. It has a pretty cool interface for news reading.
  • Reeder. For macOS, paid.

Of course, let's not forget that both CMS we support, WordPress and Joomla, have RSS feed readers built into them! After all, they create RSS feeds. It would be a serious omission if they couldn't consume them as well.

On a WordPress site you can create a page with its visibility set to Private and add an RSS block to it. Enter the feed URL https://www.akeeba.com/news.feed.

On a Joomla site you can create a backend module of the Feed Display type. Enter the feed URL https://www.akeeba.com/news.feed.

The addendums below include more technical and background information for anyone interested.

Addendum A: Reproducing The Lost Settings Issue

WordPress has pledged to never include backwards incompatible changes in minor versions, e.g. going from 6.2 to 6.3. Unfortunately, this is a lie. Like all other CMS it will introduce backwards incompatible changes whenever and pretend nothing is wrong with this.

We understand that many people refuse to believe that. Software, however, is not religion. It's code you can run. You can either reproduce an issue, or not. There is no supernaturalism involved. This Addendum describes the reproduction steps to WordPress deleting the plugin's folder on update and losing settings, despite our code involved being the same that works perfectly file on WordPress 6.2 and earlier.

First, we will prove that WordPress 6.2 used to work just fine.

  • Create a site with WordPress 6.2.2
  • IMPORTANT! After creating the site, close the browser. Then edit its wp-config.php and add the line define('WP_AUTO_UPDATE_CORE', false); after the line that reads /* Add any custom values between this line and the "stop editing" line. */. This is important! We do not want WordPress to auto-update to version 6.3.
  • Go to WordPress' wp-admin, Plugins, Add New
  • Make sure that at the very bottom it still reads WordPress 6.2.2. If it reads a different version, trash the site and start afresh; note that this happened because you skipped the second step.
  • Install Akeeba Backup CORE 7.9.1.1. This is a version released in May 2023 and, crucially, earlier than the latest one which can be found in the update stream (version 7.9.2).
  • Configure Akeeba Backup.
  • Take a backup.
  • Go to the Plugins page
  • Update Akeeba Backup to 7.9.2
  • Go to Akeeba Backup. You are NOT asked to run the configuration wizard.
  • Go to Akeeba Backup, Manage Backups. The backup archive is STILL there, the record appears with a green checkmark (OK) status.

Now, we can step that the same upgrade path from Akeeba Backup 7.9.1.1 to 7.9.2 does NOT work under WordPress 6.3. Since we only change the WordPress version we prove the problem is in the only changed variable, the WordPress version.

  • Go to Plugins.
  • Disable, and then uninstall, Akeeba Backup.
  • Remove the define('WP_AUTO_UPDATE_CORE', false); line from the wp-config.php file.
  • Upgrade to WordPress 6.3
  • Install Akeeba Backup CORE 7.9.1.1.
  • Configure Akeeba Backup.
  • Take a backup.
  • Go to the Plugins page
  • Update Akeeba Backup to 7.9.2
  • Go to Akeeba Backup. You ARE asked to run the configuration wizard.
  • Go to Akeeba Backup, Manage Backups. The backup archive is NO LONGER there, the record appears with a gray trashcan (Obsolete) status.

For those among you who prefer to follow along using the command line, here's how. You need WP-CLI (as wp in your $PATH) and wget.

##
## Install WordPress 6.2.2 and Akeeba Backup 7.9.1.1
##

wget "https://wordpress.org/wordpress-6.2.2.zip"
wp config create --dbname=client --dbuser=client --dbpass=client
# !!! IMPORTANT !!! We do not want our site to auto-upgrade to WordPress 6.3.
wp config set WP_AUTO_UPDATE_CORE false --raw
wp core install --url=https://client.local.web --title="WordPress Is Broken" --skip-email \
    --admin_user="admin" --admin_password="admin" --admin_email="This email address is being protected from spambots. You need JavaScript enabled to view it."
wget "https://cdn.akeeba.com/downloads/backupwp/7.9.1.1/akeebabackupwp-7.9.1.1-core.zip"
wp plugin install $(pwd)/akeebabackupwp-7.9.1.1-core.zip --activate

## Things to do on your site now:
## * Configure Akeeba Backup.
## * Take a backup.
## * Go to Plugins and update Akeeba Backup to 7.9.2
## * After the update, go to Akeeba Backup. The configuration is still there, you are NOT
##   asked to run the configuration wizard, and the backup archive still exists.

## And now, let's try with WordPress 6.3...

##
## Upgrade to WordPress 6.3 or later, uninstall Akeeba Backup, and install version 7.9.1.1
##

wp core update
wp core update-db
wp plugin deactivate akeebabackupwp --uninstall
wp plugin install $(pwd)/akeebabackupwp-7.9.1.1-core.zip --activate

## Things to do on your site now:
## * Configure Akeeba Backup.
## * Take a backup.
## * Go to Plugins and update Akeeba Backup to 7.9.2
## * After the update, go to Akeeba Backup. The configuration is reset, you ARE asked to
##   run the configuration wizard, and the backup archive IS GONE FOREVER (cannot download).

Addendum B. The changes we made to Akeeba Backup 8.1.0 in response to the issues

We can no longer believe WordPress to not introduce backwards incompatible changes in a minor release, despite its, well, propaganda. Therefore, we can no longer trust that WordPress can be reliably told not to delete our plugin's folder. The only way around that is to no longer store any important information in our plugin's folder at all. This required making two changes:

  • The default backup output directory has been moved from wp-content/plugins/akeebabackupwp/app/backups to wp-content/backups.
  • The backup profile settings encryption key has been moved from wp-content/plugins/akeebabackupwp/app/Solo/secretkey.php (and its previous location wp-content/plugins/akeebabackupwp/app/Solo/engine/secretkey.php) to wp-content/akeebabackup_secretkey.php

The second change is closely linked to the first. We can no longer believe that WordPress will not introduce breaking changes or bugs which prevent the execution of the post-upgrade code, just like it did with WordPress 6.3. The experience we are having is that bugs like that will remain unsolved for months, or years, or possibly never fixed. Therefore, we can no longer trust WordPress to execute our post-upgrade code. As a result, we refactored our code so that it always checks if the post-upgrade code has executed after upgrading to the currently installed version. If not, it is executed before doing anything else. This means that Akeeba Backup adds one database query and about 12 milliseconds of load time to every page of your site, since WordPress loads every plugin —including Akeeba Backup— on every page.

Addendum C. Expected risks and mitigations

The nature of the changes we had to do in Akeeba Backup 8.1.0 mean that yet another migration is necessary. However, we have introduced redundant mitigations to prevent a repeat of the issues we saw with 8.0.0.

Encryption key migration is now performed as the very first of post-upgrade code. Furthermore, it does not just look whether an old file exists. It checks if the key it contains can actually decrypt your backup profiles. If there are multiple old key files the one which decrypts the most backup profiles will be used. This is a bit slower, but it takes under half a second with three dozen backup profiles on an average commercial host.

The Default output directory is no longer a folder shipped with the plugin. It has to be created the first time we try to use it. If creating it is not possible, we raise a new critical backup error which prevents backups from running. The error links to a page on our site which tells you how to create this folder manually. We expect that a small number of users (about one in 40 users) who are on hosting still running PHP as an Apache module —a practice discouraged for well over two decades— will see this message and have to take manual action. We expect an even smaller number among them to get confused and ultimately give up on our software. This is unfortunate, but necessary to avoid far bigger issues with far more clients.

If your backup output folder is within the plugin folder we raise a critical backup error which prevents backups from running. Previously, this error was high-priority, therefore you could still run a backup. This is a deliberate change. It ensures that your backups are NOT going to be deleted by WordPress on plugin update. We expect a lot of users to see this error. They will have to go to the plugin's main page and run the migration. While this is annoying, it will take less than a day for people with approximately 200 sites. We would also like to believe that people with so many sites have heeded the warning —displayed for the past 15 years— not to use such a directory. Well, we'll find out soon enough. If you were told to come here and read this, please remember that you were told not to put your output directory inside the plugin's folder and there's an entire section in the documentation explaining the security concerns. Thank you.

Backup and backup profile migration is necessary as a result of the previous two points. We decided to NOT do that automatically because of concerns that on some sites this could lead to timeouts and half-migrated data. Moreover, the detection of whether migration is necessary is based on where you told Akeeba Backup to store backup archives and where they are actually stored. We are absolutely certain that some people moved their sites around quite a bit and have ended up with backup archives in locations they didn't expect. We, therefore, want them to see migration was necessary, so they can avoid whatever mistake they did while managing their site in the future. A minor annoyance today can save you from a lot of trouble in the future.

Post-upgrade code execution, as explained, cannot be left to chance — or, worse, to WordPress. It must be reliable. We have refactored our code to check for the execution of post-upgrade code when the plugin initialises, as well as when you run any of its command-line scripts or use the legacy URL for its Remote JSON API. This carries its own risks:

  • Detection is based on a database query. If that query fails for any reason (e.g. the #__akeeba_common table is corrupt), we cannot detect that running the post-upgrade code is necessary. This could lead to problems. We expect this to be an extremely rare circumstance.
  • Likewise, marking that running the post-upgrade code is no longer necessary requires writing to the database. If the table is corrupt, or otherwise saving that information to the table fails, Akeeba Backup will try to run the post-upgrade code continuously. We have made this code idempotent, therefore no harm will be done except wasting time in the order of 50 to 100 milliseconds per page load. We expect that to be an extremely rare circumstance.
  • The server may experience an error (e.g. time out) while the post-upgrade code is executing. In this case we will have not had the chance to mark the post-upgrade code as executed, therefore it will run again. Thanks to the aforementioned idempotence, it will complete the next time. This may mean that the first automated backup on such a site might fail to execute. We expect this to be an extremely rare if not outright unlikely circumstance.

We introduced a new update channel which uses a different update format, JSON instead of INI data. The change of the update channel was necessary considering that the first upgrade from Akeeba Backup for WordPress version 8.0.x or earlier to Akeeba Backup for WordPress version 8.1.x or later has to be manual, due to the plugin folder deletion issue in WordPress 6.3 and later. The change of format was necessary, so we can list more than one versions (the INI file only ever listed one version), therefore we can show you the latest stable and the latest testing (alpha, beta, or release candidate) version which allows more people to test these releases. This comes with two risks:

  • Old versions cannot update directly. This is by design. Most importantly, however, is that the old versions cannot be notified of an update being available without allowing them to install that update. Unfortunately, there is no solution to that. If we make the new version available in the old channel, those who have not already updated manually to 8.1.0.b1 or later will see their backup profiles wiped out once again. We are NOT letting that happen again.
  • The new update code is tested only in a limited number of configurations. We can only test with whatever sites and hosts we have access to. The real test of any piece of code is when it's released to a wide audience. There are configuration out there we can't account for: we can't write a workaround for something we cannot think of, and have never heard of. Considering that we've been using JSON data in our software for a long time, and the core of the updater (retrieving updates, downloading and installing updates) has not changed we do not expect this to be an issue. Some people will report “red herring” issues which have nothing to do with this change, but this always happens with every new release, regardless of whether we have changed anything or not.