Automatic Updates

Updating a Drupal site is difficult, time-consuming, and expensive. It may appear easy its face, but ensuring secure and reliable updates that give assurance to site owners and availability to site visitors is a tricky problem.

The Automatic Updates service for Drupal aims to simplify this process and provide confidence that an update will apply cleanly.

Key Features of the Automatic Updates Module

Public service announcements (PSAs)

Announcements for highly critical security releases for core and contrib modules are done infrequently. When a PSA is released, site owners should review their sites to verify they are up to date with the latest releases and the site is in a good state to quickly update once the fixes are provided to the community.

Update readiness checks

Not all sites are able to always update. The readiness checks are an automated method to determine if a site is ready for automatically updating once a new release is provided to the community. For example, sites that have un-run database updates, are mounted on read-only file systems or do not have sufficient disk space to update in-place can't receive automatic updates. If your site is failing readiness checks and a PSA is released, it is important to resolve the underlying readiness issues so the site can quickly be updated.

In-place updates

Once the PSA service has notified a Drupal site owner of an available update, and the readiness checks have confirmed that the site is ready to be updated, the Automatic Update service can then apply the update.

A specific site (or agency or hosting provider) might decide to provide additional DB handling options beyond these. For example, run a DB dump and offload it to S3 or send emails/notices to slack. And finally, run the DB updates.

If developing your own custom actions, keep in mind that any actions that require code that might have changed during the update should be done via shelled out command-line interface commands. Otherwise, execution will trigger the old version of the code. This is a built-in limitation of PHP. For examples of how you can do this, see the 'execute_updates' plugin, which calls a Symfony console command.

Installation

To install the contrib version of the Automatic Updates module, you will follow the same instructions that you would use for many other modules on Drupal.org:

1. Important: download the module via tarball. Installation via Composer is not supported at this time.

2. Then install the module via your preferred method.

Use of the Module

Attended Use

The PSA feature will display a Drupal.org served PSA directly in the Drupal admin interface, to notify users of an upcoming release.

The Readiness check feature will run regularly to ensure that there are no problems that would prevent an update from applying.

On the module configuration page, a user can choose to manually trigger the in-place update.

Unattended Use

To enable unattended updates, simply check the box on the module configuration page allowing updates to be run on cron. Updates will only be applied if the site is passing it's readiness checks.

Extending Automatic Updates

Database updates can be tricky and site owners have different motivations for how to handle updates that contain them. In Drupal 8, the Automatic Updates module uses a plugin architecture to handle database updates so that the system is extensible.

The default setup is to put a site in maintenance mode, run DB updates, then take the site out of maintenance mode. There is no UI for changing this (yet). The order and sequence of how to handle DB updates is configurable via config in automatic_updates.settings.yml. Alternatively, override via settings.php $config['automatic_updates.settings']['database_update_handling'] = ['rollback', 'alternative_plugin_id', 'yet_another_plugin']. It is an array of plugin IDs.

Available plugins bundled in the module:

• 'execute_updates'
• 'ignore_updates'
• 'maintenance_mode_activate'
• 'maintenance_mode_disactivate'
• 'rollback'

As a site owner or a service provider, you can write additional plugins to further enhance this functionality, such as a custom DB backup plugin, for example.

The architecture of the Automatic Updates System

Core Features

Public Service Announcements (PSAs)

The Public Service announcements are architected by consuming the provided PSA.json feed from Drupal.org and displaying the results with a simple drupal_set_message().

Readiness Checks

The readiness checks are a pluggable system allowing a variety of different types of checks to be run, and warnings or errors to be displayed in the Drupal admin interface.

In-Place Updates

In-place updates are architected using hashed and signed 'quasi-patches' generated by Drupal.org. These quasi-patches are verified using the php-libsodium library, which is available and backported to PHP version 5.3.

Once verified, the quasi-patch is applied with the PHP copy function - simply overwriting all of the files changed in the update.

Test Features

In the current version of the Automatic Updates module, the user can enable a test version of the Drupal.org PSA json feed, allowing you to see how the PSA information will be displayed.

To do so:

1. Enable the automatic_updates_test module using the Drupal module administrative interface, or using the command:

$ drush pm-enable automatic_updates_test

1. Set the variable to enable the test feed, by using the command:

$ drush vset automatic_updates_psa_endpoint http://localhost/automatic_updates/test-json

    If you build your own test feed, you can substitute the URL to your test feed with this command.

To set back the feed to the Drupal.org official PSA feed:

1. Run command

$ drush vset automatic_updates_psa_endpoint https://updates.drupal.org/psa.json

1. And disable the automatic_updates_test module, either using the Drupal module administrative interface or by running the command:

$ drush pm-disable automatic_updates_test

Drupal.org Infrastructure

Automatic Updates for Drupal are supported by the infrastructure of Drupal.org and funded by the activities of the Drupal Association.

Public Service Announcement (PSA) feed

Drupal.org provides a JSON feed of Drupal Public Security Announcements to be consumed by the automatic updates module.

The canonical URL for this feed is https://updates.drupal.org/psa.json, there is a test feed at https://updates.drupal.org/psa-this-is-only-a-test.json which will be used to test functionality as needed.

That feed includes a list of currently-active PSAs with the following details:

• title: The title of the PSA.
• link: The URL to the full PSA on Drupal.org.
• project: The short name of the project the PSA is for.
• type: The type of the project the PSA is for, core, module, theme, distribution, etc.
• is_psa: The flag which indicates that the post is a PSA, and not another kind of Security Advisory.
• insecure: List of versions of the affected project that are currently insecure. This does not indicate which versions will be marked as insecure. This list will be updated after the security release is published, to also include newly-insecure versions.
• pubDate: The date the PSA was published.

For example, if Drupal 7 and 8 release on May 8th, 2019 - PSA-2019-05-07 and Various 3rd Party Vulnerabilities - PSA-2019-09-04 were included in psa.json, the feed would appear as follows:

[
   {
      "title" : "Drupal 7 and 8 release on May 8th, 2019 - PSA-2019-05-07",
      "insecure" : [
         "4.7.0-beta3",
         …
         "8.7.0-rc1",
         "8.7.0",
         "8.7.4"
      ],
      "link" : "https://www.drupal.org/psa-2019-05-07",
      "pubDate" : "2019-09-20T22:09:16+00:00",
      "project" : "drupal",
      "type" : "core",
      "is_psa" : "1"
   },
   {
      "project" : "securitydrupalorg",
      "pubDate" : "2019-09-12T21:35:55+00:00",
      "is_psa" : "1",
      "type" : "module",
      "insecure" : [],
      "title" : "Various 3rd Party Vulnerabilities - PSA-2019-09-04",
      "link" : "https://www.drupal.org/psa-2019-09-04"
   }
]

This feed is then parsed by the Automatic Updates module for display in the Drupal admin interface. Other modules or services could also consume and display this feed.

More information about the psa.json feed can be found in this issue: #3068539: Add psa.json API endpoint to support automatic updates

Package Generation

The Drupal.org packaging system is what produces the .tar.gz and .zip downloads of projects on Drupal.org. At the same time that this system runs, it also updates the Composer façade and, with the addition of this Automatic Updates system generates the 'quasi-patches' that are used to update a site with the automatic_update module.

Package Signing and Security

To ensure that the 'quasi-patch' packages are secure and can be verified, Drupal.org uses a package hashing and signing architecture based on the BSD Signify project.

Drupal contributors have created a PHP implementation of Signify, which is available on the Drupal GitHub namespace: https://github.com/drupal/php-signify

This library is used to create SHA hashes of the files included in the project hash, which are then signed using a Public/Private key pair generated from an HSM in the Drupal.org infrastructure.

For more detail about how the hashing and signing system is being architected, please consult these issues:

• #3072104: Automatic Updates meeting on 5 September 2019
• #3071193: Use live SHA256SUMS
• #3077737: [Policy, no patch] use SHA256 vs SHA512 hashing

Providing Feedback

To provide your feedback on this first generation of the Automatic Updates module, please create an issue in the Automatic Updates issue queue.